部署(HEL-235): 修正构建留痕的远端参数传递

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`。
 
 重新上传代码后执行：
 

tools/README.md

@@ -17,6 +17,12 @@ registry, and verification tools.
   `backend/features/*/routes.py` owners.
 - `python tools/build_architecture_inventory.py [--check]`: generate or verify
   `config/architecture-inventory.json` from the current source tree.
+- `bash tools/build_image.sh <commit> <tag>`: the only sanctioned way to build the
+  production Docker image. Streams `git archive <commit>` to the deploy host over SSH
+  (default `moxiaobai@192.168.200.11`), refuses tags that do not end with the commit
+  short SHA, verifies the revision label after the build, and appends a record to
+  `~/xiaobai-build/BUILD_LOG.tsv` on the host. Building from any server-side working
+  tree is forbidden; see `DOCKER_DEPLOY.md`.
 
 `verify_baseline.py` does not inspect a parent checkout or skip tests according to files outside
 this application. Historical comparison scripts were retired after final standalone acceptance;

tools/build_image.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# 小白复盘唯一安全构建入口（HEL-235 固化）
+# 方式：从明确 Git 提交 git archive 流式传输到部署机 docker build，不使用任何服务器工作树。
+# 铁律：禁止在服务器目录（如 /opt/1panel/docker/compose/xiaobaifupan）里 docker build；
+#       禁止构建 latest 等不带提交短号的 tag；严禁向 192.168.200.36 构建或部署。
+set -euo pipefail
+
+HOST_DEFAULT="moxiaobai@192.168.200.11"
+REPO_NAME="xiaobai-review"
+
+usage() {
+  cat <<'EOF'
+用法: tools/build_image.sh <commit> <tag>
+  <commit>  提交号（完整或前缀），必须能被 origin 解析；构建前会自动 fetch
+  <tag>     镜像 tag，必须以 -<提交短号7位> 结尾，锁定镜像来源；禁止 latest、rollback-*
+示例: tools/build_image.sh cefc86917d89 verify-hel235-cefc869
+说明: 仅构建镜像，不启动、不替换任何容器；换版与回滚另行人工执行。
+EOF
+  exit 2
+}
+
+[ $# -eq 2 ] || usage
+COMMIT="$1"
+TAG="$2"
+HOST="${XB_BUILD_HOST:-$HOST_DEFAULT}"
+
+case "$HOST" in
+  *192.168.200.36*)
+    echo "拒绝：192.168.200.36 已永久废弃，严禁在其上构建或部署。" >&2
+    exit 1
+    ;;
+esac
+
+cd "$(git rev-parse --show-toplevel)"
+
+echo "==> 同步远端引用"
+git fetch origin --prune --quiet
+
+FULL_SHA="$(git rev-parse --verify --quiet "${COMMIT}^{commit}" || true)"
+if [ -z "$FULL_SHA" ]; then
+  echo "拒绝：提交 ${COMMIT} 无法解析。构建源必须锁定到已推送 origin 的明确提交。" >&2
+  exit 1
+fi
+SHORT="${FULL_SHA:0:7}"
+SUBJECT="$(git log -1 --format=%s "$FULL_SHA")"
+
+case "$TAG" in
+  latest)
+    echo "拒绝：禁止构建 latest，模糊 tag 无法追溯来源提交。" >&2
+    exit 1
+    ;;
+  rollback-*)
+    echo "拒绝：rollback-* 是部署时对既有镜像的人工 docker tag，不允许用来构建。" >&2
+    exit 1
+    ;;
+esac
+if [[ "$TAG" != *-"$SHORT" ]]; then
+  echo "拒绝：tag「${TAG}」必须以 -${SHORT} 结尾，保证镜像 tag 与来源提交一一对应。" >&2
+  exit 1
+fi
+
+echo "==> 构建计划"
+echo "    提交: ${FULL_SHA}  ${SUBJECT}"
+echo "    镜像: ${REPO_NAME}:${TAG}  @ ${HOST}"
+echo "    方式: git archive 流式构建（不读取服务器上任何代码目录）"
+
+echo "==> 流式构建开始"
+git archive --format=tar "$FULL_SHA" \
+  | ssh -o BatchMode=yes "$HOST" docker build --rm \
+      -t "${REPO_NAME}:${TAG}" \
+      --label "org.opencontainers.image.revision=${FULL_SHA}" \
+      --label "org.opencontainers.image.created=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+      --label "org.opencontainers.image.source=git-archive-stream" \
+      -
+
+echo "==> 回读校验镜像内记录的提交号"
+GOT="$(ssh -o BatchMode=yes "$HOST" "docker image inspect ${REPO_NAME}:${TAG} --format '{{index .Config.Labels \"org.opencontainers.image.revision\"}}'" 2>/dev/null || true)"
+if [ "$GOT" != "$FULL_SHA" ]; then
+  echo "校验失败：镜像 revision='${GOT:-<空>}'，期望 ${FULL_SHA}。删除不可信镜像，中止。" >&2
+  ssh -o BatchMode=yes "$HOST" docker rmi "${REPO_NAME}:${TAG}" >/dev/null 2>&1 || true
+  exit 1
+fi
+
+IMAGE_ID="$(ssh -o BatchMode=yes "$HOST" "docker image inspect ${REPO_NAME}:${TAG} --format '{{.Id}}'")"
+SHORT_ID="${IMAGE_ID##*:}"
+
+ssh -o BatchMode=yes "$HOST" \
+  "mkdir -p ~/xiaobai-build && printf '%s\t%s\t%s\t%s\tgit-archive-stream\n' \"\$(date '+%F %T')\" ${REPO_NAME}:${TAG} ${FULL_SHA} ${SHORT_ID} >> ~/xiaobai-build/BUILD_LOG.tsv"
+
+echo "==> 完成"
+echo "    ${REPO_NAME}:${TAG}  (${SHORT_ID})"
+echo "    来源提交 ${FULL_SHA} 已写入镜像 label 与 ~/xiaobai-build/BUILD_LOG.tsv"