docs(deploy): IP 访问证书警告的兼容边界(bump 0.42.4)

497 跳转目标示例改写死域名——明文 http://IP 访问被 301 带回域名,无
证书警告;https://IP 直连的警告是 TLS 固有行为(握手先于跳转)nginx 层
无解,入口统一域名 / 内网 DNS 补记录。进故障兜底表。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

PROGRESS.md

@@ -2,7 +2,7 @@
 
 > 配合 `DESIGN.md`。本文件只记 phase 状态、决策偏差、文件量、下一步。每条 1-2 句:做了啥 + 关键判断;细节查 `git log` / `git diff` / `DESIGN §7.9`。
 
-最后更新:2026-07-06(nginx TLS 示例与 497 跳转坑位文档,bump 0.42.3)
+最后更新:2026-07-06(IP 访问证书警告兼容说明,bump 0.42.4)
 
 ---
 
@@ -23,6 +23,7 @@
 
 ### 2026-07
 
+- **07-06 / 0.42.4**:497 跳转目标示例改写死域名(http://IP 进来被带回域名无证书警告;https://IP 直连警告 nginx 层无解,入口统一域名),进故障兜底。
 - **07-06 / 0.42.3**:nginx 示例补 TLS 正确写法(同端口单条 listen + error_page 497 跳 https;`if ($scheme)` 在 ssl-only 端口不触发)+ 企微回调只认 80/443 提醒;实际部署上 SSL 踩出,进故障兜底。
 - **07-06 / 0.42.2**:部署脚本 pip install 加 `-q`——日常部署依赖没变,整屏 "already satisfied" 纯刷屏;装新包/报错仍输出。
 - **07-06 / 0.42.1**:修 `update_bluegreen.sh` wait_health 首次真跑就崩——`local a="$1" b="...$a..."` 同行赋值,bash 先展开整行再执行 local,`$a` 展开时无值,`set -u` 报 unbound;拆多行。

RUN.md

@@ -855,6 +855,7 @@ sudo xfs_quota -x -c "limit -p bhard=10g zcbot_<user_uuid>" /opt
 | 蓝绿并存期微信 ClawBot 没反应 | 入站长轮询走 PG advisory lock 选主。两实例 journalctl 里找 `[wechat] inbound leader lock acquired`——都没有 → 检查 DB 连通;锁在已停实例上不可能(连接断锁即释),新实例最长 15s 接管 |
 | 蓝绿部署后旧色 sandbox 容器残留 | 正常:旧实例 stop 时 `shutdown_all` 只清自己色,失败/超时的靠下次该色启动兜底。手动清:`docker rm -f $(docker ps -aq -f label=zcbot.instance=<色>)` |
 | nginx 上 TLS 后 `nginx -t` 报 `duplicate listen options` / HTTP 跳转不生效 | 同端口只能一条 listen(`listen 8765 ssl` 与 `listen 8765` 不能并存);「HTTP 自动跳 HTTPS(同端口)」用 `error_page 497 =301 https://$host:8765$request_uri;`——`if ($scheme = http)` 在 ssl-only 端口永远不触发(握手层就报 497)。模板见 deploy/nginx/zcbot.conf.example TLS 注释段 |
+| 用 IP 访问弹「连接不是专用连接」 | 证书签给域名,IP 访问域名对不上,TLS 固有行为。`error_page 497` 跳转目标**写死域名**(别用 `$host`),明文 http://IP 进来即被带回域名无警告;https://IP 直连的警告 nginx 层无解(握手先于跳转)——入口统一域名,内网解析不了域名就让 IT 加内网 DNS 记录 |
 | 启动报 `ZCBOT_REDIS_URL 已设但 Redis 连不上` | redis-server 没起 / URL 错。`systemctl status redis-server` + `redis-cli ping` 验;或从 `.env` 删掉该行回退进程内 broker(蓝绿切换边缘会回来,见「broker 外置」段) |
 | 日志刷 `[broker] redis publish failed`(10s 节流) | redis 运行中挂了。降级:直播丢帧、SSE 卡 ping,run 本身照常跑完落库;`systemctl restart redis-server` 恢复后 pubsub reader 1s 退避自动重连,无需重启 zcbot |
 | 蓝绿切换窗口刷新丢直播 / 停止失灵(设了 ZCBOT_REDIS_URL 仍出现) | 两实例 journalctl 找 `[broker] redis pub/sub enabled` —— 没有 = 该实例没读到 env(改完 .env 没 restart 实例);有但仍异常看是否伴随 publish failed(redis 本身故障) |

core/__init__.py

@@ -1,3 +1,3 @@
 # zcbot 版本号单一事实源:web/app.py 的 FastAPI version、/healthz 返回、前端展示都引这里。
 # 改版本只动这一行。
-__version__ = "0.42.3"
+__version__ = "0.42.4"

deploy/nginx/zcbot.conf.example

@@ -29,7 +29,9 @@ server {
     # ssl_certificate_key /path/to/privkey.pem;
     # # 明文 HTTP 打到 ssl 端口 → nginx 报 497,借它 301 跳 https。
     # # 注意 `if ($scheme = http)` 在 ssl-only 端口永远不触发(握手层就 497 了),别用。
-    # error_page 497 =301 https://$host:8765$request_uri;
+    # # 跳转目标写死域名而非 $host:用户敲 http://IP 进来也被带回域名,不撞证书警告
+    # # (https://IP 直连的警告 nginx 层无解 —— TLS 握手先于跳转,入口统一用域名)。
+    # error_page 497 =301 https://bot.example.com:8765$request_uri;
     # # 企业微信回调 / OAuth 可信域名只认 80/443 标准端口 —— 要用企微入站/扫码登录,
     # # 另加一个 listen 443 ssl 的 server 块同样 proxy 到 zcbot_backend。