Skip to main content

DeepSeek Harness 部署方案

已确认项目身份与全部部署参数（官方仓库、npm 版本、Node 要求、启动参数、凭据解析）。以下是 Ubuntu 24.04 的部署方案：

项目与最新版本

  • DeepSeek Harness（dsh）：DeepSeek 官方开源 agent 框架，采用“一切皆插件”架构（基于 Cordis）。仓库：deepseek-ai/deepseek-harness，文档：官方文档站。
  • 最新版本：npm latest = 0.1.5-rc.1（2026-09-10 发布）；next 通道 = 0.1.5-rc.2（最新）。处于开发者预览阶段，会有破坏兼容性的变更，部署时建议钉住版本号。
  • 运行要求：Node.js ^22.19.0 || >=24.0.0（package.json engines），Ubuntu 24.04 上推荐 Node 24 LTS。
  • 默认端口：http://127.0.0.1:3080。

推荐部署形态

  • npm 全局安装 + systemd 守护：dsh web 本身只监听本机，适合再套一层 nginx 反代 + HTTPS。
  • 不建议用 Docker：官方维护者指出容器路线有已知坑（pnpm 符号链接、node-pty 等原生模块与 musl/glibc、profile patch 被卷挂载覆盖），npm 直装最稳。
  • 生产建议：127.0.0.1 回环绑定（webserver 无内置 TLS/鉴权），远程访问走 SSH 隧道或 nginx+HTTPS。

部署步骤

1. 前置准备（Ubuntu 24.04）

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl ca-certificates git ufw
# 全程用非 root 的 sudo 用户执行

2. 安装 Node.js 24 LTS（NodeSource）

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node -v   # 必须 >= v22.19，推荐 v24.x
npm -v

3. 创建运行用户与工作区目录

sudo useradd --system --create-home --shell /usr/sbin/nologin dsh
sudo mkdir -p /srv/dsh/workspace
sudo chown -R dsh:dsh /srv/dsh
# 启动时所在目录 = 默认 workspace 根目录（Web UI 里还需手动“选择工作区”）

4. 全局安装 DeepSeek Harness（钉住版本）

sudo npm install -g @deepseek-ai/dsh@0.1.5-rc.1
dsh --version        # 预期 0.1.5-rc.1
dsh --help

想用最新 rc.2 就装 @deepseek-ai/dsh@0.1.5-rc.2。CLI 参数：dsh --profile web（web 是别名），web 应用参数需放在其后：--host（仅 127.0.0.1/0.0.0.0）、--port、可重复的 --trusted-host、--no-open。

5. 配置 DeepSeek API Key（无交互方式）

凭据解析顺序：进程环境变量 → $DSH_HOME/.credentials.yaml → 调用目录 .env → $DSH_HOME/.env（$DSH_HOME 默认 ~/.dsh）。Web 搜索使用 DEEPSEEK_API_KEY。推荐直接在 systemd 里注入环境变量（第 6 步会用）。

手动方式也可以：启动后浏览器打开 http://127.0.0.1:3080 → 设置 → 模型 → DeepSeek 卡片填 Key（密钥只写，存于 $DSH_HOME/.credentials.yaml）。模型变更立即生效，无需重启。

6. systemd 服务

# /etc/systemd/system/dsh.service
[Unit]
Description=DeepSeek Harness Web UI
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=dsh
Group=dsh
WorkingDirectory=/srv/dsh/workspace
Environment=DSH_HOME=/home/dsh/.dsh
Environment=DEEPSEEK_API_KEY=sk-你的密钥
ExecStart=/usr/bin/dsh web --no-open --host 127.0.0.1 --port 3080
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now dsh
journalctl -u dsh -f          # 观察 "dsh web:" URL 行（内含进程 token，属敏感信息）
curl -sI http://127.0.0.1:3080/ | head -1   # 预期 HTTP/1.1 200

若 dsh 不在 /usr/bin，用 which dsh 修正 ExecStart。

7.（可选）nginx 反代 + HTTPS（远程访问必做）

# /etc/nginx/sites-available/dsh
server {
    listen 80;
    server_name dsh.example.com;
    location / {
        proxy_pass http://127.0.0.1:3080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;      # WebSocket 必需
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
sudo ln -s /etc/nginx/sites-available/dsh /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d dsh.example.com

浏览器同源策略要求：反代后需把域名加入可信主机，否则 WebSocket 连不上 → 在服务参数追加 --trusted-host dsh.example.com（重启生效）。需要登录密码可选装社区插件 dsh-webui-auth；自己只想内网用的也可以不加反代，直接 ssh -L 3080:127.0.0.1:3080 user@server 隧道访问。

8. 防火墙与验收

sudo ufw allow OpenSSH && sudo ufw allow 80/tcp && sudo ufw allow 443/tcp && sudo ufw enable

验收：浏览器打开 https://dsh.example.com → 设置→模型配 Key → 选择工作区 → 发一条任务（例如“Summarize this repository”）→ 确认能读文件、跑命令、委派子任务。

运维与注意事项

  • 升级：开发者预览迭代快，升级前备份整个 $DSH_HOME（settings.yaml、.credentials.yaml、profiles/、会话库），再 sudo npm install -g @deepseek-ai/dsh@<新版本>；先看 npm 发布说明和 SAFETY.md。
  • 安全：保持回环绑定；启动 URL 里的进程 token 是 API/WebSocket 的认证凭据，注意别把完整 URL 打进日志/截图；密钥只写入 $DSH_HOME/.credentials.yaml，建议 chmod 600；0.0.0.0 直绑无 TLS 无鉴权，谨慎。
  • 扩展：一次性任务用 dsh --profile headless "任务文本"；插件管理 dsh plugin --profile web add <包>（需 pnpm，sudo corepack enable && corepack prepare pnpm@latest --activate）；国内网络需代理时见文档 network-proxy。

现状确认：服务器没有 pnpm（需要用 corepack/npm 启用），dsh plugin 必须带 --profile。给你一套可直接照抄的完整示例——以官方插件 Codex 子代理（@deepseek-ai/dsh-subagent-codex） 为例：

第一步：装 pnpm（dsh 插件管理依赖它）

sudo npm install -g pnpm@11.7.0     # 项目本身用的 pnpm 11.7.0
pnpm --version                       # 验证

第二步：安装插件到 web 配置

sudo -u dsh /usr/bin/dsh plugin --profile web add @deepseek-ai/dsh-subagent-codex

要点：

  • 必须用 sudo -u dsh 跑（profile 在 /home/dsh/.dsh/profiles/web 下，以 dsh 用户运行才能读到正确的 DSH_HOME）
  • --profile web 指定装到哪个配置（还有 headless、sdk、acp 或自定义 profile）
  • 该命令等价于在该 profile 目录里执行 pnpm add，装完会自动把包写进 dsh.profile.bundles（因为包的 package.json 声明了 "dsh": {"bundle": {"patch": "./cordis.patch.yml"}}）

第三步：重启服务让新 bundle 挂载

sudo systemctl restart dsh
dsh-url        # 重启后 token 变了，取新访问地址

第四步：验证

sudo -u dsh /usr/bin/dsh plugin --profile web list        # 已安装列表
sudo -u dsh env DSH_HOME=/home/dsh/.dsh /usr/bin/dsh --profile web --dump-config | grep -i subagent

Web UI 里新建会话后，Agent 面板会出现 Codex 子代理提供方（实际可用还要求服务器上装了 Codex CLI 并完成登录）。

其他“装插件”的形态（顺带说明）

  • 移除：sudo -u dsh /usr/bin/dsh plugin --profile web remove @deepseek-ai/dsh-subagent-codex，然后重启
  • 本地/社区插件：... plugin --profile web add <npm包名>，或本地目录 ... add /path/to/plugin（GitHub 上带 dsh-plugin topic 的都是生态插件）
  • 可选覆盖层（非 npm 包）：官方 config/examples/ 里的 github-review、schedule、mcp-memory 是 cordis patch 文件，用 dsh --profile web --patch ./xx.yml 或写入 cordis.patch.yml，不需要 pnpm

需要我直接在服务器上把 pnpm 和这个 Codex 子代理插件装上吗？装完我会重启并给你新的访问地址。

Back to top