fix(avatar): prevent stale deployment images

digital-avatar-app/docs/H5_PRODUCTION_DEPLOYMENT.md

@@ -61,8 +61,10 @@ WECHAT_VIRTUAL_PRODUCT_2=<100元套餐商品ID>
 WECHAT_VIRTUAL_PRODUCT_3=<1000元套餐商品ID>
 WECHAT_VIRTUAL_PRODUCT_4=<10000元套餐商品ID>
 
-DATABASE_URL=sqlite:////data/avatar.db
-UPLOAD_DIR=/data/uploads
+AVATAR_DB_PATH=/srv/digital-avatar/data/avatar.db
+AVATAR_UPLOAD_DIR=/srv/digital-avatar/data/uploads
+DATABASE_URL=sqlite:////app/avatar.db
+UPLOAD_DIR=/app/uploads
 CHAT_MODEL_CONFIG_URL=http://<huihuisquare-api>/api/ai-models/runtime/digital-avatar
 EMBEDDING_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
 EMBEDDING_API_KEY=<production-embedding-api-key>
@@ -74,13 +76,17 @@ VISION_OCR_MODEL=qwen-vl-ocr
 VISION_MAX_OUTPUT_TOKENS=2048
 VISION_TIMEOUT_SECONDS=90
 VISION_TOKEN_RESERVE=12000
+APP_GIT_SHA=<本次发布的完整提交SHA>
+APP_BUILD_TIME=<UTC ISO-8601构建时间>
 CHAT_IMAGE_MAX_BYTES=8388608
 CHAT_IMAGE_MAX_PIXELS=16000000
 CHAT_ATTACHMENT_RETENTION_HOURS=24
 CHAT_ATTACHMENT_CLEANUP_MINUTES=60
 ```
 
-如生产 AI 配置中心不可用，还应提供当前项目支持的 `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`CHAT_MODEL` 等兜底配置。`/data` 必须挂载持久卷，数据库与知识库文件不可存放在容器临时层。
+如生产 AI 配置中心不可用，还应提供当前项目支持的 `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`CHAT_MODEL` 等兜底配置。数据库文件与上传目录必须从宿主机显式挂载，不能存放在容器临时层。
+
+`AVATAR_DB_PATH` 和 `AVATAR_UPLOAD_DIR` 必须是已备份的宿主机绝对路径，编排缺少任一变量都会直接拒绝构建或启动，防止误挂空卷造成用户、分身或知识库“丢失”的假象。
 
 `EMBEDDING_API_URL` 同时支持 OpenAI 兼容基础地址（如上面的 `/v1`）和完整的 `/v1/embeddings` 地址，后端会统一请求 `/embeddings`。发布后必须在后端容器内执行一次最小向量探针，确认返回向量数量和维度，而不能只检查 `/api/health`。
 
@@ -107,13 +113,22 @@ tar -C /srv/digital-avatar/data -czf "$BACKUP_DIR/uploads.tgz" uploads
 git fetch origin
 git checkout <已验收的提交SHA>
 cd digital-avatar-app
-docker compose build --pull avatar-backend avatar-frontend
-docker compose up -d avatar-backend avatar-frontend
+export APP_GIT_SHA="$(git rev-parse HEAD)"
+export APP_BUILD_TIME="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+docker compose build --pull --no-cache avatar-backend avatar-frontend
+docker compose up -d --force-recreate --wait avatar-backend avatar-frontend
 docker compose ps
-curl -fsS http://127.0.0.1:8099/api/health
+python3 scripts/verify-deployment.py \
+  https://digital.99hui.com "$APP_GIT_SHA" \
+  --backend-container avatar-backend \
+  --frontend-container avatar-frontend \
+  --expected-db-source /srv/digital-avatar/data/avatar.db \
+  --expected-upload-source /srv/digital-avatar/data/uploads
 docker compose exec avatar-backend python -c 'import embeddings; v=embeddings.embed(["部署向量探针"]); print(len(v), len(v[0]))'
 ```
 
+Jenkins 必须以 `verify-deployment.py` 返回成功作为发布成功条件，不能只以镜像构建或容器启动成功作为条件。脚本会同时核对公网前后端 Git SHA、数据库可读、上传目录可写、PDF OCR 依赖和宿主机数据挂载；任意一项不一致都会返回非零状态并阻止发布标绿。镜像使用 Git SHA 标签，不再依赖可被旧缓存覆盖的 `latest`。
+
 生产编排应把示例中的测试端口改为内网暴露，由统一 HTTPS 网关接入。后端暂时使用 SQLite，必须保持单实例写入；若扩展为多后端实例，应先迁移到 PostgreSQL，并把延迟接管任务改为共享队列。
 
 ## 4. 网关要求
@@ -153,7 +168,7 @@ location /api/ {
 5. 使用过期或伪造 token 时进入登录页并显示凭证失效，不得继续访问旧用户数据。
 6. 分身聊天 SSE 逐段输出正常，Markdown 正常渲染，知识库优先级和积分扣费正常。
 7. 开启 BOXIM 主动接管后保持在线，默认三分钟回复、自定义等待时间、已读回执、分身防回环和主人发言暂停均正常。
-8. 重建容器后数据库、头像、知识库文档仍存在，`/api/health` 返回成功。
+8. 重建容器后数据库、头像、知识库文档仍存在，`/api/health` 的 `gitSha` 与发布 SHA 一致，`database`、`uploads`、`pdfOcr` 三项检查均为 `true`。
 9. `https://digital.99hui.com/api/health` 可访问，证书域名和有效期正确，HTTP 自动跳转 HTTPS。
 10. 微信和支付宝各创建一笔最小套餐订单，未付款时积分不变；支付成功后回调到账一次，重复回调积分不重复增加。
 11. 微信虚拟支付在沙箱环境完成下单、支付回调、查单兜底和退款回调；错误 OpenID、商品、环境或金额均被拒绝。