# 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`
- 仅对新生成章节启用图片功能