huang
95fc0b0a1b
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 8m16s
329 lines
8.5 KiB
Markdown
329 lines
8.5 KiB
Markdown
# 生产数据库手工上线流程
|
|
|
|
## 1. 适用场景
|
|
|
|
本文档用于君鸿卡管系统**首次生产上线**时的数据库初始化，目标是：
|
|
|
|
1. **不依赖应用启动自动建表**
|
|
2. **人工创建生产库和表结构**
|
|
3. **人工导入基础数据**
|
|
4. **人工对齐 `schema_migrations` 版本**
|
|
5. 后续继续沿用 `migrations/` 中的新增迁移
|
|
|
|
> 截至 **2026-05-06**，仓库内最新迁移版本为 **140**。
|
|
> 当前仓库缺少可直接用于“全新环境从 0 建表”的 `000114_squash_baseline`，因此首次生产上线建议走“**手工 schema 基线 + 手工基础数据导入 + 手工迁移版本对齐**”。
|
|
|
|
---
|
|
|
|
## 2. 上线原则
|
|
|
|
### 2.1 本次建议做的事
|
|
|
|
1. 从你确认过的**源库**生成一份生产首发 schema 基线 SQL
|
|
2. 在生产环境手工创建空数据库
|
|
3. 手工执行 schema 基线 SQL 建表
|
|
4. 导入基础数据
|
|
5. 手工写入 `schema_migrations=140`
|
|
6. 启动 API / Worker
|
|
|
|
### 2.2 本次不建议做的事
|
|
|
|
1. 不依赖应用自动建表
|
|
2. 不直接把当前活跃 `migrations/` 当作全新建库链路执行
|
|
3. 不把业务数据表（订单、卡、设备、钱包流水等）从测试库整库导入生产
|
|
4. 不直接复用测试环境里的密钥、回调地址、商户配置而不做复核
|
|
|
|
---
|
|
|
|
## 3. 基础数据范围
|
|
|
|
### 3.1 建议导入的非敏感基础数据
|
|
|
|
以下表建议从已确认的源库导出，再导入生产库：
|
|
|
|
1. `tb_permission`
|
|
2. `tb_role`
|
|
3. `tb_role_permission`
|
|
4. `tb_carrier`
|
|
5. `tb_commission_withdrawal_setting`
|
|
6. `tb_polling_config`
|
|
7. `tb_polling_concurrency_config`
|
|
8. `tb_polling_alert_rule`
|
|
9. `tb_data_cleanup_config`
|
|
|
|
### 3.2 建议单独处理的敏感基础数据
|
|
|
|
以下表包含支付、公众号、小程序、证书、密钥等敏感信息，建议单独导出或手工填充：
|
|
|
|
1. `tb_wechat_config`
|
|
|
|
### 3.3 不建议首发直接导入的数据
|
|
|
|
以下数据不属于“生产首发基础数据”，通常不要从测试库带入生产：
|
|
|
|
1. `tb_account`
|
|
2. `tb_account_role`
|
|
3. `tb_shop`
|
|
4. `tb_enterprise`
|
|
5. `tb_iot_card`
|
|
6. `tb_device`
|
|
7. `tb_order`
|
|
8. 各类钱包、流水、日志、审计、导入任务表
|
|
|
|
---
|
|
|
|
## 4. 关于表结构基线
|
|
|
|
### 4.1 建议默认排除的确认遗留表
|
|
|
|
以下两张表已具备明确“遗留/保留历史”的语义，生成生产首发 schema 基线时建议默认排除：
|
|
|
|
1. `tb_data_usage_record`
|
|
2. `tb_card_replacement_record_legacy`
|
|
|
|
### 4.2 建议保守保留、后续再评估的表
|
|
|
|
以下表当前在代码里的活跃引用较少或暂无数据，但仍不建议在首次生产上线时贸然删除，先按兼容方式保留更稳：
|
|
|
|
1. `tb_card_replacement_request`
|
|
2. `tb_number_card`
|
|
3. `tb_payment_merchant_setting`
|
|
4. `tb_dev_capability_config`
|
|
|
|
---
|
|
|
|
## 5. 交付文件
|
|
|
|
本目录对应的手工上线辅助文件位于：
|
|
|
|
`scripts/manual_db_release/`
|
|
|
|
按执行顺序主要包括：
|
|
|
|
1. `01_create_database.sql`
|
|
2. `02_generate_schema_baseline.sh`
|
|
3. `03_export_base_data_from_source.sh`
|
|
4. `04_import_base_data_into_target.sh`
|
|
5. `05_repair_base_data_sequences.sql`
|
|
6. `06_mark_schema_migrations.sql`
|
|
7. `07_verify_manual_release.sql`
|
|
|
|
---
|
|
|
|
## 6. 手工上线步骤
|
|
|
|
## 6.1 第一步：确定源库
|
|
|
|
源库应满足：
|
|
|
|
1. 结构版本已确认正确
|
|
2. 基础配置完整
|
|
3. 权限、角色、运营商、轮询配置经过业务验收
|
|
|
|
建议不要临时选一个“有人随手改过但未复核”的测试库。
|
|
|
|
---
|
|
|
|
## 6.2 第二步：手工创建生产数据库
|
|
|
|
先修改：
|
|
|
|
`scripts/manual_db_release/01_create_database.sql`
|
|
|
|
将其中的占位符替换为：
|
|
|
|
1. `__DB_NAME__`
|
|
2. `__DB_USER__`
|
|
3. `__DB_PASSWORD__`
|
|
|
|
然后执行：
|
|
|
|
```bash
|
|
psql "postgres://postgres:你的密码@生产PG主机:5432/postgres?sslmode=disable" \
|
|
-f scripts/manual_db_release/01_create_database.sql
|
|
```
|
|
|
|
---
|
|
|
|
## 6.3 第三步：生成 schema 基线 SQL
|
|
|
|
使用脚本：
|
|
|
|
```bash
|
|
SOURCE_DSN="postgres://源库账号:源库密码@源库主机:5432/源库名?sslmode=disable" \
|
|
OUTPUT_SQL="/你的目录/00_schema_baseline.sql" \
|
|
bash scripts/manual_db_release/02_generate_schema_baseline.sh
|
|
```
|
|
|
|
默认会排除：
|
|
|
|
1. `schema_migrations`
|
|
2. `tb_data_usage_record`
|
|
3. `tb_card_replacement_record_legacy`
|
|
|
|
生成后请人工复核一次：
|
|
|
|
1. 是否包含你确认不需要的历史表
|
|
2. 是否错误带入测试专用对象
|
|
3. 是否包含意外的 `OWNER TO`
|
|
4. 是否包含不应该进入生产的注释性对象
|
|
|
|
---
|
|
|
|
## 6.4 第四步：在生产库执行 schema 基线
|
|
|
|
```bash
|
|
psql "postgres://junhong_cmp:CtCom1zBzPQbpVNf3rCNxH@cxd.whcxd.cn:16159/junhong_cmp_prod?sslmode=disable" \
|
|
-v ON_ERROR_STOP=1 \
|
|
-f /你的目录/00_schema_baseline.sql
|
|
```
|
|
|
|
执行后先不要急着启动应用，先导入基础数据。
|
|
|
|
---
|
|
|
|
## 6.5 第五步：导出基础数据
|
|
|
|
导出非敏感基础数据：
|
|
|
|
```bash
|
|
SOURCE_DSN="postgres://erp_pgsql:erp_2025@cxd.whcxd.cn:16159/junhong_cmp_test?sslmode=disable" \
|
|
bash scripts/manual_db_release/03_export_base_data_from_source.sh
|
|
```
|
|
|
|
如需连同微信配置一起导出：
|
|
|
|
```bash
|
|
SOURCE_DSN="postgres://erp_pgsql:erp_2025@cxd.whcxd.cn:16159/junhong_cmp_test?sslmode=disable" \
|
|
INCLUDE_SENSITIVE=1 \
|
|
bash scripts/manual_db_release/03_export_base_data_from_source.sh
|
|
```
|
|
|
|
导出结果会放到：
|
|
|
|
`scripts/manual_db_release/generated/`
|
|
|
|
> 注意：`generated/` 下的 SQL 可能包含密钥和证书内容，不要提交到 Git。
|
|
|
|
---
|
|
|
|
## 6.6 第六步：导入基础数据
|
|
|
|
在生产库执行：
|
|
|
|
```bash
|
|
TARGET_DSN="postgres://junhong_cmp:CtCom1zBzPQbpVNf3rCNxH@cxd.whcxd.cn:16159/junhong_cmp_prod?sslmode=disable" \
|
|
bash scripts/manual_db_release/04_import_base_data_into_target.sh
|
|
```
|
|
|
|
如需导入敏感配置：
|
|
|
|
```bash
|
|
TARGET_DSN="postgres://生产库账号:生产库密码@生产库主机:5432/生产库名?sslmode=disable" \
|
|
INCLUDE_SENSITIVE=1 \
|
|
bash scripts/manual_db_release/04_import_base_data_into_target.sh
|
|
```
|
|
|
|
---
|
|
|
|
## 6.7 第七步：修正序列值
|
|
|
|
```bash
|
|
psql "postgres://junhong_cmp:CtCom1zBzPQbpVNf3rCNxH@cxd.whcxd.cn:16159/junhong_cmp_prod?sslmode=disable" \
|
|
-v ON_ERROR_STOP=1 \
|
|
-f scripts/manual_db_release/05_repair_base_data_sequences.sql
|
|
```
|
|
|
|
这一步用于避免显式插入 ID 后，自增序列仍停留在旧值。
|
|
|
|
---
|
|
|
|
## 6.8 第八步：手工对齐迁移版本
|
|
|
|
```bash
|
|
psql "postgres://生产库账号:生产库密码@生产库主机:5432/生产库名?sslmode=disable" \
|
|
-v ON_ERROR_STOP=1 \
|
|
-f scripts/manual_db_release/06_mark_schema_migrations.sql
|
|
```
|
|
|
|
执行后，生产库会被视为已处于 `140` 版本。
|
|
后续如果仓库新增 `141+` 迁移，就可以继续正常执行 `migrate up`。
|
|
|
|
> 如果你上线时仓库最新迁移版本已经不是 `140`，记得同步修改 `06_mark_schema_migrations.sql`。
|
|
|
|
---
|
|
|
|
## 6.9 第九步：上线前校验
|
|
|
|
```bash
|
|
psql "postgres://生产库账号:生产库密码@生产库主机:5432/生产库名?sslmode=disable" \
|
|
-f scripts/manual_db_release/07_verify_manual_release.sql
|
|
```
|
|
|
|
重点关注：
|
|
|
|
1. `schema_migrations.version=140`
|
|
2. 权限、角色、角色权限数量不为 0
|
|
3. 运营商配置数量不为 0
|
|
4. 轮询配置数量不为 0
|
|
5. `tb_wechat_config` 是否按预期导入
|
|
|
|
---
|
|
|
|
## 6.10 第十步：启动应用
|
|
|
|
确认以下环境变量改为生产值：
|
|
|
|
1. `JUNHONG_DATABASE_HOST`
|
|
2. `JUNHONG_DATABASE_PORT`
|
|
3. `JUNHONG_DATABASE_USER`
|
|
4. `JUNHONG_DATABASE_PASSWORD`
|
|
5. `JUNHONG_DATABASE_DBNAME`
|
|
6. `JUNHONG_REDIS_*`
|
|
7. `JUNHONG_JWT_SECRET_KEY`
|
|
|
|
特别注意：
|
|
|
|
1. 当前仓库里的 `docker-compose.prod.yml` 示例仍是测试库参数，不能原样直接用于生产
|
|
2. 如果生产库里没有超级管理员账号，应用启动时会自动创建一个超级管理员账号
|
|
3. 如不希望使用默认超管账号，请提前设置 `JUNHONG_DEFAULT_ADMIN_USERNAME`、`JUNHONG_DEFAULT_ADMIN_PASSWORD`、`JUNHONG_DEFAULT_ADMIN_PHONE`
|
|
|
|
---
|
|
|
|
## 7. 推荐执行顺序汇总
|
|
|
|
```text
|
|
手工创建生产库
|
|
-> 生成 schema 基线 SQL
|
|
-> 执行 schema 基线 SQL
|
|
-> 导出基础数据
|
|
-> 导入基础数据
|
|
-> 修正序列
|
|
-> 写入 schema_migrations=140
|
|
-> 校验
|
|
-> 启动 API / Worker
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 风险提醒
|
|
|
|
### 8.1 关于 `tb_wechat_config`
|
|
|
|
该表包含敏感配置，建议：
|
|
|
|
1. 单独导出
|
|
2. 单独传输
|
|
3. 单独审批
|
|
4. 导入后立刻校验回调地址、商户号、证书内容
|
|
|
|
### 8.2 关于账号初始化
|
|
|
|
本次流程**不建议**直接从测试库导入 `tb_account`。
|
|
首发生产环境建议只导入权限体系和系统配置，让生产超管账号在受控条件下独立创建。
|
|
|
|
### 8.3 关于后续迁移
|
|
|
|
本次只是首次生产上线的“人工基线落地”。
|
|
后续版本发布仍应继续补齐正式的 `000114_squash_baseline`，避免长期依赖手工基线流程。
|