前言¶

DeepSeek Harness 的擴展思路是「一切皆插件」；插件目錄是獨立站點，不等同於 DeepSeek 或幻方官方應用商店。

一個常見場景是：DSH Web 本應在本機 loopback 上運行，運維人員希望通過 HTTPS 從瀏覽器訪問，但不希望頁面、API、下載、SSE、WebSocket 在未登錄狀態下直接暴露。dsh-auth 是針對 DeepSeek Harness 的非官方社區插件，用於給 DSH Web 增加管理員登錄。它由 hxy91819 維護，核心做法是讓 Harness 保持在 loopback，再安裝一個項目持有的 Caddy forward_auth edge 來統一做登錄校驗。

這是什麼¶

dsh-auth 是 DeepSeek Harness 的社區插件，用於給 DSH Web app 增加 secure administrator login。

• GitHub 倉庫：https://github.com/hxy91819/dsh-auth
• package.json 中版本：0.2.3
• README 提供精確版本安裝：dsh-auth@0.2.3
• 許可證類型在本次資料中未確認；資料中只出現 LICENSE 文件和 license badge。

核心能力¶

下面介紹已覈實的 dsh-auth 能力：

• 讓 Harness 保持在 loopback，並安裝項目持有的 Caddy forward_auth edge，覆蓋 pages、APIs、downloads、SSE、WebSockets。
• 提供 interactive setup、plan preview 和 non-interactive JSON setup。
• 支持通過 password 或 login-token 進行管理員初始化。
• Password source 會經過 Argon2id hash，不以 plaintext 存儲。
• 支持 HTTPS，並支持 automatic 或 manual TLS；automatic TLS 是 HTTPS default。
• 複製 checksum-verified 的 bundled Caddy binary，並啓用獨立的 dsh-auth-caddy.service。
• 支持可選的中文和英文 token-failure 頁面文案。
• 支持 --behind-tls-proxy，用於保持 managed HTTP edge 在 loopback、要求可信 HTTPS forwarding headers，並 issue Secure cookies。

安裝與啓用¶

插件預安裝不等於啓用認證¶

先執行下面的命令，將 dsh-auth bundle 添加到 DSH Web profile：

dsh plugin --profile web add dsh-auth

這一步只增加 bundle，不等於已經啓用認證。插件命令不會創建 secrets、不會安裝 Caddy、也不會保護任何內容。啓用認證仍需全局安裝 CLI 並運行 sudo dsh-auth setup。

安裝 CLI¶

安裝當前穩定版 CLI：

sudo npm install -g dsh-auth

如果你需要按供應鏈策略鎖定版本，可以安裝 README 中給出的精確版本：

sudo npm install -g dsh-auth@0.2.3

運行 setup¶

正常部署需要 Linux x64 或 ARM64、systemd、Node.js 24.7 或更高版本，以及 DSH Web 0.1.0-rc.7。

運行交互式 setup：

sudo dsh-auth setup

交互式安裝會要求確認 DSH service、管理員初始化方式、HTTPS hostname 和 TLS mode；它會先展示 secret-free plan，並在你輸入確認值後才修改系統。setup 會安裝 pinned bundle、複製 checksum-verified Caddy binary、寫入權限受限的 authentication state，並啓用 dsh-auth-caddy.service。它不會存儲 plaintext password，也不會在 setup 時下載 Caddy。

先查看 plan¶

在執行 setup 前，可以用 plan 查看同樣的 typed plan。它不會讀取密碼，也不會改變文件系統：

sudo dsh-auth plan

查看幫助與版本¶

可以打印 usage 和 CLI 版本：

dsh-auth --help
dsh-auth --version

典型用法¶

交互式 password 初始化¶

安裝 CLI 後，從已有 DSH Web systemd service 開始 setup。示例如下：

sudo npm install -g dsh-auth
sudo dsh-auth setup

下面是 README 中的交互示例，省略了實際密碼輸入：

$ sudo dsh-auth setup
Existing DSH Web systemd unit: dsh-web.service
Administrator initialization (password/login-token): password
Login tokens (enabled/disabled) [disabled]: enabled
Administrator username: operator
Edge mode (https/http) [https]:
TLS (automatic/manual) [automatic]:
Public HTTPS hostname: harness.example.com
...
Type install to apply this exact plan: install
dsh-auth setup completed successfully.

非交互 JSON + password 初始化¶

非交互模式要求顯式給出 administrator initialization method。使用 password 初始化時，需要把 plaintext password 作爲平臺提供的 temporary 0600 secret file 掛載；dsh-auth 只讀取一次，用於創建 Argon2id hash，不會複製 plaintext。

下面的示例是完整的 HTTPS system install，使用 password initialization 和 automatic TLS：

sudo dsh-auth setup \
  --non-interactive \
  --json \
  --dsh-service dsh-web.service \
  --dsh-home /var/lib/dsh \
  --dsh-executable /usr/local/bin/dsh \
  --profile web \
  --admin-bootstrap password \
  --admin-username operator \
  --login-token enabled \
  --password-file /run/secrets/dsh-auth-password \
  --mode https \
  --tls automatic \
  --upstream 127.0.0.1:3080 \
  --listen-address 0.0.0.0 \
  --server-name harness.example.com

非交互 JSON + login-token 初始化¶

使用 login-token 初始化時，不傳 password 和 username；第一個授權用戶可以在瀏覽器中設置，或選擇 Later：

sudo dsh-auth setup \
  --non-interactive \
  --json \
  --dsh-service dsh-web.service \
  --admin-bootstrap login-token \
  --login-token enabled \
  --mode https \
  --tls automatic \
  --server-name harness.example.com

常用參數¶

以下參數來自 README 示例與說明，完整參數仍以倉庫文檔爲準。

• --mode：選擇 https 或 http，默認 https。
• --tls：選擇 automatic 或 manual，默認 automatic。
• --server-name：Public HTTPS hostname，--mode https 時需要。
• --admin-bootstrap：非交互時選擇 password 或 login-token。
• --admin-username：password setup 時的初始管理員登錄名。
• --login-token：非交互時選擇 enabled 或 disabled；token initialization 需要 enabled。
• --listen-address：Literal IP bind address；HTTP 仍需顯式 private 或 loopback address。
• --behind-tls-proxy：保持 managed HTTP edge 在 loopback，要求 trusted HTTPS forwarding headers，並 issue Secure cookies。
• --login-token-error-message-zh / --login-token-error-message-en：可選的 token-failure 頁面文案，需要 --login-token enabled。
• --certificate / --certificate-key：manual TLS 時使用的 certificate 和 private key 絕對路徑。

升級、冪等與限制¶

• Version 0.2.0 是從 legacy v1 deployments 的 breaking upgrade；previous installer flags、Nginx-managed installations、old sessions 不會被遷移。
• 按 README 描述的 breaking upgrade path，需要先卸載 previous installation，再運行 setup。
• 重複執行相同命令是冪等的；已有 managed installation 如果非密配置相同，會報告 unchanged。
• 不同 settings，或沒有 ownership record 的文件，會被拒絕而不是覆蓋。
• 部分配置缺失時，系統會 fail loudly，而不是帶着不完整配置 boot。
• HTTP 模式仍然要求 explicit private 或 loopback address。

適用場景與注意¶

dsh-auth 適合這類部署：

• 已有 DSH Web systemd service，例如 dsh-web.service。
• DSH Web upstream 只在 loopback 監聽。
• 需要通過 HTTPS 暴露 Web，並增加管理員登錄。
• 需要 Caddy forward_auth edge 同時覆蓋 pages、APIs、downloads、SSE、WebSockets。
• 希望通過 password 或 login-token 初始化管理員，並希望避免 plaintext password 長期存儲。

啓用前需要注意：

• dsh plugin --profile web add dsh-auth 只是預安裝 bundle，不等於啓用認證。
• sudo dsh-auth setup 會修改主機系統，包括安裝 pinned bundle、複製 Caddy binary、寫入 authentication state、啓用 dsh-auth-caddy.service。
• 插件內容以當前 dsh 進程權限運行；安裝前應檢查源碼與許可證。
• 許可證類型在本次資料中未確認，只看到 LICENSE 文件和 license badge；請自行確認後再部署。
• 本文不採用未確認的信息，例如目錄頁 URL、分類、星標數、fork 數、revocable sessions、bilingual UI 等。

鏈接¶

• GitHub：https://github.com/hxy91819/dsh-auth
• 目錄頁：本文已覈實資料未給出可確認的目錄頁 URL；請以插件目錄站點實際發佈地址爲準。