前言¶
DeepSeek Harness (DSH) 採用插件化架構，允許通過 Web 客戶端進行遠程管理。爲了在遠程訪問（如 https://dsh.example.com）下安全地操作 Settings、Credentials、Agent Preset 管理及模型發現等功能，需要驗證請求來源的合法性。
dsh-cloudflare-access 是一個運行在 DSH 進程內部的插件。它不替代 Cloudflare Access，而是作爲 Origin 端的驗證層，讀取並驗證 Cloudflare Access 注入的 Cf-Access-Jwt-Assertion 頭部。驗證通過後，DSH 將其作爲認證令牌使用，從而允許遠程特權操作。
插件簡介¶
- 名稱: dsh-cloudflare-access
- 維護者: Luawig
- 許可證: MIT
- 核心功能:
- 在 DSH Origin 端驗證 Cloudflare Access JWT。
- 實現遠程特權授權（Settings、Credentials、Agent Preset 管理、模型發現）。
- 提供 Profile Bundle + Web Client 的雙重模式。
- 不提供登錄頁、密碼存儲、MFA、會話表或 Cloudflare API 客戶端。
安裝與啓用¶
此插件需要配合 Web profile 使用。
安裝命令如下：
dsh plugin --profile web add dsh-cloudflare-access
如需卸載：
dsh plugin --profile web remove dsh-cloudflare-access
安裝後需重啓 DSH 進程。插件版本 2.0.x 針對的是 DeepSeek Harness 0.1.5-alpha.1。
配置說明¶
- 將 DSH Web 源置於 Cloudflare Access 應用之後。
- 在環境變量中配置 Team Domain 和 Audiences。
環境變量¶
| 變量名 | 說明 | 示例 |
|---|---|---|
DSH_CF_ACCESS_TEAM_DOMAIN |
團隊域名 / Issuer | https://example.cloudflareaccess.com |
DSH_CF_ACCESS_AUDIENCES |
訪問應用的 Audience（逗號分隔） | your-access-application-aud |
systemd 示例¶
在 systemd 服務配置中鎖定這些值：
[Service]
Environment=DSH_CF_ACCESS_TEAM_DOMAIN=https://example.cloudflareaccess.com
Environment=DSH_CF_ACCESS_AUDIENCES=your-access-application-aud
Environment=DSH_CF_ACCESS_ORDINARY_MODE=off
ExecStart=/usr/bin/dsh --profile web --trusted-host dsh.example.com
驗證配置¶
執行以下命令確認插件已加載並配置正確：
dsh --profile web --dump-config
輸出中應包含名爲 dsh-cloudflare-access 的層以及 id: cloudflare-access 的插件行。
認證模式¶
對於遠程非特權 API（如 /api/remote.mux），auth.ordinary 模式決定了是否需要 JWT。
| 模式 | 無 JWT | 有效 JWT | 無效 JWT |
|---|---|---|---|
off (默認) |
DSH 原有策略 | 忽略 JWT | 忽略 JWT |
optional |
DSH 原有策略 | 允許 | 拒絕 |
required |
拒絕 | 允許 | 拒絕 |
注意：無論上述模式如何設置，遠程特權 API 始終要求有效的 JWT（v2.0 版本）。同時，localhost / 127.0.0.1 / ::1 等迴環地址不要求 JWT。
架構與安全¶
- 運行位置: 插件運行在 DSH 進程內部，不修改 DSH 本身。
- 頭部處理: 插件會透傳
Host、Origin和Cf-Access-Jwt-Assertion，不會移除該頭部。 - 安全模型: 遠程特權請求必須同時通過 DSH 的 Host/Origin 檢查（
--trusted-host）和有效的 Cloudflare Access JWT。 - 網絡隔離: 建議僅允許 Cloudflare（或等效入口）訪問 DSH Origin。安裝此插件不是將 DSH 暴露在公網的理由。
注意事項¶
- 不編輯配置文件: 不要手動編輯
$DSH_HOME/profiles/web/cordis.patch.yml。 - Loopback 限制: 迴環訪問不需要 JWT，這是爲了保持 SSH Tunnel 等本地調試方式的可用性。
- 版本兼容性: 請勿假設其他 DSH 版本可用，請查看兼容性矩陣。
總結¶
dsh-cloudflare-access 爲 DeepSeek Harness 提供了基於 Cloudflare Access 的遠程認證能力。它通過在 Origin 端驗證 JWT，解決了 Web profile 遠程管理時的權限校驗問題，同時保持了 DSH 進程的輕量和插件化特性。
