clarknu/dsh-gateway

dsh-gateway

为 DeepSeek Harness 的 Web 界面加一层「HTTPS 加密 + 账号登录」的远程访问网关：作为 dsh 插件安装，无需任何外部程序，装上即用。

A self-contained HTTPS + login gateway for the DeepSeek Harness web surface. Install it as a dsh plugin — no external programs needed.

它能做什么

- 远程访问 DSH Web 界面：在局域网内的另一台电脑或手机上，打开 https://本机IP:端口 就能访问；配置好端口映射后，从互联网也能访问
- HTTPS 加密：全程加密传输；有域名可用自己的证书，没有域名（IP 直连）会自动生成证书
- 登录保护：访问前必须先登录；账号、密码、会话有效期都可配置，登录失败自动限速；密码不以明文存储
- 会话可一键全部失效：在设置页点一下，所有已登录的设备立即退出，下次访问需重新输入用户名和密码（不再担心旧登录残留）
- 多站点：一个网关可同时服务多个域名或 IP
- 完整体验：远程访问与本地一致，实时消息等长连接功能正常工作
- 配置热生效：改配置立即生效，无需重启

安装

dsh plugin --profile web add dsh-gateway

重启 web 应用后，网关默认只在本机 127.0.0.1:3443 上监听、且没有任何账号——谁都登录不进去（fail-closed，安全优先）。要让别人能访问，按下面的「快速开始」配置账号与监听地址。

快速开始

以“局域网内另一台机器访问”为例：

1. 配置登录账号与监听地址（设置页的 Remote Gateway 卡片，或直接编辑 $DSH_HOME/settings.yaml）：

gateway:
listenHost: '0.0.0.0'   # 监听所有网卡，允许局域网访问
users:
admin: 'scrypt$...'   # 用 node scripts/hash-password.mjs '你的密码' 生成

2. 记住网关端口（默认 3443）。
3. 在另一台设备浏览器打开 https://本机IP:3443，首次访问需信任自签证书，然后登录即可使用。

从互联网访问：在路由器上做端口映射，把外部端口转发到本机 gateway.port，用公网 IP（或域名）访问；使用域名时建议配置自己的证书。

注意：示例中的 admin / change-me 只是演示用。只要该凭据仍在生效，网关就拒绝在非本机地址上启动。

配置

所有配置走 $DSH_HOME/settings.yaml 的 gateway: 段，也可以在 DSH 设置页的 Remote Gateway 卡片里直接修改（两者完全等价：同样校验、持久化、热生效）。

gateway:
enabled: true            # false = 完全停用
listenHost: '127.0.0.1'  # 监听地址：127.0.0.1 = 仅本机；0.0.0.0 = 所有网卡
port: 3443               # 对外端口
upstream: ''             # 留空 = 自动跟随 DSH web 服务端口
sessionDays: 30          # 会话有效期（天）
loginFailLimit: 5        # 每 IP 连续登录失败次数上限
lockoutSeconds: 60       # 超过上限后的锁定秒数
users:                   # 登录账号（值为密码哈希，推荐）
admin: 'scrypt$...'
sites:                   # 站点列表：只响应这里列出的域名/IP
- hosts: ['你的域名', '你的IP']
cert: '证书路径'      # 留空 = 自动生成
key: '密钥路径'

- 默认 users 为空、listenHost 为 127.0.0.1：不配置 = 无人可登录、仅本机可达
- sites[].hosts 支持 .example.com 通配；网关只响应白名单内的域名/IP
- 密码生成哈希：node scripts/hash-password.mjs '你的密码'；设置页保存的密码会自动哈希，无需手动生成

设置页配置面板

安装后，DSH 设置页会出现 Remote Gateway 卡片，可完成：

- 查看运行状态（运行中 / 已停用 / 异常 / 重启中，右上角状态点实时反映）
- 启用 / 停用、一键重启——每次操作都有明确反馈（“正在重启… → 重启成功”，失败显示原因）
- 修改绑定 IP 与端口：保存后监听自动重启，并等待就绪后提示结果
- 管理登录账号：新增 / 修改 / 删除（删除有确认），密码自动哈希存储
- 使所有登录会话失效：一键让所有已登录设备退出（有确认），下次访问需重新登录
- 查看最近日志（每 3 秒自动刷新）

证书、多站点、限速等配置仍走 settings.yaml 的 gateway: 段。

衔接条件（使用前确认）

- 局域网访问：本机与访问设备在同一网络；listenHost 为 0.0.0.0；端口未被防火墙拦截
- 互联网访问：路由器已配置端口映射；用域名时，域名需解析到本机并配置证书
- 建议：让 DSH 本体只绑定本机 127.0.0.1，使所有远程访问都经过网关的登录保护（见「安全基线」第 3 条）

安全基线

1. 不要使用示例凭据：users 中不得保留 admin / change-me——非本机监听下网关会拒绝启动（强制门禁，不只是告警）
2. 密码不以明文存储：优先使用密码哈希（设置页保存会自动哈希；手写配置见上面的生成命令）
3. DSH 本体只绑回环：在 web profile 的 cordis.patch.yml 中把 webserver 锁定到 127.0.0.1：
- id: webserver
config:
host: '127.0.0.1'
port: 3080

4. 配置站点白名单：sites[].hosts 只列你实际使用的域名/IP
5. 会话说明：登录令牌在到期前有效（默认 30 天）；改密码不会让已登录的设备退出。需要让所有客户端重新登录时，在设置页点「退出所有登录」（轮换签名密钥，立即生效）；需要撤销单个用户时，删除该账号即可
6. 端口映射：路由器把外部端口转发到本机 gateway.port

反向代理行为(v1.7.0)

网关默认以 loopback 伪装模式转发请求：上游看到的是 127.0.0.1:
的 Host/Origin，而不是客户端的真实域名。效果：

- DSH 的 API 信任围栏（要求 Host 为回环地址或 --trusted-host 白名单）无需任何
启动参数即可放行，包括凭据 / 设置等特权 API——不需要再给 dsh web 传
--trusted-host*
- 上游返回的绝对 Location 头会自动改写回客户端的公开地址（https:///...）
- WebSocket 升级走同一转发逻辑，无需额外配置
- sec-fetch-site: cross-site 的跨站请求仍被上游拒绝，CSRF 防护不受影响
- DSH 进程 token 中继（自动建立会话）：远程浏览器登录网关后，若上游对文档请求
返回 401（浏览器还没有 DSH 的 dsh-auth- 会话 cookie），网关会用本进程的 DSH 启动
token* 回一次 302 /?token=，让浏览器无感完成 DSH 会话建立——否则远程设备拿不到
只存在于 web 进程 stdout / 托盘日志里的进程 token，只能停在 401 页。中继严格限定为
GET + 文档导航 + URL 未带 token 参数，并下发一枚 60 秒标记 cookie dsh_gw_relay：
若 token 已过期（web 进程重启过），交换会再次 401，标记 cookie 保证只跳这一次、绝不循环。
非文档请求（fetch/XHR/资源）的 401 一律原样透传。此改动需重启 dsh web 进程后生效。

Windows 托盘启动器（可选）

tools/dsh-tray/ 附带一个 Windows 托盘小工具，用于隐藏命令行窗口并以菜单方式管理 DSH 实例（启动 / 重启 / 停止 / 打开页面等），实例异常退出时会弹气泡通知。

开发

npm install
npm test        # node:test 单元测试

- lib/：核心逻辑（认证、代理、证书、HTTPS 服务器），与插件框架无关，可独立测试
- dsh/index.js：插件封装（配置解析、生命周期、热重载、安全守卫）
- client.js：设置页卡片（浏览器端）
- scripts/：配套脚本（hash-password.mjs 生成密码哈希等）

License

MIT