前言¶
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 的風險。
