dsh-login-gateway：爲 DeepSeek Harness Web UI 增加 TOTP 登錄

前言¶

DeepSeek Harness (DSH) 的 Web UI 默認通過進程啓動令牌進行認證，這種機制在本地開發時很方便，一旦端口暴露到公網，任何持有該令牌的人都能直接訪問 Harness，存在安全隱患。dsh-login-gateway 插件在不修改 Harness 核心代碼的前提下，在 Web UI 前面加了一道用戶名、密碼和 TOTP 二次驗證的網關。

這是什麼¶

dsh-login-gateway 是 DeepSeek Harness (DSH) 的一個插件，由開發者 ButterHost69 維護，許可證爲 MIT。它監聽獨立的端口，提供標準的登錄頁面，驗證通過後將流量轉發給 Harness，從而避免直接暴露未認證的 API。

核心功能¶

獨立監聽與路由：監聽自己的主機和端口，提供 /login、/logout 和 /_dsh-login-gateway/health 接口。
多因素認證：驗證用戶名、scrypt 哈希密碼以及 TOTP 代碼，簽發自己的 HMAC 會話 Cookie。
流量轉發：將認證後的請求（含 WebSocket 升級）轉發給 Harness，並保留瀏覽器側的 Host 頭。
服務端令牌交換：在服務端完成 Harness 的啓動令牌到 Cookie 的交換，瀏覽器端不接觸敏感憑證。
首次初始化：當沒有配置賬戶時，自動提供設置界面，生成 TOTP 密鑰並存儲憑證。
限流保護：針對客戶端地址和用戶名分別限制失敗的登錄嘗試次數。

安裝與啓用¶

安裝前需確保環境滿足要求：dsh 版本爲 0.2.1-alpha.1 或兼容版本，Node.js 版本爲 ^22.19 || >=24，並且已啓動 dsh web Web 配置文件。

從 GitHub 安裝（會自動構建）：

dsh plugin --profile web add -w github:ButterHost69/dsh-login-gateway

如果使用 pnpm >= 10，可能會因爲默認的安全策略拒絕運行 git 依賴的構建腳本。如果安裝失敗，需在 Web 配置文件的 pnpm-workspace.yaml 中添加 allowBuilds 配置：

allowBuilds:
  dsh-login-gateway: true

然後再執行一次 add 命令。

典型用法¶

安裝後，插件會處於首次運行狀態，此時需要在瀏覽器中設置第一個賬戶。

首次設置：訪問 http://127.0.0.1:8080/login（或通過隧道訪問帶 ?setup=... 的鏈接）。
創建賬戶：輸入用戶名和密碼。用戶名需以字母開頭，包含 2-32 個小寫字母、數字或連字符；密碼至少 12 個字符。
綁定 TOTP：提交後會出現 TOTP 密鑰和 otpauth:// URI，將其添加到 Google Authenticator 等應用中。
添加更多用戶：對於可復現的部署或後續添加用戶，使用插件提供的腳本生成配置並寫入 $DSH_HOME/profiles/web/cordis.patch.yml：

   cd /path/to/dsh-login-gateway
   npm install
   npm run build
   node scripts/enroll.mjs --username alice

將輸出的 passwordHash 和 totpSecret 填入 cordis.patch.yml 的 users 列表中。

暴露服務：將隧道或反向代理指向網關端口（默認 8080），而不是 Harness 的端口。例如使用 Caddy：

   harness.example.com {
     reverse_proxy 127.0.0.1:8080
   }

啓動 Harness 時需加上 --trusted-host 參數以允許外部 Host 頭：

   dsh web --trusted-host harness.example.com

適用場景與注意¶

適用場景：需要在公網或內網通過反向代理訪問 DSH Web UI，且需要強認證的場景。
權限風險：該插件以當前 DSH 進程的權限運行，建議安裝前檢查源碼和許可證（MIT）。
TLS 處理：網關本身只處理 HTTP，TLS 終止應在反向代理（如 Caddy、Nginx 或 Cloudflare Tunnel）處完成。
Host 頭依賴：反向代理必須保留瀏覽器側的 Host 頭並轉發 WebSocket 升級頭，否則 Harness 的 API 會返回 403。

短結尾¶

dsh-login-gateway 爲 DSH 提供了標準化的登錄入口，解決了公網暴露的安全痛點。更多配置細節和源碼，可在 GitHub 查看詳情。