RaulLazaro/dsh-server-setup

DSH 服务器搭建

在远程 VPS 上通过反向代理运行 DeepSeek Harness，作为 DSH 插件。

这是一个经过生产环境验证的搭建方案，用于在 Ubuntu 服务器（ARM64 或 x64）上运行 DSH，具备以下特性：

特性

- systemd 服务 — 自动重启、日志记录、持久化
- 反向代理插件 — smanx/dsh-proxy 在 DSH 内部运行，可从设置中配置
- 基本认证（可选） — 保护你的实例免受未授权访问
- 文件上传与预览 — DSH 0.1.5+ 内置（无需插件）
- PWA 支持 — 通过自定义插件安装为应用
- 可信主机 — 通过域名远程访问，无需在 URL 中携带令牌

架构

Browser/Phone
│
▼
DSH (0.0.0.0:3080)        ← dsh-proxy plugin handles external access
│
▼
DSH core (127.0.0.1:3079) ← internal port
│
▼
DeepSeek API / MCP servers / Filesystem

代理作为 DSH 插件运行 — 无需单独的进程。它随 dsh web 一起启动和停止。

快速开始

1. 安装前置依赖

Node.js 24+ (via fnm recommended)
curl -fsSL https://fnm.vercel.app/install | bash
source ~/.bashrc
fnm install 24

pnpm
npm install -g pnpm

DSH
npm install -g @deepseek-ai/dsh@0.1.5-rc.1

2. 创建 web 配置文件

mkdir -p ~/.dsh/profiles/web
cd ~/.dsh/profiles/web

3. 添加插件

Reverse proxy
pnpm add github:smanx/dsh-proxy

Other recommended plugins
pnpm add dshmarket dsh-mnemon dsh-free-search dsh-config-manager dsh-mcp-sync

4. 配置配置文件

~/.dsh/profiles/web/package.json：

{
"name": "dsh-profile-web",
"private": true,
"dependencies": {
"@smanx/dsh-proxy": "github:smanx/dsh-proxy",
"dshmarket": "^1.45.1"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"@smanx/dsh-proxy",
"dshmarket"
]
}
}
}

~/.dsh/profiles/web/cordis.patch.yml：

dsh-proxy: reverse proxy for LAN/remote access
- id: dsh-proxy
name: "@smanx/dsh-proxy"
config:
listenPort: 3080
username: admin       # Uncomment to enable Basic Auth
password: changeme    # Uncomment to enable Basic Auth

5. 配置凭据

创建 ~/.dsh/.credentials.yaml：

version: 1
refs:
OPENCODE_GO_API_KEY: sk-your-api-key-here
records: {}

6. 安装 systemd 服务

sudo cp systemd/dsh.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable dsh
sudo systemctl start dsh

7. 验证

Check DSH is running
curl -s http://127.0.0.1:3079/ | head -5

Check proxy is accessible
curl -s http://YOUR_SERVER_IP:3080/ | head -5

Check logs
journalctl -u dsh -f

更新 DSH

update_all.sh 脚本通过 cron 自动处理更新。如需手动更新：

Update DSH
npm install -g @deepseek-ai/dsh@latest
重启服务
sudo systemctl restart dsh

配置

代理设置（通过 UI）

在 DSH 网页界面中进入 设置 → 局域网代理，可以：

- 启动/停止代理
- 更改监听端口
- 设置 Basic Auth 的用户名和密码
- 查看连接状态

代理设置（通过 cordis.patch.yml）
yaml
- id: dsh-proxy
name: "@smanx/dsh-proxy"
config:
listenPort: 3080        # 外部端口 (0.0.0.0)
username: admin         # Basic Auth 用户名（留空 = 禁用）
password: changeme      # Basic Auth 密码

HTTPS / 远程访问

该代理不处理 HTTPS。在生产环境中，请在前面放置一个 TLS 终止器：

- Pangolin（推荐）—— 自托管的身份感知 VPN + 反向代理，带有 WireGuard、仪表盘和访问控制
- Cloudflare Tunnel —— cloudflared tunnel --url http://127.0.0.1:3080
- Caddy —— 使用 reverse_proxy localhost:3080 自动配置 HTTPS
- Nginx + Let's Encrypt —— 标准反向代理配置

Pangolin 设置

Pangolin 是一个自托管隧道，无需开放端口即可为你提供 HTTPS + 身份验证 + WireGuard VPN。它作为 Docker 容器运行在同一台 VPS 上。

1. 安装 Pangolin：
bash
git clone https://github.com/fosrl/pangolin.git ~/pangolin
cd ~/pangolin
bash install.sh

2. 配置（~/pangolin/config/config.yml）：
yaml
domain: yourdomain.com

letsencrypt:
email: you@yourdomain.com
useLetsEncrypt: true

flask_secret:   # 使用以下命令生成：openssl rand -hex 32
jwt_secret:     # 使用以下命令生成：openssl rand -hex 32

3. 在 Pangolin 仪表盘中添加 DSH 资源：

1. 打开 https://yourdomain.com → 登录
2. 进入 资源 → 新建资源
3. 设置：
- 名称：dsh
- 协议：HTTP
- 目标 IP：127.0.0.1
- 目标端口：3080
4. 创建一个目标（Gerbil 客户端）并生成配置
5. 在你的 VPS 上，添加 Gerbil 客户端：
bash
sudo nano /etc/pangolin/client/config.yml
sudo systemctl restart pangolin-client

4. 访问 DSH：

https://dsh.yourdomain.com

相较于直接代理的优势：
- 使用自动 Let's Encrypt 证书的 HTTPS
- 内置身份验证（基于电子邮件或 SSO）
- 用于完整网络访问的 WireGuard VPN 选项
- 访问控制和审计日志
- 无需开放额外端口

反向代理功能

该代理（smanx/dsh-proxy，MIT 许可证）提供：

crypto.randomUUID polyfill
DSH 的前端使用 crypto.randomUUID() 生成 RPC ID，但此 API 仅在安全上下文（HTTPS/localhost）中可用。当通过局域网 IP 或公共 URL 访问时，该 polyfill 会注入一个使用 getRandomValues() 的兼容实现。

回环信任补丁
DSH 检查 location.hostname 以判断浏览器是否为本地。非回环主机会获得降级行为（仅内存模式，无设置）。代理会修补客户端 JS，将代理连接视为回环，从而启用完整功能。

WebSocket 支持
代理转发 WebSocket 连接，以支持 DSH 的实时功能（流式传输、实时更新）。

公共路径白名单
/manifest.webmanifest、/favicon.svg 和 /favicon.ico 无需认证即可提供，以便浏览器无需凭据即可获取 PWA 元数据。

DSH 0.1.5 变更

内置功能（无需插件）
- 文件上传 — 直接在聊天中拖放或粘贴图片
- 文件预览 — 带语法高亮、PDF、图片的侧边栏
- 侧边栏 — 多标签页、分屏视图、文件和交付物的全屏显示

已移除的功能
- Telegram 集成 — dsh-telegram 和 dsh-telegram-bridge 在 DSH 0.1.5 中均已损坏
- Cron 调度器 — dsh-cron 的 Host 端无法启动
- Webhook — 已移除，曾与 cron 配合使用

已知问题
- dsh-telegram v0.2.0 — Host 端的 apply() 从不执行
- dsh-telegram-bridge — 依赖于 DSH 0.1.5 中不存在的 apiProxy
- dsh-cron (@goodandready) — Host 端无法启动，不生成日志

OpenCode Go 会话头

OpenCode Go 需要 x-opencode-session 头来进行按对话路由。DSH 原生不发送此头。

变通方法（在 ~/.dsh/settings.yaml 中）：
yaml
llm-pi-ai:
providers:
opencode-go:
headers:
x-opencode-session: "dsh-global"

状态： 已在 DSH #5495 提出 PR，添加 sessionHeader 配置字段以支持动态的按会话 ID。

故障排除

DSH 无法启动
- 检查日志：journalctl -u dsh -f
- 验证 Node.js 在 PATH 中：which node
- 检查 DSH 主目录存在：ls ~/.dsh/
- 验证凭据：cat ~/.dsh/.credentials.yaml

代理无法访问
- 检查插件是否加载：设置 → 插件 → dsh-proxy
- 检查端口是否开放：ss -tlnp | grep 3080
- 检查防火墙：sudo ufw allow 3080/tcp
- 如需远程访问，在 run.sh 中添加 --trusted-host yourdomain.com

WebSocket 不工作
- 代理必须转发 Upgrade 和 Connection 头
- 如果位于其他代理（nginx/Caddy）之后，请确保那里也启用了 WebSocket

设置页面显示“在此浏览器中不可用”
- 回环修补可能未应用
- 检查代理插件是否在设置 → 插件中启用
- 清除浏览器缓存并重新加载

插件未加载
- 检查插件是否在 package.json 的 bundles 数组中
- 检查 cordis.patch.yml 语法
- 检查日志中的错误：journalctl -u dsh -f | grep -i error

找不到凭据
- 验证 ~/.dsh/.credentials.yaml 存在且格式正确
- 检查文件权限：ls -la ~/.dsh/.credentials.yaml
- 确保凭据名称与插件期望的匹配

文件

dsh-server-setup/
├── README.md                    # 本文件
├── PLUGINS.md                   # 插件栈列表
├── run.sh                       # DSH 包装脚本
├── systemd/
│   └── dsh.service              # Systemd 单元文件
└── dsh-proxy/                   # 独立代理（备选方案）
└── node/
├── index.js
├── proxy-core.js
└── package.json

插件

有关已安装插件的完整列表及说明，请参阅 PLUGINS.md。

致谢

- 反向代理 — smanx/dsh-proxy（MIT 许可证）。同时提供用于独立部署的 Go 构建版本。
- 远程访问 — Pangolin（自托管 VPN + 基于 WireGuard 的反向代理）
- DSH — DeepSeek Harness，由 DeepSeek AI 开发

许可证

MIT