life-echo/docs/before-prod/production-readiness-summary-2026-03-11.md

Production 上线判断总结（2026-03-11）

结论

当前代码已经接近可上线状态，但是否可以直接进入 production，取决于图片功能的上线策略。

• 如果接受丢弃历史旧图，并且上线时将 MEMOIR_IMAGE_ENABLED=false，则本次改动不需要额外做数据库迁移，整体风险可控，可以作为保守方案进入生产。
• 如果准备在生产立即启用章节配图功能，则仍需确认生产 COS 资源、Liblib 凭证、Celery worker 部署和新依赖安装均已就绪，之后再启用更稳妥。

本次评估范围

本次评估针对 8b4a058..HEAD 期间的改动，重点检查了以下内容：

• 数据库模型和迁移脚本是否变化
• API / WebSocket / Celery 是否有生产兼容性风险
• 回忆录图片链路是否会影响现网章节读取、阅读页和 PDF 导出
• 生产环境变量和容器部署形态是否能承接新能力

数据库与迁移判断

不需要新增 schema 迁移

本次区间内没有新增数据库表、字段或字段类型修改。

• api/database/models.py 中 Chapter.images 只有注释语义变化，从“图片 URL 列表”变成“图片元数据对象列表”
• api/migrations/sync_schema_to_models.sql 在这段提交区间没有新增迁移内容

因此：

• 不需要新增 SQL migration
• 不需要执行结构性数据迁移

图片功能判断

MEMOIR_IMAGE_ENABLED 不是“全功能总开关”

这个开关能控制的是：

• 是否初始化待生成图片资产
• 是否派发 generate_chapter_images 任务
• 是否在读取章节时过滤掉未完成图片状态

这个开关不能完全关闭的内容：

• 章节正文里的图片占位符注入逻辑仍会存在
• 已完成图片仍可能继续被返回和渲染
• 章节接口仍会进入图片归一化逻辑
• PDF 导出仍会处理已完成图片

旧 chapters.images 数据兼容性

历史文档里 images 被定义为“图片 URL 列表”，但当前代码要求每个元素都具备至少以下字段：

• placeholder
• description

否则在归一化时会被过滤掉。

结论：

• 如果必须保留历史旧图，需要额外做读兼容或数据修复
• 如果业务允许丢弃历史旧图，则这项不再构成上线阻塞

当前推荐策略

结合当前讨论结果，推荐采用以下上线策略：

1. 允许丢弃历史旧图
2. 生产环境先保持 MEMOIR_IMAGE_ENABLED=false
3. 先完成主链路上线
4. 等生产 COS / Liblib / worker 验证完成后，再单独开启图片能力

这样做的好处：

• 不需要补兼容代码
• 不需要回填旧数据
• 能把风险集中在“新生成图片”而不是“历史数据”

生产环境配置判断

已具备的条件

• Dockerfile 会安装新的 Python 依赖，包括 cos-python-sdk-v5
• docker-compose.yml 已包含 api 和 celery-worker
• api/.env.production 已经包含图片链路需要的 LIBLIB_* 和 TENCENT_COS_* 配置项

仍需确认的点

• TENCENT_COS_BUCKET 和 TENCENT_COS_BASE_URL 是否为真正的生产资源
• API 镜像和 Celery worker 是否会同步升级
• 部署时是否一定会基于最新 requirements.txt 重新构建镜像

当前建议的上线结论

可以进入生产的前提

满足以下条件时，可以作为稳妥方案进入生产：

1. 接受丢弃历史旧图
2. 保持 MEMOIR_IMAGE_ENABLED=false
3. 使用最新镜像同时部署 api 与 celery-worker
4. 确认 COS 配置不是误填开发资源

不建议直接开启图片功能的场景

如果满足以下任一情况，建议不要在本次发版里直接启用图片生成：

• 生产 COS bucket 尚未确认
• Liblib 凭证未经生产验证
• Celery worker 不会同步升级
• 希望保留历史旧图但尚未做兼容或数据修复

最短上线检查单

发版前至少确认以下 5 项：

1. api/.env.production 中 MEMOIR_IMAGE_ENABLED 是否符合本次上线策略
2. TENCENT_COS_BUCKET / TENCENT_COS_BASE_URL 是否为生产资源
3. api 和 celery-worker 是否会使用同一版新镜像
4. 镜像是否会基于最新 requirements.txt 重建
5. 团队是否明确接受“历史旧图可能消失”

建议的发布策略

推荐分两步：

第一步：保守上线

• 发布当前代码
• MEMOIR_IMAGE_ENABLED=false
• 观察 API、WebSocket、章节读取、PDF 导出是否稳定

第二步：功能放量

• 确认 COS / Liblib / worker 正常
• 再将 MEMOIR_IMAGE_ENABLED=true
• 仅对新生成章节启用图片功能