给 dsh web 配反向代理与 HTTPS：DeepSeek Harness 的 Nginx 与 Caddy 写法

给 DeepSeek Harness 的 dsh web 配反向代理，难点不是怎么写配置，而是三项必须透对：WebSocket 升级、流式响应不缓冲、长连接超时。 漏任何一项都会出现「页面能打开但用不了」——连接失败、数据不刷新或输出停在半路，报错藏在浏览器控制台与代理日志里。方案上 Nginx 与 Caddy 都能满足要求（Caddy 更短、自动 HTTPS；Nginx 更细、团队更熟），不想开端口还可以走隧道。

反代 dsh web 要透什么：DeepSeek Harness 的三条硬要求与三种实现

一句话结论：WebSocket 升级头要转发、流式响应不要缓冲、超时要够长——三条缺一就会出现「页面能开、功能不能用」。

1. WebSocket 升级：转发 Upgrade 与 Connection 头，并把代理协议版本设为 HTTP/1.1；否则长连接建立失败。
2. 不缓冲流式响应：关闭响应缓冲（或按需调小），让服务端的逐段输出立刻到达浏览器——否则会给人「卡住」的错觉。
3. 长超时：把读写超时调大（会话空闲时连接仍需保持），避免长任务中途被代理断开。
4. 顺手透出真实来源：转发 X-Forwarded-* 系列头，便于在日志与来源限制策略里看到真实客户端。

方案 A：Nginx 反代写法

一句话结论：Nginx 配置的关键是「两处 Upgrade 头 + 一处关闭缓冲 + 三处超时」，其余按常规站点配置即可。

server {
  listen 443 ssl;
  server_name dsh.example.com;

  ssl_certificate     /etc/ssl/dsh/fullchain.pem;
  ssl_certificate_key /etc/ssl/dsh/privkey.pem;

  location / {
    proxy_pass http://127.0.0.1:3080;      # 指向本机 dsh web 的实际端口
    proxy_http_version 1.1;                # 硬要求 1：长连接需要 1.1
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_buffering off;                   # 硬要求 2：流式响应不缓冲
    proxy_read_timeout 3600s;              # 硬要求 3：长超时
    proxy_send_timeout 3600s;
  }
}

1. 改端口：proxy_pass 指向你实际启动 dsh web 的地址与端口（参数名以 dsh web --help 为准）。
2. 验证升级头是否透对：浏览器控制台看长连接是否建立成功；代理访问日志里应能看到 101 Switching Protocols。
3. HTTPS 强制：另配 80 端口跳转到 443，避免明文访问。
4. 回退点：保留一份注释掉的原配置，改坏时能立刻回滚。

方案 B：Caddy 反代写法（更短，自动证书）

一句话结论：Caddy 的价值是「配置短 + 证书自动化」——域名写对，其余交给默认值，适合不想维护证书链的场景。

dsh.example.com {
  reverse_proxy 127.0.0.1:3080
}

1. 默认行为已覆盖硬要求：Caddy 的 reverse_proxy 默认处理连接升级与流式传输，通常不用额外写头。
2. 证书自动签发与续期：域名可达即可自动申请，省掉手动维护。
3. 需要细调时再补指令（超时、来源限制、压缩策略），按文档逐项加。
4. 取舍：默认帮你做了很多事，出问题时排查需要理解它的默认值——建议把关键默认项写进注释备查。

方案 C：内网穿透 / 隧道（不想开端口时）

一句话结论：服务只监听回环、由隧道客户端主动外连，不在防火墙上开监听端口——牺牲一点延迟与合规可控性，换来「不暴露端口」的安全边界。

1. 自建中转：更可控，适合有合规要求、会话内容敏感的团队；需要自己维护中转端证书与访问控制。
2. 商业隧道服务：更省事，几分钟可用；注意流量经过第三方，评估是否允许。
3. 无论哪种，都要叠访问控制：隧道只解决「可达」，不解决「该不该让人访问」。
4. 与反代组合：隧道入口之后再挂一层反代做鉴权与来源限制，是较常见的稳妥组合。

DSH plugin 网页端子路径部署：三个坑

一句话结论：优先挂子域；确实只能挂子路径时，准备好处理资源路径、接口前缀与跳转链接三处改写。

1. 静态资源路径：前端按根路径加载资源时，挂到 /dsh/ 下会出现 404 与白屏。
2. 接口与长连接前缀：API 与长连接的路径若未跟随前缀改写，会全部落到父路径之外。
3. 跳转与回调链接：登录类或深链类跳转若拼接了绝对路径，会跳出子路径范围。
4. 建议：能申请子域就用子域（dsh.example.com），语义清晰、零改写成本；只有无法申请时才走子路径，并预留调试时间。

DeepSeek Harness 的鉴权与暴露面：三层叠加

一句话结论：反代之后别只靠一层——来源限制、访问认证、HTTPS 强制三层叠加，才配得上「公网可达」。

1. 来源限制：只允许特定 IP 段、或要求先连 VPN 再访问。
2. 访问认证：代理层加基础认证或接入统一身份网关（dsh web 自身的本地便利性不等于公网安全）。
3. HTTPS 强制：明文一律跳转，避免会话内容在链路上裸奔。
4. 收敛暴露面：不需要远程时就把反代停掉——很多事故来自「当初为了临时用一下配的，后来忘了关」。

DSH plugin 排查注意事项

一句话结论：反代相关问题先分「连不上」与「连上了但功能异常」——前者查头与协议版本，后者查缓冲与超时。

1. 连不上→ 查 Upgrade / Connection 头与 HTTP/1.1 协议版本，看日志有没有 101。
2. 连上但输出不动→ 查缓冲是否关闭。
3. 长任务中途断→ 查读写超时。
4. 白屏或资源 404→ 查是否挂在子路径上（这也是建议用子域的原因）。
5. 插件市场打不开→ 反代后从浏览器访问市场页是否正常，可用 DSH Plugin Hub 页面作为「端到端是否通」的直观验证。
6. 修复状态如实：本文的 Nginx / Caddy 配置基于各自官方文档的通用写法（WebSocket 升级、反向代理指令），未针对某一版本 DeepSeek Harness 做过官方背书；dsh web 的端口与绑定参数请以本机 dsh web --help 输出为准，配置上线前先在本机验证一次。

反代后的端到端验证有个省事办法：从浏览器打开 DSH Plugin Hub 页面，能正常浏览就说明静态资源、接口与长连接都通了——比逐项猜测快。

来源：apps/cli/README.md、nginx Docs · WebSocket proxying、Caddy Docs · reverse_proxy。