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