ServerBox 工作原理全解析双传输通道、Rust 共享解析器与加密 SQLite 存储架构【免费下载链接】flutter_server_boxServerBox - server status toolbox项目地址: https://gitcode.com/GitHub_Trending/fl/flutter_server_boxServerBox 是一款基于 Flutter 与 Rust 的服务器状态监控工具箱其客户端与服务器端 Agentmonitor共享同一套命令清单与状态解析器从而保证同一命令输出、两端解读一致。本文以仓库内 .claude/skills/serverbox-onboarding/references/principles.md 为骨架结合源码逐层拆解其架构决策一个服务器为何可以同时暴露 SSH 与 HTTP 两种传输通道、能力协商Capabilities如何取代猜传输方式、状态解析为何必须住在 Rust 且保持纯函数、全部数据如何收敛进一个加密 SQLite 文件以及跨平台构建背后的两块原生机制。读完你将能够按图索骥在仓库中一步定位到对应模块的实现与测试。整体分层视图、状态、数据三层 一颗 Rust 解析内核从 principles.md 的shape of it一节可以看到应用本身是经典的分层结构lib/view/负责渲染页面与组件lib/data/provider/持有基于 Riverpod 的状态lib/data/model/与lib/data/store/构成数据层模型定义与持久化访问。关键的架构决策在于状态解析status parsing根本不是 Dart 实现的而是一个与服务器端 Agent 共享的 Rust crate。这样一来无论命令由 App 通过 SSH 远程执行还是由 monitor Agent 在本机采集两端对一段命令输出到底意味着什么的解读永远一致不会出现客户端以为的字段格式与 Agent 上报的不一样这类漂移问题。仓库布局与这一设计一一对应crates/sbm_parser—— 命令清单、解析器、脚本生成的唯一权威来源single source of truthcrates/sbm_ffi—— flutter_rust_bridge 绑定 crate供 Dart 侧通过 FFI 调用crates/sbm_native—— 仅 monitor 使用的原生采样器通过 syscall 而非 shell 命令采样。一个服务器可暴露两种传输通道能力靠询问而非试探从 SPI 出发的传输选择每个服务器保存着服务器私有信息Spi其中可以同时携带SshCredential与monitorHttp两类凭据仅配置 SSH纯 SSH 服务器仅配置 monitor纯 Monitor 服务器没有 SSH 凭据两者都配置同时保留两种连接带来的能力。ServerConnectCredential.fromSpi负责选出优先传输preferred transport而fallbackOf给出另一种。注意一个服务器不能两者皆无——SpiValidationError.noConnectionMethod与建表约束CHECK (ssh_ip IS NOT NULL OR monitor_addr IS NOT NULL)双重拒绝这种非法状态。ServerCapabilities把需要什么与由谁提供解耦一个功能在使用前通过ServerCapabilities询问这台服务器能不能做这件事而不去关心背后是 SSH 还是 monitor。这保证了需要一个 shell 的功能永远不必知道SSH才是提供 shell 的那个东西。接口定义见 lib/data/model/server/capabilities.dart每个传输通道一个实现类能力含义SSHMonitor HTTPshell可执行命令并读取输出进程/服务页、容器、电源控制✅取决于granted.fullAccessterminal可打开交互式终端终端页、snippet、iperf✅取决于granted.fullAccessbyteStream可建立双向字节流SFTP 传文件、端口转发转 TCP✅❌ 恒为 falsefiles可浏览和移动文件文件页、传输两端✅取决于granted.filesstoredHistory传输通道自带趋势历史可预填本地缓冲区❌App 自行采样刚打开页面时缓冲区为空✅Agent 在 App 询问前就在采样persistentSession已连接但尚未取到数据这一状态是否可观察✅❌只有是否已应答其中 Monitor 侧的两个回答值得展开byteStream恒为false因为 Agent 没有任何端点会把连接中继到App 指定的地址所以 SFTP 与端口转发天然缺席storedHistory恒为true因为运行 Agent 的意义就在于App 还没问的时候它已经在采样。当一个服务器同时具备两种传输时ServerCapabilities.ofSpi返回的是两者的并集UnionCapabilities见 capabilities.dart这样的服务器确实能同时做两套事情——Agent 持有 App 从未采样过的历史sshd 持有 Agent 没有端点的字节流。因此能力协商回答的是关于服务器的能力而不是关于某一次连接的能力具体某个功能最终走哪条通道在使用处按谁扛得住决定。ensureExec 与 ensureShellClient两条不同的落点路径ServerNotifier.ensureExec()是命令如何到达服务器的唯一决策点SSH 服务器 → 走SshExecMonitor 服务器 → 走POST /api/v1/exec。Monitor 服务器永远不会回退到 sshd——回退就意味着向用户索要他刻意没有给过 App 的凭据。而ensureShellClient()仅走 SSH 路径并且使用独立的TryLimiterkey${id}#shell这样shell 打不开不会连带拖垮状态页的刷新。SSH 字节流的三条来源轴线SSH 的字节流从哪里来是另一条独立的轴线统一在genClientlib/core/utils/server.dart中解析直连directSSHSocket.connect(ssh.ip, ssh.port)跳板机jump server对每个跳板递归调用genClient再通过forwardLocal(ssh.ip, ssh.port)转发目标地址ProxyCommand通过ProxyCommandSocket.connect执行用户配置的代理命令。后两者互斥由Spix.validate()强制。无论走哪条路SSHSocket之上的一切逻辑完全一致且每种情况下 App 都自行校验主机密钥。另外genClient内置了跳板链环路检测分别按服务器 id 与addr:ip:port检测并在诊断系统中记录via: jump|proxy|direct便于区分网络/跳板/代理故障与密钥/口令/主机密钥不匹配两类失败阶段。状态解析在 Rust 中完成且保持纯函数命令清单与分段协议crates/sbm_parser/src/commands.rs是命令清单command manifest的所在地每个命令键如cpu、mem、net映射到各平台的真实 shell 命令脚本输出以SrvBoxSep.cmd分段SEPARATOR SrvBoxSepApp 与 monitor 都从这里取命令从而保证脚本生成逐字节一致。以 Linux 为例快路径命令包括cat /proc/stat | grep cpu、cat /proc/meminfo | grep -E Mem|Swap、cat /proc/net/dev、cat /proc/diskstats等见 commands.rs。解析入口是 lib.rs 的parse_status(system, raw)输入是命令键 → 原始输出的映射输出是结构化的ServerStatus按SystemType::{Linux, Bsd, Windows}分发到对应的平台解析器。任何一个命令缺失或解析失败只影响该字段对应 App 的按段 try-catch 容忍不会拖垮整轮结果。纯函数设计可变状态绝不跨 FFI这是整个解析器最核心的约束解析器只输出原始计数器raw counters——CPU 的 ticks、网卡累计字节数、磁盘扇区数任何需要窗口计算的东西如网络速率都是两个采样点之上的纯函数而可变的时间序列状态留在调用方一侧。注释原文即No mutable state crosses the FFI boundary可变状态不跨越 FFI 边界。这直接规避了 FFI 边界的并发与内存安全问题。EXTENDED 慢路径为磁盘寿命设计的取舍commands::EXTENDED见 commands.rs把三类命令从快路径中剥离交给扩展函数SbStatusExt以分钟级慢节奏执行smartctldiskSmart读取本身免费但触达磁盘会唤醒处于待机状态的盘。若按几秒一次的轮询频率去跑 smartctl配置了停转的磁盘永远无法停转每次唤醒还会消耗Start_Stop_Count/Load_Cycle_Count计数AMD GPUamd-smi/rocm-smi每次调用要 fork 多个工具ip地址查询答案只在机器移动或租约变化时才改变几秒一问纯属浪费进程 spawn。App 以分钟级定时器刷新这些命令monitor 则在扩展周期extended cycle执行。monitor 独享的原生采样器monitor 额外拥有crates/sbm_native通过sysinfoBSD/Windows或直接读 procfs/sysfsLinux采集 CPU、内存、磁盘、网络与 uptime全程不依赖 shell 命令——这是 App 没有的选项因为 App 永远面对的是远程主机只能通过 SSH 收集。test-as-spec用测试锁定迁移crates/sbm_parser/tests/dart_compat.rs用原始 Dart 实现的 fixtures 锁定了行为。迁移规则是测试即规范test-as-spec把某个模块的 Dart fixture 测试先移植到 Rust断言 FFI 结果与原始实现逐字节一致最后才删除 Dart 实现。这样共享解析器的每一次演进都有回归防线。存储一个加密 SQLite 文件两种表形态所有数据收敛为单一文件store.db通过package:sqlite3打开并启用sqlite3mc加密扩展。采用哪种形态是刻意决策形态一kv 表设置与历史kv(store, key, value, updated_at)容纳上百个互不相关的偏好设置与历史记录新增一条只需一行改动value是 JSON因此写入的任何值都需要toJsonSqliteStore.set在拿不到toJson时返回false而不是抛异常——意味着一个缺少.g.dart的模型会被静默丢弃历史上PortForwardConfig正是因此在导入时整个丢失其toJson必须手工维护并与fromJson保持同步。形态二实体表有关系的数据服务器、私钥、snippet、端口转发、连接统计、Agent 会话等各自拥有表结构带外键与索引。动手改 schema 前必须知道的约定主键必须是 id绝不能是用户输入的东西。私钥曾以名字为主键导致重命名后所有指向它的服务器全部失联现在两者都有生成的 id 与UNIQUE名称列重命名是一次UPDATE冲突则以DuplicateNameException暴露。列表/映射字段是子表不是列里的 JSON 数组server_tag、server_env、server_jump、snippet_tag、container_host。子表不带同步列随父表整体移动编辑子行会盖章父行通过Stores.server.synced.stamp。INSERT OR REPLACE在带同步列或子表的行上是错的它删除再插入会把未命名的列重置为默认值rev归零并级联清掉子表。正确做法是EntityStore.upsertON CONFLICT DO UPDATE仅更新数据列。枚举按名字存储不按索引索引会在插入新 case 时悄然改变含义而这些值存活的时间超过写出它们的构建版本。迁移读取旧记录时要显式翻译如ConnectionStat的JsonValue是 snake_case而列存的是枚举name五个中有三个不同。Drift 只拥有 DDL查询全部手写且同步因为 UI 是在构建期间读取 store 的。同步单元与墓碑Tables.syncRoots指名同步以什么为单位移动每个 root 携带updated_at与rev同一毫秒内的两次编辑靠时钟无法区分所以需要 rev删除时写入一行tombstone表定义见 lib/data/store/db.dart——没有墓碑对端会把缺席读成新增然后把记录放回来。conn_stat与agent_conversation刻意不是同步 root连接不是编辑会话则携带终端输出与推理内容。迁移的完整纪律含永久回归测试、fixtures 机制见 docs/src/content/docs/development/testing.md简短版本是一次迁移只在真实用户数据上跑一遍bug 在其中表现为静默而非崩溃因此每个迁移都要配一个由旧版本真实写出的字节喂出来的常驻测试。状态管理与一个导航器陷阱状态栈为Riverpod 代码生成providers、Freezed不可变模型、GetIt服务定位。长文见 docs/src/content/docs/principles/state.md。最容易出 bug 的陷阱是对话框导航showRoundDialog把对话框放在根导航器上而页面的context找到的是持有该页面的导航器——在 pane 或 tab 内部两者不是同一个因此从对话框按钮里context.pop()关掉的是页面对话框留在屏幕上被 await 的 future 永不完成调用方后续代码也不执行正确做法用context.popDialog()显式关根导航器上的对话框更好的做法是让对话框回答——await context.showRoundDialogbool(...)配合Btnx.cancelOk由调用方在页面上完成后续动作并关闭页面破坏点在于给Btn.ok传onTap没有onTap时Btn用按钮自己的 context在对话框内解析导航器行为正确传了onTap就替换掉这份正确的导航器解析f必须自己弹对话框。对话框内Input的onSubmitted同理。仓库还给出了两条第一轮排查用的 grep 命令rg -U showRoundDialog[\s\S]*?context\.pop\( lib与rg -n Btn\.ok\(onTap:|Btnx?\.\w\(onTap: lib。跨平台同一套代码五个平台外加两块原生机制iSHiOS 本地运行 Linux 用户态third_party/ish-arm64是 iSH 的一个 fork——iOS 构建可以在本地运行的 Linux 用户态。默认关闭SBM_ISH0由scripts/build-ish-ios.sh在源码树外构建输出到build/ish/build-arch/这也解释了为什么flutter clean会破坏它它不在 Flutter 的清理范围内被清掉后 iOS 链接会报三个No such file or directorylib{ish,ish_emu,fakefs}.a且报错信息完全不指向原因。CocoaPods 已从 iOS/macOS 移除hook/build.dart与packages/flutter_ptyfork 用 Dart 构建钩子取代了各平台的原生构建集成因此仓库里没有Podfile也不应再加回一个。packages/flutter_pty与上游 0.4.2 的差异仅在于改用native_toolchain_c其余完全一致。本地化本地化是lib/l10n/下的 ARB 文件本项目字符串通过l10n访问fl_lib已有的字符串通过libL10n访问。规则是优先复用已有的libL10n字符串即使语义并非完全精确匹配。文档导航哪个问题对应哪份文档principles.md 末尾提供了一张问题 → 文档映射表是深入阅读的路线图想了解的问题对应文件分层、连接方式与核心系统如何组合docs/src/content/docs/principles/architecture.md连接流程、认证、主机密钥校验、会话生命周期docs/src/content/docs/principles/ssh.md文件操作、路径处理、传输、编辑docs/src/content/docs/principles/sftp.md终端字节流来源、标签页、虚拟键盘、选择docs/src/content/docs/principles/terminal.mdProvider 类型、更新模式、持久化、Riverpod 测试docs/src/content/docs/principles/state.md文件该放在树里哪个位置docs/src/content/docs/development/structure.md该跑哪个生成器、为何某个 adapter 被冻结docs/src/content/docs/development/codegen.md测试策略、fixtures、集成测试docs/src/content/docs/development/testing.mdAgent 的 API 表面、远程访问模型、控制面板monitor/CLAUDE.md改动这套代码的规则CLAUDE.mddocs/src/content/docs/下的页面都有对应的zh/版本scripts/check-locale-parity.mjs会在缺失翻译时让构建失败而两份CLAUDE.md不是文档页面、没有翻译——它们是写给改动代码的人的指令。小结一张地图而非文档的替代品principles.md 的定位是一张地图不是文档的替代品A map, not a replacement for the documentation。它浓缩的是解释仓库大多数行为的少数几个决策Flutter 分层 共享 Rust 解析内核、双传输通道 能力协商、纯函数解析与 test-as-spec 迁移、单一加密 SQLite 两种表形态、对话框导航陷阱、以及跨平台的两块原生机制。沿着本文给出的源码路径与文档路线图你可以一步定位到任何一个具体实现并在 CLAUDE.md 与 monitor/CLAUDE.md 中找到改动代码时必须遵守的规则。【免费下载链接】flutter_server_boxServerBox - server status toolbox项目地址: https://gitcode.com/GitHub_Trending/fl/flutter_server_box创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考