前言¶
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 进程的轻量和插件化特性。
