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，安全优先）。要让别人能访问，按下面的「快速开始」配置账号与监听地址。

快速开始

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

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

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

• 记住网关端口（默认 3443）。

• 在另一台设备浏览器打开 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 条）

安全基线

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

  - id: webserver
    config:
      host: '127.0.0.1'
      port: 3080
  

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

反向代理行为(v1.7.0)

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

• DSH 的 API 信任围栏（要求 Host 为回环地址或 --trusted-host 白名单）无需任何 启动参数即可放行，包括凭据 / 设置等特权 API——不需要再给 dsh web 传 --trusted-host
• 上游返回的绝对 Location 头会自动改写回客户端的公开地址（https://<clientHost>/...）
• WebSocket 升级走同一转发逻辑，无需额外配置
• sec-fetch-site: cross-site 的跨站请求仍被上游拒绝，CSRF 防护不受影响

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