155 lines
4.4 KiB
Markdown
155 lines
4.4 KiB
Markdown
|
# 生产数据库升级指南 (最终版)
|
|||
|
|
|
|||
|
|
## 重要改进
|
|||
|
|
|
|||
|
|
本方案使用 PostgreSQL 的 `session_replication_role` 特性，**彻底解决外键约束问题**：
|
|||
|
|
|
|||
|
|
### 优势
|
|||
|
|
- ✅ **无需关心插入顺序** - 可以任意顺序导入数据
|
|||
|
|
- ✅ **大幅提升速度** - 跳过外键检查，导入速度提升数倍
|
|||
|
|
- ✅ **事务安全** - 失败自动回滚，数据一致性有保障
|
|||
|
|
- ✅ **自动验证** - 完成后自动检查数据完整性
|
|||
|
|
|
|||
|
|
### 原理
|
|||
|
|
```sql
|
|||
|
|
-- 1. 开启"上帝模式"：暂时忽略外键和触发器
|
|||
|
|
SET session_replication_role = 'replica';
|
|||
|
|
|
|||
|
|
-- 2. 执行所有数据操作（不受外键限制）
|
|||
|
|
BEGIN;
|
|||
|
|
-- 随意导入数据
|
|||
|
|
COMMIT;
|
|||
|
|
|
|||
|
|
-- 3. 恢复正常模式
|
|||
|
|
SET session_replication_role = 'origin';
|
|||
|
|
|
|||
|
|
-- 4. 验证数据一致性
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 快速开始
|
|||
|
|
|
|||
|
|
### 方式1：一键自动升级（推荐）
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd /Users/jiliu/WorkSpace/cosmo/backend/scripts
|
|||
|
|
./upgrade_final.sh
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 方式2：手动执行
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 1. 备份数据库
|
|||
|
|
docker exec cosmo_postgres pg_dump -U postgres -d cosmo_db > backup_$(date +%Y%m%d_%H%M%S).sql
|
|||
|
|
|
|||
|
|
# 2. 执行升级（Navicat 或命令行均可）
|
|||
|
|
cat upgrade_production_final.sql | docker exec -i cosmo_postgres psql -U postgres -d cosmo_db
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 关于 display_name 字段
|
|||
|
|
|
|||
|
|
脚本已适配 `roles` 表的 `display_name` 字段。如果你的生产环境没有这个字段，请：
|
|||
|
|
|
|||
|
|
1. 打开 `upgrade_production_final.sql`
|
|||
|
|
2. 找到第 20-27 行（带 display_name 的版本）
|
|||
|
|
3. 注释掉它们
|
|||
|
|
4. 取消注释第 29-36 行（不带 display_name 的版本）
|
|||
|
|
|
|||
|
|
## 权限要求
|
|||
|
|
|
|||
|
|
**需要 superuser 权限**才能使用 `session_replication_role`。
|
|||
|
|
|
|||
|
|
如果你的数据库用户不是 superuser：
|
|||
|
|
|
|||
|
|
```sql
|
|||
|
|
-- 由 superuser 执行
|
|||
|
|
ALTER USER your_user WITH SUPERUSER;
|
|||
|
|
|
|||
|
|
-- 升级完成后可以撤销
|
|||
|
|
ALTER USER your_user WITH NOSUPERUSER;
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 升级内容
|
|||
|
|
|
|||
|
|
1. ✅ 创建/更新 roles（admin、user）
|
|||
|
|
2. ✅ 添加 celestial_bodies.short_name 字段
|
|||
|
|
3. ✅ 完整导入 14 条 menus 记录
|
|||
|
|
4. ✅ 完整导入 16 条 role_menus 记录
|
|||
|
|
5. ✅ 清空 celestial_events（由定时任务重新生成）
|
|||
|
|
6. ✅ 导入 2 条 scheduled_jobs
|
|||
|
|
7. ✅ 导入/更新 3 条 system_settings
|
|||
|
|
8. ✅ 为现有用户分配角色
|
|||
|
|
9. ✅ 自动验证数据完整性
|
|||
|
|
|
|||
|
|
## 数据完整性保障
|
|||
|
|
|
|||
|
|
脚本在恢复约束后会自动执行以下验证：
|
|||
|
|
|
|||
|
|
- ✅ 检查 role_menus 的 role_id 引用
|
|||
|
|
- ✅ 检查 role_menus 的 menu_id 引用
|
|||
|
|
- ✅ 检查 menus 的 parent_id 引用
|
|||
|
|
|
|||
|
|
如果发现无效引用，会输出 WARNING 信息。
|
|||
|
|
|
|||
|
|
## 回滚方案
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 如果升级失败，使用备份恢复
|
|||
|
|
cat backup_YYYYMMDD_HHMMSS.sql | docker exec -i cosmo_postgres psql -U postgres -d cosmo_db
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 为什么不迁移到 MySQL？
|
|||
|
|
|
|||
|
|
PostgreSQL 的优势：
|
|||
|
|
- 更强的 JSON 支持（你的系统用到 JSONB）
|
|||
|
|
- 更好的 GIS 扩展（PostGIS，适合天文坐标）
|
|||
|
|
- 更完善的窗口函数和 CTE
|
|||
|
|
- 更严格的数据完整性保障
|
|||
|
|
|
|||
|
|
使用 `session_replication_role` 后，外键约束不再是问题！
|
|||
|
|
|
|||
|
|
## 常见问题
|
|||
|
|
|
|||
|
|
### Q: 为什么需要 superuser 权限？
|
|||
|
|
A: `session_replication_role` 是为数据库复制设计的特性，PostgreSQL 限制只有 superuser 可以修改它，以防止普通用户破坏数据一致性。
|
|||
|
|
|
|||
|
|
### Q: 会影响生产环境吗？
|
|||
|
|
A: 不会。这个设置只影响当前会话，不影响其他连接。而且在事务中执行，失败自动回滚。
|
|||
|
|
|
|||
|
|
### Q: 如果我没有 superuser 权限怎么办？
|
|||
|
|
A:
|
|||
|
|
1. 联系 DBA 临时授予权限
|
|||
|
|
2. 或者使用之前的 `upgrade_production_smart.sql`（会慢一些）
|
|||
|
|
|
|||
|
|
### Q: 数据一致性如何保证？
|
|||
|
|
A: 脚本在恢复约束后会自动验证所有外键引用。如果有问题会立即报告。
|
|||
|
|
|
|||
|
|
## 性能对比
|
|||
|
|
|
|||
|
|
| 方案 | 导入速度 | 复杂度 | 推荐度 |
|
|||
|
|
|------|---------|--------|--------|
|
|||
|
|
| 传统方案（严格顺序） | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ |
|
|||
|
|
| DISABLE TRIGGER | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
|
|||
|
|
| **session_replication_role** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ |
|
|||
|
|
|
|||
|
|
## 升级后操作
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 1. 重启后端服务
|
|||
|
|
docker restart cosmo-backend
|
|||
|
|
|
|||
|
|
# 2. 验证前端功能
|
|||
|
|
# - 登录系统
|
|||
|
|
# - 检查菜单显示
|
|||
|
|
# - 测试用户功能
|
|||
|
|
|
|||
|
|
# 3. 手动执行定时任务（可选）
|
|||
|
|
# 在后台管理 -> 定时任务设置 -> 立即执行
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 联系支持
|
|||
|
|
|
|||
|
|
如有问题，请检查：
|
|||
|
|
1. PostgreSQL 日志: `docker logs cosmo_postgres --tail 100`
|
|||
|
|
2. 用户权限: `SELECT current_user, usesuper FROM pg_user WHERE usename = current_user;`
|
|||
|
|
3. 数据一致性验证输出
|