dsh-login-gateway: Add TOTP Login to the DeepSeek Harness Web UI

前言¶

DeepSeek Harness (DSH) 的 Web UI 默认通过进程启动令牌进行认证，这种机制在本地开发时很方便，一旦端口暴露到公网，任何持有该令牌的人都能直接访问 Harness，存在安全隐患。dsh-login-gateway 插件在不修改 Harness 核心代码的前提下，在 Web UI 前面加了一道用户名、密码和 TOTP 二次验证的网关。

这是什么¶

dsh-login-gateway 是 DeepSeek Harness (DSH) 的一个插件，由开发者 ButterHost69 维护，许可证为 MIT。它监听独立的端口，提供标准的登录页面，验证通过后将流量转发给 Harness，从而避免直接暴露未认证的 API。

核心功能¶

独立监听与路由：监听自己的主机和端口，提供 /login、/logout 和 /_dsh-login-gateway/health 接口。
多因素认证：验证用户名、scrypt 哈希密码以及 TOTP 代码，签发自己的 HMAC 会话 Cookie。
流量转发：将认证后的请求（含 WebSocket 升级）转发给 Harness，并保留浏览器侧的 Host 头。
服务端令牌交换：在服务端完成 Harness 的启动令牌到 Cookie 的交换，浏览器端不接触敏感凭证。
首次初始化：当没有配置账户时，自动提供设置界面，生成 TOTP 密钥并存储凭证。
限流保护：针对客户端地址和用户名分别限制失败的登录尝试次数。

安装与启用¶

安装前需确保环境满足要求：dsh 版本为 0.2.1-alpha.1 或兼容版本，Node.js 版本为 ^22.19 || >=24，并且已启动 dsh web Web 配置文件。

从 GitHub 安装（会自动构建）：

dsh plugin --profile web add -w github:ButterHost69/dsh-login-gateway

如果使用 pnpm >= 10，可能会因为默认的安全策略拒绝运行 git 依赖的构建脚本。如果安装失败，需在 Web 配置文件的 pnpm-workspace.yaml 中添加 allowBuilds 配置：

allowBuilds:
  dsh-login-gateway: true

然后再执行一次 add 命令。

典型用法¶

安装后，插件会处于首次运行状态，此时需要在浏览器中设置第一个账户。

首次设置：访问 http://127.0.0.1:8080/login（或通过隧道访问带 ?setup=... 的链接）。
创建账户：输入用户名和密码。用户名需以字母开头，包含 2-32 个小写字母、数字或连字符；密码至少 12 个字符。
绑定 TOTP：提交后会出现 TOTP 密钥和 otpauth:// URI，将其添加到 Google Authenticator 等应用中。
添加更多用户：对于可复现的部署或后续添加用户，使用插件提供的脚本生成配置并写入 $DSH_HOME/profiles/web/cordis.patch.yml：

   cd /path/to/dsh-login-gateway
   npm install
   npm run build
   node scripts/enroll.mjs --username alice

将输出的 passwordHash 和 totpSecret 填入 cordis.patch.yml 的 users 列表中。

暴露服务：将隧道或反向代理指向网关端口（默认 8080），而不是 Harness 的端口。例如使用 Caddy：

   harness.example.com {
     reverse_proxy 127.0.0.1:8080
   }

启动 Harness 时需加上 --trusted-host 参数以允许外部 Host 头：

   dsh web --trusted-host harness.example.com

适用场景与注意¶

适用场景：需要在公网或内网通过反向代理访问 DSH Web UI，且需要强认证的场景。
权限风险：该插件以当前 DSH 进程的权限运行，建议安装前检查源码和许可证（MIT）。
TLS 处理：网关本身只处理 HTTP，TLS 终止应在反向代理（如 Caddy、Nginx 或 Cloudflare Tunnel）处完成。
Host 头依赖：反向代理必须保留浏览器侧的 Host 头并转发 WebSocket 升级头，否则 Harness 的 API 会返回 403。

短结尾¶

dsh-login-gateway 为 DSH 提供了标准化的登录入口，解决了公网暴露的安全痛点。更多配置细节和源码，可在 GitHub 查看详情。