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` 还没回填完，此时旧代码在跑会