Flutter Server Box 使用指南：把服务器状态装进手机
摘要
Server Box 是 Flutter 写的跨平台服务器监控与 SSH 工具，AGPLv3 开源。含各平台安装渠道、服务端 Monitor agent 装法与 full_access 风险说明。
Flutter Server Box 使用指南：把服务器状态装进手机
有没有过这种场景：出门在外，服务器突然没响应，你只能打开一个黑底白字的 SSH 终端，敲
top、敲df -h、敲systemctl status，靠一串字符判断机器到底怎么了。Server Box 想解决的就是这件事——把服务器的 CPU、内存、磁盘、网络画成图表，装进你的手机和电脑。
下面从安装讲到那个容易被忽略的服务端 agent——它决定了推送、桌面小部件和历史曲线能不能用。
一、先把三个前提说清楚
这三条查错率最高，先摆出来：
项目 | 事实 |
|---|---|
许可证 | AGPLv3（主项目）；Monitor 子项目另为 GPL v3 |
界面语言 | 16 种（完整列表见 |
服务端组件 | 有独立的 ServerBox Monitor agent，没有它就没有消息推送、桌面小部件和 watch 应用 |
「服务端组件」这条最值得展开。 Server Box 的常规用法是 Agentless——服务器上什么都不用装，App 直接通过 SSH 连过去看状态。这足够日常用了，但意味着你只能在打开 App 的那一刻看到数据：App 一关，推送、小部件、历史曲线全部没有。这不是 bug，是少了那个 agent。 想从「随手的查看器」升级成「真正的运维面板」，就得装 Monitor，第五节会详细讲。
另外两件事也值得知道：项目现在有官方文档站，功能上支持 RDP / VNC 远程桌面（透过 SSH 转发）和 S.M.A.R.T. 磁盘健康检测。
二、它能做什么
状态图表：CPU、内存、磁盘、网络，以及传感器和 GPU 指标
SSH 终端：基于
xterm.dart，移动端也能正常用SFTP 文件传输、Docker / 进程 / systemd 服务管理、S.M.A.R.T. 磁盘健康
RDP 与 VNC：通过 SSH 转发访问远程桌面
Snippet 自动化：把常用命令存成片段，支持变量替换
平台特性：生物认证、消息推送、桌面小部件、watchOS 应用、跟随系统配色
多语言：16 种界面语言
三、安装：按平台选渠道
平台 | 下载渠道 |
|---|---|
iOS | App Store；或 GitHub Releases 的 |
macOS | App Store（仅 Apple silicon）；或 GitHub Releases 的架构对应 |
Android | |
Linux / Windows |
两个容易踩的细节：
macOS 的 App Store 版只支持 Apple silicon。 Intel Mac 用户请走 GitHub Releases 的
.dmg或 Homebrew。Android 分
arm/arm64/amd64三种安装包。 装错架构会直接安装失败，别急着怀疑是包坏了。官方文档只有一句提醒，但很重要：只从你信任的来源下载。这类工具手里握着的是你所有服务器的凭据。
四、第一次连接：用 SSH 加服务器
最直接的方式就是用 SSH 添加。连接信息保存在本地 App 里，不上传。几个建议：
优先用密钥认证，不要用密码。 这个 App 会长期持有你的服务器凭据，密码一旦泄露就是全盘失守。
服务器侧只需开放 SSH 端口，无需在服务器上装任何东西。这也是它比很多「监控面板」轻的地方——Agentless，不用在被管机器上部署。
如果你同时用它管很多台机器，建议按用途分组命名，再配合 Snippet 做批量运维。
五、ServerBox Monitor：让推送、小部件和历史图表真正可用
这一节常被跳过，但它是从「能用」到「好用」的分水岭。
5.1 它解决什么问题
Monitor 是配套的服务端 agent，职责是：记录服务器指标、提供 Monitor HTTP API、并可承载自己的 Web 面板。
装上它之后你会多拿到三样东西：
App 关着也能报警 —— 消息推送
桌面小部件和 watch 应用 —— 它们都需要一个能持续取数的后端
历史图表 —— 包括你接入 App 之前那段时期的指标记录
还有一个常被忽略的好处：它提供了第二种添加服务器的方式。App 可以通过 HTTP 连 Monitor，而不是走 SSH——适合那些你不想暴露 SSH 端口的主机。
5.2 一键安装
sh -s -- 之后的参数会原样传给脚本，所以 uninstall 和 upgrade 用法完全一致。脚本也随仓库发布，在该目录下直接 ./install.sh install 效果相同——但用的是当前 checkout 里的那份脚本，不一定等于上面命令从 main 拉的那份。
install.sh install 拉取的是本仓库最新的 monitor-v* release。这些 release 由 monitor-release.yml 工作流产出，而该工作流只支持手动触发（workflow_dispatch）——所以如果仓库里没有这样的 release，上面的一键安装会拿不到包，此时改用 SBM_INSTALL_PKG 指定本地构建，或者走仓库里的 Dockerfile。
配置在二进制旁边的 config.toml 里，每个键及其说明都在 config.example.toml。Agent 默认监听 0.0.0.0:3770，当 frontend/dist 存在时会在该端口提供 Web 面板。
5.3 第一次登录：密码在哪里
这里有个非常容易误解的设计，值得单独说：
面板用户存在 SQLite 数据库里，不在
config.toml里。 配置里的jwt_secret是用来签发 token 的密钥，它不是密码。
首次启动、用户表为空时，agent 会创建用户 admin 并生成一个随机密码，写在数据库旁边的 initial-admin-credentials.txt（权限 0600）。改完密码记得把这个文件删掉：
它会无回显地提示输入两次。也支持 --password-env VAR 从环境变量读取；没有命令行参数形式——因为命令行会进入 ps 输出和 shell 历史。同一条命令对不存在的用户会直接创建。
务必在 agent 自己的目录里执行这条命令。 config.toml 和数据库路径都是相对于当前工作目录解析的——换个目录执行，它会静默地在一个新的空数据库里设密码，然后你会困惑为什么新密码登不上。
5.4 以 Monitor 方式添加服务器：能做什么，做不到什么
以 monitor 方式添加的服务器，只通过这个 agent 的 HTTP API 访问，不带任何 SSH 凭据。能力清单由 agent 通过 GET /api/v1/capabilities 上报，App 只会展示它声明支持的功能：
App 功能 | 需要什么 |
|---|---|
状态、图表、历史记录 | 仅需登录 |
进程、systemd、容器、Snippet、电源操作 |
|
终端 |
|
文件浏览器 |
|
一个必须提前知道的边界：Monitor 方式不提供 SFTP 和端口转发。 原因很直接——agent 没有能把连接中继到「App 指定地址」的端点。需要 SFTP 或端口转发，就必须改用 SSH 方式添加这台服务器。
5.5 远程访问开关：默认全关，且有一个高风险项
[remote_access] 相关能力默认全部关闭，而且终端无法从面板里打开，必须改 config.toml。
[remote_access.terminal] enabled 会在面板里加一个浏览器终端。此时 agent 扮演的是 SSH 客户端，连到配置里的 ssh_addr——所以光有面板密码拿不到 shell，会话权限取决于浏览器登录的那个 SSH 账号，sshd 自己的日志、AllowUsers、双因素提示全部照常生效。会话在连接断开后会保留几分钟，手机切换网络时能回到同一个 shell 而不是丢掉。
full_access 则去掉了 SSH 登录这一步：任何登录面板的人都能开 shell、执行命令、访问这台机器能到达的任何地址，身份就是 agent 运行的那个账号。未设置时跟随平台——Linux 默认开，macOS 和 Windows 默认关。官方把这句后果写得很直白：你的面板密码就等于买下了这台机器。这也正是 install.sh 默认以普通账号运行 agent 的原因。如果你用 root 跑 agent，请务必关掉它。 也可以用 SBM_FULL_ACCESS=0/1 设置；面板的首次运行提示只能关，不能开。
为什么终端和其他能力是同一个开关而不是拆成多个？官方的解释很干净：谁能在 shell 里执行命令，谁就能在那个 shell 里执行任何东西、连到任何地方——所以「开终端、关其他」实际上什么都没关。
5.6 三个安全细节
明文监听的限制。 终端拒绝在明文监听上运行，因为它发的第一条消息里带着 SSH 密码。TLS 可以满足；同主机上的反向代理也可以，因为回环流量不在网络上暴露。在传输层已经有加密的可信私网（比如 Tailscale）里，运维者可以设 [remote_access.terminal] allow_insecure = true——但 App 端还必须为这个单独的 Monitor 连接额外打开「Allow insecure HTTP」，两个开关都要开才生效。文件 API 有完全相同的限制与两个 opt-in 要求。普通局域网、或你不掌控的网络，不要这么用。
主机密钥固定。 Agent 第一次连接时会固定（pin）目标 sshd 的主机密钥，之后如果密钥变了会直接拒绝，不会静默重新固定。要清除必须主动操作：删掉 ssh_known_hosts 里对应的行。
审计与限流。 access_log 记录谁、从哪、打开了什么、是否成功——但从不记录凭据。失败登录会按来源地址和用户名分别限流。
六、RDP 与 VNC：透过 SSH 的远程桌面
Server Box 支持通过 SSH 转发使用 RDP 和 VNC，也就是远程桌面流量走你已经建好的 SSH 通道，不必再额外暴露 3389 之类的端口。官方文档在这里。
对于「服务器只有 SSH 一个入口」的场景，这个能力比很多独立的远程桌面方案更省事——你不用为它开新端口，也不用再维护一套认证。
七、Snippet：把运维命令变成按钮
Snippet 是自定义代码片段，可以指定在某台服务器上运行，支持变量替换和特殊指令（比如延迟、模拟按键）。日常巡检命令写成 Snippet 之后，就不用每次重新敲一遍——这也是它在手机上比 SSH 终端更好用的一点：手机上敲长命令是真的难受。
八、版本与更新
当前最新版本 v1.0.1617（2026-09-12）。发布产物命名有规律，认准平台和架构即可：ServerBox_v1.0.1617_{arm,arm64,amd64}.apk、ServerBox-1.0.1617-{amd64,arm64}.dmg、ServerBox_v1.0.1617_amd64.AppImage、ServerBox_v1.0.1617_windows_amd64.zip、ServerBox_v1.0.1617_NoSign.ipa。
升级 Monitor 时注意：它的配置格式可能在不同 release 之间变化，官方明确要求升级后重新核对 config.example.toml。绑定某个版本的改动前，先看一眼那份示例文件。
九、常见问题
必须装 Monitor 吗？
不必。不装也能用 SSH 方式连服务器看实时状态。但推送、桌面小部件、watch 应用必须有它，历史图表也依赖它。
为什么 Monitor 模式下没有 SFTP？
设计如此。Agent 没有中继任意地址的端点。需要 SFTP 或端口转发，就用 SSH 方式添加这台服务器。
改了面板密码却登不上？
大概率是没在 agent 自己的工作目录里执行 user set-password——那样会把密码写进一个新的空数据库。回到 agent 目录重来。
GPU 指标看不到？
监控数据依赖主机侧暴露的指标接口。部分 Windows 或虚拟化环境拿不到 GPU 传感器，属于正常现象。
数据会传到第三方吗？
连接信息、指标都存在你本地 App 与自己的 Monitor 实例里。前提是：只连你信任的主机，并优先使用密钥认证，不要在公共设备上保存凭据。
十、提 Issue 的正确姿势
维护者把规则写得很清楚，照着做能省双方时间：
把完整日志贴进模板 —— 首页右上角可以导出
先确认问题确实出在 ServerBox，而不是目标服务器
具体、建设性的反馈欢迎；主观的 UI 偏好类反馈可能不被采纳
确认过上面几点，再去 开 issue。求助渠道还有 QQ 群、Telegram 和 Discord。
顺带一提，如果你在用 AI 编码助手，仓库里自带一个安装与使用引导的 skill：
源码在 .claude/skills/serverbox-onboarding，装之前可以先读一遍它会对你的 Agent 说什么——这个习惯值得养成。
十一、写在最后
装之前先记住三句话：许可证是 AGPLv3；界面语言有 16 种；没有 Monitor 就没有推送、小部件和历史曲线。第三条决定了你装的是一个「随手的查看器」还是一个「真正的运维面板」。
补一句关于安全的判断：Monitor 的 full_access 把「面板密码」和「机器 root 权限」之间的墙推倒了，官方自己用「你的面板密码就等于买下了这台机器」来形容。默认配置下这堵墙是立着的——所以除非你完全清楚后果，别为了图方便把它拆掉。