前言¶
把 DeepSeek Harness（DSH）暴露到局域网或公网时，若仍依赖 dsh 自身入口，往往缺少「设备级」第二因素：谁从哪台终端进来、凭证变更后如何一次性作废所有会话，都需要额外设计。社区插件 dsh-pairing-gate（维护者 chjy090）在 dsh 前面加一道独立 HTTP/HTTPS 网关：TOTP 授权的扫码设备配对、用户名密码登录、通过后反代 dsh（含 WebSocket）。它与同名但功能不同的 TecFancy/dsh-auth-gate（密码/共享令牌 + 用户管理 CLI）不是同一套方案；npm 包名为 dsh-pairing-gate，本地插件目录名仍为 dsh-auth-gate。
下面介绍其定位、能力与安装用法；事实以仓库 README 与 package.json（当前版本 0.7.5，MIT 许可证）为准。
这是什么¶
dsh-pairing-gate 是 DSH 的 admin-security 类前台认证网关插件：在默认 127.0.0.1:3443 上监听，校验网关会话后把流量反代到本机 dsh（默认 http://127.0.0.1:3080）。目标模型是「单人自用」的 设备绑定即第二因素——已配对设备只需用户名 + 密码；新设备须先经 6 位 TOTP 授权生成配对二维码或链接。未通过网关认证的浏览器看不到 dsh 的 launch token，也拿不到 dsh 会话 cookie。
状态与密钥落在 dsh 状态目录下 $DSH_HOME/auth-gate/...；未设置 DSH_HOME 时回退到 ~/.dsh/auth-gate（含 admin.key、state.json、setup.token、network.json）。
核心功能¶
认证与配对¶
- 登录两要素：已配对设备 cookie（配对时由 6 位 TOTP 授权）+ 用户名密码（scrypt）。正常登录不填 TOTP；未配对设备返回
device_required。 - 新设备：管理页输入当前 6 位 TOTP 生成一次性配对二维码/链接（票据在 URL fragment，默认 120 秒；服务端只存 SHA-256）。
- 改密码 / 重置 TOTP 需当前密码，并会撤销全部设备与会话，所有终端需重新配对。
- 可选 Android 客户端 DSH-Mobile 扫码配对与设备令牌续期；App 扫码只接受 https 配对 URL。
会话与设备¶
- 滑动窗口 + 绝对上限：默认设备
deviceTtlDays: 90、deviceAbsoluteTtlDays: 365；Web 会话sessionTtlHours: 48、sessionAbsoluteTtlDays: 30（配置见 profile 内完整 override）。 - 默认最多 100 台设备；可单独吊销，吊销会级联删除该设备全部会话。
- 同一客户端可用
clientDeviceId重复配对，仍只占一条设备记录。
管理与网络¶
- Web 管理页
/__admin：账号、配对码、设备与会话、审计（API 最近 100 条）、网络设置。 - dsh 侧边栏「认证管理」原生 React 面板（非 iframe）：配对二维码、改密、重置 TOTP、设备/会话表格等；从 3080 直连时仅提示跳转 3443。
- 管理页可改 监听地址/端口、publicUrl（生成配对链接）、publicFingerprint（前置代理 TLS 时证书 pinning）；覆盖写入
$DSH_HOME/auth-gate/network.json，监听支持热重建。 - loopback 安全：管理页/
network.json禁止 loopback 监听地址；网关实际绑定 loopback 时会禁用「本机 loopback 即管理员」通道，仅保留 adminKey 与会话。
反代与安全细节¶
- HTTP(S) 与 WebSocket 反代；Host/Origin 改写、注入 dsh 会话 cookie、上游 401 自动刷新 cookie 重试一次。
- 限流：登录失败 15 分钟内 5 次锁 15 分钟；配对/续期、QR 签发等按 IP 限流（详见 README）。
- 网关是 dsh 前面的第二道门；能直连 3080 的人仍可能看到 dsh 自身登录入口，生产环境建议用防火墙限制 3080。
安装与启用¶
dsh plugin add 会自动注入 auth-gate，安装命令以 README 为准，不要重复写 insert:。
- 进入插件目录安装 npm 依赖（含
qrcode），再用 link 或 git URL 加入 profileweb，最后重启 dsh：
cd $PLUGIN_DIR && npm install --no-audit --no-fund # 首次安装 qrcode 依赖
dsh plugin --profile web add link:$PLUGIN_DIR # 也可以是一个 git URL
systemctl restart dsh
- 改配置应在 profile 的
cordis.patch.yml里对id: auth-gate做 整体 override（Cordis 对config整体替换，需写全字段，可复制仓库内config.example.json）。不要直接改插件包内的cordis.patch.yml，升级会覆盖。
典型用法：首次初始化与本机试用¶
仓库默认是可移植的本机 HTTP：127.0.0.1:3443 反代 127.0.0.1:3080，适合首装试用，不要直接暴露到公网。
- 启动后若未初始化，日志会出现一次性 setup 链接，也可读
setup.token：
auth-gate: setup required — open http://127.0.0.1:3443/__admin#setup=<token>
未设置 DSH_HOME 时 token 文件路径为 ~/.dsh/auth-gate/setup.token。在本机浏览器打开 http://127.0.0.1:3443/__admin#setup=<token>，按向导创建管理员、绑定 TOTP；完成后当前浏览器即被配对。
- 查日志示例：
journalctl -u dsh -n 200 --no-pager | grep 'setup required'
- 跨机 / 公网 / App 配对必须先改配置：网关需配置
tlsCert/tlsKey，且publicUrl与 TLS 一致（配 TLS 则publicUrl必须为https:；未配 TLS 则必须为http:）。App 无法用「代理终止 TLS + 明文回源 + 网关不配证书」的组合配对。两种常见拓扑：网关自身终止 TLS，或 Caddy/Nginx 对外终止 TLS 且 HTTPS 回源到网关（网关仍要自签证书等）。详见 README「快速开始」第 4–5 条与docs/installation.md。
请求路径概览：
手机 / 浏览器 ──HTTP/HTTPS(:3443)──> dsh-pairing-gate
├─ /__auth/* 登录、配对、续期、登出
├─ /__admin* 管理页与 API
└─ 其它路径 → 校验会话 → 反代 dsh（含 WS）
适用场景与注意¶
适合：单人或小规模自用，希望「可信设备 + 密码」访问 dsh，并需要 Web 管理、可选移动端扫码、frp 等场景下可配置 publicUrl / 证书指纹。
务必注意：
- 插件以 当前 dsh 进程权限 运行；安装前请自行审阅 GitHub 源码 与 MIT 许可证。
- 默认配置仅适合本机试用；生产、跨机、App 配对需按文档配置 LAN 监听、TLS 与
https://的publicUrl。 - 社区目录 SkillHub 插件页 与 GitHub 为独立生态信息源，与 DeepSeek / 幻方无官方从属关系；DSH 理念是「一切皆插件」，选型以仓库文档为准。
结尾¶
dsh-pairing-gate 把 TOTP 授权的扫码配对、滑动会话与 dsh 反代收进一个可配置的网关层，适合在暴露 DSH 前补上设备级第二因素。进一步了解可查阅 SkillHub 目录页 与 GitHub 仓库 README。
