DeepSeek Harness (dsh) 部署运维实践

1. 概述

DeepSeek Harness（dsh）是 DeepSeek 官方开源的 agent 框架（智能体），以 Web UI 模式运行，默认监听 http://127.0.0.1:3080。当前处于开发者预览阶段，版本 0.1.0-rc.6。

2. 官方默认部署方式的缺点

官方 README 提供的启动方式是 npx @deepseek-ai/dsh web，适合快速体验，但作为长期运行存在以下短板：

1. 无进程守护：前台运行，终端关闭或 SSH 断开即停止；进程崩溃不会自动重启，服务器重启后也不会自动拉起。
2. 依赖 npm 临时缓存：npx 将包下载到 npm 缓存目录（cache/_npx/<hash>/），路径带随机 hash、非正式安装位置，npm 清理缓存后服务将无法启动，也不便于固定版本管理。
3. 原生模块编译不可控：dsh 依赖 node-pty 等原生模块，Linux 无预编译产物；npx 安装时若安装脚本被策略跳过（如 npm 的 allow-scripts），会出现 Failed to load native module: pty.node 导致启动即崩溃。
4. 仅本机可访问：默认只监听 127.0.0.1:3080，且官方禁止 --host 0.0.0.0（安全考虑），局域网/公网访问必须自行再加一层反向代理。
5. 无任何认证：Web UI 没有登录机制，一旦通过反代暴露到网络，任何人拿到地址即可操作（含命令执行能力），必须自行在外层加认证。

因此本文采用 systemd 托管 + 固定目录安装 的方式补齐这些短板，下文详述。

3. 部署架构

• 进程托管：systemd（服务名 dsh），开机自启、崩溃自动重启
• 可执行文件：固定目录安装的 dsh 包（/opt/dsh/node_modules/.bin/dsh）
• 监听地址：127.0.0.1:3080（仅回环，官方安全限制禁止 0.0.0.0）

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

[Service]
Type=simple
ExecStart=/opt/dsh/node_modules/.bin/dsh web --trusted-host dsh.example.com
Restart=always
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

4. 常用运维命令

systemctl status dsh       # 查看运行状态
systemctl restart dsh      # 重启
systemctl stop dsh         # 停止
systemctl start dsh        # 启动
journalctl -u dsh -f       # 实时查看日志

5. 访问方式

5.1 nginx 反向代理

dsh 官方刻意禁用 --host 0.0.0.0（安全原因：其远程执行能力不可直接暴露网络），对外访问必须走反向代理。示例（443 HTTPS + WebSocket）：

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

    ssl_certificate     /etc/nginx/certs/dsh.example.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/dsh.example.com/privkey.pem;

    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-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }
}

6. 已知问题与注意事项

1. 固定目录部署：dsh 安装于 /opt/dsh（npm i --prefix），不依赖 npm 临时缓存，清理缓存不影响运行。
2. node-pty 原生模块：安装时若 npm 的 allow-scripts 策略跳过 node-pty 的 install 脚本，Linux 将缺少 pty.node 产物（仅有 darwin/win32 prebuild）。此时 Web UI 可正常运行，但使用终端/子进程功能会报 Failed to load native module: pty.node，到对应 node-pty 目录执行 npm rebuild 编译修复（依赖 python3/make/g++）。
3. 版本迭代快：开发者预览阶段，升级可能破坏兼容性，建议固定版本运行。
4. 访问本地化：127.0.0.1:3080 在任意电脑上均指向该电脑自身回环地址；若发现"局域网电脑能访问"，通常是端口转发或该电脑自身有其他程序占用 3080 所致。
5. 浏览器安全上下文：Web UI 前端依赖 crypto.randomUUID()，仅 HTTPS 或 localhost 下可用。非 HTTPS 访问时添加工作区会报 crypto.randomUUID is not a function——必须走 HTTPS 或浏览器 flag 临时放行。

7. 升级 dsh

在安装目录原地更新，无需借助 npx 缓存：

cd /opt/dsh
npm i --prefix /opt/dsh @deepseek-ai/dsh@latest   # 更新到最新版

# 或锁定指定版本
npm i --prefix /opt/dsh @deepseek-ai/dsh@0.1.0-rc.6

systemctl restart dsh
systemctl status dsh

注意事项：

• 不建议 npx + 复制缓存方式：npx 会优先复用旧缓存不拉新版，且只复制主包会破坏依赖树。
• 安装后若报 pty.node 错误，到 node-pty 目录执行 npm rebuild。
• 服务配置（--trusted-host）及 Web UI 中的模型/工作区配置保存在服务端目录，升级不会覆盖。
• 预览期存在破坏性变更，升级前留意官方 release 说明。

8. 公网访问架构

dsh 仅监听 127.0.0.1，公网访问需在外层提供入口，常见方案：

博主实例采用 DDNS + 端口转发 组合（公网域名 → 边缘加速 → 网关 DDNS IPv6 回源 → 端口转发 801/4431 → nginx 反代 → dsh），内网主机仅暴露两个反代端口，dsh 本体不直接暴露到公网。

9. 安全加固

已实施：nginx Basic Auth

访问需输入认证信息，否则返回 401：

• 认证文件：/opt/dsh/.htpasswd（账号与密码部署时自行生成，切勿公开）
• nginx 配置：#BASICAUTH 区块

#BASICAUTH START
auth_basic "dsh restricted";
auth_basic_user_file /opt/dsh/.htpasswd;
#BASICAUTH END

权限要求：.htpasswd 必须为 nginx 运行用户可读，否则报 Permission denied 导致 500：

chown www:www /opt/dsh/.htpasswd && chmod 640 /opt/dsh/.htpasswd

修改密码：

printf "user:%s\n" "$(openssl passwd -apr1 '新密码')" > /opt/dsh/.htpasswd
chown www:www /opt/dsh/.htpasswd && chmod 640 /opt/dsh/.htpasswd

建议：CDN 控制台加固

• IP 白名单：访问控制中只放行常用 IP（注意宽带动态 IP，配合 DDNS 或频控）。
• WAF 规则：开启对敏感路径的拦截。
• 清理缓存：改动后若公网访问异常，到控制台清缓存（401/500 可能被 CDN 缓存）。