DeepSeek Harness for fnOS

把 DeepSeek 官方 Agent 浏览器 UI（DeepSeek Harness / dsh）装成飞牛 fnOS 常驻应用：离线安装免联网，局域网与 FN Connect 直连，自带 28001 管理面板

下载 · 功能 · 快速开始 · 访问方式 · 管理面板 · 配置 · 贡献者致谢 · 更新日志

上游项目：deepseek-ai/deepseek-harness（DeepSeek Harness 开发者预览版，官网 https://www.deepseek.com/harness/）。本仓库不 fork 上游代码，只负责 fpk 打包、fnOS 生命周期脚本和少量运行时 / 构建期补丁；应用图标为 DeepSeek 官方黑色鲸鱼 logo。

下载

从 Releases 下载对应架构的 fpk：

版本号跟随上游 @deepseek-ai/dsh 发行版（目前均为 -rc 预览版本，如 0.1.7-rc.2），本地修复不单独抬版本号。 全部为离线包（内置对应架构的 node_modules），安装时无需联网拉取 dsh；单个 fpk 约 120 MB。0.1.7 起 fpk 超过 Gitee 附件 100 MB 上限，安装包只在 GitHub Release 提供。 依赖应用：安装时 fnOS 自动安装 nodejs_v24 与 bunjs（manifest install_dep_apps）。manifest 未声明最低 fnOS / 应用中心版本。 ARM 版在 manylinux_2_28 容器中编译原生模块，要求系统 glibc ≥ 2.28（fnOS ARM 设备为 Debian 12 / glibc 2.36）。

架构

功能

离线自托管

• 安装免联网：@deepseek-ai/dsh 连同 node_modules 随 fpk 内置；只有离线包缺失时才回退到在线 npm install（单线程 + 512 MB 堆，照顾 1 GB 内存的小设备）
• 双架构：x86 与 ARM 各出 iframe / url 两个变体，均由 GitHub Actions 在线打包
• 常驻服务：以应用专属账号 dsh 运行（run-as: package），由 cmd/main 管理 start / stop / status / restart

访问与安全

• 局域网直连：通过 cordis.patch.yml 把 dsh web 绑定到 0.0.0.0:28000（dsh CLI 本身拒绝 --host 0.0.0.0）
• 信任围栏：/api/* 校验 Host / Origin，只放行回环地址 + --trusted-host 列表（启动时自动探测的本机 IP + fnos.net / 5ddd.com + trusted_hosts.conf 中的域名），其余来源 403
• 桌面免 401：上游 0.1.2 起的浏览器 token 鉴权对静态桌面入口不可用，运行时补丁对已通过围栏的请求放行（等效「围栏即认证」）
• FN Connect / DDNS 远程访问：安装向导或应用设置里填 FN ID / 自定义域名，自动写入信任域，远程访问不再 403
• 设置页 host 模式：构建期补丁让非回环访问（局域网 IP、FN Connect 域名）也能读写服务端配置，插件 / 模型设置不再空白

运维

• 28001 管理面板：服务状态、三路日志、插件启停 / 删除 / 安装、版本检查、一键重启 dsh、一键下载并热安装更新（见 管理面板）
• 启动自愈：启动前把 .credentials.yaml / .env 修正为 600 权限、清理占用 28000 端口的残留进程、修正被 root 误建的 .gitconfig 权限
• 数据保留：升级不动数据区，卸载脚本只清理日志与 pid，都不删除 dsh_home（工作空间、会话、API Key、代理与信任域配置）

Agent 运行环境

• dsh 的 Agent / bash 工具可直接使用 node / npm / npx / pnpm / yarn / corepack / bun（来自依赖应用，启动时自动加入 PATH；见 Agent 环境命令）
• npm 全局安装与 corepack 缓存都指向数据区，不占系统盘

官方插件兼容

• 语音输入（实验性）：官方 @deepseek-ai/dsh-experimental-voice-input-bundle（本地 SenseVoice 转写）在 fpk 下完整可用 —— 模型下载走 proxy.conf 代理，麦克风走 FN Connect HTTPS 入口或浏览器标志位启用；实测记录与局域网方案见 语音输入插件兼容指南

快速开始

安装

1. 从 Releases 下载对应架构的 fpk（推荐 iframe 变体），在 fnOS 应用中心选择手动安装

2. 安装向导（所有项都可留空，之后再配）：

   字段	说明
   DeepSeek API Key	sk- 开头，写入数据区 dsh_home/.env
   代理 IP / 代理端口	两项都填才生效，拼成 http://IP:端口 写入 proxy.conf；访问 GitHub / 外部 API 超时再填
   FN Connect ID	只填 ID（如 techysy），自动生成 <ID>.fnos.net、dsh.<ID>.fnos.net 信任域；fnos.net 与 5ddd.com（飞牛两条域名后缀）已内置
   自定义域名	用自己的域名做 DDNS 远程访问时填完整域名（不带 https://），追加到信任域

3. 在 fnOS 桌面打开 DeepSeek Harness 图标进入 UI；或浏览器访问 http://<NAS_IP>:28000

升级

• 应用中心：下载新版 fpk 后手动安装覆盖，数据区保留
• 管理面板一键更新：http://<NAS_IP>:28001/ →「一键下载到 NAS」→「安装更新」（需先做一次 sudo 授权，见 管理面板）

卸载

卸载前先停止 dsh 与网关代理，卸载后清理数据区的 *.log / *.pid；dsh_home 不会被卸载脚本删除，重装后数据仍在。

访问方式

统一网关细节与打通过程见 docs/dsh-access-and-gateway.md。远程场景推荐网关入口；28000 直连入口保留。

安全机制（0.2.0-rc.2 现状，补丁均为幂等，每次启动 / 安装时自动检查）：

📖 围栏与回环限制详解：docs/dsh-loopback-restriction.md

管理面板

0.1.5-rc.2 起内置独立管理面板（cmd/dashboard.js，零依赖纯 node），随 dsh 自动启动，浏览器打开 http://<NAS_IP>:28001/：

• 信任面与 dsh 一致：本机 / 局域网 IP、fnos.net / 5ddd.com 及其子域、trusted_hosts.conf 自定义信任域可访问，其余来源 403
• 面板日志写入数据区 dashboard.log；cmd/main stop 不停面板，卸载时由 uninstall_callback 显式停止

启用热更新（一次性，SSH 到 NAS 执行；面板「已下载的更新」卡片会给出跟随当前下载目录的完整命令，直接复制即可）：

# 默认下载目录 (共享工作区) 的白名单示例:
echo 'dsh ALL=(root) NOPASSWD: /usr/local/bin/appcenter-cli install-fpk /vol*/@appshare/dsh/dsh_home/update/*' | sudo tee /etc/sudoers.d/dsh-hotfix
sudo chmod 440 /etc/sudoers.d/dsh-hotfix

白名单是永久生效的精确路径授权：仅允许 appcenter-cli install-fpk 安装该目录内的 fpk，无法执行其他命令。授权状态面板会自动探测显示；若下载目录换到其他授权目录，按面板提示更新白名单路径即可。不授权则按钮提示失败，可改用应用中心手动安装（fpk 已下载在工作区 update/ 或所选下载目录）。

配置

DeepSeek API Key

• 安装向导填写，或编辑数据区 dsh_home/.env：

  DEEPSEEK_API_KEY=sk-xxx

• 也可在 dsh 设置页内直接配置官方 / 自定义提供方的 API Key（改后重启应用生效）
• 应用设置页不含 API Key 字段；.env 权限每次启动自动修正为 600

网络代理（可选）

在安装向导或应用设置页填写代理 IP + 端口，写入 dsh_home/proxy.conf：

PROXY=http://127.0.0.1:7890

启动时据此设置 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY 并写入 git 全局代理，dsh 的出站请求（git / npm / API）走该代理；没有 proxy.conf 或没有 PROXY= 行则不走代理。启动环境已带 HTTP_PROXY 时以环境变量为准；上游 0.1.2 起也遵循 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY。

信任域（FN Connect / 自定义域名）

dsh_home/trusted_hosts.conf，每行一个主机名，# 开头为注释；http(s):// 前缀和结尾 / 会被自动去掉。可在安装向导或应用设置页修改：

• FN Connect ID：重写整个文件为 <ID>.fnos.net、dsh.<ID>.fnos.net、fnos.net
• 自定义域名：追加一行

应用设置页的字段留空表示保留当前值；修改后重启应用生效。

端口与数据区

数据分两处存放 —— 工作空间放共享目录（文件管理器可见、SMB 可共享、卸载不删），凭据留在数据区（不对外暴露）：

凭据以软链形式接入共享 HOME（dsh 仍从同一 HOME 读取），真实文件始终留在数据区。 卸载行为：@appshare 是 config/resource 声明的共享目录，fnOS 卸载时不清理——工作空间与会话得以保留；@appdata 会被清理，凭据随之移除（重装后重填，符合预期）。 老版本（数据全部在 @appdata/dsh/dsh_home）首次启动会自动迁移到上述布局：逐文件校验大小，任一文件不符即整体回退旧布局并保留原数据，下次启动重试。

Agent 环境命令

安装后可在 dsh 的 Agent / bash 工具里直接使用以下命令（来自 fnOS 依赖应用，启动时自动加入 PATH）：

# 一键验证全部命令
node -v && npm -v && pnpm --version && yarn --version && bun --version

完整命令兼容矩阵与实测版本号见 docs/dsh-nodejs-commands.md。

项目结构

deepseek-harness-fnos/
├── app/
│   ├── server/                  package.json 只声明 @deepseek-ai/dsh 版本；打包时 npm install 成离线 node_modules
│   └── ui/                      桌面入口配置 config（iframe / url）与图标
├── cmd/
│   ├── main                     start / stop / status / restart：运行时补丁、信任域、启动 dsh + proxy + 面板
│   ├── install_* · upgrade_*    安装 / 升级：写 .env / proxy.conf / trusted_hosts.conf、settings 补丁、离线包检查
│   ├── config_*                 应用设置页保存（代理 / FN ID / 自定义域名）
│   ├── uninstall_*              停止进程、清理日志与 pid
│   ├── dashboard.js             28001 管理面板
│   ├── proxy.py                 统一网关代理（app.sock → 127.0.0.1:28000）
│   └── patch_settings_memory.py 设置页 memory→host 补丁
├── config/                      privilege（run-as package）· resource（data-share 声明）
├── wizard/                      install（安装向导）· config（应用设置页）
├── scripts/                     离线打包、ARM node_modules 构建、补丁注入、401 热修、Release 通知、临时测试脚本
├── docs/                        打包 / 访问 / 回环限制 / Node 环境 / 上游同步文档，forum-templates/ 论坛发帖模板
├── release-0.1.7-rc.2/          该版本 Release 正文
├── .github/workflows/           build-fpk.yml（在线打包 + 上传 Release）· build-arm-node-modules.yml
├── manifest · VERSION           fpk 清单与版本号
├── ICON.PNG · ICON_256.PNG      应用图标
├── CHANGELOG.md · test log.md   更新日志 / 各版本测试报告
└── LICENSE

gh workflow run build-fpk.yml --ref main -f arch=x86     # 或 -f arch=arm（默认 arm）
gh run watch                                             # 产物: gh run download <run-id>
# 打包完成后直接上传到 Release（不存在则创建，同名资产覆盖）
gh workflow run build-fpk.yml -f arch=x86 -f release_tag=v0.1.7-rc.2

bash scripts/build-x86-offline.sh                                  # x86：url + iframe，交付到应用中心扫描目录
bash scripts/package-arm-offline.sh node_modules-arm64-<sha>.tar.gz  # ARM：用 build-arm-node-modules.yml 产出的 node_modules 打包

文档

• fpk 打包指南 — 在线 Actions / 离线脚本双路径、版本号策略、升级 SOP
• 同步上游后检查清单 — 每次同步上游 / 重装后验证本地补丁是否还在
• 访问与网关 — 访问入口、统一网关 /app/dsh 不可行的调查
• 回环限制详解 — 信任围栏 / trusted-host / settings host-mode
• ARM 打包
• dsh Node.js 自托管 — node / npm 基础接入
• dsh Agent 命令兼容矩阵 — node / npm / npx / pnpm / yarn / bun / corepack 完整命令与数据区配置
• 语音输入插件兼容指南 — 官方 SenseVoice 语音输入安装、模型代理 / 离线部署、麦克风安全上下文与局域网方案

已知限制

• 28000 / 28001 除信任围栏外没有登录鉴权（浏览器 token 鉴权已被补丁关闭），只适合局域网 / FN Connect 使用，请勿直接暴露到公网
• 语音输入插件在局域网 HTTP 直连时无法录音 —— 浏览器只在 HTTPS / localhost 开放麦克风（与封装无关的安全上下文限制，FN Connect 外网 HTTPS 不受影响）；局域网方案见 语音输入插件兼容指南
• fnOS 统一网关 /app/dsh 需 fnOS 登录会话（0.2.0-rc.2.2 起打通）；更早版本的 fpk 请用 28000 直连或 FN Connect 访问
• 上游仍是开发者预览版（-rc），本地补丁依赖上游代码的特定写法，上游改动后可能失效，需按检查清单核对
• v0.1.7-rc.2 及更早的 fpk 中，Web 侧边栏终端可能因服务账号登录 shell 为 nologin 而打开即退出（提示 This account is currently not available.）；0.2.0-rc.2 起安装脚本自动修正，老版本可手动执行 sudo usermod -s /bin/bash dsh
• 桌面打开出现 dsh web authentication required 401（启动补丁在个别环境没打上）时，SSH 到 NAS 执行热修脚本后在应用中心重启 dsh：

  curl -sL https://gitee.com/techysy/deepseek-harness-fnos/raw/main/scripts/fix-browser-auth-401.sh | sudo bash

• 面板「安装更新」需要一次性 sudo 授权；一键下载固定取 iframe 变体
• ARM 版与 x86 同一套打包流程，但作者未在 ARM 实机上做自动化测试；原生模块要求 glibc ≥ 2.28
• 离线包缺失而回退在线安装时，需要 nodejs_v24；如 node-pty 等原生模块需要重编译，还需 sudo apt install -y build-essential

贡献者致谢

许可证

MIT