部署(HEL-235): 固化 git 归档流式构建为唯一安全构建入口

Co-authored-by: multica-agent <github@multica.ai>

DOCKER_DEPLOY.md

@@ -149,7 +149,31 @@ docker compose restart xiaobai-review
 docker compose down
 ```
 
-### 使用 Gitea 更新程序（推荐）
+### 镜像构建的唯一安全入口（2026-08 HEL-235 起）
+
+生产机 `192.168.200.11` 上的 `/opt/1panel/docker/compose/xiaobaifupan` 只是历史文件树：
+不是 Git 仓库、内容停在旧提交、与线上镜像不一致，且其 `compose.yaml` 会把构建结果打进
+`xiaobai-review:latest`。**禁止在该目录（或任何服务器工作树）里 `docker build` /
+`docker compose build`**，否则会把已上线功能悄悄打回旧版。
+
+唯一安全构建方式是在有仓库检出、能免密 SSH 到部署机的机器上运行：
+
+```bash
+tools/build_image.sh <提交号> <镜像tag>
+# 示例：tools/build_image.sh cefc86917d89 verify-hel235-cefc869
+```
+
+该脚本的行为约束：
+
+- 先 `git fetch`，再把提交号解析为完整 SHA，解析失败立即中止，绝不使用本地脏状态或服务器旧目录；
+- 镜像 tag 必须以 `-<提交短号7位>` 结尾（如 `hel234-cefc869`），禁止 `latest`、`rollback-*`；
+- 通过 `git archive <提交> | ssh 部署机 docker build -` 流式构建，服务器上不存在构建用工作树；
+- 构建后回读镜像 label 里的 `org.opencontainers.image.revision`，与预期提交不一致则删除镜像并中止；
+- 每次构建在部署机 `~/xiaobai-build/BUILD_LOG.tsv` 留痕，可追溯每个镜像的来源提交。
+
+构建只产出镜像，不启动、不替换任何容器；换版用新 tag 起新容器，回滚用既有镜像 tag 重跑。
+
+### 使用 Gitea 更新程序（旧方式，生产机禁用）
 
 代码仓库为：
 
@@ -174,7 +198,9 @@ cd /opt/xiaobai-review
 `data/private-mentor-skills/` 复制到服务器项目的同名 `data` 目录，并保持目录仅由
 部署账号和容器运行用户读取。该内容不会通过 Gitea 同步。
 
-每次更新前先创建 SQLite 一致性备份，再拉取并重建容器：
+每次更新前先创建 SQLite 一致性备份，再拉取并重建容器（注意：`docker compose up -d --build`
+从服务器本地工作树构建，仅适用于来源可信的全新环境；生产机 `192.168.200.11` 禁用，
+请用 `tools/build_image.sh` 构建后换容器）：
 
 ```bash
 cd /opt/xiaobai-review
@@ -189,7 +215,10 @@ curl --fail http://127.0.0.1:8765/api/health
 数据库迁移会在新容器启动时自动执行。若 `git pull --ff-only` 提示本地代码有修改，
 先用 `git status` 查明原因，不要用强制重置覆盖 `.env` 或 `data`。
 
-### 不使用 Git 时更新
+### 不使用 Git 时更新（生产机禁用）
+
+`docker compose build` 会从服务器本地目录构建，来源提交不可追溯。生产机
+`192.168.200.11` 上禁止使用本节方式，一律改用上一节的 `tools/build_image.sh`。
 
 重新上传代码后执行：