前言¶
DeepSeek Harness (DSH) 採用插件化架構，Web GUI 默認以迴環地址對外提供服務。在需要直接對外暴露或在內網多環境共享時，直接訪問缺乏鑑權機制。本插件在 DSH Web 前面加一道靜態令牌登錄牆，無需修改 DSH 源碼即可爲 Web 服務增加令牌校驗與訪問控制。
是什麼¶
dsh-auth-proxy 是一個由 wxyzh 維護的插件。它監聽在本地地址（默認 127.0.0.1:8443），未認證訪問顯示內置登錄頁，校驗令牌後簽發 HttpOnly 會話 cookie，再把 HTTP 與 WebSocket 流量轉發給迴環的 dsh webserver（默認 127.0.0.1:3080）。
安裝與啓用¶
安裝插件需要確保 pnpm 在 PATH 上。插件會自動掛進 web profile roster。
dsh plugin --profile web add @wxyzh/dsh-auth-proxy
核心功能¶
- 令牌鑑權反向代理：提供內置登錄頁，使用 SHA-256 + timingSafeEqual 校驗令牌，避免時序側信道攻擊。
- HttpOnly 會話 Cookie：會話爲 HttpOnly、SameSite=Lax 的簽名 Cookie，Max-Age 設爲 10 年。服務端不存會話，重啓後 Cookie 依然有效；但更換令牌會使所有已登錄會話立即失效。
- IP 白名單與失敗鎖定：支持 CIDR 格式的 IPv4 白名單，可配置失敗鎖定閾值與時長。
- 配置實時可改：通過 Host 的 settings 分區管理，無需重啓或重啓進程即可修改配置。
- 品牌層重寫：支持在代理層重寫頁面標題、favicon、PWA manifest，支持注入側邊欄視覺。
- web-all 兼容：兼容
web-all插件，還原/remote前綴，適配移動端設置面板的響應式佈局。
配置¶
插件通過 Host 的 settings 管理配置，支持熱更新。
組合入口配置示例：
enabled: true
host: 127.0.0.1
port: 8443
targetHost: 127.0.0.1
targetPort: 3080
# 推薦使用環境變量
token: !!js process.env.DSH_AUTH_TOKEN
brand.enabled: true
brand.title: 'MyApp'
accessUrls: ['https://my-app.example.com']
allowedIps: ['127.0.0.1', '10.0.0.0/8']
maxFailures: 0
lockoutMinutes: 15
配置項說明：
* token：共享訪問令牌。安全默認爲空或佔位符 change-me 時，代理保持禁用、絕不監聽。
* brand：開啓後進行品牌層重寫，支持自定義標題、圖標和側邊欄視覺。
* accessUrls：僅用於展示，聲明對外訪問的入口地址（可含 HTTPS 域名）。
* allowedIps：IP 白名單，留空則一律要令牌。
注意事項與限制¶
- 無 TLS：插件本身不處理 TLS，禁止綁通配或公網 IP（如
0.0.0.0或公網 IP）。外部訪問請在前方掛 TLS 反向代理（如 nginx/Caddy）終止加密後回指本監聽地址。 - 無單點剔除：會話爲無狀態簽名 Cookie，重啓不失效，但更換令牌即全體下線，登出僅清客戶端 Cookie。
- 移動端耦合：移動端設置面板的摺疊與寬度優化耦合了
web-all的結構，若 web-all 語義級重構可能影響適配。 - 配置分層：僅通過 Host 的 settings 寫入，不提供獨立的配置文件。
總結¶
dsh-auth-proxy 提供了一個輕量級的令牌鑑權層，通過在本地端口監聽並轉發流量，實現了對 DSH Web GUI 的安全訪問控制。適合需要在無源碼改動的情況下爲本地 DSH 實例增加鑑權能力的場景。
