113 lines
3.1 KiB
Markdown
113 lines
3.1 KiB
Markdown
# 生产环境部署指南 - 学校班级ID迁移
|
||
|
||
## 背景说明
|
||
|
||
由于雪花算法生成的 ID（19位数字）超出了 JavaScript 安全整数范围（`9007199254740991`），导致前端在处理 `pg_school_class.id` 时会丢失精度。
|
||
|
||
本次更新将 `pg_school_class` 表的 ID 生成策略从雪花算法改为数据库自增。
|
||
|
||
## 涉及的代码变更
|
||
|
||
| 文件 | 变更内容 |
|
||
|------|----------|
|
||
| `PgSchoolClass.java` | `@TableId(type = IdType.ASSIGN_ID)` → `@TableId(type = IdType.AUTO)` |
|
||
| `SchoolClassIdMigration.java` | 新增，应用启动时自动迁移（仅开发环境使用） |
|
||
|
||
## 部署步骤
|
||
|
||
### 1. 准备工作
|
||
|
||
- [ ] 通知相关人员，安排维护窗口
|
||
- [ ] 备份生产数据库（完整备份）
|
||
- [ ] 准备好回滚方案
|
||
|
||
### 2. 执行数据库迁移
|
||
|
||
**重要：在部署新代码之前执行！**
|
||
|
||
```bash
|
||
# 连接到生产数据库
|
||
mysql -h <host> -u <user> -p <database>
|
||
|
||
# 执行迁移脚本
|
||
source production_migrate_school_class_id.sql
|
||
```
|
||
|
||
脚本执行过程中会显示：
|
||
- 需要迁移的记录数
|
||
- ID 映射详情（旧ID → 新ID）
|
||
- 数据完整性验证结果
|
||
|
||
### 3. 验证迁移结果
|
||
|
||
确认脚本输出中所有检查项都显示 `✓ 通过`：
|
||
- 数据完整性检查
|
||
- 学生关联检查
|
||
- ID范围检查
|
||
|
||
### 4. 部署新代码
|
||
|
||
```bash
|
||
# 停止应用服务
|
||
systemctl stop pangu-business
|
||
|
||
# 部署新版本 JAR
|
||
cp pangu-business-new.jar /opt/pangu/pangu-business.jar
|
||
|
||
# 启动应用服务
|
||
systemctl start pangu-business
|
||
```
|
||
|
||
**注意**：新代码中包含 `SchoolClassIdMigration.java`，但由于数据库已经迁移完成，该组件会检测到无需迁移并跳过。
|
||
|
||
### 5. 功能验证
|
||
|
||
- [ ] 登录系统，访问学生管理页面
|
||
- [ ] 查看学生列表，确认班级名称正常显示
|
||
- [ ] 编辑学生，选择班级后保存
|
||
- [ ] 再次编辑该学生，确认班级信息正确回显
|
||
- [ ] 新增班级，确认功能正常
|
||
|
||
### 6. 清理临时表
|
||
|
||
确认功能正常后，执行清理：
|
||
|
||
```sql
|
||
DROP TABLE IF EXISTS tmp_school_class_id_mapping;
|
||
DROP TABLE IF EXISTS pg_school_class_backup_prod;
|
||
DROP TABLE IF EXISTS pg_student_class_backup_prod;
|
||
```
|
||
|
||
## 回滚方案
|
||
|
||
如果迁移出现问题，执行回滚脚本：
|
||
|
||
```bash
|
||
mysql -h <host> -u <user> -p <database>
|
||
source production_rollback_school_class_id.sql
|
||
```
|
||
|
||
回滚后需要部署旧版本代码。
|
||
|
||
## 常见问题
|
||
|
||
### Q: 迁移脚本执行失败怎么办？
|
||
|
||
A: 脚本在执行过程中创建了备份表，可以通过回滚脚本恢复。如果回滚脚本也失败，使用完整数据库备份恢复。
|
||
|
||
### Q: 新代码部署后，自动迁移组件会重复执行吗？
|
||
|
||
A: 不会。`SchoolClassIdMigration.java` 会检测是否存在超出安全范围的 ID，如果没有则跳过迁移。
|
||
|
||
### Q: 迁移后新增的班级 ID 是什么样的？
|
||
|
||
A: 新增班级的 ID 将是小的自增数字（如 113, 114, 115...），不再是 19 位的雪花 ID。
|
||
|
||
## 文件清单
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `production_migrate_school_class_id.sql` | 生产环境迁移脚本 |
|
||
| `production_rollback_school_class_id.sql` | 回滚脚本 |
|
||
| `DEPLOYMENT_GUIDE.md` | 本文档 |
|