docs(deploy): 497 跳转 301→308——修平台 POST 经跳转被降级成 GET(bump 0.42.5)

平台配 http:// 入口调 POST /v1/auth/login:497→301 后 requests 按规范把
POST 降成 GET 重发,只挂 POST 的路由回 405。示例改 =308(保留方法和
body,浏览器行为不变);治本是调用方直配 https(明文首跳会把
platform_key/JWT 暴露在网络上,重定向救不了已发出的那次)。进故障兜底。

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(IP 访问证书警告兼容说明,bump 0.42.4)
+最后更新:2026-07-06(497 跳转 301→308:修平台 POST 被降级成 GET 报 405,bump 0.42.5)
 
 ---
 
@@ -23,6 +23,7 @@
 
 ### 2026-07
 
+- **07-06 / 0.42.5**:497 跳转示例 301→308——平台走 http 入口 POST login 被客户端按 301 语义降级成 GET 报 405;308 保留方法/body。治本仍是调用方直配 https(明文首跳暴露 platform_key)。
 - **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" 纯刷屏;装新包/报错仍输出。

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 注释段 |
+| 平台调 `/v1/auth/login` 报 405 Method Not Allowed | 平台配了 `http://` 入口:明文 POST → 497 → 301 → requests 等客户端跟随 301 时把 POST 降成 GET → 只挂 POST 的路由回 405。治本:平台 base URL 换 `https://`(明文首跳会暴露 platform_key);服务端把 497 跳转从 `=301` 改 `=308`(保留方法/body)作兼容 |
 | 用 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 |

core/__init__.py

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

deploy/nginx/zcbot.conf.example

@@ -27,11 +27,14 @@ server {
     # server_name bot.example.com;
     # ssl_certificate     /path/to/fullchain.pem;
     # ssl_certificate_key /path/to/privkey.pem;
-    # # 明文 HTTP 打到 ssl 端口 → nginx 报 497,借它 301 跳 https。
+    # # 明文 HTTP 打到 ssl 端口 → nginx 报 497,借它跳 https。
     # # 注意 `if ($scheme = http)` 在 ssl-only 端口永远不触发(握手层就 497 了),别用。
     # # 跳转目标写死域名而非 $host:用户敲 http://IP 进来也被带回域名,不撞证书警告
     # # (https://IP 直连的警告 nginx 层无解 —— TLS 握手先于跳转,入口统一用域名)。
-    # error_page 497 =301 https://bot.example.com:8765$request_uri;
+    # # 用 308 不用 301:301 会让多数 HTTP 客户端把 POST 降级成 GET 重发(API 调用
+    # # 变 405),308 保留方法和 body;浏览器行为不变。API 调用方仍应直配 https ——
+    # # 明文首跳会把 platform_key/JWT 暴露在网络上,重定向救不了已发出的那次。
+    # error_page 497 =308 https://bot.example.com:8765$request_uri;
     # # 企业微信回调 / OAuth 可信域名只认 80/443 标准端口 —— 要用企微入站/扫码登录,
     # # 另加一个 listen 443 ssl 的 server 块同样 proxy 到 zcbot_backend。