前言¶
DSH 的插件化思路適合把擴展能力作爲獨立包接入。對於需要把 WebUI 暴露給團隊、反代或局域網訪問的場景，一個常見問題是：未登錄的瀏覽器是否還能讀取頁面資源、調用接口、建立即時連接。
dsh-webui-auth 針對這個點提供一個持久化認證插件：先在設置中創建賬號密碼，之後訪問 WebUI 需要先登錄。
這是什麼¶
dsh-webui-auth 是 DeepSeek Harness（DSH）的 WebUI 身份認證插件，許可證爲 MIT，零依賴。
它做的事情比較集中：在 DSH WebUI 前增加登錄門禁。創建賬號密碼後，未認證的瀏覽器無法加載 WebUI 的資源、調用接口或建立即時連接。認證在 HTTP/傳輸層強制執行。
核心能力¶
下面介紹它已具備的能力。
- 四層防護：覆蓋 WebUI 資源、插件 bundle、
/apiRPC 接口、WebSocket。 - 不改動 DSH 核心包源碼：通過運行時包裝
webServer路由實現。 fail-closed：預期路由缺失或包裝不完整時拒絕啓用認證。- 會話持久化：服務端會話寫入
sessions.jsonl，由HttpOnly; SameSite=LaxCookie 攜帶。 - 憑據存儲：密碼以
scrypt哈希保存在dsh-webui-auth.json，明文不落盤。 - 登錄限流：登錄失敗按客戶端 IP 限流，每分鐘最多 5 次。
- 審計日誌：安全事件追加寫入
audit.jsonl，客戶端 IP 以HMAC-SHA256假名化存儲。 - 首次初始化：需要每次啓動生成的
setup token。 - 安全頭：登錄頁與 API 響應帶嚴格 CSP、
nosniff、DENY、no-referrer、noindex、no-store。 - 外觀：登錄頁與設置頁跟隨 DSH 自帶外觀設置。
- 零依賴。
安裝與啓用¶
先執行安裝命令：
npx @deepseek-ai/dsh plugin --profile web add dsh-webui-auth
安裝後重啓 DSH 即生效。
首次啓用時，先打開 WebUI 的「設置 → 身份認證」，或訪問：
/dsh-webui-auth/login
然後輸入啓動日誌中打印的 setup token，創建賬號密碼。
啓用後：
1、未登錄訪問任意路徑會跳轉登錄頁。
2、登錄後按會話有效期免登錄，默認 12 小時。
3、修改、禁用、退出均需當前密碼。
4、修改密碼會弔銷所有其他已登錄會話。
如果忘記密碼，刪除數據目錄中的 dsh-webui-auth.json。最多 1 分鐘內認證會自動關閉，之後用新的 setup token 重新創建賬號。
審計與數據文件¶
審計日誌追加寫入 audit.jsonl。可以通過 CLI 查看：
node index.js audit --limit 50
數據目錄按安裝方式區分：
- npm / GitHub / tarball 安裝：插件包體位於
node_modules內，數據目錄爲node_modules上級的.dsh-webui-auth/。 - 本地 link / 源碼安裝：數據目錄爲插件源碼目錄。
- 兜底目錄：
$DSH_HOME/dsh-webui-auth/。
從 0.3.x 升級時，運行數據不自動遷移。需要手動拷貝以下文件：
dsh-webui-auth.json
sessions.jsonl
audit-hmac-key
audit.jsonl
使用注意與邊界¶
以下邊界在安裝和部署前最好先確認。
- 插件以當前
dsh進程權限運行，安裝前應檢查源碼與許可證。 - WebSocket 升級仍受核心
isTrustedApiRequest限制。反代或局域網部署時，需要把對外域名加入client-connection.trustedHosts。 - 運行時路由包裝在熱重載到下一次重掃之間存在不超過 10 秒的未保護窗口。
- 反代與 DSH 不在同一臺機器時，代理頭不被信任，限流會按代理 IP 聚合。
- 審計日誌中的 IP 假名化不能防止擁有文件權限的本地攻擊者。
- 威脅模型爲瀏覽器/網絡客戶端。能直接讀寫宿主進程內存或文件的本地進程不在防護範圍內。
0.1.x的 SHA-256 憑據自0.2.0起不再可校驗。需要刪除憑據文件後重新創建賬號。
適用場景¶
dsh-webui-auth 適合需要給 DSH WebUI 增加登錄門禁的受控訪問場景：賬號密碼一次創建後會話可持久化，認證覆蓋資源、接口和 WebSocket，審計日誌可本地查看，部署上不需要改動 DSH 核心源碼。
GitHub 倉庫地址：
