前言¶
DSH 的插件生態強調「一切皆插件」；社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係。dsh-auth-gate 是這個生態裏的一個認證插件，目標很具體：給 DSH web 實例增加一道登錄門，使頁面、API 調用和 WebSocket 連接都需要有效會話。
它適合需要把 dsh web 實例開放給瀏覽器用戶和腳本調用的場景。經過這個插件後，未登錄的瀏覽器訪問會看到登錄頁，腳本請求則需要顯式攜帶令牌或會話憑據。
這是什麼¶
dsh-auth-gate 是 DSH web 實例的登錄門插件。
倉庫地址爲 https://github.com/TecFancy/dsh-auth-gate。已抓取資料沒有單獨的 author / maintainer 字段，因此本文只把地址中的 TecFancy 作爲 owner 線索，不把它當成正式維護者聲明。
資料中可見的基礎信息包括：
- 許可證：MIT。
- 運行環境要求：
Node >=22.19.0。 package.json聲明瞭兩個 bin：dsh-auth和dsh-auth-proxy。已覈實資料詳細列出的是dsh-auth的用戶管理命令。
核心能力¶
統一攔截頁面、API 和 WebSocket¶
dsh-auth-gate 的核心行爲是：頁面、API 調用和 WebSocket 連接都需要有效會話。沒有有效會話的訪問會被擋下，瀏覽器側可走登錄頁，腳本或 curl 請求則需要使用 Authorization: Bearer <token> 跳過登錄頁。
兩種認證模式¶
插件支持兩種認證模式：
- 密碼認證：使用用戶名和口令。
- 共享令牌認證：使用一個共享密鑰。
默認掛載配置爲 mode: token，共享密鑰使用 DSH_AUTH_TOKEN 環境變量保存。
可選 TOTP 兩步認證¶
密碼模式下支持可選的 TOTP 兩步認證，遵循 RFC 6238。totp 可配置爲 off、optional 或 required。
啓用某個用戶的 TOTP 後，登錄時需要額外輸入驗證碼。驗證碼每 30 秒變化，並允許前後窗口容差。
默認安全策略¶
已覈實資料中列出的默認安全策略包括：
- 口令以哈希存儲。
- 登錄嘗試會受限速。
- 會話 cookie 使用
secure設置。 - 配置缺失或損壞時會阻止訪問，而不是靜默放行。
用戶管理 CLI¶
插件提供 dsh-auth CLI，用於：
- 添加用戶。
- 列出用戶。
- 禁用用戶。
- 啓用或禁用 TOTP。
安裝與啓用¶
先安裝插件到 web profile：
dsh plugin --profile web add dsh-auth-gate
這個命令會把插件安裝到對應 profile 中。安裝後，CLI 不直接加入 PATH，需要通過 profile 調用。
如果啓用密碼模式，先創建管理員賬戶。示例中通過 pnpm --dir 進入 web profile 目錄執行 dsh-auth：
printf '%s\n' 'choose-a-strong-password' | pnpm --dir "$DSH_HOME/profiles/web" exec dsh-auth user add admin --password-stdin
接着在 $DSH_HOME/cordis.patch.yml 中覆蓋掛載配置。下面示例只覆蓋 mode、totp 和 cookieSecure：
- id: dsh-auth-gate
config:
mode: password
totp: optional
cookieSecure: true
經過上面的步驟後，訪問 DSH web 實例時會進入登錄門。默認 cookieSecure: true 適合 HTTPS 環境；只有在普通 http 測試時才考慮將其設爲 false。
配置項¶
已覈實資料列出以下配置項：
| 配置項 | 說明 |
|---|---|
mode |
認證模式。默認掛載配置爲 token，也可配置爲 password。 |
totp |
密碼模式下的 TOTP 策略，可配置爲 off、optional 或 required。 |
sessionTtl |
登錄會話有效期，單位爲秒。默認爲 604800。 |
cookieName |
會話 cookie 名稱。 |
tokenRef |
令牌模式下引用的環境變量。默認掛載配置使用 DSH_AUTH_TOKEN。 |
cookieSecure |
會話 cookie 的 secure 設置。默認爲 true，僅普通 http 測試時才考慮設爲 false。 |
usersFile |
密碼模式下的用戶列表文件位置。資料說明默認爲 $DSH_HOME/auth/users.yaml。 |
logoutOrder |
控制 Settings → General 中 Sign out 按鈕的槽位順序，數值越大越靠下。 |
典型用法¶
管理用戶¶
資料中列出的用戶管理命令包括：
dsh-auth user add admin --password-stdin
dsh-auth user list
dsh-auth user disable admin
dsh-auth user totp enable admin
dsh-auth user totp disable admin
如果插件是通過 dsh plugin --profile web add dsh-auth-gate 安裝到 profile 中，可以按 profile 調用，例如：
pnpm --dir "$DSH_HOME/profiles/web" exec dsh-auth user list
啓用 TOTP¶
爲某個用戶啓用 TOTP：
dsh-auth user totp enable admin
命令會輸出 TOTP secret 或 otpauth:// URI。將該 secret 或 URI 添加到驗證器應用後，用戶即可在密碼模式下使用驗證碼登錄。
腳本請求¶
腳本或 curl 請求可以攜帶 Bearer token 跳過登錄頁：
Authorization: Bearer <token>
適用場景與注意¶
適合以下場景：
- DSH web 實例需要對外提供服務，但頁面、API 和 WebSocket 都需要登錄校驗。
- 瀏覽器用戶走登錄頁，自動化腳本走 Bearer token。
- 密碼模式下需要管理多個用戶，並對部分或全部用戶啓用 TOTP。
注意以下事項：
- 該插件會以當前 DSH 進程權限運行，安裝前應檢查源碼和許可證。本插件許可證爲 MIT。
- 共享令牌模式下，
DSH_AUTH_TOKEN是敏感憑據，應避免寫入倉庫或日誌。 cookieSecure默認爲true，僅在普通http測試時才考慮關閉。- 配置缺失或損壞時會阻止訪問，這是預期行爲，不是靜默放行。
- TOTP 驗證碼每 30 秒變化，並允許前後窗口容差。
相關鏈接¶
GitHub 倉庫：https://github.com/TecFancy/dsh-auth-gate
如需在 DSH 社區目錄中查找，可在獨立目錄站點中檢索 dsh-auth-gate。
