飞牛 NAS 部署包 CAN230921/dsh-fnos-docker

DeepSeek Harness for fnOS（飞牛）—— 社区 Docker 打包版

把 DeepSeek Harness（DeepSeek 官方的开源 AI 智能体工作台）打包成飞牛 fnOS 可安装的 .fpk 应用，Docker 方式运行。

非官方社区打包：本项目由第三方社区维护，与 DeepSeek 官方无隶属/授权关系。图标为社区自制，不含 DeepSeek 商标与官方 Logo。DeepSeek Harness 上游目前处于 Developer Preview，可能发生破坏性变更，请以固定 commit 构建（见「本地重新构建」）。

产物（out/）

| 文件 | 说明 |
| deepseek-harness_<版本>_all.fpk | 飞牛应用安装包（应用中心 → 手动安装） |
| deepseek-harness-web_<版本>_arm64.tar | arm64（ARM 机型）Docker 镜像（离线安装用） |
| deepseek-harness-web_<版本>_amd64.tar | amd64（x86 机型）Docker 镜像（离线安装用） |

镜像同时发布在 ghcr.io/can230921/deepseek-harness-web:<版本>（arm64 + amd64 双架构，构建自同一源码树并有一致性校验）。.fpk 安装包应从本仓库的 GitHub Releases 下载；out/ 是本地构建目录，不纳入 Git。

在飞牛 NAS 上安装

方式 A（推荐，直接安装）：镜像已发布在 ghcr.io（公开），安装时自动拉取：

飞牛桌面 → 应用中心 → 右上角「手动安装」→ 选择对应版本 deepseek-harness_<版本>_all.fpk → 安装向导里设置 Web UI 端口（默认 3080）和访问密码 → 完成。

镜像加速（国内直连 ghcr.io 慢时）：compose 的 image 支持 registry 变量覆盖，把 DSH_REGISTRY 设为已验证可用的加速源即可，例如：

在应用数据目录的 docker-compose.yaml 所在处或系统环境里设置（或直接改 image 行前缀）：
DSH_REGISTRY=ghcr.nju.edu.cn docker compose up -d

或先在 NAS SSH 里预拉并改名（推荐，不动 compose）：

VERSION=0.1.0-rc.23
docker pull ghcr.nju.edu.cn/can230921/deepseek-harness-web:${VERSION}
docker tag ghcr.nju.edu.cn/can230921/deepseek-harness-web:${VERSION} \
ghcr.io/can230921/deepseek-harness-web:${VERSION}
之后 compose pull_policy: missing 会直接用本地镜像，不再联网拉取

已实测加速源：ghcr.nju.edu.cn（全链路 200，无需认证，路径与 ghcr.io 完全一致）。其余第三方代理如 ghcr.m.daocloud.io（403）、ghcr.dockerproxy.com（301）当前不可用，勿用。

方式 B（完全离线）：先从 out/ 取对应架构的镜像 tar，在 NAS SSH 终端导入，再装 fpk（pull_policy: missing 会优先用本地镜像）：

docker load -i deepseek-harness-web_<版本>_amd64.tar # x86 机型
或 docker load -i deepseek-harness-web_<版本>_arm64.tar # ARM 机型

使用

- 打开地址 https://<NAS_IP>:<端口>（默认 3080）→ 首次访问浏览器会提示自签证书警告（正常现象，见下方「TLS 与证书」核对指纹）→ 输入安装时设置的访问密码 → 进入工作台，在「设置 → 模型」里填入你的 DeepSeek API Key 后即可使用。
- 3080 只提供 HTTPS/WSS（默认）。明文 http:// 访问会被 TLS 握手拒绝，浏览器显示协议错误，改为 https:// 即可；这是刻意设计，杜绝降级攻击。
- 登录会话有效期默认 1 天（可在 compose 里加 DSH_AUTH_TTL_DAYS 调整）；右上角/代理登出端点 POST /__auth/logout 可退出（仅接受 POST）。
- 忘记/想改密码：飞牛应用中心 → DeepSeek Harness → 应用设置 → 重新填写访问密码并保存；或在 NAS 上直接编辑应用数据目录里的 auth.conf 后重启容器。
- 数据保存在 DSH_HOME=/data/dsh-home（对应 NAS 上应用数据目录 TRIM_PKGVAR/data），升级/卸载保留。

TLS 与证书

- 默认开启 HTTPS：容器第一次启动会在应用数据目录生成自签证书（TRIM_PKGVAR/data/tls/server.key / server.crt），ECDSA P-256、SHA-256、有效期 3 年；私钥权限 600、目录 700。升级/重启继续复用原证书，指纹不变。
- 证书 SAN：默认含 DNS:localhost,IP:127.0.0.1；如需用域名/IP 访问并在证书里带上，在 compose 设置 DSH_TLS_DOMAINS（逗号分隔 DNS 名）与 DSH_TLS_IPS（逗号分隔 IP）。注意 SAN 要在首次生成证书前设置，之后需删除证书文件并重启重新生成。
- 核对指纹（独立通道优先）：首次信任前，优先通过不受同一 HTTPS 连接控制的通道核对指纹——例如 NAS 本机文件 openssl x509 -in <应用数据目录>/data/tls/server.crt -noout -fingerprint -sha256、SSH 到 NAS 查看、或 fnOS 管理界面里的证书信息。curl -k https://<NAS_IP>:3080/__auth/tls 可作参考，但该指纹与证书走同一条 HTTPS 连接，若整条链路被同时劫持则无法独立证明，请勿仅依赖它。
- 故障恢复：证书丢失或损坏时容器拒绝启动（绝不回退明文 HTTP）。删除 TRIM_PKGVAR/data/tls/ 目录后重启即可重新生成（指纹会变化）；DSH 数据、密码、TOTP、API Key 均不受影响。明确需要明文时，在 compose 设 DSH_TLS_ENABLED=0（仅当你自己在反代层终结 TLS）。
- HTTPS 下会话 Cookie 自动带 Secure 属性（无需再设 DSH_COOKIE_SECURE，仅反代终结 TLS 时才需要该变量）。

登录认证

- 安装向导收集的访问密码写入应用数据目录 auth.conf（不暴露在 docker inspect 环境变量中），容器启动时读取。安装时密码必填（向导校验 + 安装回调强制），空密码会被拒绝安装。
- 认证由内置代理实现：未登录的页面请求返回内置登录页，/api 请求返回 401，WebSocket 连接被拒绝；登录后下发 HttpOnly 会话 Cookie，浏览器自动携带（含 WebSocket 握手）。
- 高级：compose 环境变量 DSH_AUTH_PASSWORD 可覆盖密码文件；DSH_AUTH_TTL_DAYS 调整会话有效期。
- 强制 OTP 默认开启：无论外网还是本机访问，每次登录都必须同时提供密码与动态验证码；首次登录会引导完成 Authenticator 设置（设置页提供二维码扫码，也支持手动输入密钥；密钥写入应用数据目录 totp.conf）。如需关闭，在 compose 中设置 DSH_FORCE_TOTP=0，或在应用数据目录写 2fa.conf（内容为 force=0）后重启容器。会话有效期默认 1 天，期间同一浏览器免重复验证，可用 DSH_AUTH_TTL_DAYS 调整。
- 公网经 HTTPS 反代/隧道访问时，建议在 compose 中设置 DSH_COOKIE_SECURE=1，让会话 Cookie 仅经 TLS 传输（明文 HTTP 下不要开启，否则登录会失败）。
- 插件源默认直连官方：npm 走 registry.npmjs.org、GitHub 直连 github.com（不经过第三方代理，降低供应链篡改面）。国内网络直连慢时，可显式开启加速：DSH_NPM_REGISTRY=https://registry.npmmirror.com、DSH_GITHUB_PROXY=https://ghfast.top/（均为可选）。
- 进程隔离边界：代理与 Harness 后端以同一容器用户（非 root）运行，访问密码、TOTP 密钥由代理进程持有、落在 /data 下。能在容器内执行命令的智能体理论上可读取同用户进程信息或 /data 配置——这是单进程用户模型的固有限制；请勿在容器内运行不受信任的代码，并做好 NAS 宿主层隔离。
- DSH_TRUST_PROXY=1 慎用：仅在受信反向代理能独占容器端口、外部无法直连 3080 的场景下启用。若外部可直接访问端口，客户端可伪造 X-Forwarded-For 绕过来源地址判断与基于 IP 的登录限速。

启用 IPv6

镜像原生支持 IPv6（代理、运行时均无 IPv6 障碍，isPrivateAddress 已识别 fc00::/7、fe80::/10）。要让容器真正拿到 IPv6 地址，需在 NAS 宿主层开启 docker IPv6：

1. 编辑 /etc/docker/daemon.json，加入：
{ "ipv6": true, "ip6tables": true, "fixed-cidr-v6": "fd00::/64" }

（fixed-cidr-v6 可换成你的 ULA/公网前缀）后重启 docker。
2. 在应用数据目录的 docker-compose.yaml 中取消 networks.default 的 IPv6 注释块，按你的前缀修改 subnet，保持容器可用 v6 地址。
3. 如需把 3080 也以 IPv6 暴露，端口映射改用 "[::]:${TRIM_SERVICE_PORT}:3080"（见 compose 注释）。

注意：宿主 docker 未开启 IPv6 时，不要启用 compose 的 enable_ipv6，否则应用会因 "IPv6 is not enabled in this daemon" 启动失败。

运行原理

- 镜像从官方源码构建：pnpm install + pnpm run build（monorepo 全量构建），运行时执行 dsh --profile web。
- dsh 出于安全设计拒绝绑定 0.0.0.0，因此容器内它只监听 127.0.0.1:3081，由内置的 HTTP/WebSocket 代理在 0.0.0.0:3080 对外提供服务，并把 Host/Origin 重写为回环地址以通过浏览器的信任围栏（代理即信任边界，与其它 NAS Web 应用一致）。
- 高级选项：在 compose 中设置 DSH_TRUSTED_HOSTS=192.168.1.100（host 或 host:port，逗号分隔）后，代理不再改写请求头，dsh 会把该地址加入信任围栏，保留完整安全校验。
- 如你的飞牛反代或隧道会透传 X-Forwarded-For / X-Real-IP，并且你希望将来源 IP 限制建立在真实客户端上，可额外设置 DSH_TRUST_PROXY=1。

⚠️ 安全说明

- 请务必设置访问密码（安装已强制必填）。即便有登录认证，该应用仍可驱动智能体在容器内执行命令，请勿把端口直接映射到公网；如需公网访问，建议放在飞牛反向代理之后。
- 登录认证保护的是"谁能进入工作台"，不区分多用户；内置 TLS 加密传输（自签证书，首次信任请核对指纹）。
- 容器隔离已被放宽（重要披露）：为让 AI bash 工具的 bubblewrap 沙箱能在 fnOS 默认 Docker 下创建非特权用户命名空间，compose 显式设置了 seccomp:unconfined 与 apparmor:unconfined。这意味着容器内任意进程不受 seccomp/AppArmor 系统调用级过滤，若容器内被攻破（如沙箱逃逸、0day），内核利用面会增大。缓解措施：容器仍以非特权用户（TRIM_UID）运行、无危险 capability、未挂载 docker.socket，文件沙箱（bwrap/landlock）仍在。建议：若你的 fnOS 内核允许非特权用户命名空间（可在容器内试跑 bwrap --ro-bind / / true），可自行收紧——把 compose 的 security_opt 改为只保留实际需要的一项，或移除后验证沙箱仍工作。
- 镜像/插件供应链：插件源默认直连官方（npm/GitHub），不经第三方代理；如需加速请显式设置 DSH_NPM_REGISTRY / DSH_GITHUB_PROXY。镜像发布在 ghcr.io 公开仓库；目前未做可验证的镜像签名（仅有构建 attestation，不能替代签名），离线包请核对 SHA-256。
- 上游未固定：DeepSeek Harness 上游是 Developer Preview，可能发生破坏性变更。构建时应固定 commit（DSH_REPO_REF=<commit> ./build.sh），并以仓库记录的构建 commit 复核。

本地重新构建

前置：Docker (Desktop) 运行中；fnpack 在 PATH 或设 FNOS_FNPACK（fnOS 官方工具，
从飞牛开放平台/官方仓库获取）；上游源码 clone 后通过 DSH_REPO 指定。
export DSH_REPO=/path/to/deepseek-harness
建议固定上游 commit（官方为 Developer Preview，可能破坏性变更）：
export DSH_REPO_REF=dsh-v0.1.0-rc.7 # 或某个具体 commit hash
./build.sh # 默认：未指定 DSH_VERSION 时自动迭代版本（自增 rc）并打包 fpk ./build.sh --arch arm64 推送双架构镜像并合成 multi-arch manifest： ./build.sh --push ghcr.io/<user>/deepseek-harness-web:0.1.0-rc.x

默认会自动将 fpk/manifest 里的 version 与 fpk/app/docker/docker-compose.yaml 的镜像标签提升到新版本；如果你不想自动加版本号，可设置 DSH_VERSION_AUTO_BUMP=0。
也可直接指定版本：DSH_VERSION=0.2.0-rc.1 ./build.sh。

产物中的镜像 tar 会输出到 out/；fpk 文件会输出到桌面（可通过 DSH_FPK_OUTPUT_DIR 指定输出目录）。图标默认使用本仓库 assets/icon_1024.png（社区自制，DSH_ICON_SRC 可覆盖）。

发布约定

- Git 仓库只保存构建脚本、fnOS 打包文件、补丁和文档。
- .fpk 安装包发布到 GitHub Releases，不提交到源码历史。
- 多架构容器镜像发布到 GHCR；导出的 .tar 仅作本地离线分发。
- 发布前建议固定上游 DeepSeek Harness 的 commit，并记录在 Release Notes 中，便于复现构建。

许可与声明

本仓库的原创打包与集成代码采用 MIT License。上游 DeepSeek Harness 及内置第三方组件各自保留原许可证与版权，详见 THIRD_PARTY_NOTICES.md。本项目是社区打包项目，并非 DeepSeek 官方发行版。