From 26066858b603a4e7c11ac8bc311572d7fd562a28 Mon Sep 17 00:00:00 2001
From: yml2213 <a2213290201@gmail.com>
Date: Sun, 18 Oct 2026 11:02:09 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E4=B8=80=E4=B8=AA=E9=83=A8?=
 =?UTF-8?q?=E7=BD=B2=E5=9D=91=20=E2=80=94=E2=80=94=20=E9=87=8D=E5=BB=BA?=
 =?UTF-8?q?=E9=95=9C=E5=83=8F=E5=90=8E=20up=20-d=20=E4=B8=8D=E4=B8=80?=
 =?UTF-8?q?=E5=AE=9A=E6=8D=A2=E5=AE=B9=E5=99=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

2026-10-18 部署礼包修复时实际踩到：`docker compose build` 出了新镜像
（ID 变了），`docker compose up -d douyu-login` 只打了句 Started，
容器仍是上一版（ps 显示 Up 11 hours，容器里搜不到新函数），差点把
「没生效」报成「部署成功」。

- AGENTS 坑 #10：重建过镜像就 `up -d --force-recreate <服务名>`
  （必须带服务名，不带会把 mysql 一起重建），部署后核对镜像 ID 或 grep 容器内新代码。
- 部署清单同步改命令（顺带给 `docker compose run` 补上 -T 与 </dev/null，
  同 AGENTS 坑 #5）。
---
 AGENTS.md                  | 6 ++++--
 docs/上线清单-S1-S7部署.md | 7 +++++--
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index fd07acd..040e190 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -74,12 +74,13 @@ gzip -t /root/backup_*.sql.gz
 # 采 CK 基线：样本解密长度 + 持有 CK 账号数（部署后要一字不差地对比）
 # 查在途任务：正在跑的批次会被重启打断，先看能不能等
 
-# ② 执行：先停 → 再迁移 → 再起
+# ② 执行：先停 → 再迁移 → 再起（镜像重建过就必须 --force-recreate + 服务名）
 docker compose stop douyu-login
 docker compose run --rm -T douyu-login alembic upgrade head </dev/null
-docker compose up -d douyu-login
+docker compose up -d --force-recreate douyu-login
 
 # ③ 部署后：版本 / CK 基线 / 新接口 / 前端产物 / 日志无 ERROR，逐条核对
+#    另外核对「运行中的镜像 ID == 刚构建的镜像 ID」（见坑 #10）
 ```
 
 - 部署前**必须备份**（即使这次零迁移）；**CK 检查是唯一不能省的功能性验证**
@@ -108,6 +109,7 @@ docker compose up -d douyu-login
 | 7 | **`set -e` + 输出过滤（管道接 `grep -v`）会半途静默中止**：过滤把输出全吃掉时 grep 返回 1，被 `set -e` 当成失败（曾在「已删库、还没导入」处中止，镜像库一度是空的） | 过滤输出后别让 `set -e` 接管退出码；关键步骤显式检查成功 |
 | 8 | **`ruff check` 通过 ≠ 能提交**：钩子查的是 `ruff format` | 提交前本地跑一遍 `.githooks/pre-commit` |
 | 9 | **偷换概念把「账号级状态」当成「全局字段」**：斗鱼商城 `storehome` 的 `count`（库存）确实是全局的，但 **`status` 字段是强账号维度的！`status=1` 就是「已达兑换上限」（限量 1 件已满/已兑换）**。曾把两者混为一谈，误以为商品列表全不可信，跑去依赖早已被官方清空的 `exchangeList`，导致已兑换的账号被错误打上「两个都可兑换」绿标 | 判定高价值资产准入：**以 `storehome.status==1` 为最高裁判**；`exchangeList` 仅做历史展示兜底，绝不可当作否定已拥有的依据 |
+| 10 | **镜像重建了，`docker compose up -d` 不一定换容器**：2026-10-18 实际踩到 —— `build` 出了新镜像（ID 变了），`up -d douyu-login` 只打了句 `Started`，容器还是**旧镜像**（`docker compose ps` 显示 `Up 11 hours`，容器里根本找不到新函数）。差点把「没生效」报成「部署成功」 | 重建过镜像就 `docker compose up -d --force-recreate <服务名>`（**必须带服务名**，不带会把 mysql 一起重建）；部署后**核对镜像 ID**：`docker inspect -f '{{.Image}}' <容器>` 要等于 `docker images --no-trunc` 里 latest 的 ID，或直接 `grep` 容器内新增的函数/文案 |
 
 ## 8. 仓库事实（速查）
 
diff --git a/docs/上线清单-S1-S7部署.md b/docs/上线清单-S1-S7部署.md
index 0dc75ac..30f2a70 100644
--- a/docs/上线清单-S1-S7部署.md
+++ b/docs/上线清单-S1-S7部署.md
@@ -64,10 +64,13 @@ PY
 docker compose stop douyu-login
 
 # 2) 跑迁移（实测 9 秒）
-docker compose run --rm douyu-login alembic upgrade head
+docker compose run --rm -T douyu-login alembic upgrade head </dev/null
 
 # 3) 起新代码
-docker compose up -d douyu-login
+#    ⚠️ **镜像重建过就必须 --force-recreate + 服务名**：2026-10-18 踩到
+#    「build 出了新镜像，up -d 只打了句 Started，容器还在跑旧镜像」。
+#    带服务名只会重建 app，不会连 mysql 一起重建（见 AGENTS 坑 #10）。
+docker compose up -d --force-recreate douyu-login
 ```
 
 **为什么先停应用**：迁移期间 `accounts.cookie` 还没回填完，此时旧代码在跑会