DSH 远程部署完整教程：账号密码认证与域名访问

这篇教程记录如何在一台全新的 Linux 服务器上部署 DeepSeek Harness（DSH），使用 dsh-web-startup-auth 提供管理员账号密码认证，并修复 LAN 远程访问时的回环判定、设置面板和浏览器认证兼容问题。可信局域网可直接访问；如需公网访问，应另行部署 HTTPS 反向代理。

🎯

可信 LAN 访问链路：浏览器 → 服务器 LAN 地址 → DSH → dsh-web-startup-auth 账号密码 / 会话认证。插件负责认证，不提供传输加密；首次设置管理员账号必须在对外开放之前完成。不可信网络访问应使用 HTTPS。

一、系统准备

1.1 环境要求

操作系统：Ubuntu 22.04 / 24.04 LTS 或 Debian 12

Node.js：≥ 22.19.0，推荐使用 NodeSource 安装 Node.js 22.x

网络：客户端能够访问服务器的 LAN 地址；明文 HTTP 仅用于可信内网

域名（可选）：LAN IP 直连无需域名；使用域名或 HTTPS 反向代理时再按实际情况配置

1.2 安装 Node.js 与 pnpm

⚠️

DSH 核心版本明确要求 Node.js ≥ 22.19.0，低于此版本会在启动时报错。

1.3 创建工作目录

本教程统一以 root 用户执行安装、插件管理与维护命令，并以 root 用户运行 systemd 服务。

⚠️

以 root 运行 DSH 时，其命令执行、文件操作和插件也将拥有 root 权限。仅允许可信管理员访问，谨慎安装插件；账号密码认证不能限制服务在本机的权限。

二、安装 DSH

2.1 全局安装

安装完成后验证：

2.2 最小化启动测试

先不要配置任何插件，直接启动基础 Web 服务，确认 DSH 能正常运行：

终端应输出类似内容：

看到访问地址说明基础服务正常。按 Ctrl+C 停止服务，然后安装认证插件，再配置 systemd。

2.3 安装账号密码认证插件

这是一个 DSH bundle，安装后补丁会自动生效，不需要手动编辑配置，也不要重复添加 --patch。它支持非回环地址启动、管理员账号密码登录，并补齐 LAN 场景的浏览器认证与设置面板兼容性。

项目当前声明支持 DSH >=0.1.7-rc.1，不支持 0.3.0 及其预发布版本线，当前适配基线为 0.2.0-rc.2。安装或升级前请核对实际 DSH 版本与项目兼容说明；超出范围时 bundle 会被跳过，不能把“服务启动成功”当成“认证已生效”。

三、配置 systemd 服务

3.1 创建服务文件

关键配置说明：

配置项	说明
`User=root` / `Group=root`	以 root 用户和组运行服务，具有完整系统权限
`WorkingDirectory`	必须设置，避免 DSH 的文件操作散落在根目录
`HOME=/root` / `DSH_HOME=/root/.dsh`	明确 root 的主目录和 DSH 数据目录，保证服务与插件管理使用同一份配置
`ExecStart`	使用绝对路径，因为 systemd 不读取 `.bashrc` 中的 PATH
`--host 127.0.0.1`	域名方案保持回环监听，由同机 HTTPS 反向代理回源；仅 LAN 直连时才按第五节更改
`--trusted-host`（可选）	使用域名时供上游 Host 信任围栏放行实际域名；不代替账号密码认证

💡

如果使用 nvm 管理 Node.js，dsh 会安装到 nvm 的版本目录。此时 ExecStart 必须填写实际绝对路径，并可能需要额外设置 Environment="PATH=..."。

3.2 通过域名访问（HTTPS 反向代理）

本教程的域名访问示例使用 dsh.example.com，请替换为自己的实际域名。第三节的服务文件已加入 --trusted-host dsh.example.com，推荐由同一台服务器上的 Nginx、Caddy 等 HTTPS 反向代理提供入口：

域名解析：将实际域名的 A / AAAA 记录指向反向代理所在服务器可达的公网地址；仅内网使用时可使用内网 DNS 解析到 LAN 地址

HTTPS 入口：在反向代理中配置该域名与有效证书，回源地址为 http://127.0.0.1:3080；需支持 WebSocket

Host 转发：保留真实访问域名，不能把 Host 改成 127.0.0.1 或 localhost，否则在默认本机免登录配置下可能绕过认证

监听地址：反向代理与 DSH 在同机时，保持 --host 127.0.0.1，不必改为 0.0.0.0，也不要把域名写进 --host

开放顺序：先按第四节在 SSH 终端完成管理员注册，再开放域名入口；浏览器使用 https://dsh.example.com 登录。域名方案无需执行第五节的 LAN 监听变更

--trusted-host 只放行上游 Host 信任检查，不会自动配置 DNS、证书或反向代理，也不会让远程访问免登录。

若已有同机 Nginx HTTPS 站点，可在其对应的 server 内配置以下回源规则；这只是代理片段，不是完整的 HTTPS 站点配置：

修改 systemd 配置后执行：

3.3 启动并验证服务

服务应显示 active (running)。检查日志，确认认证 bundle 未因版本不兼容而被跳过；完成第四节的管理员注册后，再启用 3.2 节的 HTTPS 域名入口，并按第六节验证认证保护。第五节仅供需要 LAN IP 直连时参考。

四、首次设置管理员账号密码

4.1 在 SSH 终端设置管理员账号密码

SSH 登录服务器，确认 DSH 已启动且尚未开放域名入口。替换用户名和密码后，执行这一条命令完成首次注册（密码至少 8 位）：

返回 {"ok":true} 即注册成功，再启用 HTTPS 反向代理，通过 https://dsh.example.com 登录。已有账号请勿重复注册。

⚠️

此简写会将密码放入命令参数，并可能留在 Shell 历史中，请勿公开终端记录。用无痕窗口验证域名访问必须登录；共享服务器建议开启“本机登录校验”。

4.2 账号、会话与密码恢复

在 设置 → 认证 中修改用户名、修改密码、退出登录或调整会话有效期，默认会话为 14 天

密码使用 scrypt 哈希存储，不保存明文；凭据文件也包含会话签名密钥，不得公开

退出登录只清除当前浏览器的 cookie，不能单独吊销泄露的会话；修改用户名、修改密码或执行密码重置会轮换密钥，使旧会话全部失效

忘记密码时，在服务器本机执行：

该命令仅重置已有账号，不能用于首次创建账号。优先使用交互方式，避免把密码放进命令参数、Shell 历史或截图。

4.3 从旧认证方案迁移

先限制远程访问，在本机完成新插件安装、首次注册及验证，再恢复对外访问。删除旧认证插件及其版本豁免，清理 systemd 中旧插件的环境变量，确认新插件的账号密码保护已生效。

五、LAN 访问与回环兼容

5.1 按访问方式选择监听地址

场景	建议配置
本机访问 / 同机 HTTPS 反向代理	保持第三节的回环监听，通过 `127.0.0.1:3080` 访问或回源
直接从可信 LAN 访问	将 systemd 的 `ExecStart` 改为下方命令，仅在防火墙允许可信网段访问

0.0.0.0 会监听全部 IPv4 接口，并不等于“只监听内网”。可改为服务器具体 LAN IP，减少暴露面。使用域名访问时，再按需追加 --trusted-host <实际域名>。开放监听之前必须已完成第四节的管理员注册。

修改后执行：

可信 LAN 客户端使用 http://<服务器LAN-IP>:3080/ 访问并登录。HTTP 不加密账号密码或会话，不适合不可信网络；公网应使用 HTTPS 反向代理。

5.2 插件解决哪些 LAN 问题

支持原版启动器拒绝的 --host 0.0.0.0 等非回环地址绑定

修复远程浏览器的回环判定兼容问题，使 Models、提供方目录等设置面板能够正常加载

为已通过插件认证的请求补发 DSH 原生浏览器认证 cookie，无需复制启动时打印的 token URL

补齐非安全 HTTP 上下文缺失的 crypto.randomUUID，避免相关 RPC 失败

这不代表所有第三方插件的回环限制都会自动解除。若第三方接口返回 request-not-trusted，仍需检查该插件自身的远程访问配置。

5.3 本机免登录与域名信任的区别

默认只有“TCP 对端地址与 Host 头均为回环”的请求才免登录；LAN 客户端与保留真实公网 Host 的反向代理请求均需有效会话。--trusted-host 只影响上游 Host 信任围栏，不是免登录开关。

如果上游返回纯文本 forbidden，检查代理是否保留真实 Host，并确认实际域名已加入 --trusted-host。若插件认证失败，应重新登录；不要通过把代理 Host 改成回环地址来绕过认证。

六、访问与验证

6.1 首次访问

确认管理员账号已在 SSH 终端通过本机注册 API 创建，再启用 HTTPS 反向代理的域名入口

使用无痕窗口打开 https://dsh.example.com（替换为实际域名）；仅 LAN 直连时才使用 http://<服务器LAN-IP>:3080/

应进入插件的 /login 页面，使用已设置的管理员账号密码登录

登录后进入 设置 → 模型 与 设置 → 认证，确认页面及功能正常

退出登录后刷新，确认不能继续访问受保护功能；不要仅以首页能打开或端口可连通作为认证成功的依据

6.2 检查 WebSocket

打开浏览器开发者工具，进入 Network → WS，检查 WebSocket 连接状态码是否为 101 Switching Protocols。这是 DSH 实时功能正常工作的关键。

6.3 安全检查

建议额外确认：

使用同机 HTTPS 反向代理时，DSH 仅监听回环，公网无法直接访问服务器的 3080 端口

LAN 直连方案下，监听地址与防火墙规则只允许预期的可信网络，避免意外开放公网

管理员已在开放入口之前注册，远程未登录时无法调用受保护 API 或完成受保护的 WebSocket 握手

代理保留真实 Host，没有将公网请求伪装成回环访问

公网使用 HTTPS，密码、会话 cookie 和凭据文件没有出现在公开日志或截图中

共享服务器启用“本机登录校验”；密码泄露时通过修改密码或 auth-reset 轮换会话密钥

七、日常维护

7.1 更新 DSH

7.2 插件管理

✅

每安装一个插件，都应立即重启 DSH 并确认服务正常，再安装下一个。不要一次安装多个插件，否则出现问题时很难定位冲突来源。

7.3 查看日志

7.4 建议的更新流程

备份 /root/.dsh

记录当前 DSH 与插件版本

更新 DSH

重启并检查日志

逐个更新插件，每次更新后单独验证

最后测试账号密码登录、退出后的访问限制、LAN / 公网设置页面和 WebSocket

若认证 bundle 被跳过或登录保护失效，立即关闭对外入口，恢复兼容版本后再开放

八、故障排除

症状	可能原因	解决方案
服务反复重启	插件兼容性冲突	先限制远程访问，再按下方紧急恢复步骤手动禁用问题插件
`settings are unavailable` / 提供方目录加载失败	认证插件版本过旧或未生效，LAN 兼容层未加载	执行 `dsh plugin --profile web add dsh-web-startup-auth@latest`，重启并核对兼容范围
WebSocket 连接失败	登录会话失效、网络不通或反向代理未转发握手	重新登录，检查 LAN 连通性、防火墙与反向代理的 WebSocket 配置
仍要求 token 或登录页循环跳转	认证 bundle 未生效、旧版本兼容问题或残留 cookie	核对版本与启动日志，更新认证插件，清除站点 cookie 后重试
远程未登录却可访问	代理把 Host 改成回环，或认证 bundle 被跳过	立即关闭入口；恢复真实 Host、检查监听与兼容范围，验证登录保护后再开放
纯文本 `forbidden` / 第三方 `request-not-trusted`	上游 Host 围栏 / 第三方插件独立限制	前者检查真实 Host 与 `--trusted-host`；后者查对应插件的远程访问配置
忘记密码	管理员凭据需要重置	在服务器执行 `dsh --profile web auth-reset`，旧会话会全部失效
插件安装被拒绝	插件版本与 DSH 不兼容	核对版本；确认风险后再使用 `allow-version --accept-risk`
systemd 找不到 `dsh`	`ExecStart` 路径错误	使用 `which dsh` 查找真实路径并更新服务文件
使用反向代理时出现 502	DSH 未运行或代理上游地址错误	检查 `systemctl status dsh`、实际监听地址与代理上游配置

紧急恢复

如果 DSH 完全无法启动，可按以下方式离线修复。

⚠️

禁用认证插件或恢复数据之前，先关闭反向代理的对外入口并限制 LAN 访问。不得在缺少认证保护的状态下重新开放服务；修复后先在本机验证，再测试远程未登录的访问限制。

手动禁用问题插件

在文件中为问题插件添加：

修改完成后重启并检查日志：

九、完整部署流程速查

结语

通过 systemd 与 dsh-web-startup-auth，可以用统一的账号密码登录访问 DSH，并处理 LAN 访问的回环判定与设置面板兼容问题。首次注册必须先于网络开放，LAN 访问应限制在可信网络；如需公网访问，应另行部署 HTTPS 反向代理并保留真实 Host。升级后必须重新验证认证保护。由于本教程以 root 运行服务，DSH 与插件拥有完整系统权限，入口认证不能替代本机权限隔离。

部署完成后，建议保存一份当前版本、插件列表、systemd 配置和监听地址的脱敏记录，后续升级或故障恢复会轻松很多。