飞牛原生套件 xiguan99/deepseek-harness-fnos

DeepSeek Harness for fnOS

DeepSeek Harness 的飞牛 OS（fnOS）原生打包版，拆成本体与面板两个应用，分开安装、分开升级。

| 应用 | 作用 | 入口 |
| DeepSeek Harness（本体） | DSH 服务 + Web UI | 桌面图标 / http://<NAS>:2299/ |
| Harness Panel（面板，可选） | 运行状态、启停、日志、配置、快照、插件 | 桌面图标（飞牛 Web 内打开）/ http://<NAS>:2296/ |

本体单独也能用；面板只是管理与运维入口，不装面板不影响对话。两个包请一起装：只装本体时没有管理界面，只装面板时面板会提示「本体未就绪」。

主要功能

- 一键安装，运行时随包分发，首启解包，不联网拉包也能起
- 本体桌面图标直达 Web UI，手机用局域网 IP 打开同样可用
- 面板提供 9 个视图：总览、运行控制、版本管理、日志、配置、快照、授权与访问、设置、面板更新
- 面板与本体分离：面板升级不影响本体运行，本体升级不影响面板
- 控制接口令牌鉴权：面板与本体之间走启动时随机生成的控制令牌，不是裸接

系统要求

- 飞牛 OS（fnOS）x86_64
- 依赖应用中心的 nodejs_v24（安装时自动带上）
- 磁盘：本体约 1 GB（含运行时 tar）；数据目录（会话、插件、记忆）随使用增长
- 内存：DSH 运行时单进程约 200～400 MB，长会话更高，可在面板设置里调堆内存上限
- 不需要另装 Node / Go / CUDA

架构与端口

| 端口 | 绑定 | 用途 |
| 2298 | 127.0.0.1 | DSH 服务自身，只对本机开放 |
| 2299 | 0.0.0.0 | 对外 HTTP 入口（Web UI），桌面图标与手机都走它 |
| 2297 | 127.0.0.1 | 控制面，面板专用，需要控制令牌 |
| 2296 | 0.0.0.0 | 面板直连端口（桌面图标走飞牛网关，这条留给排障） |

为什么 2298 不对外：DSH 启动时会给一个 ?token= 的访问令牌，如果把服务端口直接暴露到局域网，等于连令牌一起暴露。对外只开 2299，由它做代理与鉴权。

安全说明（建议读完再决定是否对外暴露）

- 控制令牌：本体启动时用系统随机数生成，写在应用数据目录的 control.token（权限 0640），面板自动读取；访问控制接口没有令牌一律 401
- 本体网关 socket：权限 0660，且同样要求控制令牌，不是只靠文件权限
- 面板访问控制：默认只信局域网网段（127/8、10/8、172.16/12、192.168/16、169.254/16）；来自其它网段必须设置访问密码，未设密码直接拒绝（401）；连续 5 次密码错误后按来源 IP 延后
- 本体以 root 运行：这是当前实现的事实——打包沿用上游设计，Go 管理进程与 DSH 进程都是 root。这不是推荐做法，如果你对权限敏感，请只在内网使用，并自行收紧应用目录权限
- 四个端口都不建议直接映射到公网。需要外网访问请走飞牛反代或 FnConnect

运行时版本策略

- 运行时（@deepseek-ai/dsh）钉死在包内随包分发，首次启动解包，不联网安装
- 面板里的「在线升级运行时」默认关闭；开启后运行版本会偏离包内版本，出问题时需要手动回退
- 版本号跟官方运行时同步，后面挂我们自己的补丁号

血缘表

| 本包版本 | 对应官方运行时 | 说明 |
| 0.2.1-rc.3.1 | 0.2.1-rc.3 | 官方运行时 + 本仓双包改造第 1 号补丁（当前） |

后续官方升 rc.3 → 本包跟进 0.2.1-rc.3.1；我们自己的改动递增最后的补丁号（.2、.3）。

安装

1. 应用中心 → 手动安装 → 选 deepseek.harness_v0.2.1-rc.3.1_x86.fpk（本体）
2. 同样方式安装 harness-panel_v1.0.1_x86.fpk（面板）
3. 首次启动要解出运行时并初始化 pnpm 环境，1～3 分钟，期间打不开属正常
4. 桌面图标：本体打开 DSH Web UI，面板打开管理面板

两个包安装之间的十几秒里，面板会显示「本体未就绪」，装完刷新即可。

使用

- 本体：桌面图标直达 http://<NAS>:2299/；第一次进去按引导连接模型服务商
- 面板：桌面图标在飞牛 Web 桌面内以 iframe 打开（网关前缀 /app/harness-panel）；直连 http://<NAS>:2296/ 保留作排障
- 面板里的「打开 Web UI」按钮会跳到 http://<当前访问主机>:2299/，手机点同样可用

升级与卸载

升级：应用中心覆盖安装，数据目录与运行时都保留。运行时只在包内 tar 缺失时才重建，正常升级不会重装运行时。

卸载（以下是实测结论，不是推断）：

- 卸载只删应用载荷（/vol1/@appcenter/deepseek.harness），不动数据目录（/vol1/@appdata/deepseek.harness）。会话、技能、配置、记忆、附件都在数据目录里，卸载后重装仍在
- 重装不会重装运行时：数据目录里的 dsh-runtime 还在，安装回调会跳过运行时部署，运行版本保持卸载前的样子，不会因为重装变成包内声明的版本。要换运行时版本请显式操作，或先删掉 dsh-runtime 再重启
- 数据目录属主：安装回调每次都会对整个数据目录 chown -R 到当前运行用户，所以卸载重装后即使应用用户 uid 变了，属主也会自动纠正，不需要手工 chown
- 彻底清理：先卸载，再手工删除 /vol1/@appdata/deepseek.harness

常见问题

桌面图标打开是空白 / 连不上

本体图标是端口直达（<NAS>:2299）。确认应用已启动、2299 没被别的程序占用。2298 只绑本机，浏览器直接开 2298 连不上是设计如此。

面板显示「本体未就绪」 读不到控制令牌。确认本体在跑、control.token 存在且面板用户可读（同在 AppUsers 组）。本体刚重启时等几秒再刷新。

面板要密码，但我没设过

面板默认只信局域网网段。从其它网段访问会被要求密码；在内网访问，或在面板数据目录的 shell_config.json 里设置访问密码即可。

版本号和下载的文件名对不上

应用中心显示的是包内 manifest 的版本。

运行时版本不是官方最新

这是设计：运行时随包钉死，避免自动升级把环境改坏。要新运行时请等本包跟进，或手动开启「允许在线升级运行时」。

构建与打包

仓库只放源码与构建脚本，二进制走 Releases。

一次性准备：Go 1.23.12、Node 24
1) 前端（Vue 3 + Vite）
cd frontend && npm ci && npm run build

2) Go 二进制（内嵌前端 dist）
go build -trimpath -ldflags="-s -w" -o ../dsh-build/bin/deepseek.harness .

3) 运行时 tar 与打包（含包纹核对） bash scripts/build.sh bash scripts/build-pkg.sh

打包前置校验，任一不通过直接中止：图标 256×256、四角透明且不与其它应用重复，且权限必须是 644（组不可读会导致应用中心读不到图标、静默退回默认占位图）；manifest 版本与仓库 VERSION 一致且不带 v 前缀；运行时 tar 内声明版本与实物版本都必须等于 RUNTIME_VERSION；端口钉死 2298/2299/2297；桌面入口只能有一个 url 形态；包内不得残留上游维护者标识。

发 Release 的两条注意事项（本体和面板是两条独立版本线，共用一个仓库）：

1. 本体 Release 必须显式标记为 latest（创建/更新 Release 时 make_latest=true，或发布后在页面上「设为最新版本」）。否则后创建的面板 Release 会被 GitHub 当成最新，而本体的「检查更新」读的正是 /releases/latest，会把面板版本号误判成新版本。
2. 面板 Release 也可以用「预发布（pre-release）」标记，效果相同：预发布不会参与 /releases/latest 的判定。

隐私

本应用不包含设备指纹、统计上报、使用量上报、远程校验或遥测。除你自己配置的模型服务商、以及你主动开启的更新检查外，不主动外连。

版本

- 本体：0.2.1-rc.3.1（= 官方运行时 0.2.1-rc.3 + 本仓双包改造第 1 号补丁）
- 面板：1.0.1（独立版本线，不对应官方）

来源与致谢

- DSH 运行时：@deepseek-ai/dsh（DeepSeek 官方 npm 包）
- 飞牛打包形态参考社区项目：<https://github.com/yuexps/deepseek.harness.fnos>
- 本仓库只做应用层打包与面板，不修改上游运行时逻辑
- 许可见 LICENSE