docs(server): 台账记下 8081(TLS)+8082(明文) 的端口设计与背后的两个约束

yeg

2026-09-29 5e89d1441a35be0865fb3d2d17d879b8c6c73006

docs(server): 台账记下 8081(TLS)+8082(明文) 的端口设计与背后的两个约束

① HSTS 按主机生效且覆盖所有端口、升级时保留显式端口，所以 8081 只要被浏览器访问就必须有 TLS；② nginx 不允许同一 address:port 混用 ssl 标志，两个 server 块分别 listen 8081/8081 ssl 会校验失败且报错行号指向明文块。这两条都记下来，免得下一个想「合并成一个块」的人重踩。

 .scratch/server-testenv/README.md

@@ -62,7 +62,8 @@
| 证书 | 华为云签发的 DV（TrustAsia 签发）。`/etc/nginx/ssl/talent-card/server.crt` 是**含中间链的 bundle**（4451 字节），`server.key` 权限 `600` |
| 覆盖域名（SAN） | `dqrcfwpt.com` + `www.dqrcfwpt.com` |
| **到期** | **2027-02-11** ⚠️ **不会自动续到本机** —— 到期前在华为云重新下载再传一次（或那时改用 Let's Encrypt：80 已通，certbot 一条命令且自带自动续期） |
| 端口 | **8081 = 测试环境**（完整功能）；**443 = 生产预留，现在是占位页**（`/data/talent-card/placeholder/index.html`，正文「本域名对应的生产环境尚未部署」）；80 只做 301 跳转到 https |
| 端口 | **8081 = 测试环境（TLS）**：`https://www.dqrcfwpt.com:8081/`；**8082 = 测试环境（明文兜底）**：`http://117.172.73.106:8082/`；**443 = 生产预留，现在是占位页**（`/data/talent-card/placeholder/index.html`，正文「本域名对应的生产环境尚未部署」）；80 只做 301 跳转到 https |
| ⚠️ 为什么 8081 必须是 TLS、明文要另开 8082 | 443 上发了 HSTS，而 **HSTS 按「主机」生效、覆盖该主机的所有端口**（RFC 6797 §8.3），且升级时**显式端口会保留**（`http://host:8081` → `https://host:8081`）。所以 8081 若只说纯 HTTP，浏览器（只要访问过一次域名）一律打不开。**也不能让 nginx 用两个 server 块在 8081 上分别 listen 明文与 ssl** —— 同一个 address:port 的 ssl 标志必须一致，混用直接校验失败，报 `no "ssl_certificate" is defined for the "listen ... ssl" directive`，而且**错误行号指向那个明文块**，极易看错地方（2026-09-29 就在这里绕了几圈）。所以拆成 8081(TLS) + 8082(明文)。 |
| 生产上线时 | 把 443 块里的 `root` 与 `location` 换成 `include snippets/talent-card-locations.conf;`，80 的 301 不用动。该域名上的 `/api` 目前返回 503 JSON，避免请求落到静态页被误解为可用 |
| HSTS | `max-age=86400`（1 天），**没有** `includeSubDomains` / `preload` |
| 公网实测 | 链 2 张、`Verify return code: 0 (ok)`、`curl` 不带 `-k` 返回 200、`http://` → 301、HSTS 头存在、`https://` Origin 的登录请求不再 403 |