家庭服务器部署版 samuelrubiodev/deepseek-harness-community

DeepSeek Harness — Community Fork

面向家庭服务器与局域网部署的 DeepSeek Harness（dsh）自助发行版。它提供一条命令的 Docker 部署、局域网与反向代理访问，以及声明式环境配置——同时不重写上游代码，让 git merge upstream/master 保持低成本。

安全须知：DeepSeek Harness 会执行模型生成的代码。在将其暴露到你的网络之前，请先阅读 SAFETY.zh.md，并且只信任你自己控制的主机。

本 fork 的改动

上游默认只绑定 127.0.0.1，并有意拒绝局域网与代理访问。本 fork 保留上游的安全模型，但将其改为声明式：

- 局域网访问（http://<你的IP>:3080）：通过显式的受信主机白名单（DSH_TRUSTED_HOSTS）实现，而不是硬编码的 403 拒绝。
- 反向代理支持（Nginx、Caddy、Traefik、Cloudflare Tunnel）：代理转发 X-Forwarded-Host / X-Forwarded-Proto 后，信任栅栏与会话 Cookie 会跟随浏览器所见的权威地址。
- 设置界面解锁：来自受信主机的客户端也能使用设置面板——不再局限于 localhost。
- 内置动态端口反向代理（/proxy/<端口>/）：通过 DSH 单一暴露端口，直接在浏览器中访问与预览 agent 在内部任意端口启动的开发服务器（如 http://<服务器IP>:3080/proxy/8210/、5173、3000），无需在 Docker 中映射额外端口。
- 容器内无头浏览器与视觉自检：Docker 镜像预装了 Chromium、系统图形库与 Playwright，支持 agent 原生运行无头浏览器、截取 WebGL 渲染图并在对话中完成视觉自验。
- Docker 原生插件管理：pnpm 已预装，其存储区持久化在 /data 卷上。
- 结构化诊断：被拒绝的请求会在 docker compose logs 中输出精确且不含凭据的原因（untrusted host "…"、origin mismatch (…)、session cookie expired at …）。
- 默认拒绝遥测：OTel 会话遥测、桌面产品埋点，以及随官方 DeepSeek API 请求携带的非推理元数据（dsh_session_log、dsh_plugin_packages）全部默认关闭，且不内置任何收集器地址。每项都有显式的选择加入变量，而 DSH_TELEMETRY_DISABLED 会覆盖全部。参见遥测与隐私。
- 西班牙语界面：Web 界面提供英文、中文与西班牙语。它会跟随浏览器语言，也可在设置中固定选择。

其余一切——agent 循环、插件、会话存储——都是未修改的上游代码。

运行

使用 Docker 运行

参见上文的快速开始（Docker）。

从源码运行

参见下文的从源码运行（无 Docker）。

快速开始（Docker）

环境要求：Docker Engine 24+ 与 Docker Compose v2。

git clone https://github.com/samuelrubiodev/deepseek-harness-community.git
cd deepseek-harness-community
cp .env.example .env
docker compose up -d --build

打开 http://<服务器IP>:3080，在引导对话框中填入你的 DEEPSEEK_API_KEY（也可先在 .env 中设置）。首次构建会编译 TypeScript monorepo，需要几分钟；之后的启动是即时的。

不想自行构建？fork 在 ghcr.io/samuelrubiodev/deepseek-harness-community 发布多架构（amd64/arm64）镜像至 GitHub Container Registry (GHCR)，包含标签 :stable（最新发布版本）、:latest（master 默认分支的最新构建）以及 :dsh-v<version>（固定的具体发布版本，如 dsh-v0.1.7-alpha.2-community.1）；deploy/nas/ 中的模板直接匿名拉取，无需登录、检出或构建——面向 NAS（Synology、Unraid、TrueNAS）与服务器。

两个卷在升级与容器重建后保留全部状态：

| 卷 | 挂载点 | 内容 |
| dsh-data | /data | $DSH_HOME：会话、profile、插件、凭据、设置 |
| dsh-workspace | /workspace | agent 的工作目录与你的项目 |

检查健康状态与日志（期望 Up (healthy)）：

docker compose ps
docker compose logs -f harness

如果在 NAS（Synology、Unraid、TrueNAS）或缺少构建工具链的服务器上运行，请使用 deploy/nas/ 中的模板并加载预构建镜像。日常运维——/data 备份、恢复、更新锚定与回滚——已脚本化于 deploy/operations/。

配置

所有配置项都是环境变量，在 .env.example 中有详尽说明。将其复制为 .env，然后用 docker compose up -d 重启。

| 变量 | 默认值 | 用途 |
| DSH_HOST | 0.0.0.0 | 服务器在容器内绑定的网络接口。 |
| DSH_PORT | 3080 | 监听端口（Compose 同时映射该端口）。 |
| DSH_TRUSTED_HOSTS | （空） | 允许访问 Web UI 的主机名/IP 白名单，如 192.168.1.50,harness.lan。携带其他 Host 头的请求会得到 403。 |
| DSH_REVERSE_PROXY | false | 在 Nginx/Caddy/Traefik/隧道后设为 true：代理的 X-Forwarded-Host / X-Forwarded-Proto 随即决定信任与 Cookie 权威。 |
| DSH_AUTH_MODE | token | token：登录需携带 /?token=…。none：无 token 无 Cookie——仅由 DSH_TRUSTED_HOSTS 把关（见下文）。 |
| DSH_AUTH_TOKEN | （空） | 固定登录令牌，取代随每次启动随机的启动令牌，使你的 URL 在重启后依然有效。 |
| DEEPSEEK_API_KEY | （空） | DeepSeek API 密钥；也可在 Web UI 中输入。 |
| DSH_HOME | /data | 容器内的持久状态根目录。 |

DSH_ 变量属于进程级引导配置：Compose 以原生方式注入它们，分层环境加载器会拒绝工作区 .env 文件中的此类变量——请放在仓库根目录的 .env（或 Compose 的 environment: 块）中，绝不放入 /workspace/.env。

局域网访问

把用户在浏览器中输入的每个地址加入 DSH_TRUSTED_HOSTS，然后重启：

DSH_TRUSTED_HOSTS=192.168.1.50,harness.lan docker compose up -d

该列表中的主机还能使用 Web UI 中持久的设置面板。

登录令牌

默认情况下，每次启动都会生成随机启动令牌并打印 http://<host>:<port>/?token=…——每次重启都要从日志里找它。两种不再找它的方式：设置固定令牌（登录链接从此不再改变），或完全不用令牌（信任白名单内的任何主机直接访问 UI）：

1. Stable URL: set your own token once; the sign-in link never changes again.
DSH_AUTH_TOKEN=my-long-random-secret docker compose up -d
open http://192.168.1.50:3080/?token=my-long-random-secret

2. No token at all: any host on the trust fence reaches the UI directly.
DSH_AUTH_MODE=none docker compose up -d

设为 DSH_AUTH_MODE=none 后，凡是地址通过 DSH_TRUSTED_HOSTS 的机器都能访问 Web UI——包括 agent 的代码执行工具。仅在你完全掌控的网络中使用；Host/Origin 信任栅栏（上一节）在任一模式下都仍然生效，且本 fork 的 Docker 镜像在该模式关闭时会在启动日志中打印警告。

反向代理

针对 Nginx、Caddy、Traefik 与 Cloudflare Tunnel 的参考配置（含 TLS 终结、WebSocket 透传 /api/remote.mux、为流式输出关闭缓冲、长超时）位于 deploy/reverse-proxy/。任何代理的最低要求：

1. 设置 DSH_REVERSE_PROXY=true，并把公开主机名加入 DSH_TRUSTED_HOSTS。
2. 转发 X-Forwarded-Host: $host 与 X-Forwarded-Proto: https（在终结 TLS 的代理上）。
3. 传递 Upgrade / Connection 头，并关闭响应缓冲。

遥测与隐私

除非你主动选择加入，否则不会有任何数据离开你的部署。每条遥测通道以及随官方 DeepSeek API 请求携带的每项非推理贡献都默认拒绝，且不内置任何收集器地址。

| 变量 | 默认值 | 用途 |
| DSH_TELEMETRY_ENABLED | （空）* | 选择加入 OpenTelemetry 通道。会话遥测还需要 DSH_TELEMETRY_MODE=FEEDBACK_ONLY 与 DSH_TELEMETRY_OTLP_URL；桌面产品埋点还需要 DSH_PRODUCT_ANALYTICS_OTLP_URL。 |
| DSH_TELEMETRY_MODE | DISABLED | 会话遥测共享策略。FEEDBACK_ONLY 仅在新的显式反馈后释放规范会话前缀；FULL 会被拒绝。 |
| DSH_TELEMETRY_OTLP_URL | （空） | 会话遥测的 OTLP 日志端点。上传模式必须提供；已选择加入却缺少它时会在加载时失败。 |
| DSH_PRODUCT_ANALYTICS_OTLP_URL | （空） | 桌面产品埋点的 OTLP 日志端点。 |
| DSH_SESSION_LOG_UPLOAD | （空） | 选择加入：将规范会话日志附加到官方 DeepSeek API 请求。 |
| DSH_PLUGIN_INVENTORY_UPLOAD | （空） | 选择加入：将已安装插件清单附加到官方 DeepSeek API 请求。 |
| DSH_TELEMETRY_DISABLED | （空） | 覆盖上述所有选择加入项。任何非空值都拒绝，包括 0 和 false。 |

DeepSeek 推理路径不受影响：无论是否启用遥测，api.deepseek.com 请求、harness 身份请求头与 user-agent 的行为都相同。

升级

./scripts/sync-upstream.sh --check
./scripts/sync-upstream.sh --merge

同步工具及其冲突解决手册见 deploy/sync/README.md。合并前先固定回滚点并备份数据；合并本身不会触碰 /data：

./deploy/operations/update-image.sh save
./deploy/operations/backup-data.sh --service

构建后重建容器（docker compose up -d --build）；若新镜像行为异常，用 ./deploy/operations/update-image.sh rollback 把标签切回。完整的更新、备份、恢复与回滚流程（以及 NAS 部署模板）见 deploy/operations/README.md。

从源码运行（无 Docker）

与上游相同的环境要求：Node.js ^22.19 或 24，以及 pnpm 11。

pnpm install
pnpm run build
DSH_HOST=0.0.0.0 DSH_TRUSTED_HOSTS=192.168.1.50 pnpm dsh web --no-open

--host 0.0.0.0 会打印一条安全警告并绑定所有网络接口；配合 DSH_TRUSTED_HOSTS 决定谁可以连接。

故障排查

先从日志读取拒绝原因——每个 403/401 都会说明确切原因：

| 日志消息 | 原因 | 解决办法 |
| untrusted host "…", trustedHosts: (…) | Host 头不在白名单中 | 把该主机加入 DSH_TRUSTED_HOSTS 并重启 |
| origin mismatch ("https://…" vs "http://…") | 代理终结了 TLS 但未转发 X-Forwarded-Proto | 设置 proxy_set_header X-Forwarded-Proto https; |
| session cookie authority mismatch | Cookie 是为不同的主机/端口签发的 | 通过同一代理权威重新打开启动 URL |
| session cookie expired at … | 30 天 Cookie 有效期已过 | 重新打开 dsh web 打印的 URL 重新认证 |

健康检查：容器探测 http://127.0.0.1:<port>/，把 200/303/401 都视为健康——401 是预期的未认证质询，证明 HTTP 服务器与 Cordis 运行时存活。

仓库结构（fork 特有）

docker/ Dockerfile, entrypoint, healthcheck, Cordis bind patch
docker-compose.yml Production-ready orchestrator (uses .env)
.env.example Exhaustive declarative configuration template
deploy/reverse-proxy/ Reference Nginx / Caddy / Traefik / Tunnel configs
deploy/nas/ Synology / Unraid / TrueNAS / server Compose templates
deploy/operations/ Backup, restore, update and rollback scripts and guide
deploy/sync/ Upstream sync runbook
scripts/sync-upstream.sh Automated upstream merge with conflict simulation
.github/workflows/docker-publish.yml Multi-arch image publishing to GHCR
deploy/lab/ Reproducible test lab (proxy scenarios, WebSockets, SSL)

上游的 packages/、apps/ 与文档均未修改，仅上文描述的受信主机、反向代理与诊断特性除外。

社区与支持

- 通过 GitHub Discussions 提交反馈或 bug 报告。fork 特有的问题请提交到本仓库的 issues。
- 为你的插件仓库添加 dsh-plugin 话题，便于被发现。
- 欢迎加入 DeepSeek Harness 企微群！扫描下方二维码填写入群问卷，小助手会定期发送入群邀请。

入群问卷微信公众号

参与贡献

参见 CONTRIBUTING.md。

开发

请先阅读开发指南与架构文档。

pnpm run dev:web 会在一个终端里完成构建、启动，并在源码修改时重建 client bundle；make help 列出 Web 与 Desktop 对应的 Make target。完整表格见开发指南的「应用命令」一节。

面向 agent：请遵循 AGENTS.md。

引用

@misc{deepseek-harness2026,
title={DeepSeek Harness: Everything is a Plugin},
author={DeepSeek-AI},
year={2026},
publisher={GitHub},
howpublished=},
}

许可证

MIT，与上游一致。第三方声明：THIRD_PARTY_NOTICES.md。