dsh-gateway

Readme

# 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
- **完整体验**：远程访问与本地一致，实时消息等长连接功能正常工作
- **配置热生效**：改配置立即生效，无需重启

## 安装

```sh
dsh plugin --profile web add dsh-gateway
```

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

## 快速开始

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

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

   ```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** 卡片里直接修改（两者完全等价：同样校验、持久化、热生效）。

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

## Windows 托盘启动器（可选）

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

## 开发

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

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

## License

MIT