前言¶
DSH（DeepSeek Harness）采用插件化架构，其 Web GUI 提供了强大的可视化管理能力。但在将 DSH Web 暴露在局域网或公网时，直接暴露端口意味着绕过了 SSH 层的访问控制，使得具备 Bash 执行能力的 Agent 直接暴露在风险之下。缺乏内置的 HTTP 认证机制，使得 Web UI 在反代场景下处于“裸奔”状态。
下面介绍 dsh-web-auth，一个为 DSH Web 增加密码访问认证与反代友好配置的插件。它通过登录页和 HttpOnly 签名 Cookie 实现了全站访问控制，并处理了 WebSocket 升级与反向代理环境下的 Cookie 安全问题。
插件介绍¶
- 名称:
fonlan/dsh-web-auth - 定位: DSH Web 插件，提供密码门认证（登录页 + HttpOnly 签名 Cookie），用于在反向代理后暴露 DSH Web。
- 维护者: fonlan
- 类别: admin-security
- 许可证: MIT
核心功能¶
该插件通过服务端拦截与客户端 Cookie 签发，实现了以下能力：
- 登录页与 Cookie 管理：提供登录页，使用 HMAC-SHA256 对 Cookie 签名，7 天滑动续期。浏览器自动携带 Cookie，覆盖 HTTP、WebSocket、SSE 及静态资源。
- 首次引导与改密：未配置密码时显示设置表单。支持 GUI 改密，改密会轮换签名密钥并强制全员下线。
- 防爆破：基于 IP 的限速机制，连续失败触发指数退避，15 分钟内累计限制。
- 反代友好：Cookie 自动标记
Secure（跟随x-forwarded-proto），限速信任反向代理的X-Forwarded-For。 - 监听地址切换：支持在设置卡片中一键切换监听地址（
127.0.0.1<->0.0.0.0），热生效，无需重启进程。 - 远程设置解锁（可选）：通过配置开启后，允许已登录用户在反代域名下访问设置面（模型页、插件配置等），默认关闭。
- 启动令牌收口：插件接管 DSH 的启动令牌逻辑，无需用户手工访问
?token=链接，登录后自动续期 DSH 会话。 - 密码存储：使用 scrypt 加盐哈希存储，文件权限 0600，不落明文。
安装与启用¶
安装插件需要 DSH 版本 0.1.5 起。
1、通过命令行安装：
dsh plugin --profile web add @fonlan/dsh-web-auth
2、重启 DSH Web 进程使插件生效。
3、首次设置密码：重启后访问 dsh web，系统会自动重定向到登录页。如果未设置过密码，页面将显示“设置访问密码”表单。输入 ≥8 位的新密码并确认即可完成初始化。
典型用法¶
修改密码¶
登录后进入 设置 → 插件 → 插件配置 → 访问认证 卡片，点击改密。需输入旧密码，新密码设置成功后，旧会话立即失效。
切换监听地址¶
在“访问认证”卡片底部，可以切换监听地址。
* 127.0.0.1：仅本机可访问。
* 0.0.0.0：监听所有网卡，局域网可访问。
切换操作会通过 HMR 热重载 WebServer，WebSocket 会短暂断开后自动重连。
启用远程设置解锁¶
默认情况下，通过反代域名访问时，设置页面会报错（因为 dsh 客户端判定域名非回环地址）。如需启用，需在 profile 的 cordis.patch.yml 中添加配置：
- id: web-auth
config:
unlockRemoteSettings: true
行为细节¶
插件对各类请求的处理逻辑如下：
| 场景 | 行为 |
|---|---|
| 未登录访问页面 | 302 重定向到 /login?next=原路径 |
| 未登录访问 API | 401 JSON 响应 |
| DSH 启动令牌交换 | 仅插件服务端 mint 重入，或持有插件会话的请求放行，并将响应中的 dsh-auth Set-Cookie 转发给浏览器 |
| 浏览器直接打开旧令牌 URL | 302 到 /login，并丢弃 token 参数（旧令牌重启后即失效） |
| 反代域名下已登录访问 | 请求被改写为回环来源，插件围栏不再拦截 |
| 反代域名下设置页 | 默认报错（settings are unavailable）；开启 unlockRemoteSettings 后可用 |
| 跨站请求 | 403 拒绝 |
| 未登录 WebSocket 升级 | 401 拒绝握手 |
| 会话过期 | 跳回登录页；若剩余时间 < 24h，自动刷新续期 |
| 修改密码 | 轮换密钥，全员下线 |
| 切换监听地址 | 写入 settings，触发 HMR 重绑 webserver |
安全模型与风险¶
使用该插件时，需特别注意以下安全点：
- 认证是访问控制，不是安全边界：DSH Agent 拥有 Bash 执行能力，即使有密码保护，也不要将其视为不可攻破的堡垒。
- 首密窗口期：未设置密码时，任何人都能访问登录页并抢注密码。建议在安装后第一时间设置密码，或通过 SSH 端口转发完成首密设置后再开放网络。
- 会话无状态：服务端无法单独吊销会话，密码泄露需修改密码以轮换签名密钥。
- 存储位置：密码哈希与密钥存放在
$DSH_HOME/web-auth/，权限 0600。 - 限速限制：限速为进程内存级，多实例部署时各自独立。
开发¶
插件的源码与构建逻辑如下：
pnpm install
npm run build # host: tsc；client: esbuild
npm run typecheck
npm run test # 单元 + 集成测试
总结¶
dsh-web-auth 通过轻量级的插件方式，为 DSH Web 提供了必要的认证与反代支持。它解决了“Web 界面如何安全暴露”的问题，同时也通过严格的会话管理、防爆破机制和透明的令牌收口，降低了直接暴露 Web UI 的风险。
