DeepSeek Harness 怎么用原生 TLS 启动 dsh web？证书链、私钥与 Secure cookie

DeepSeek Harness 的 dsh web 可以自己终止 TLS：加 --tls-cert 与 --tls-key 两个参数，监听器就直接用 HTTPS 提供服务，默认端口仍是 3080。 这条路径适合单机、内网或不想再维护一层 Nginx 的场景。它的代价是证书生命周期要自己管：文件读一次、缺了不启动、换了要重启，而且浏览器信不信由浏览器自己的信任库决定。

DeepSeek Harness：什么时候值得让 dsh web 自己终止 TLS

只有“访问端能直接连到这台机器”时，原生 TLS 才划算；如果前面已经有统一入口，交给代理更合适。 可以先按访问形态分三类：（来源）

原生 TLS 的边界也要提前知道：它不会帮你申请证书、不会自动续期、不会监控文件变化。它只做一件事——把指定证书和私钥装载进监听器，然后用 HTTPS 接请求。

三条常见路径可以这样取舍：

1. 原生 TLS — 证书直接交给 dsh web，适合单机、内网、临时对外演示。代价：续期和文件轮换要自己安排。
2. 反向代理终止 TLS — Nginx 或 Caddy 持有证书，dsh web 继续听 loopback。代价：多一层配置，但域名、WAF、日志都能集中。
3. 隧道 + 自签证书 — 先解决可达性，再补信任链。代价：链路经过第三方，敏感会话要评估合规性。

三种方式都能配 --public-url，区别只在“证书归谁管、访问日志在哪看”。下面只讲第一种。

DeepSeek Harness：证书与私钥的四个硬要求

官方对文件的要求很具体：证书要带完整链，私钥要无口令，路径按进程工作目录解析，文件只在启动时读一次。 四条逐项核对：（来源）

1. 证书文件放完整链 — 不只是站点证书，中间证书也要按顺序拼进去。预期：用 openssl s_client -connect 域名:3080 -showcerts 能看到完整链，而不是只返回一张站点证书。
2. 私钥必须是不带口令的 PEM — 带口令的私钥在启动时无法自动解密。预期：openssl pkey -in server.key -noout 不提示输入口令即可通过。
3. 路径按进程工作目录解析 — --tls-cert 与 --tls-key 接收的是相对路径时，基准是启动 dsh 时所在目录，不是配置文件目录。预期：在任意目录启动前，先用绝对路径排除歧义。
4. 证书必须覆盖实际访问名 — 浏览器用自己的信任库和名称校验，证书 SAN 里没有你访问的域名或 IP 就会拒绝。预期：访问地址与证书 SAN 完全一致。

这四条里任何一条不满足，表现都不是“降级成 HTTP”，而是启动直接失败。官方明确写了：文件缺失或无效时启动失败，绝不回退到 HTTP。

DeepSeek Harness：启动命令与三步验证

最小启动形态是 dsh web --tls-cert <证书> --tls-key <私钥>；对外访问时再补 --public-url 与 --trusted-host。 按下面顺序做：（来源）

dsh web \
  --tls-cert /etc/dsh/fullchain.pem \
  --tls-key /etc/dsh/privkey.pem \
  --public-url https://dsh.example.com/ \
  --trusted-host dsh.example.com

1. 先只验证监听器 — 在本机执行 curl -vk https://127.0.0.1:3080/。预期：TLS 握手成功；自签证书会提示不受信任，但不应出现连接被拒。
2. 再验证证书链 — 用 openssl s_client -connect 127.0.0.1:3080 -servername dsh.example.com -showcerts。预期：输出里能看到站点证书和中间证书，Verify return code 为 0 或仅因本地未装根证书而失败。
3. 最后验证浏览器访问 — 打开 --public-url 公告的地址，完成启动令牌换 cookie。预期：地址栏是 HTTPS，登录后不再反复跳认证页。

如果第 1 步就失败，先看终端报错里是“文件不存在”“私钥无法解析”还是“证书与私钥不匹配”，不要先去改代理配置。

DeepSeek Harness：Secure cookie、public-url 与 trusted-host 的关系

TLS 只解决传输加密，不解决“这个域名是否被信任”；--public-url 只公告地址，--trusted-host 才放行 authority。 三者经常被混为一谈：（来源）

• TLS 监听器会给会话 cookie 加 Secure — 浏览器之后只会通过 HTTPS 回传它。如果前面又套了一层终止 TLS 的代理，代理到监听器这一段也要保证 cookie 不被降级。
• --public-url 是公告，不是授权 — 它影响打印出来的启动 URL、DSH_WEB_URL 和 agent 运行时上下文里的 Web GUI URL，不会让别的 Host 通过栅栏。
• --trusted-host 是栅栏名单 — 浏览器以未列入的 authority 访问时，每个 /api 调用都会得到 403，即使 TLS 完全正常。

一个常见误判是：证书配好了、页面能打开，但所有接口都 403。这时不是证书问题，而是 Host 没进信任名单。把浏览器地址栏里的 authority 原样写进 --trusted-host，再重启验证。

DeepSeek Harness：证书验证的三个命令

配好 TLS 不等于证书正确；先用三条只读命令确认链、SAN 和实际握手。 三条命令分别回答三个问题：（来源）

1. 证书覆盖了哪个名字 — openssl x509 -in fullchain.pem -noout -text | grep -A1 "Subject Alternative Name"。预期：输出里能看到你实际访问的域名或 IP；没有就是名称校验必失败。
2. 链是否完整 — openssl verify -CAfile ca.pem -untrusted intermediate.pem server.pem。预期：返回 OK；只放站点证书时这里会报 unable to get issuer certificate。
3. 实际握手是否成功 — openssl s_client -connect 127.0.0.1:3080 -servername dsh.example.com -showcerts。预期：能看到站点证书与中间证书，Verify return code 为 0 或仅因本地未装根证书失败。

这三条命令只验证传输层，不验证 Web 认证与 --trusted-host；握手成功但 API 403，仍然要回到信任栅栏。

DeepSeek Harness：换证书、排错与不适合的场景

换证书的动作不是“覆盖文件”，而是“覆盖后重启或重新加载监听器”；否则旧证书会一直用到进程退出。 官方说明监听器只读一次文件，不监视变化。换证书时按这个顺序：（来源）

1. 先备份旧文件 — 保留旧证书和私钥，确认新文件权限正确。预期：出问题时可以立即换回。
2. 校验新链与新私钥 — 分别跑 openssl verify 与 openssl pkey -noout。预期：两条命令都不报错，再重启。
3. 重启并复验 — 重启 dsh web，重复上一节的 curl 与 s_client。预期：新证书指纹出现在输出里。

不适合原生 TLS 的情况也很明确：需要自动续期、需要按路径分流到多个后端、需要统一 WAF 或访问日志时，把 TLS 交给反向代理。原生 TLS 更适合“就这一台、就这一个入口”的部署。

DeepSeek Harness 常见问题

Q：自签证书能不能用？ 能，但访问端必须信任签发它的根证书。浏览器不会因为你在 DSH 里配了证书就自动信任，尤其手机和另一台电脑要分别安装。

Q：端口能不能换成 443？ 可以，dsh web --port 443 即可；但 443 通常需要额外权限，容器里还要确认端口映射。换端口后，--public-url 和 --trusted-host 里的 authority 也要同步。

Q：TLS 配好后还需要反向代理吗？ 不需要，除非你还要域名分流、WAF、统一证书管理或访问日志。原生 TLS 与代理部署是两种并列方案，不是必须叠加。

Q：为什么重启后浏览器又要重新认证？ 会话 cookie 绑定 hostname 与 port。换端口、换域名或证书配置改变了访问 authority，旧 cookie 就不再匹配，需要重新用启动令牌换一次。

一句话收束： 原生 TLS 是把证书交给 dsh web 自己管，适合单入口部署；配好证书只是第一步，--trusted-host 与 Secure cookie 才是能正常用起来的关键。