ghisgit/deepseek-harness-deploy

DeepSeek Harness — Docker Compose 部署

基于 Debian 的 Docker 部署方案，用于运行 DeepSeek Harness（dsh）
的 web 模式，并将数据持久化在宿主机上。

DeepSeek Harness 是 DeepSeek 开源的 agent harness：一种一切皆插件的架构，
由 Cordis 驱动。该镜像会构建 Node.js CLI
（@deepseek-ai/dsh）并运行 dsh web，默认在端口 3080 上提供 Web UI。

开发者预览版。 DeepSeek Harness 迭代迅速，会引入
破坏兼容性的变更。请将 DSH_VERSION 固定到特定版本，以便
稳定地升级/回滚。

目录结构

| 本地路径 | 容器路径 | 用途 |
|---|---|---|
| dsh/ | /data/.dsh | Harness 主目录：profiles、cordis.patch.yml、settings.yaml、.credentials.yaml、.env、storages、.agent-presets |
| data/ | 逐文件挂载（见下文） | 你希望容器主目录中可用的其他项目文件 |
| workspace/ | /workspace | web 会话的工作目录 |
| entrypoint.sh | /entrypoint.sh（已烘焙进镜像） | 创建主目录、映射 PUID/PGID 用户、修复所有权、生成 $DSH_HOME/cordis.patch.yml、降权运行 |

安全性

Web UI 不包含 TLS 或身份验证，并且 DeepSeek Harness agent
会在工作区中执行任意代码。因此 compose 文件默认
仅发布到宿主机回环地址（127.0.0.1:3080）：

- 对于纯本地/SSH 转发的场景，保持 BIND_ADDRESS=127.0.0.1。
- 若要将其暴露到受信任的网络，请设置 BIND_ADDRESS=0.0.0.0，并在其前面
放置一个真正的反向代理（TLS + 认证）。如果没有反向代理，任何能连接的人
都可以触达 agent 的代码执行。

请注意，dsh CLI 会有意拒绝 --host 0.0.0.0；本镜像
通过文档化的部署通道启用全接口绑定——即由 entrypoint.sh 在首次启动时
生成的 Harness 主目录 cordis.patch.yml
（参见网络）。/api 浏览器信任防护仍然要求
回环 Host 或已命名的 DSH_TRUSTED_HOSTS 授权。

快速开始

1. （可选）复制并调整环境文件：

cp .env.example .env

.env 是可选的——不存在时会应用合理的默认值。如果存在，
请将 PUID/PGID 设置为与你的宿主机用户匹配（id -u / id -g），
以便持久化文件保持正确的所有权。

注意：可选的 env_file 需要 Docker Compose v2.24+。

2. 启动：

docker compose up -d

默认情况下，这会从 GHCR 拉取预构建镜像（见下文）。若要改为
在本地构建镜像，请将 docker-compose.override.example.yml 复制为
docker-compose.override.yml——其模板包含 build 块，并使用一个单独的本地名称
（deepseek-harness-deploy:local，参见 DSH_LOCAL_IMAGE）为结果打标签，
因此它绝不会与云端镜像混淆。

3. 打开 http://127.0.0.1:3080。
4. 配置模型：打开 Settings → Models，输入
DeepSeek API key，然后保存。该密钥
存储在 $DSH_HOME/.credentials.yaml 中。（你也可以在容器环境中传入
DEEPSEEK_API_KEY。）

5. 选择工作区：点击 Choose workspace，然后添加容器的
/workspace 目录。

容器健康检查会探测 Web 根路径；状态在 docker ps 中显示为
(healthy)。

网络

entrypoint.sh 会在首次启动时写入 $DSH_HOME/cordis.patch.yml（仅当该
文件尚不存在时，因此你可以手动编辑它；删除它以重新生成）。
它会：

- 将 Web 服务器绑定到 0.0.0.0，以便 compose 的端口发布能够到达它
（出于安全考虑，dsh web --host 0.0.0.0 会被 CLI 拒绝），
- 使 /api 浏览器信任围栏对 localhost、127.0.0.1
和 [::1] 继续有效，外加 DSH_TRUSTED_HOSTS
中列出的任何额外授权主机（逗号分隔，host 或 host:port）。

如果你通过 BIND_ADDRESS=0.0.0.0 在局域网上暴露该 harness，请将浏览器
实际连接使用的主机名/IP 添加到 DSH_TRUSTED_HOSTS，例如：

DSH_TRUSTED_HOSTS=my-workstation.example.local,10.0.0.5:3080

将文件持久化到容器主目录（/data）

dsh 以 HOME=/data 和 DSH_HOME=/data/.dsh 运行。本地 data/
目录用于将其他项目文件持久化到容器主目录中，例如 .gitconfig 或 .ssh。

不要将整个 data/ 目录挂载到 /data 上——这会遮蔽容器主目录。
而应通过 docker-compose.override.yml 挂载单个文件
（这样 docker-compose.yml 保持不动——Compose 会自动合并 override）。

从已跟踪的模板开始：

cp docker-compose.override.example.yml docker-compose.override.yml

services:
dsh:
volumes:
- ./data/.gitconfig:/data/.gitconfig:ro

每个文件添加一行 volume。对于容器必须能够写入的文件，去掉 :ro 后缀。

docker-compose.override.yml 已被 git 忽略（它引用了诸如
data/.gitconfig 之类的个人文件，这些文件未被跟踪），因此请在本地调整它。
先在 data/ 中创建源文件——如果它不存在，bind mount 会启动失败。

data/ 中的文件会被提交到 git（默认只跟踪 .gitkeep），
而 dsh/ 下的运行时状态则被 git 忽略。

添加插件

树外插件按 profile 使用 dsh plugin 命令安装
（该命令转发到 pnpm，pnpm 已捆绑在镜像中）：

docker compose exec dsh dsh plugin --profile web add

之后重启服务，以便拾取该 profile 的 bundle 集：

docker compose restart dsh

工具链（mise）

Node.js 运行时由 mise 管理，它会将其安装在
/mise 下，并在 PATH 上暴露版本固定的 shim（npm 和 npx
随 Node 发行版一起提供）。pnpm——dsh plugin 会转发到它
— 是通过 npm 全局安装的，而不是通过 mise：mise 的独立 pnpm
构建约为 440MB，而 npm 包约为 20MB，这样可以保持镜像小巧。Web UI 运行在
dsh 所需的 Node 版本上（参见 DSH_NODE）。在容器内，agent 可以使用
mise install / mise use / npm install -g 安装不同的 Node 版本（或任何
npm 包）；/mise 对容器用户可写。

内置用户和 sudo

镜像自带一个默认的 dsh 用户（UID/GID 1000，bash shell，HOME=/data），
该用户是 sudo 组的成员，并拥有免密码 sudo
（/etc/sudoers.d/dsh，NOPASSWD: ALL）。这使得 devcontainers
（"remoteUser": "dsh"）和 docker run --user dsh 开箱即用，并
让 agent 在需要时通过 sudo 提权。

启动时，entrypoint 仍会将用户/组重新映射为 PUID/PGID
（默认为 1000），以便主机上持久化的文件保持正确的
所有权——无需构建参数。

预构建镜像（GHCR）

GitHub Actions 将多架构镜像（linux/amd64、linux/arm64）发布到
ghcr.io/ghisgit/deepseek-harness-deploy。标签：

| 标签 | 含义 |
|---|---|
| latest | 最新构建 |
| （例如 0.1.1-rc.2） | 固定 dsh 版本；稳定，可用于回滚 |
| sha- | 镜像构建所基于的确切 git 提交 |

构建运行时机：

- 每次推送到 main 时
- 通过 Run workflow 手动触发，可选择固定 DSH_VERSION
- 每天 UTC 02:00——当解析出的 dsh 版本已发布时跳过

手动拉取特定版本：

docker pull ghcr.io/ghisgit/deepseek-harness-deploy:

使用 VS Code 进行开发（Dev Containers）

该仓库自带 .devcontainer/devcontainer.json，可将 VS Code 附加到
用于部署的同一个 compose 项目——相同的镜像、卷和
.env 设置。

前提条件：

- VS Code，并安装
Dev Containers
扩展
- Docker Compose v2.24+（用于可选的 env_file，如上所述）

用法：

1. （可选）按照快速开始中的说明创建 .env。
2. 在 VS Code 中打开此文件夹，然后从命令面板（F1）运行
Dev Containers: Reopen in Container。

你将获得：

- 以内置的 dsh 用户在 /workspace 中的 shell/编辑器会话，并
可使用免密码 sudo。
- 正在运行的 dsh Web 服务器可通过 compose 自身的端口发布直接在
http://localhost:${PORT:-3080} 访问——无需
VS Code 端口转发。
- 你的 docker-compose.override.yml 也会被应用——Dev Containers 不会
自动加载它，因此在
.devcontainer/devcontainer.json 中显式引用了它。该文件已被 git 忽略；一个跨平台的
initializeCommand（在 Linux/macOS 主机上为 shell 脚本，在
Windows 上为 .cmd 批处理文件）会在全新克隆时创建一个空占位文件，以便开发容器
开箱即用。
- UID/GID 映射由 PUID/PGID 处理，与正常运行时完全一致；
Dev Containers 自身的 UID 重写已禁用，以避免重复映射。

注意：停止开发容器（例如 Dev Containers: Stop Container）
也会停止 Web 服务器——它们是同一个服务。

配置（.env）

| 变量 | 默认值 | 描述 |
|---|---|---|
| PORT | 3080 | Web 服务器端口（主机:容器） |
| DSH_VERSION | latest | 用于本地镜像构建的 dsh 版本，例如 0.1.1-rc.2 |
| DSH_NODE | 24 | 由 mise 管理的 Node.js 主版本线（例如 24） |
| DSH_PNPM | latest | pnpm 版本，通过 npm 全局安装 |
| DSH_LOCAL_IMAGE | deepseek-harness-deploy:local | 用于本地构建的镜像标签（区别于 ghcr.io/ghisgit/deepseek-harness-deploy:latest 云端镜像） |
| BIND_ADDRESS | 127.0.0.1 | 要发布的主机地址；0.0.0.0 会将 harness 暴露到网络 |
| DSH_TRUSTED_HOSTS | （空） | 额外的 /api 浏览器信任授权（逗号分隔） |
| PUID / PGID | 1000 | 容器运行所使用的主机用户/组 ID |
| DATA_DIR | ./dsh | 存放 Harness 主目录的主机目录（挂载到 /data/.dsh） |
| WORKSPACE | ./workspace | 挂载到 /workspace 的主机目录 |
| DEEPSEEK_API_KEY | （空） | 提供商密钥；也可在 Web UI 中配置 |

许可证

DeepSeek Harness 由 DeepSeek AI 以 MIT 许可证授权；请参阅上游
LICENSE。
第三方依赖及其许可证在上游
THIRD_PARTY_NOTICES.md 中披露。