rebuild(deploy): make NAS preflight reversible

next/docs/deployment.md

@@ -7,7 +7,8 @@
 1. 将 `.env.example` 复制为 `.env`，写入固定的 Fernet `APP_ENCRYPTION_KEY`。该密钥必须与迁移旧数据时使用的密钥一致。
 2. 创建 `data/private-mentor-skills/`，把不公开的 Skill 放在该持久化目录；镜像内只含公开 Skill。
 3. 先在独立目录运行迁移，并查看报告中的迁移数、主动跳过项、完整性和校验和。
-4. 使用尚未占用的端口启动新容器并完成验收。不要停止旧容器。
+4. 保持`APP_PUBLISH_PORT=8876`在临时端口启动新容器并完成验收。不要停止旧容器，也不要提前改成正式端口。
+5. `APP_IMAGE`使用可回溯的验收标签；正式切换和回退均不得只依赖浮动的`latest`标签。
 
 ```powershell
 $env:APP_ENCRYPTION_KEY='<现有固定密钥>'
@@ -20,6 +21,10 @@ docker compose build
 docker compose up -d
 ```
 
+启动后先检查`http://NAS地址:8876/api/health`，再访问`http://NAS地址:8876/`完成真实账号抽验。
+宿主`data`目录必须允许镜像中的非root用户写入；若启动日志出现权限错误，先用
+`docker compose run --rm web id`确认容器UID/GID，再只修正该绑定目录的所有权，不得改为root运行容器。
+
 `legacy_migration` 以只读 URI 打开旧库，可重复执行；会保留用户编号和密码散列，不迁移会话。旧的每用户 LLM 配置和可由正式数据源重建的原始因子表会明确记录为主动跳过，不会进入新运行时。
 
 ## 备份
@@ -55,11 +60,14 @@ python -m tools.restore `
 ## 升级与回退
 
 1. 升级前生成一致备份，记录当前镜像标签与数据库 migration 版本。
-2. 用新镜像启动独立验收容器；健康检查通过后再切换反向代理或宿主端口。
+2. 用固定`APP_IMAGE`标签和临时`APP_PUBLISH_PORT=8876`启动独立验收容器；健康检查通过后再切换反向代理或宿主端口。
 3. 代码回退只切换至旧镜像，不自动降级数据库。
 4. 若新 migration 与旧镜像不兼容，使用升级前的整套备份恢复到独立目录，再启动旧镜像。
 5. NAS 正式切换属于单独人工确认项，本仓库脚本不会自动执行切换。
 
+若最终采用宿主端口直连，只有在旧容器停止写入且用户确认切换窗口后，才把`APP_PUBLISH_PORT`
+改为`8765`并重新创建新容器。若通过反向代理切流，则继续保留临时宿主端口，由反向代理修改上游。
+
 ## 本机验证边界
 
 开发机未安装 Docker 时仍可执行全部 Python、前端构建、迁移和备份恢复测试，但不能声称镜像已经实际构建或容器健康检查已经运行。最终切换前应在有 Docker 的 NAS 或预发布机补做 `docker compose build`、只读文件系统、数据卷写入和重启恢复验证。

next/docs/final/cutover-checklist.md

@@ -8,7 +8,8 @@
 - [ ] 验证容器以非root、只读根文件系统启动，`/app/data`可写，健康检查稳定。
 - [ ] 验证容器重启后账号、行情、自选、复盘、会员、模型、问天和选股记录不丢失。
 - [ ] 在NAS受控目录完成数据库、环境密钥和私有Skill整套备份，并做一次独立恢复。
-- [ ] 为新容器分配临时端口，完成真实数据的日间/夜间、1080P/4K/390px抽验。
+- [ ] 保持`APP_PUBLISH_PORT=8876`启动新容器，完成真实数据的日间/夜间、1080P/4K/390px抽验。
+- [ ] 记录实际`APP_IMAGE`标签，确认该标签可在不重新构建的情况下用于回退演练。
 - [ ] 用户明确确认最终切换窗口。
 
 ## 切换步骤