dsh-web-cloud

把 DeepSeek Harness (dsh) 的 Web GUI 安全地托管到云服务器、并在远端经浏览器访问的 DSh bundle 插件包。

• 产品文档：docs/PRD.md
• 架构文档：docs/ARCHITECTURE.md

一句话

dsh web 没有内置认证，且授予 LLM 对整台主机的 shell/文件系统/网络权限 —— 它绝不能直接暴露公网。本包把"零信任托管"这件事做成一个可发布的 DSh 插件：叠在官方 dsh-web bundle 之上，强制回环绑定 + 隧道信任围栏，并附带一键生成 cloudflared + Caddy + systemd 部署配置的 CLI。

安装

dsh plugin --profile web add @rene-zhou/dsh-web-cloud

使用

# 生成云托管部署配置（cloudflared / Caddy / systemd）
dsh-web-cloud setup --tunnel-host dsh.example.com --auth authentik

# 以加固后的配置启动（仍只回环绑定，经隧道访问）
dsh --profile web --host 127.0.0.1 --port 3080 --trusted-host dsh.example.com

# 在 profile 用户层把隧道域名并入信任围栏（SR-2）
# ~/.dsh/profiles/web/cordis.patch.yml:
#   - id: web-cloud
#     config:
#       tunnelHosts: ['dsh.example.com']

--auth 必须显式选择 authentik 或 access（fail-closed，无默认值）。两种模式共用同一条链路：cloudflared → Caddy 闸门（127.0.0.1:8080，bind 回环）→ dsh（127.0.0.1:3080）。差别只在闸门：access 由 Caddy 校验 Cloudflare Access 注入的 Cf-Access-Jwt-Assertion 头，authentik 由 Caddy 向本地 authentik 做 forward_auth。闸门放行后，Caddy 把请求回环化呈现给 dsh（Host 改写为 127.0.0.1:3080、剥离 Origin）——dsh 把整个配置平面（settings.describe 等）硬编码钉在回环来源，这一步让远端浏览器获得完整的设置页/添加模型能力（方案 B，详见 ARCHITECTURE §3.1）。Caddy 为必需组件：apt install caddy 后把生成的 caddy/Caddyfile 放入 /etc/caddy/ 并 systemctl enable --now caddy。

卸载

dsh plugin --profile web remove @rene-zhou/dsh-web-cloud

移除后 profile 回到纯官方 web 层：web-cloud 行消失，connection 行的 inject 与信任围栏表达式恢复官方原值（冒烟脚本第 6 步自动验证）。

验证

npm test                        # 66 项单测（三个已确认接缝 + 模板/CLI，含方案 B 头改写契约）
bash scripts/smoke-test.sh "$(which dsh)"   # 真实 dsh boot 冒烟（含卸载验证）

CI（.github/workflows/ci.yml）：单测矩阵（Node 20/24）+ npm pack --dry-run 发布白名单检查 + 真实 dsh 0.1.0-rc.6 冒烟；另有手动触发的 npm publish 工作流（Trusted Publishing：GitHub OIDC 免密发布，无需 token；首次发布需先在 npm 侧配置 Trusted Publisher）。

包名已加 scope（@rene-zhou/dsh-web-cloud）；发布时 publishConfig.access = public 已声明，直接 npm publish 即可。

目录

dsh-web-cloud/
├─ package.json            # dsh.bundle.patch 标记 + bin + files 白名单
├─ cordis.patch.yml        # 叠层 patch：注入云安全护栏行 + 扩展 connection 信任围栏
├─ lib/
│  ├─ index.js             # 云安全护栏插件（web-cloud）
│  ├─ cli.js               # dsh-web-cloud setup（bin 入口 + 程序化核心）
│  ├─ templates.js         # 四个部署模板的纯渲染函数
│  └─ types/               # 公开类型声明
├─ test/                   # node:test 单测（三个接缝：纯函数 / 插件导出面 / patch 契约 + CLI/模板）
└─ docs/
   ├─ PRD.md
   └─ ARCHITECTURE.md

状态

• M1 完成：lib/index.js 护栏插件 + cordis.patch.yml 叠层（SR-1 回环不变式、SR-2 隧道信任围栏）。
• M2 完成：四个部署模板渲染函数 + dsh-web-cloud setup CLI（SR-3 默认拒绝、SR-4 密钥零入库）。
• M3 完成：真实 dsh 0.1.0-rc.6 boot 冒烟全过（scripts/smoke-test.sh）；VPS + Cloudflare Access + 隧道真机部署（dsh.renezhou.com）。
• M4 完成：卸载验证进冒烟脚本（FR-7），双认证模式经 --auth 切换。
• 方案 B（0.2.0）：隧道 → Caddy 闸门 → 回环化呈现，特权平面（设置/凭据/添加模型）可在域名下完整使用；本地 Caddy 2.10.2 真机验证（缺断言头 401 / settings.describe 200）。

单测 66 项 + 冒烟 6 项全绿。详见 PRD 的里程碑章节。