1、为什么要在博客上部署 DeepSeek Harness#

2026 年 8 月 13 日，DeepSeek Harness 正式发布，正如它的宣传语所说——探索未至之境——上手一试，确实很强：Agent 会话、评测任务管理一应俱全，本地跑起来只能「自己用」，总感觉有点浪费。

于是我就琢磨开了：既然博客就搭在云服务器上，那能不能把 DeepSeek Harness 也部署上去，让它成为我的远程「运维助手」？人在哪儿，助手就在哪儿，浏览器一开就能用。说干就干，这么做的好处其实很实在：

• 家里、公司、出差路上，只要有浏览器就能访问，不用背着开发机跑；
• Agent 长任务（评测、批量跑实验）可以 7×24 小时挂在服务器上跑，不占本地资源；
• 多台设备共享同一个会话历史（session.history），工作记录不丢。

2、踩坑记录：三次典型排障#

问题① 外部可访问但 /api 返回 403 → 添加 --trusted-host#

• 现象：公网访问 DeepSeek Harness Web UI 页面正常（HTML 加载正常），但页面里的 /api 相关请求全部返回 403，功能不可用。浏览器开发者工具（Network 标签）可见大量 /api/* 请求返回 403。

• 根因：DeepSeek Harness 的 trustedHosts（Host 信任）机制会校验请求 Host。公网 Host 是 服务器公网地址:对外端口，不在默认信任列表里，非特权 API 方法被拒绝。

• 修复：

  1. 在 systemd 服务 ExecStart 中追加两个 --trusted-host（带端口与不带端口双形态）：

     1
     dsh web --trusted-host 服务器公网地址:对外端口 --trusted-host 服务器公网地址

  2. 同时 location / 里必须用 proxy_set_header Host $http_host; 保留端口，不能用 $host（会丢弃端口）。因为后端 browser-trust fence 校验 Host 与 Origin 一致性，浏览器 Origin 带端口（服务器公网地址:对外端口），若 Host 无端口仍会 403。

  1
  proxy_set_header Host $http_host;   # ✅ 保留端口
  2
  # proxy_set_header Host $host;      # ❌ $host 不含端口，会丢端口

  3. 改完 service 文件后 systemctl daemon-reload && systemctl restart dsh-web；改完 nginx 配置后 nginx -t && nginx -s reload。

• 验证：非特权 API 请求恢复 200，页面基础功能可用。

问题② 控制台报 crypto.randomUUID is not a function → sub_filter 注入 polyfill#

• 现象：前端控制台（Console）报 Uncaught TypeError: crypto.randomUUID is not a function，页面部分功能（依赖随机 UUID 的逻辑）不可用。

• 根因：部分浏览器环境未实现 crypto.randomUUID，调用即抛 TypeError。

• 修复：用 nginx sub_filter 在返回的 HTML </head> 前注入一个基于 crypto.getRandomValues 的 UUID v4 polyfill（完整代码见第四节 location /）：

  1
  proxy_set_header Accept-Encoding "";   # 必须：让后端返回未压缩 HTML，sub_filter 才能匹配
  2
  sub_filter '</head>' '</head><script>(function(){...})();</script>';
  3
  sub_filter_once on;

  • proxy_set_header Accept-Encoding ""; 是必须的：否则后端返回 gzip 压缩的 HTML，sub_filter 无法匹配到 </head>，注入不生效；
  • sub_filter_once on;：只在第一个 </head> 处注入一次；
  • 不要显式声明 sub_filter_types text/html：会与全局 mime.types 重复定义，产生 nginx -t 警告。

• 验证：polyfill 注入生效，页面无 JS 报错，Console 干净。

问题③ /api/settings.describe 等特权方法仍返回 403 → location /api 伪造回环 Host/Origin#

• 现象：已配置 --trusted-host 后，非特权 API 已恢复 200，但 settings.describe、settings.update、credentials.set 等特权方法仍返回 403，即使带认证凭据访问也一样。

• 根因：DeepSeek Harness 将 settings.describe、settings.update、credentials.set 等敏感 API 注册在 loopback 信任通道（authority: 'loopback'，见 packages/client/connection/src/rpc-host.ts）上，强制要求请求来自回环地址（loopback fence），这是 DeepSeek Harness 的故意安全设计——--trusted-host 只是防止 DNS-rebinding 的 Host 校验，并非认证层，因此无法放行特权方法。要让公网请求通过，必须让后端「以为」请求来自回环。

• 修复：新增独立的 location /api，转发时伪造回环 Host/Origin：

  1
  location /api {
  2
      proxy_pass http://127.0.0.1:后端端口;
  3
  
  4
      # 伪造回环 Host/Origin，使特权方法通过 DeepSeek Harness 回环 fence
  5
      proxy_set_header Host 127.0.0.1:后端端口;
  6
      proxy_set_header Origin http://127.0.0.1:后端端口;
  7
      # ... 其余反代头与 WebSocket 配置同 location /
  8
  }

  • Origin 必须硬编码为 http://127.0.0.1:后端端口 与 Host 保持一致；若用 $http_origin 携带公网原始 Origin，仍会因与 Host 不一致而 403；
  • /api/events.mux、/api/events.host 等 WebSocket 端点也走本 location，loopback 为最高信任，升级握手仍能通过 fence；
  • 权衡：这一步等于绕过了 DeepSeek Harness 内置的回环保护，真实的访问认证完全由 server 级 Basic Auth 承担——即「Basic Auth 是替代认证方案」。安全权衡必须明确记录：一旦凭据泄露，任何通过认证的请求都可调用特权方法，凭据强度就是最后一道防线。

• 验证：浏览器访问 settings.describe、session.history 等请求全部返回 200，页面完整功能可用。

3、方案选择：Nginx 反代 + Basic Auth#

公网 IP + 对外端口 + Basic Auth，由 Nginx 反代到仅监听回环地址的后端 DeepSeek Harness 的 web 服务。

整体架构如下：

1
浏览器 ──► Nginx(服务器公网地址:对外端口) ──反代──► DeepSeek Harness web(127.0.0.1:后端端口)
2
        │                                                       │
3
        └── Basic Auth                                         └── --trusted-host

方案要点：

• 对内：DeepSeek Harness 的 web 服务默认只监听 127.0.0.1:后端端口（有意不支持 --host 0.0.0.0），后端不直接暴露网卡，对外统一交给 Nginx，这个设计其实更安全；
• 对外：Nginx 监听 对外端口，叠加 Basic Auth 做访问认证；

1、克隆官方仓库并固定 commit#

克隆 DeepSeek Harness 官方仓库，并固定到一个已知正常的提交，避免上游漂移导致构建问题：

1
# 克隆自 deepseek-harness 官方仓库，固定提交
2
git clone https://github.com/deepseek-ai/deepseek-harness.git 部署目录/deepseek-harness
3
cd 部署目录/deepseek-harness
4
git checkout 47f943859b    # Merge pull request #2519 from deepseek-harness/feat/npm-public

2、Node 与 pnpm 工具链#

仓库根目录 package.json 声明了 "packageManager": "pnpm@11.7.0"，而系统预装的 pnpm 是 10.9.0。执行 pnpm install 时 pnpm 检测到版本与声明不符，会触发「自动切换到声明版本」的流程，但该流程依赖 corepack，而这个环境里 corepack 不可用，于是安装流程直接卡死。

解法：直接把全局 pnpm 升级到仓库声明的版本（旧版备份保留，可随时回退）：

1
# 1) 升级全局 pnpm 至 11.7.0（旧版 10.9.0 已备份为 pnpm.bak-10.9.0，未删除，可随时回退）
2
npm install -g pnpm@11.7.0
3
pnpm -v   # 输出 v11.7.0 ✅
4

5
# 2) registry 切换为 npmmirror 国内镜像（加速依赖下载）
6
npm config set registry https://registry.npmmirror.com/
7
npm config get registry   # 输出 https://registry.npmmirror.com/ ✅

3、依赖安装与构建（小内存服务器务必限制堆内存）#

1
cd 部署目录/deepseek-harness
2
pnpm install              # 使用 pnpm-lock.yaml 锁定版本，安装成功
3

4
# 构建：服务器内存紧张，必须限制 Node 堆内存，避免 OOM
5
NODE_OPTIONS="--max-old-space-size=2048" pnpm run build

1、服务文件：dsh-web.service#

在 systemd 服务目录（/etc/systemd/system/ 是 systemd 服务的标准存放位置）创建 dsh-web.service：

1
[Unit]
2
Description=DeepSeek Harness Web UI
3
After=network.target
4

5
[Service]
6
Type=simple
7
WorkingDirectory=部署目录/deepseek-harness
8
Environment=NODE_OPTIONS=--max-old-space-size=2048
9
# 同时信任带端口与无端口两种 Host 形态：
10
# - nginx 的 $host 变量不含端口，实际转发 Host 为 服务器公网地址
11
# - 浏览器/直连可能携带 Host: 服务器公网地址:对外端口
12
ExecStart=pnpm dsh web --trusted-host 服务器公网地址:对外端口 --trusted-host 服务器公网地址
13
Restart=on-failure
14
RestartSec=5
15
User=root
16
# 日志追加写入 /var/log/dsh-web.log
17
StandardOutput=append:/var/log/dsh-web.log
18
StandardError=append:/var/log/dsh-web.log
19

20
[Install]
21
WantedBy=multi-user.target

加载并启动：

1
systemctl daemon-reload
2
systemctl enable dsh-web    # 开机自启
3
systemctl start dsh-web
4
systemctl status dsh-web    # active (running) ✅

2、关键点说明#

• 监听地址：DeepSeek Harness 的 web 服务默认只监听 127.0.0.1:后端端口（有意不支持 --host 0.0.0.0），对外统一交给 Nginx 反代，这个设计其实更安全——后端不直接暴露网卡。
• --trusted-host 参数（解决 /api 403）：同时传入带端口（服务器公网地址:对外端口）与不带端口（服务器公网地址）两种形态，确保 nginx 的 $host 转发头与浏览器直连 Host 都能通过 DeepSeek Harness 的 Host 信任校验（trustedHosts），避免非特权 API 因 Host 不符返回 403。具体原理见第一节「2、踩坑记录」问题①。
• 开机自启：systemctl enable dsh-web 后状态为 enabled。

1、对外端口块（核心对外入口）#

1
server {
2
    listen 对外端口;
3
    server_name _;
4

5
    # DeepSeek Harness 应用访问日志（通用日志目录，可自行调整）
6
    access_log /var/log/nginx/dsh-access.log;
7
    error_log /var/log/nginx/dsh-error.log;
8

9
    # Basic Auth 访问认证（仅对外入口端口生效，后端监听地址不受影响）
10
    # 注意: 密码文件必须放在 nginx worker 可读的路径下
11
    #（Nginx 站点配置目录权限通常是 700 root，nginx worker 进程读不到）
12
    auth_basic "DeepSeek Harness Restricted Access";
13
    auth_basic_user_file 部署目录/dsh-auth/dsh-htpasswd;
14

15
    # DeepSeek Harness 可能上传文件 / Agent 任务产物，放宽请求体大小
16
    client_max_body_size 20m;
17

18
    # ---- location / ：反代 + WebSocket + sub_filter 注入 polyfill ----
19
    location / {
20
        proxy_pass http://127.0.0.1:后端端口;
21

22
        # 让后端返回未压缩的 HTML，确保 sub_filter 能注入 polyfill
23
        proxy_set_header Accept-Encoding "";
24

25
        # 兼容部分浏览器对 crypto.randomUUID 的支持差异
26
        # (部分环境未实现 crypto.randomUUID，改用 getRandomValues 模拟)
27
        sub_filter '</head>' '</head><script>(function(){try{if(typeof crypto!=="undefined"&&crypto&&!crypto.randomUUID){crypto.randomUUID=(function(){function b(a){return a.toString(16).padStart(2,"0")}return function(){var c=new Uint8Array(16);crypto.getRandomValues(c);c[6]=(c[6]&0x0f)|0x40;c[8]=(c[8]&0x3f)|0x80;var h="";for(var i=0;i<16;i++){h+=b(c[i]);if(i===3||i===5||i===7||i===9){h+="-"}}return h}})()}}catch(e){}})();</script>';
28
        sub_filter_once on;
29

30
        # 必须用 $http_host（保留端口），不能用 $host（会丢弃端口）。
31
        # 后端 DeepSeek Harness 的 browser-trust fence 校验 Host 与 Origin 一致性，
32
        # 浏览器 Origin 带端口(服务器公网地址:对外端口)，若 Host 无端口会 403。
33
        proxy_set_header Host $http_host;
34
        proxy_set_header X-Real-IP $remote_addr;
35
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
36
        proxy_set_header X-Forwarded-Proto $scheme;
37

38
        # WebSocket 支持（DeepSeek Harness 前端实时通信/事件推送）
39
        proxy_http_version 1.1;
40
        proxy_set_header Upgrade $http_upgrade;
41
        proxy_set_header Connection "upgrade";
42

43
        # 长连接/超时设置（Agent 任务长时运行，务必给足）
44
        proxy_read_timeout 300s;
45
        proxy_send_timeout 300s;
46
        proxy_connect_timeout 30s;
47
    }
48

49
    # ---- location /api ：伪造回环 Host/Origin（特权方法信任）----
50
    location /api {
51
        proxy_pass http://127.0.0.1:后端端口;
52

53
        # 伪造回环 Host/Origin，使特权方法通过 DeepSeek Harness 回环 fence
54
        proxy_set_header Host 127.0.0.1:后端端口;
55
        proxy_set_header Origin http://127.0.0.1:后端端口;
56
        proxy_set_header X-Real-IP $remote_addr;
57
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
58

59
        # WebSocket 支持（/api/events.* 升级握手）
60
        proxy_http_version 1.1;
61
        proxy_set_header Upgrade $http_upgrade;
62
        proxy_set_header Connection "upgrade";
63

64
        proxy_read_timeout 300s;
65
        proxy_send_timeout 300s;
66
        proxy_connect_timeout 30s;
67
    }
68
}

2、Basic Auth 凭据#

• 账号：admin
• 密码：you_passwd（占位，部署时务必替换为自设的强密码，不要沿用任何示例密码）
• 密码文件：dsh-htpasswd，放在「Nginx worker 可读的目录」下（如 部署目录/dsh-auth/dsh-htpasswd）

生成密码文件：

1
mkdir -p 部署目录/dsh-auth
2
# 生成 Basic Auth 密码文件（账号 admin，密码 you_passwd，htpasswd 加密格式）
3
htpasswd -bc 部署目录/dsh-auth/dsh-htpasswd admin you_passwd
4
# 调整属主与权限：root:nginx，nginx worker 可读
5
chown root:nginx 部署目录/dsh-auth/dsh-htpasswd
6
chmod 640 部署目录/dsh-auth/dsh-htpasswd
7

8
ls -l 部署目录/dsh-auth/dsh-htpasswd
9
# 期望：-rw-r----- root nginx  dsh-htpasswd（nginx worker 可读 ✅）

3、location /api 为什么要伪造回环 Host/Origin（原理与权衡，务必理解）#

• DeepSeek Harness 有意设计了一个回环信任围栏（loopback fence）：settings.describe、settings.update、credentials.set 等敏感 API 注册在 loopback 信任通道（authority: 'loopback'，见 packages/client/connection/src/rpc-host.ts），强制要求请求来自回环地址（127.0.0.1 / localhost）。这是 DeepSeek Harness 的故意安全设计——即使 --trusted-host 也只是防止 DNS-rebinding 的 Host 校验，并非认证层，无法放行特权方法。
• 因此 nginx 在 location /api 中把转发请求的 Host 与 Origin 伪造为 127.0.0.1:后端端口，让特权方法误以为请求来自回环，从而通过 fence。
• 权衡：这一步等于绕过了 DeepSeek Harness 内置的回环保护，真实的访问认证由 server 级 Basic Auth 承担——即「Basic Auth 是替代认证方案」。
• 注意 /api/events.mux、/api/events.host 等 WebSocket 端点也走本 location，升级握手依然能通过 fence。
• Origin 必须硬编码为 http://127.0.0.1:后端端口 与 Host 保持一致；若用 $http_origin 携带公网原始 Origin，反而会 403。

4、生效确认#

1
nginx -t && nginx -s reload   # 语法校验通过后重载

1、浏览器访问入口#

在任意设备（笔记本、手机、公司电脑）的浏览器打开：

1
服务器公网地址:对外端口

浏览器会弹出 Basic Auth 登录框，输入：

• 账号：admin
• 密码：you_passwd（你部署时设置的真实密码）

登录成功后进入 DeepSeek Harness Web UI，即可远程操作。

2、验证链路（命令与预期输出）#

1
# 无凭据访问 → 401（认证生效）
2
curl -I 服务器公网地址:对外端口
3
# HTTP/1.1 401 Unauthorized  ✅
4

5
# 带凭据访问 → 200
6
curl -I -u admin:you_passwd 服务器公网地址:对外端口
7
# HTTP/1.1 200 OK  ✅

3、WebSocket 实时通信#

DeepSeek Harness 前端与后端通过 WebSocket 保持长连接，用于任务进度实时推送、Agent 执行日志流式输出、前端事件总线。这依赖 Nginx 正确转发升级握手：

1
proxy_http_version 1.1;
2
proxy_set_header Upgrade $http_upgrade;
3
proxy_set_header Connection "upgrade";

如果漏掉这两行，页面能打开但实时数据不更新，任务跑起来看不到进度，表现为「页面死了一样」。排障时优先检查这个。

4、页面主要功能如何远程操作#

1、管理脚本：dsh-manage.sh#

四合一管理脚本，基于 systemd，提供 start / stop / restart / status 四个操作。放在项目目录下即可：

1
#!/bin/bash
2
# 用法:
3
#   bash dsh-manage.sh start    开启 DeepSeek Harness
4
#   bash dsh-manage.sh stop     关闭 DeepSeek Harness
5
#   bash dsh-manage.sh restart  重启 DeepSeek Harness
6
#   bash dsh-manage.sh status   查看运行状态
7

8
SERVICE="dsh-web"          # DeepSeek Harness 的 systemd 服务名
9
WAIT_SECONDS=5             # 操作后等待秒数
10
URL="服务器公网地址:对外端口"
11

12
case "$1" in
13
  start)
14
    echo ">>> 正在开启 DeepSeek Harness ..."
15
    systemctl daemon-reload
16
    systemctl start "$SERVICE"
17
    sleep "$WAIT_SECONDS"
18
    if systemctl is-active --quiet "$SERVICE"; then
19
      echo "[OK] 已开启，访问地址: $URL"
20
    else
21
      echo "[ERROR] 开启失败，最近日志:"
22
      journalctl -u "$SERVICE" -n 20 --no-pager
23
      exit 1
24
    fi
25
    ;;
26
  stop)
27
    echo ">>> 正在关闭 DeepSeek Harness ..."
28
    systemctl stop "$SERVICE"
29
    sleep 2
30
    if systemctl is-active --quiet "$SERVICE"; then
31
      echo "[ERROR] 正常停止失败，强制终止..."
32
      systemctl kill "$SERVICE"
33
      sleep 2
34
    fi
35
    if systemctl is-active --quiet "$SERVICE"; then
36
      echo "[ERROR] 关闭失败，请手动检查: journalctl -u $SERVICE"
37
      exit 1
38
    else
39
      echo "[OK] 已关闭"
40
    fi
41
    ;;
42
  restart)
43
    echo ">>> 正在重启 DeepSeek Harness ..."
44
    systemctl daemon-reload
45
    systemctl restart "$SERVICE"
46
    sleep "$WAIT_SECONDS"
47
    if systemctl is-active --quiet "$SERVICE"; then
48
      echo "[OK] 已重启，访问地址: $URL"
49
    else
50
      echo "[ERROR] 重启失败，最近日志:"
51
      journalctl -u "$SERVICE" -n 20 --no-pager
52
      exit 1
53
    fi
54
    ;;
55
  status)
56
    systemctl status "$SERVICE" --no-pager
57
    ;;
58
  *)
59
    echo "用法: bash $0 {start|stop|restart|status}"
60
    exit 1
61
    ;;
62
esac
63
exit 0

使用与验证：

1
bash -n 部署目录/dsh-manage.sh                    # 语法检查通过（无输出）
2
chmod +x 部署目录/dsh-manage.sh
3
bash 部署目录/dsh-manage.sh start                 # 开启
4
bash 部署目录/dsh-manage.sh restart               # 重启验证
5
bash 部署目录/dsh-manage.sh status                # 状态

例如在任务调度系统中配置如下定时任务：

2、日志位置速查#

1
tail -f /var/log/nginx/dsh-access.log   # 实时看访问
2
tail -f /var/log/dsh-web.log            # 实时看应用日志
3
journalctl -u dsh-web -n 50 --no-pager  # 看 systemd 日志

3、常见操作速查#

记住两件事：改 systemd 必须 daemon-reload；改 Nginx 必须先 nginx -t 再 reload。