docs(deploy): 环境镜像全量同步原则固化

2026-09-14 起为部署原则:175 全部 26 个环境类镜像
(8 bioflow-* + 16 plantai-env-* + allenv + protected)必须部署
到 176——扩展分析 runtime_image 可选范围 = 176 本地镜像全集。
含新增/修复镜像的同步流程、旧 tag 回退纪律、activate.d
宿主路径断链陷阱(panfamily 案例)。同步 175 docs/DEPLOY_SKILL.md
与本地 skill 的 §7.4。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/DEPLOY_FLOW.md

@@ -101,6 +101,16 @@ cp ../../../../agent/qa/env/prod.env.example qa/env/prod.env.example
 # 4.2 生信镜像导出（目标机要生信才做；约 20G+）：
 docker save -o /tmp/plantai-bioflow-images.tar $(docker images --format '{{.Repository}}:{{.Tag}}' | grep -E '^(bioflow|plantai-env)-')
 
+# 4.2b 环境镜像全量同步原则（2026-09-14 起为部署原则，必做）：
+#   175 上全部 26 个环境类镜像（8 bioflow-* + 16 plantai-env-* +
+#   plantai-allenv + plantai-protected）必须部署到 176——扩展分析的
+#   runtime_image 可选范围 = 176 本地镜像全集。新增/修复镜像后必须同步，
+#   并在 playbook 台账登记。流式传输（逐镜像，勿 tar 中转）：
+#     docker save <ref> | ssh -i ~/.ssh/id_ed25519_p2p -p 26518 xzq@192.168.0.176 'docker load'
+#   修复镜像覆盖同名 tag 前先回退保存旧 tag（如 :dev-before-xxx）。
+#   activate.d 陷阱：镜像构建后排查 conda env activate.d/*.sh 的宿主
+#   绝对路径注入（PYTHONPATH 断链，panfamily 案例），必要时 COPY 模块进镜像。
+
 # 4.3 目标机备份（同机/异机部署前备份；可选）：
 #   目标机：cp -r <deploy-root> <deploy-root>.bak.$(date +%s)
 

docs/DEPLOY_SKILL.md

@@ -1,8 +1,8 @@
 # PlantAI-rag-new 打包部署 Skill(175 构建机 → 176 生产)
 
 > 本文件是 Claude Code skill 形态的部署方法(与 DEPLOY_FLOW.md 流程互补,侧重 agent 自动执行)。
-> 生成于 2026-09-12,融合当日全部实战陷阱;2026-09-12 晚增补部署变体(换机/无生信/自定义库路径)与提示词示例。
-> skill 源文件:本地 ~/.claude/skills/plantai-deploy/SKILL.md。
+> 生成于 2026-09-12;2026-09-14 增补部署变体(换机/无生信/自定义库路径)与提示词示例、
+> **环境镜像全量同步原则(§7.4)**。skill 源文件:本地 ~/.claude/skills/plantai-deploy/SKILL.md。
 
 ## 0. 前置事实(agent 必读,勿想当然)
 
@@ -134,7 +134,6 @@ start_all 的生信编排(9d7ed1b)探测 `install 同级 bioflow/bioflow_service
 > 质检时 §5.3 的 bioflow health 返回 UPSTREAM_DOWN 属预期,跳过该项。
 
 ### 7.3 三个向量库用自定义路径(纯配置,零代码改动)
-
 | 库 | 数据路径决定 | 连接键(QA 服务 env) |
 |---|---|---|
 | Neo4j | `QA_DB_ROOT` env → `$QA_DB_ROOT/neo4j/data`(install_neo4j.sh 的 server.directories.data) | `NEO4J_URI` |
@@ -145,6 +144,15 @@ start_all 的生信编排(9d7ed1b)探测 `install 同级 bioflow/bioflow_service
 - 换库(如水产库)是同一机制:换路径 + 换 `NORMALIZED_RELEASE_ID`/`V15_QDRANT_COLLECTION` 两个键,整库替换走 `replace_db.sh`(自动探活+回滚)。
 - **db 层不在 start_all 编排**:systemd 的 neo4j/qdrant 在安装期定路径,之后 start_all 不动它们。
 
+### 7.4 环境镜像全量同步(2026-09-14 起为部署原则)
+
+**原则:175 上所有环境类镜像(8 个 bioflow-* + 16 个 plantai-env-* + plantai-allenv + plantai-protected = 26 个)必须全部部署到 176。** 扩展分析的 runtime_image 可选范围 = 176 本地镜像全集,缺一个环境就少一类分析能力。
+
+- **首次全量同步**:逐个 `docker save <ref> | ssh p2p docker load`(流式,175→176 内网直连;18 个 plantai 系约 69GB,全部完成后 176 镜像计数应为 26)。
+- **新增环境镜像后**:175 打新镜像(playbook `docs/bioflow_image_build_playbook.md`)后,同法同步到 176 并更新 playbook 台账;176 上 tag 按 `dev`/构建日期后缀(`20260906`)保持与 175 一致。
+- **镜像修复后**:修复版覆盖同名 tag 前,旧镜像 tag 回退保存(如 `bioflow-pan:dev-before-panfamily`),新镜像 load 到 176 后旧 tag 可随时回滚。
+- **activate.d 陷阱**:镜像构建后必须排查 conda env 的 `activate.d/*.sh` 是否注入了宿主绝对路径(PYTHONPATH 断链,panfamily 案例)——容器内无法访问宿主路径,需把模块 COPY 进镜像。
+
 ## 8. 陷阱速查(全部实测)
 
 1. **rsync --delete 删本地产物**:必须 exclude venv/sdk/data/.env;prod.env 传输后从备份恢复。