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. 数据一致性验证输出
|