前言¶

如果要在 dsh web 前加登錄門禁，常見做法是在反向代理或外層服務上臨時擋一下。dsh-auth-gateway 是 xbzbing 維護的 Cordis 網關插件，MIT 許可，面向 DeepSeek Harness（dsh web）提供密碼認證、TOTP 雙因素認證、真實請求攔截、會話管理與登錄審計。

下面介紹它的能力、安裝方式、啓用 TOTP 的方法，以及卸載和密碼重置時的注意點。

這是什麼¶

dsh-auth-gateway 是一個網關層插件：它爲 dsh web 建立認證門禁，並在網關層攔截未認證的 HTTP 與 WebSocket 請求。它不是單純給頁面加一個登錄框，而是把認證、會話、限流和審計放在 dsh web 的請求路徑上處理。

維護者爲 xbzbing，許可證爲 MIT。README 說明本項目已支持 dsh 0.1.1-rc.2；package.json 聲明 Node >= 20。

核心能力¶

先做密碼門禁，再按需要啓用 TOTP。下面列出它覆蓋的主要事項：

• 爲 dsh web 提供密碼認證門禁
• 支持 TOTP 雙因素認證與一次性備份代碼
• 在網關層攔截未認證的 HTTP 與 WebSocket 請求
• 記錄登錄成功、失敗、登出、改密與暴力破解告警的審計日誌
• 提供密碼失敗鎖定、全局登錄速率限制與 OTP/備份碼獨立限流
• 提供基於內存 token 與 HttpOnly Cookie 的會話管理
• 支持反向代理子路徑 basePath 與可選認證設置面板

安裝與啓用¶

安裝插件：

dsh plugin --profile web add dsh-auth-gateway

啓動 dsh web：

dsh web --port 8080

首次部署後，會生成一次性初始密碼，並打印在控制檯。先複製初始密碼，再打開 dsh web 頁面登錄。

登錄後會進入個人密碼設置步驟。個人密碼設置是強制步驟，完成前所有功能不可用。經過上面的步驟後，後續訪問 dsh web 會先經過登錄門禁。

啓用 TOTP¶

如果啓用 TOTP，登錄後訪問：

/otp/setup

在該頁面啓用 TOTP，並保存一次性備份代碼。已啓用 OTP 後，登錄需要密碼 + 驗證碼（或備份代碼）。

OTP 密鑰以 AES-256-GCM 加密存儲。主密鑰可以來自環境變量：

DSH_AUTH_GATEWAY_MASTER_KEY

也可以來自自動生成的：

auth-gateway/otp-master.key

會話、限流與審計¶

會話管理使用內存 token 與 HttpOnly Cookie。

防護策略包括：

• 密碼失敗鎖定
• 全局登錄速率限制
• OTP/備份碼獨立限流

審計日誌會記錄登錄成功、登錄失敗、登出、改密與暴力破解告警。日誌持久化到：

$DSH_HOME/auth-gateway/audit.log

按天輪轉，保留 90 天，不記錄憑據。

子路徑部署¶

如果 dsh web 不是部署在根路徑，而是放在反向代理子路徑下，子路徑部署時需要在部署方 profile patch 中配置 basePath。插件本身也提供可選認證設置面板。

密碼重置與卸載¶

忘記密碼時，可以用 dsh-auth-gateway-reset 重置，重啓後控制檯會打印新初始密碼。

卸載時先清憑據，再移除插件：

~/.dsh/profiles/web/node_modules/.bin/dsh-auth-gateway-uninstall
dsh plugin --profile web remove dsh-auth-gateway

適用場景與注意¶

適合以下場景：

• 需要給 dsh web 加密碼登錄門禁
• 需要 TOTP 雙因素認證與備份代碼
• 需要攔截未認證 HTTP 與 WebSocket 請求
• 需要保留登錄審計與限流記錄

安裝前需要注意：

• 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證
• 許可證爲 MIT
• README 說明支持 dsh 0.1.1-rc.2，運行環境需要 Node >= 20
• 存在一項記錄在案的安全例外：LAN trust 爲域名/反代訪問模型設置頁做最小介入

相關鏈接¶

GitHub：

https://github.com/xbzbing/dsh-auth-gateway

插件目錄線索（以實際目錄爲準）：

https://www.skillhub.cn/plugins/xbzbing/dsh-auth-gateway