DeepSeek Harness 部署指南：从一行命令到 Linux 服务器上线

文章目录

• DeepSeek Harness 部署指南：从一行命令到 Linux 服务器上线
• • 一、部署前准备
  • 二、最快路径：npx 启动 Web UI
  • 三、源码部署：适合二次开发和插件开发
  • 四、无头模式：一条命令跑任务
  • 五、Linux 服务器上线
  • • 1. 创建专用用户和目录
    • 2. 安装并配置环境变量
    • 3. systemd 托管
    • 4. Nginx 反向代理
  • 六、上线前的备份和更新
  • 七、常用环境变量
  • 八、部署清单
  • 九、常见问题
  • • 启动后打不开页面？
    • 模型提示 `MISSING_CREDENTIAL`？
    • 提示 `UNKNOWN_MODEL`？
    • 能用其他模型吗？
    • 为什么不能 `–host 0.0.0.0`？
  • 参考资料

DeepSeek Harness 部署指南：从一行命令到 Linux 服务器上线

DeepSeek Harness（dsh）是 DeepSeek AI 官方开源的 agent harness，主打“一切皆插件”的架构，底层由 Cordis 驱动，采用 MIT 协议。它目前处于开发者预览阶段，版本迭代很快，官方明确提示后续会有破坏兼容性的变更。

这篇文章按四条路径写：npx 快速体验、源码部署、无头任务模式、Linux 服务器上线，最后给部署清单和常见问题。

一、部署前准备

先确认本机环境：

检查版本：

node -v
npm -v

如果你要跑源码或开发插件，再检查：

corepack enable
corepack prepare pnpm@11.7.0 –activate
pnpm -v

二、最快路径：npx 启动 Web UI

官方推荐的第一条命令：

npx @deepseek-ai/dsh web

首次运行会通过 npm 下载 @deepseek-ai/dsh，并自动初始化 web profile。默认监听地址是：

http://127.0.0.1:3080

浏览器打开后，完成三步即可跑第一个任务：

模型密钥保存在 $DSH_HOME/.credentials.yaml 中，Web UI 只展示脱敏描述符，不会回显明文。密钥保存后不需要重启服务。

如果 3080 端口被占用，换一个端口：

npx @deepseek-ai/dsh web –port 8080

长期使用建议全局安装，避免每次走 npx：

npm install -g @deepseek-ai/dsh
dsh –version
dsh web

三、源码部署：适合二次开发和插件开发

如果你要读源码、改插件或调试，从仓库运行：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

注意两点：

• 源码运行必须先执行 pnpm run build，仓库不会在启动时自动构建前端产物。
• package.json 里的 pnpm dsh 是源码入口，不是编译后的二进制。

源码部署后同样可以指定端口：

pnpm dsh web –port 8080

查看 Web UI 支持哪些启动参数：

pnpm dsh web –help

四、无头模式：一条命令跑任务

不需要浏览器时，用 headless profile 跑一次性任务。它不会监听端口，把最终答案打到 stdout，任务正常完成以 0 退出，否则以 1 退出，适合接 CI：

export DEEPSEEK_API_KEY=sk-your-key-here
dsh –profile headless "run the tests"

任务文本必须作为位置参数直接跟在命令后面，headless profile 不接受 Web UI 的 –port 等参数：

dsh –profile headless "Inspect the repository and fix the failing tests."

排查组合配置时不启动服务，可以打印配置树：

dsh –profile web –dump-default-config
dsh –profile web –patch ./extra.yml –dump-config

安装第三方插件也走 CLI：

dsh plugin –profile web add <package-or-git-spec>

插件管理命令会把参数转发给 pnpm，因此机器上需要安装 pnpm。Git 托管的插件如果带 prepare 构建脚本，第一次安装可能需要按提示在 pnpm-workspace.yaml 中允许对应构建脚本。

五、Linux 服务器上线

DeepSeek Harness 的 Web 服务器本身不提供 TLS、认证或来源策略。官方在 CLI 层故意拒绝 –host 0.0.0.0，就是为了避免把远程代码执行能力直接暴露到网络。生产部署的正确姿势是：服务只监听回环地址，前面放 HTTPS 反向代理，再加一层认证。

1. 创建专用用户和目录

sudo useradd –system –create-home –home-dir /var/lib/dsh dsh
sudo mkdir -p /srv/dsh-workspace
sudo chown -R dsh:dsh /srv/dsh-workspace /var/lib/dsh

2. 安装并配置环境变量

sudo npm install -g @deepseek-ai/dsh
which dsh

把密钥和配置目录写进 environment file，权限收紧：

sudo tee /etc/dsh.env > /dev/null <<'EOF'
DSH_HOME=/var/lib/dsh
DEEPSEEK_API_KEY=sk-your-key-here
EOF
sudo chmod 600 /etc/dsh.env

如果走 OpenAI 兼容网关，再加：

DEEPSEEK_BASE_URL=https://your-gateway.example/v1

3. systemd 托管

假设 dsh 安装在 /usr/local/bin/dsh，–trusted-host 填你的访问域名：

[Unit]
Description=DeepSeek Harness Web
After=network-online.target

[Service]
User=dsh
Group=dsh
WorkingDirectory=/srv/dsh-workspace
EnvironmentFile=/etc/dsh.env
ExecStart=/usr/local/bin/dsh web –port 3080 –trusted-host dsh.example.com
Restart=on-failure
RestartSec=5
TimeoutStopSec=10
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

写入并启动：

sudo nano /etc/systemd/system/dsh-web.service
# 保存上面的 systemd 配置后执行：
sudo systemctl daemon-reload
sudo systemctl enable –now dsh-web
sudo systemctl status dsh-web

说明：

• –trusted-host 用于把浏览器访问的域名加入 /api 信任围栏，可重复传入，例如 –trusted-host dsh.example.com。
• 不要改成 –host 0.0.0.0，CLI 会拒绝，这是安全设计。
• WorkingDirectory 是 agent 的默认 workspace，务必是专门目录。

4. Nginx 反向代理

server {
listen 443 ssl http2;
server_name dsh.example.com;

ssl_certificate /etc/letsencrypt/live/dsh.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/dsh.example.com/privkey.pem;

auth_basic "dsh";
auth_basic_user_file /etc/nginx/.dsh_htpasswd;

location / {
proxy_pass http://127.0.0.1:3080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-Forwarded-Proto $scheme;
}
}

要点：

• Web UI 需要 WebSocket/Upgrade，反向代理必须转发 Upgrade 和 Connection。
• 没有内置认证，务必在代理层加 Basic Auth、SSO 或只允许内网 IP。
• 证书申请推荐 certbot，这里只展示 Nginx 配置骨架。

六、上线前的备份和更新

至少备份整个 $DSH_HOME，里面包含密钥文件、settings、profiles 和会话数据：

sudo tar czf /backup/dsh-$(date +%F).tar.gz /var/lib/dsh

更新策略：

sudo npm update -g @deepseek-ai/dsh
sudo systemctl restart dsh-web

源码部署则执行：

git pull
pnpm install
pnpm run build
sudo systemctl restart dsh-web

因为当前是开发者预览，升级前先看官方发布说明和 Discussions，确认没有破坏性变更后再更新；更新前先备份。

七、常用环境变量

八、部署清单

• Node.js 版本符合 ^22.19.0 或 >=24.0.0
• 有 DeepSeek API Key
• 使用独立 workspace 目录
• dsh web 能启动，默认地址可访问
• 模型密钥已配置，能跑通一个任务
• 生产环境只监听 127.0.0.1
• 反向代理已启用 HTTPS
• 代理层有认证或访问限制
• –trusted-host 已配置访问域名
• systemd 开机自启和失败重启正常
• $DSH_HOME 已加入备份
• 升级前阅读发布说明

九、常见问题

启动后打不开页面？

默认地址是 http://127.0.0.1:3080。确认进程还在运行，端口没被占用；端口冲突时用 dsh web –port 8080。

模型提示 MISSING_CREDENTIAL？

到“设置 → 模型”保存 API Key，或确认 DEEPSEEK_API_KEY 环境变量已设置。密钥解析顺序是环境变量、$DSH_HOME/.credentials.yaml、调用目录 .env、$DSH_HOME/.env。

提示 UNKNOWN_MODEL？

在模型设置里选择已配置的模型；自定义 OpenAI 兼容端点需要手动补上模型 id。

能用其他模型吗？

可以。Web UI 的“添加提供方”支持 Anthropic、OpenAI 等已安装目录，“添加自定义提供方”支持任意 OpenAI 兼容端点。Bedrock、Vertex、Azure、Codex 需要各自的原生凭据。

为什么不能 –host 0.0.0.0？

CLI 有意拒绝，因为 Web UI 会执行代码、改文件、跑命令，直接绑全网卡等于把远程代码执行暴露到网络。生产环境应保持回环监听，用反向代理转发。

参考资料

• 官方仓库：https://github.com/deepseek-ai/deepseek-harness
• 中文 README：https://github.com/deepseek-ai/deepseek-harness/blob/master/README.zh.md
• Web UI 指南：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/index.zh.md
• 模型配置指南：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.zh.md
• CLI 行为参考：https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.zh.md

本文基于 DeepSeek Harness 0.1.0-rc.x 官方文档整理，整理日期 2026-08-15。项目处于开发者预览，命令和配置可能随版本变化。