209 lines
4.7 KiB
Markdown
209 lines
4.7 KiB
Markdown
# 生产发布与数据库上线方案
|
||
> 文档版本：v1.0
|
||
> 最后更新：2026-04-03 16:20:00
|
||
|
||
## 1. 目标
|
||
|
||
本文档用于约定：
|
||
|
||
- 开发测试数据库与正式生产数据库的关系
|
||
- 正式上线时数据库如何初始化与升级
|
||
- 后端服务如何与数据库发布配合
|
||
- 每次上线前后的最小检查项
|
||
|
||
当前原则只有一条：
|
||
|
||
- **测试库继续做测试，生产库独立建库，靠 migration 升级，不靠手工拷贝。**
|
||
|
||
---
|
||
|
||
## 2. 环境划分
|
||
|
||
建议至少分 2 套数据库环境：
|
||
|
||
- `dev`：开发 / 联调 / demo / workbench
|
||
- `prod`：正式生产
|
||
|
||
如果条件允许，推荐分 3 套：
|
||
|
||
- `dev`
|
||
- `staging`
|
||
- `prod`
|
||
|
||
其中：
|
||
|
||
- `dev` 用于日常开发和联调
|
||
- `staging` 用于上线前预演
|
||
- `prod` 只承载正式业务数据
|
||
|
||
---
|
||
|
||
## 3. 当前数据库结构来源
|
||
|
||
当前仓库已经采用 migration 驱动结构演进，目录位于：
|
||
|
||
- [D:\dev\cmr-mini\backend\migrations](D:/dev/cmr-mini/backend/migrations)
|
||
|
||
当前已存在的迁移文件包括：
|
||
|
||
- `0001_init.sql`
|
||
- `0002_launch.sql`
|
||
- `0003_home.sql`
|
||
- `0004_results.sql`
|
||
- `0005_config_pipeline.sql`
|
||
- `0006_resource_objects.sql`
|
||
- `0007_variant_minimal.sql`
|
||
- `0008_production_skeleton.sql`
|
||
- `0009_event_ops_phase2.sql`
|
||
|
||
因此正式上线时，数据库结构应以这些 migration 为准，而不是以当前测试库的现状为准。
|
||
|
||
---
|
||
|
||
## 4. 第一次生产上线
|
||
|
||
第一次正式上线建议按以下顺序执行：
|
||
|
||
1. 新建生产 PostgreSQL 数据库
|
||
2. 配置生产环境变量
|
||
3. 按顺序执行全部 migration
|
||
4. 导入必要的生产基础数据
|
||
5. 部署后端服务
|
||
6. 执行最小 smoke test
|
||
7. 再切前端 / 小程序到生产后端
|
||
|
||
### 4.1 生产环境变量
|
||
|
||
至少应与开发环境分离以下配置：
|
||
|
||
- `DATABASE_URL`
|
||
- JWT 相关密钥
|
||
- 微信小程序相关配置
|
||
- OSS / 资源发布相关配置
|
||
- 其它第三方服务配置
|
||
|
||
开发环境中的 `.env` 不能直接视为生产配置。
|
||
|
||
参考文件：
|
||
|
||
- [D:\dev\cmr-mini\backend\.env.example](D:/dev/cmr-mini/backend/.env.example)
|
||
|
||
### 4.2 生产初始数据
|
||
|
||
第一次上线时，建议只导入最小必要数据，例如：
|
||
|
||
- 租户
|
||
- 默认渠道
|
||
- 最小活动与地图运行数据
|
||
|
||
不建议把开发联调用的 demo 数据直接原样导入生产。
|
||
|
||
---
|
||
|
||
## 5. 后续版本上线
|
||
|
||
每次后续正式上线建议固定为以下顺序：
|
||
|
||
1. 备份生产数据库
|
||
2. 部署前确认本次新增 migration
|
||
3. 执行新增 migration
|
||
4. 发布后端服务
|
||
5. 验证关键接口
|
||
6. 再切客户端或前端流量
|
||
|
||
关键接口最少应验证：
|
||
|
||
- 登录
|
||
- 活动列表
|
||
- 活动详情
|
||
- `launch`
|
||
- `session start / finish`
|
||
- `result / history`
|
||
|
||
---
|
||
|
||
## 6. 上线原则
|
||
|
||
### 6.1 不直接复用测试库
|
||
|
||
禁止做法：
|
||
|
||
- 直接把开发测试数据库改名当生产库
|
||
- 通过手工拷表来“上线”
|
||
- 在生产库中临时手改结构但不补 migration
|
||
|
||
### 6.2 结构变更只走 migration
|
||
|
||
所有数据库结构变化都应：
|
||
|
||
- 新增 migration 文件
|
||
- 进入版本管理
|
||
- 随代码一起发布
|
||
|
||
不应依赖口头约定或临时 SQL。
|
||
|
||
### 6.3 生产数据与测试数据分离
|
||
|
||
开发 demo 数据、联调活动、手工实验数据，应停留在：
|
||
|
||
- `dev`
|
||
- 或 `staging`
|
||
|
||
不要直接进入 `prod`。
|
||
|
||
### 6.4 代码版本与数据库版本对应
|
||
|
||
每次上线都应能回答两件事：
|
||
|
||
- 当前代码对应到哪一个 migration 版本
|
||
- 当前生产库已经执行到哪一个 migration 版本
|
||
|
||
---
|
||
|
||
## 7. 推荐的发布节奏
|
||
|
||
建议发布节奏为：
|
||
|
||
### 阶段 1：数据库先行
|
||
|
||
- 新 migration 先在 `dev` 验证
|
||
- 再在 `staging` 演练
|
||
- 最后进入 `prod`
|
||
|
||
### 阶段 2：服务发布
|
||
|
||
- 后端服务发布到对应环境
|
||
- 验证启动、连接数据库、关键接口可用
|
||
|
||
### 阶段 3：客户端切换
|
||
|
||
- 小程序 / App / H5 再切到新的后端能力
|
||
- 避免客户端先切到一个数据库未升级的后端版本
|
||
|
||
---
|
||
|
||
## 8. 当前项目建议的最小上线清单
|
||
|
||
对当前仓库，正式上线前建议至少确认：
|
||
|
||
- [D:\dev\cmr-mini\backend\migrations](D:/dev/cmr-mini/backend/migrations) 已完整纳入发布
|
||
- [D:\dev\cmr-mini\doc\backend\后台生产闭环架构草案.md](D:/dev/cmr-mini/doc/backend/后台生产闭环架构草案.md) 中当前主线对象已落库
|
||
- `DATABASE_URL` 已切到生产库
|
||
- JWT / 微信 / OSS 配置已替换为生产值
|
||
- workbench / 管理接口在生产环境默认不对外暴露或受限
|
||
- demo 事件、demo variant 不进入生产正式运营入口
|
||
|
||
---
|
||
|
||
## 9. 一句话结论
|
||
|
||
当前项目的正式上线方式应固定为：
|
||
|
||
- **新建独立生产库**
|
||
- **通过 migration 初始化和升级**
|
||
- **通过生产环境变量部署后端**
|
||
- **通过最小 smoke test 验证**
|
||
- **最后再切客户端入口**
|
||
|
||
不要把开发测试数据库直接视为生产数据库。
|