前言¶
把 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。
