chore: enforce release alignment and disable implicit runtime drift

Author: ieduer

Dockerfile

@@ -8,6 +8,7 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
     PROJECT_ROOT=/app \
     DATA_ROOT=/data \
     STATE_ROOT=/state \
+    RUNTIME_DB_SYNC_MODE=disabled \
     PORT=8080 \
     HF_HOME=/state/cache/huggingface \
     HF_HUB_CACHE=/state/cache/huggingface/hub \

README.md

@@ -44,6 +44,9 @@
 
 - 涉及前端或页图行为的发布，必须从 clean release source 构建，不能直接从 VPS runtime repo 出包
 - 本机是唯一源头：代码更新先固化到 `release_manifest.json`，再推 GitHub；大文件同步到 VPS；页图同步到 R2；四端状态必须按同一轮 release manifest 对齐
+- 运行时大文件不经 GitHub 同步；`data/index/*.db`、`*.index`、runtime JSON 必须显式同步到 VPS，不能指望代码发布顺带带过去
+- R2 当前公开职责只保留页图与图片 CDN；生产容器默认禁用运行时主检索库自动拉取，避免启动时把 VPS 已验收数据盘悄悄改写
+- `textbook_mineru_fts.db` 含运行时日志表，文件级 sha 会随线上流量漂移；发布对账以稳定的运行时语料指纹为准，不再把 `search_logs` / `ai_chat_logs` 的增长误判成错版
 - 若发布涉及页图映射，镜像内必须包含 `frontend/assets/pages/book_map.json`；上线验收时需抽查 live 搜索结果返回非空 `page_url`
 - 手工发布前如需保留人工回滚点，应先按 running image digest 额外打 tag，不要直接把 `textbook-knowledge:latest` 当作回滚锚点
 - 仅 `README.md` / `docs/**` 这类说明文档更新不应触发生产部署；workflow 需继续显式忽略 docs-only push
@@ -401,9 +404,10 @@ RUNTIME_ROOT=/root/cross-subject-knowledge ./scripts/deploy_vps.sh
 3.  在 VPS 上创建临时的干净 release checkout，避免生产目录里历史热补丁或临时改动阻塞发布。
 4.  在 VPS 上先构建新镜像，再停旧容器，避免“构建失败直接打挂线上”。
 5.  部署脚本会同步补充教材索引与补充向量到运行时目录，并预热 `BAAI/bge-reranker-base`，避免首个精确查询才触发冷启动。
-6.  新容器通过 `/api/health` 健康检查后才算部署成功；当前健康闸门要求 DB、FAISS、补充教材索引可用，且在启用 reranker 时确认 `reranker.loaded=true`；失败则自动回滚到上一镜像。
-7.  运行时模型缓存保存在宿主机 `state/cache/`，避免每次发版都把 Hugging Face 缓存烘进镜像。
-8.  部署完成后自动清理悬空镜像，只保留最近几份 `pre-*` 回滚镜像，并删除历史 `build-*` tag。
+6.  生产容器默认以宿主机挂载的 `/data/index/` 为唯一运行时检索库来源；`backend/sync_db.py` 不再作为默认启动链路，只有显式设置 `RUNTIME_DB_SYNC_MODE=r2_textbook_mineru` 时才会执行应急拉库。
+7.  新容器通过 `/api/health` 健康检查后才算部署成功；当前健康闸门要求 DB、FAISS、补充教材索引可用，且在启用 reranker 时确认 `reranker.loaded=true`；失败则自动回滚到上一镜像。
+8.  运行时模型缓存保存在宿主机 `state/cache/`，避免每次发版都把 Hugging Face 缓存烘进镜像。
+9.  部署完成后自动清理悬空镜像，只保留最近几份 `pre-*` 回滚镜像，并删除历史 `build-*` tag。
 
 手工紧急发布不应再从 VPS runtime repo 直接出包。当前统一做法是：
 

backend/entrypoint.sh

@@ -1,7 +1,12 @@
 #!/usr/bin/env sh
 set -eu
 
-python /app/backend/sync_db.py
+RUNTIME_DB_SYNC_MODE="${RUNTIME_DB_SYNC_MODE:-disabled}"
+if [ "${RUNTIME_DB_SYNC_MODE}" != "disabled" ]; then
+  python /app/backend/sync_db.py
+else
+  echo "Runtime DB sync disabled; using mounted /data runtime assets."
+fi
 python /app/backend/preflight.py
 
 exec uvicorn backend.main:app --host 0.0.0.0 --port "${PORT:-8080}" --workers 1

backend/sync_db.py

@@ -1,7 +1,11 @@
-import os, urllib.request, hashlib
+import os
+import sys
+import urllib.request
 from pathlib import Path
 
 DB_URL = "https://img.rdfzer.com/db-sync/textbook_mineru_fts.db"
+SYNC_MODE = os.getenv("RUNTIME_DB_SYNC_MODE", "disabled").strip().lower()
+SYNC_MODE_R2_TEXTBOOK = "r2_textbook_mineru"
 PROJECT_ROOT = Path(os.getenv("PROJECT_ROOT", Path(__file__).resolve().parents[1])).expanduser().resolve()
 _DEFAULT_DATA_ROOT = PROJECT_ROOT / "data"
 _ALT_DATA_ROOT = PROJECT_ROOT.parent / "data"
@@ -12,6 +16,21 @@
 DB_PATH_LEGACY = DATA_ROOT / "textbook_mineru_fts.db"
 DB_PATH = DB_PATH_PRIMARY if DB_PATH_PRIMARY.exists() or not DB_PATH_LEGACY.exists() else DB_PATH_LEGACY
 
+def sync_enabled() -> bool:
+    disabled_modes = {"", "0", "false", "off", "no", "disabled", "none"}
+    if SYNC_MODE in disabled_modes:
+        print("Runtime DB sync skipped: RUNTIME_DB_SYNC_MODE is disabled.")
+        return False
+    if SYNC_MODE != SYNC_MODE_R2_TEXTBOOK:
+        print(
+            f"Unsupported RUNTIME_DB_SYNC_MODE={SYNC_MODE!r}. "
+            f"Expected {SYNC_MODE_R2_TEXTBOOK!r} or a disabled value.",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+    return True
+
+
 def download_db():
     print(f"Checking for DB updates from {DB_URL}...")
     try:
@@ -37,4 +56,5 @@ def download_db():
         print(f"Failed to check/download DB update: {e}")
 
 if __name__ == '__main__':
-    download_db()
+    if sync_enabled():
+        download_db()

docs/data_layer_lineage_memory.md

@@ -241,7 +241,7 @@ Important DB note:
 
 - `textbook_mineru_fts.db` is a mutable runtime file because local smoke tests and production traffic can append telemetry tables and log rows.
 - File-level SHA256 for this DB is therefore not a stable content identity signal by itself.
-- For release verification, pair the DB file SHA with a stable textbook-corpus fingerprint derived from `chunks WHERE source != 'gaokao'`.
+- For release verification, pair the DB file SHA with a stable runtime identity fingerprint derived from the search-critical content tables plus FTS shadow table counts, while excluding mutable telemetry tables such as `search_logs` and `ai_chat_logs`.
 
 ### Production runtime destinations
 
@@ -634,19 +634,21 @@ Conditionally required runtime assets:
 
 Startup behavior from [`platform/backend/entrypoint.sh`](../backend/entrypoint.sh):
 
-1. run `sync_db.py`
+1. optionally run `sync_db.py` only when `RUNTIME_DB_SYNC_MODE` is explicitly enabled
 2. run `preflight.py`
 3. start `uvicorn`
 
 The runtime does not rebuild FAISS or supplemental assets on the VPS.
 
 ### DB drift rule
 
-[`platform/backend/sync_db.py`](../backend/sync_db.py) auto-syncs only:
+[`platform/backend/sync_db.py`](../backend/sync_db.py) is now an explicit emergency path only. When manually enabled, it can sync only:
 
 - `textbook_mineru_fts.db`
 
-It does not auto-sync:
+By default, production startup keeps `RUNTIME_DB_SYNC_MODE=disabled`, so it does not auto-sync any runtime DB.
+
+It never auto-syncs:
 
 - `textbook_chunks.index`
 - `textbook_chunks.manifest.json`

docs/release_maintenance_design.md

@@ -47,6 +47,44 @@
 
 这样，手工紧急修复不再依赖“自己记得复制哪些文件”。
 
+### 2.5. 运行时主检索库不再允许隐式同步
+
+这次排查还暴露了另一条真正会制造状态漂移的链路：
+
+- 容器启动时自动运行 `backend/sync_db.py`
+- `sync_db.py` 会尝试从 R2 `db-sync/` 路径下载 `textbook_mineru_fts.db`
+
+这条链路直接破坏了四端对齐模型：
+
+- 本机、GitHub、VPS、R2 可以在没有显式发布动作的情况下继续分叉
+- 网站有效并不能证明 VPS `data/index/` 仍等于本轮验收版本
+- 代码发布会夹带运行时数据改写，回滚与验收都失去边界
+
+因此本轮的固定约束是：
+
+- 生产容器默认 `RUNTIME_DB_SYNC_MODE=disabled`
+- `deploy_vps.sh` 强制要求 `RUNTIME_DB_SYNC_MODE=disabled`
+- `sync_db.py` 只保留为显式应急工具，必须手动设置 `RUNTIME_DB_SYNC_MODE=r2_textbook_mineru` 才会执行
+
+未来运行时主检索库的唯一正常更新方式是：
+
+1. 本机生成或确认工件
+2. 显式同步到 VPS `data/index/`
+3. 再部署或重启容器
+
+而不是让容器在启动时自行改写数据盘。
+
+另一个必须同时固定下来的点是 `textbook_mineru_fts.db` 的“活文件”属性：
+
+- 线上流量会继续写 `search_logs` / `ai_chat_logs`
+- 因此整库 SHA 不能长期作为唯一发布对账依据
+
+本轮已把 manifest / verify 规则收成：
+
+- 保留整库 SHA 作为信息字段
+- 对真正的发布校验，改用稳定的 `runtime_identity`
+- `runtime_identity` 只覆盖检索和知识运行所需的核心内容表与 FTS 影子表计数，不把运行时日志表计入错版判断
+
 ### 3. 部署脚本必须拒绝坏包
 
 `platform/scripts/deploy_vps.sh` 现在新增硬性拦截：

docs/runtime_operations_overview.md

@@ -9,7 +9,7 @@ Before any data rebuild, deploy, rollback, or search-debugging pass, read [data_
 - Local development machine: code editing, data inspection, lightweight validation
 - Offline processing/build machine: OCR, FAISS rebuild, batch backfill, and large model downloads
 - Production VPS: serves search, graph, gaokao linkage, and AI chat APIs; does not run OCR or FAISS rebuild
-- Cloudflare R2: image and page asset delivery
+- Cloudflare R2: image and page asset delivery only; production runtime DBs should not mutate from R2 during normal startup
 - Cloudflare Worker custom domain `ai.bdfz.net`: external AI gateway bound to Worker service `apis` / `production`
 
 ## Runtime assets
@@ -29,6 +29,12 @@ Production runtime depends on host-mounted directories instead of baking data in
 
 The repository also keeps bundled fallback copies of the supplemental index under `backend/`, but production should rely on the synced `data/index/` copies and their manifest.
 
+Runtime DB rule:
+
+- `/data/index/*.db` and `/data/index/*.index` are the authoritative runtime assets once they are synced to the VPS
+- production startup must not implicitly replace them from R2 or any other remote source
+- if a runtime DB needs emergency replacement, do it as an explicit file sync step before deploy or restart
+
 Current page-image boundary:
 
 - `book_map.json` and the CDN page-image product now cover `96` books: the original `69` primary books plus `27` supported supplemental books

release_manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
-  "generated_at": "2026-03-11T14:36:55.640411+00:00",
-  "git_head": "32c69d3b69cb2ad5d31b7c9abe4ec65420a2328d",
+  "generated_at": "2026-03-11T15:26:41.781604+00:00",
+  "git_head": "33430fa149ae546feab64aae1a1c45e8a67a1f2c",
   "frontend_version": "2026.03.11-r30",
   "source_of_truth": {
     "local_workspace": "authoritative",
@@ -13,8 +13,8 @@
     {
       "kind": "source",
       "logical_path": "Dockerfile",
-      "size": 1355,
-      "sha256": "59de729b4c698c9c522eacdea60257bfbc75ed19512f76cad0fa17e2805add75"
+      "size": 1391,
+      "sha256": "81e182f30187904c62899480ddb4dfa61012dcd63d43e708b29e12d44f57051b"
     },
     {
       "kind": "source",
@@ -37,8 +37,8 @@
     {
       "kind": "source",
       "logical_path": "backend/entrypoint.sh",
-      "size": 172,
-      "sha256": "4cc0d23dbf99899c4467553caaa318a5cd4033c46c017b04dc6dec09e6f11418"
+      "size": 363,
+      "sha256": "07c195d0bf29569d11cda2b5c2928b08edec6bed90174731021b2c88bed0fa0b"
     },
     {
       "kind": "source",
@@ -49,8 +49,8 @@
     {
       "kind": "source",
       "logical_path": "backend/sync_db.py",
-      "size": 1904,
-      "sha256": "55f2b3119d1852036180cd3a6cf397a4f7c808d38c9e05f1e8a02f02d0fe5a53"
+      "size": 2571,
+      "sha256": "55dcd301704bc1d80bf0b10e86a321e208a26e505f12898481ab23aeeb9b448e"
     },
     {
       "kind": "source",
@@ -133,8 +133,8 @@
     {
       "kind": "source",
       "logical_path": "scripts/deploy_vps.sh",
-      "size": 13040,
-      "sha256": "af5c476eced7e12625fcef41bb79f88d9c634bd373b0a82f6c71c734dcd0534e"
+      "size": 13432,
+      "sha256": "d62f2a4d23a7f1be3d60069d1d6bfaadc184d9724f49753b398896eb203d92f2"
     },
     {
       "kind": "source",
@@ -145,23 +145,82 @@
     {
       "kind": "source",
       "logical_path": "scripts/build_release_manifest.py",
-      "size": 6868,
-      "sha256": "709c5782b39f84a756bf7d00d8d14f22996e24dbda0579b43afeed28790a992f"
+      "size": 9282,
+      "sha256": "161a834da14ee82dd1c61a1b5fe71b9c890fb5188228a242b3872e377c5d582e"
     },
     {
       "kind": "source",
       "logical_path": "scripts/verify_release_manifest.py",
-      "size": 3798,
-      "sha256": "be6b63e7606867e840154cc939dd44cdadecc0836a9ccfd508b1310ba6e1c78d"
+      "size": 6547,
+      "sha256": "c294a574a27f7c80a260c854cf041f02ed55d1d8bc60044b4f787b7d4cdeecbf"
     }
   ],
   "runtime_assets": [
     {
       "kind": "runtime",
       "logical_path": "data/index/textbook_mineru_fts.db",
       "size": 58892288,
-      "sha256": "766e9878195a0ceb9c385f21884017bc86d51c6066427e542c361a05b05d5f1d",
-      "source_path": "data/index/textbook_mineru_fts.db"
+      "sha256": "b3814c96092ebe90e42675420aa0066a957c51a0be837ea63d67e907726a22e0",
+      "source_path": "data/index/textbook_mineru_fts.db",
+      "runtime_identity": {
+        "type": "sqlite_textbook_runtime_identity_v1",
+        "mutable_tables": [
+          "ai_batch_ingest",
+          "ai_batch_jobs",
+          "ai_chat_logs",
+          "search_logs",
+          "sqlite_sequence"
+        ],
+        "content_tables": {
+          "chunks": {
+            "row_count": 21925,
+            "sha256": "d73e6c4bed9bccce6388ef8411270fdc9aeb67cdbef7d6ebfb52b367567988aa"
+          },
+          "ai_summaries": {
+            "row_count": 17506,
+            "sha256": "9024b21c7da9386f4ed347cd49ac2a1a2946b5f3f292a891d0ea39524c0c10e2"
+          },
+          "ai_explanations": {
+            "row_count": 126,
+            "sha256": "3411be218b600d53652d170c8c8ee8cbb6d40ee430eaf92d65978fcf4c0c3ebf"
+          },
+          "ai_synonyms": {
+            "row_count": 788,
+            "sha256": "427b888ce49c265cd10ec1c6342fc2032c467edb37393549055b2a0b0d57d770"
+          },
+          "concept_map": {
+            "row_count": 1102,
+            "sha256": "dbc7bcc6269e9dc9843391a5868ce87af100fc36f014d5f22fede990713b3563"
+          },
+          "cross_subject_map": {
+            "row_count": 83,
+            "sha256": "aecd745f59f35d5b087a090845b2c9b1c363905d49d2cf575ed38d331a724ea9"
+          },
+          "curated_keywords": {
+            "row_count": 515,
+            "sha256": "0d56877e6f7bf542b1381b1775d301fb576d2eab98e7b3fa048d1216531bead0"
+          },
+          "keyword_counts": {
+            "row_count": 1773,
+            "sha256": "0a1181df496039944a619406c5e1e9f984ad09d5281f29a3d3aee57cc8de70b6"
+          },
+          "ai_gaokao_links": {
+            "row_count": 4029,
+            "sha256": "a1f3beaedba27de965da2c5bd36b5683bbee4d16d38ae2acc6706acd2d4a2a8a"
+          },
+          "ai_relations": {
+            "row_count": 597,
+            "sha256": "b403d9353b08c20e0f0900c825cb002c8d2c5d44cbb3860fc7e02369fe905f3b"
+          }
+        },
+        "fts_shadow_counts": {
+          "chunks_fts": 21925,
+          "chunks_fts_data": 4254,
+          "chunks_fts_idx": 4134,
+          "chunks_fts_docsize": 21925
+        },
+        "integrity_check": "ok"
+      }
     },
     {
       "kind": "runtime",