DeepSeek Harness (DSH) 插件：dsh-web-auth

前言¶

DSH 的 web 進程默認只綁定 127.0.0.1，並且其 /api 的 Host 信任柵欄會把非 loopback 來源的請求全部 403（防 DNS-rebinding / cross-origin）。通過 frp 隧道暴露的訪問因此被攔下。DSH 本身沒有面向公網訪問者的登錄/密碼層。直接開啓 --trusted-host 只是“給公網 IP 開柵欄縫”，不等於認證。

dsh-web-auth 插件把柵欄和認證合併成一個正確架構：它是一個跑在 DSH web 進程裏的 loopback 反向代理，給經 frp/隧道暴露的 DSH Web 提供 token 登錄和會話管理。

插件介紹¶

dsh-web-auth 是 DSH Web 的公網鑑權門。插件運行在 DSH 進程內部，通過反向代理將請求轉發至本地 DSH Web，並處理 Token 登錄與 HttpOnly 會話 Cookie。

核心功能¶

反向代理到 DSH Web
Token 登錄認證
HttpOnly 會話 Cookie（默認 12 小時，支持滑動續期）
支持 X-DSH-Auth 頭，供腳本或工具免 Cookie 訪問
WebSocket 透傳
同源 IP 連續失敗限速（10 次觸發 10 分鐘）

安裝與啓用¶

通過插件命令將倉庫安裝進指定 profile：

dsh plugin --profile web add <git 倉庫地址>

安裝後，需要在 profile 的 package.json 中將 dsh-web-auth 追加進 dsh.profile.bundles：

"dsh": {
  "profile": {
    "bundles": [
      "@deepseek-ai/dsh-base",
      "@deepseek-ai/dsh-web-app",
      "dsh-web-auth"
    ]
  }
}

隨後生成 token 文件：

openssl rand -hex 32 > ~/.dsh/web-auth-token

配置與行爲¶

插件提供了豐富的行配置項，所有配置均爲可選：

key	默認	說明
`gateHost`	`127.0.0.1`	gate 綁定地址
`gatePort`	`3081`	gate 監聽端口 (frpc 應指向這裏)
`targetHost`	`127.0.0.1`	DSH web 地址
`targetPort`	`3080`	DSH web 端口兜底值 (運行時優先取 `webServer.port`)
`token`	—	直接內聯 token
`tokenFile`	`web-auth-token`	token 文件名 (相對 `$DSH_HOME`) 或絕對路徑
`sessionTtlMinutes`	`720`	會話 cookie 有效期 (分鐘, 滑動續期)
`maxFails`	`10`	同 IP 連續失敗多少次觸發限速
`failWindowMs`	`600000`	限速窗口 (毫秒)

請求流程如下：

公網 → frp 隧道 → 127.0.0.1:3081 (gate, token 登錄) → 127.0.0.1:3080 (DSH web, Host=loopback → 柵欄放行)

具體行爲如下：

未登錄瀏覽器 GET 頁面：302 重定向到 /__dsh-auth__/login 登錄頁。
未登錄訪問 /api、靜態資源、WebSocket upgrade：返回 401。
登錄頁 POST /__dsh-auth__/login (攜帶 token 字段，JSON 或 urlencoded)：成功後簽發 HttpOnly 會話 Cookie，302 回原路徑。
請求攜帶 X-DSH-Auth: <token> 頭：免 Cookie 訪問。
POST /__dsh-auth__/logout：清 Cookie。
同源 IP 連續失敗 10 次：觸發 10 分鐘限速。

適用場景與注意¶

零外部依賴：僅使用 Node.js 內置模塊，要求 Node.js >= 18。
Fail Closed 機制：如果找不到 token，gate 不啓動，公網入口不可用，但 DSH 本體不受影響。
部署依賴：需配合 frpc 將 dsh-web 的 localPort 指向 gatePort (3081)。

生態背景¶

DeepSeek Harness (DSH) 理念是「一切皆插件」。本插件由 ChinaBoy0618 維護，開源協議爲 MIT。更多詳情可訪問插件目錄或 GitHub 倉庫。