DSH (DeepSeek Harness) Web部署完整教程

📌 概述

本文档记录了在 Ubuntu 22.04/24.04 服务器上部署 DSH（DeepSeek Harness），并通过 Nginx 反向代理实现内网访问的完整过程。最终方案采用 dsh-web-startup-auth 认证插件，成功解决了 403 权限和 WebSocket 连接问题，实现了带安全认证的远程访问。

适用场景：希望在内网（或通过 VPN）安全访问 DSH Web UI，且要求有用户认证机制。

🛠 环境信息

项目	内容
操作系统	Ubuntu 22.04 / 24.04 LTS (无头服务器)
用户	`your-username`
Node.js	最新 LTS 版本（如 v20+）
DSH 安装路径	`~/.npm-global/bin/dsh`
内网 IP	`192.168.x.x`（示例）
DSH 监听端口	`3080`
Nginx 代理端口	`30801`（可自定义）

📦 1. 安装 DSH

1.1 安装 Node.js（若未安装）

推荐使用 NodeSource 或 nvm 安装 LTS 版本，确保 npm 可用。

1.2 全局安装 DSH

npm install -g @deepseek-ai/dsh

1.3 将 npm 全局 bin 目录加入 PATH（避免命令找不到）

echo 'export PATH="'$(npm config get prefix)'/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

验证安装：

which dsh
# 输出: /home/your-username/.npm-global/bin/dsh

🗂 2. DSH 配置目录结构

安装后，默认 profile 为 web，相关文件位于：

~/.dsh/
└── profiles/
    └── web/
        ├── cordis.yml          # 主配置（默认空数组）
        ├── cordis.patch.yml    # 补丁配置（用于覆盖）
        ├── package.json
        └── pnpm-workspace.yaml

⚙️ 3. Systemd 服务配置（实现开机自启与进程守护）

3.1 创建服务文件

路径：/etc/systemd/system/dsh.service

[Unit]
Description=DeepSeek Harness (DSH) Web Service
After=network.target

[Service]
Type=simple
User=your-username
Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/your-username/.npm-global/bin"
ExecStart=/home/your-username/.npm-global/bin/dsh --profile web --host 0.0.0.0
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

注意：--host 0.0.0.0 参数需在安装认证插件后方可生效（否则 DSH 会拒绝启动），我们将在后续步骤安装插件。

3.2 启用并启动服务

sudo systemctl daemon-reload
sudo systemctl enable dsh
sudo systemctl start dsh
sudo systemctl status dsh   # 查看状态

🌐 4. Nginx 反向代理配置（支持 WebSocket）

4.1 安装 Nginx

sudo apt update
sudo apt install nginx -y

4.2 创建站点配置文件

路径：/etc/nginx/sites-available/dsh.conf

server {
    listen 30801;
    server_name _;

    location / {
        proxy_pass http://127.0.0.1:3080;
        proxy_http_version 1.1;
        proxy_buffering off;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_read_timeout 86400;
        proxy_send_timeout 86400;
    }
}

关键点：

proxy_http_version 1.1 和 Upgrade/Connection 头是 WebSocket 握手必需的。
proxy_set_header Host $host 传递客户端原始 Host，避免后端权限校验失败。
超时时间调大，防止长连接断开。

4.3 启用站点并重启

sudo ln -s /etc/nginx/sites-available/dsh.conf /etc/nginx/sites-enabled/
sudo nginx -t              # 检查语法
sudo systemctl restart nginx

🔐 5. 安装认证插件（解决远程访问权限问题）

DSH 出于安全考虑，默认拒绝非本地请求（返回 403）。官方推荐的方式是在前端加上认证层。我们使用社区插件 dsh-web-startup-auth，它既提供认证，又允许 --host 0.0.0.0。

5.1 启用 pnpm（Node.js 包管理器）

corepack enable pnpm

5.2 安装认证插件

dsh plugin --profile web add dsh-web-startup-auth@latest

此命令会在 ~/.dsh/profiles/web/ 中安装插件依赖，并修改配置。

5.3 重启 DSH 服务

sudo systemctl restart dsh

🧪 6. 验证部署

6.1 检查 DSH 监听地址

sudo lsof -i :3080

预期输出包含 TCP *:3080 (LISTEN)，表示已监听所有网络接口。

6.2 访问 Web 界面

在浏览器中输入：http://<your-server-ip>:30801（如 http://192.168.1.111:30801）

首次访问：因为安装了认证插件，页面会跳转到注册界面，请设置管理员用户名和密码。

登录后，所有功能（包括 Agent 预设、WebSocket 连接）应该正常。

6.3 手动测试 WebSocket（可选）

在浏览器开发者工具控制台中执行：

new WebSocket("ws://<your-server-ip>:30801/api/events.mux").onopen = () => console.log("✅ WS OK");

若输出 ✅ WS OK，说明 WebSocket 代理成功。

📋 7. 常用维护命令速查

操作	命令
启动 DSH	`sudo systemctl start dsh`
停止 DSH	`sudo systemctl stop dsh`
重启 DSH	`sudo systemctl restart dsh`
查看 DSH 状态	`sudo systemctl status dsh`
实时查看 DSH 日志	`sudo journalctl -u dsh -f`
重启 Nginx	`sudo systemctl restart nginx`
查看 Nginx 错误日志	`sudo tail -f /var/log/nginx/error.log`

⚠️ 8. 常见问题与排错

8.1 `dsh: command not found`

原因：npm 全局 bin 目录未加入 PATH。
解决：执行 export PATH="$PATH:$(npm config get prefix)/bin" 并永久写入 ~/.bashrc。

8.2 访问页面返回 403 Forbidden

原因：DSH 拒绝非本地请求，或未安装认证插件。
解决：确保已安装 dsh-web-startup-auth 并添加了 --host 0.0.0.0 启动参数。

8.3 WebSocket 连接失败（`connection lost`）

原因：Nginx 缺少 WebSocket 升级头，或 Host 头被强制固定。
解决：检查 Nginx 配置是否包含 proxy_set_header Upgrade $http_upgrade; 和 proxy_set_header Connection "upgrade";，且 proxy_set_header Host $host; 使用动态值。

8.4 `crypto.randomUUID is not a function`

原因：浏览器或 Node.js 环境不支持该 API。
解决：dsh-web-startup-auth 插件已自动注入 polyfill，无需额外操作。

8.5 Nginx 启动失败（端口占用）

检查：使用 sudo lsof -i :<port> 查看端口占用，杀掉冲突进程或更改监听端口。

🔗 9. 参考资料

📝 结语

通过以上步骤，你可以在内网环境中搭建一个带用户认证、稳定运行的 DSH Web 服务，享受 AI 编程助手的便捷。如有任何问题，欢迎在评论区交流。

文档版本: 1.0
最后更新: 2026-09-04
作者: xiaji / 社区贡献