ccdi/docs/plans/2026-02-28-database-migration-design.md

# 数据库迁移设计文档

## 概述

将 CCDI 纪检初核系统的开发环境数据库完整迁移到生产环境，包括所有表结构和数据的导出与导入。

## 需求分析

### 迁移目标
- **源数据库**: 116.62.17.81:3306/ccdi
- **目标环境**: 全新的生产数据库（空库）
- **迁移范围**: 所有表的结构和数据

### 关键要求
1. 表结构和数据分离导出（两个独立文件）
2. 只导出表，不包括视图、存储过程、触发器等
3. 完整导出所有数据，不需要脱敏
4. 确保字符集正确，避免乱码问题
5. 使用 mysqldump 命令导出
6. 提供自动化脚本简化操作

## 技术方案

### 导出工具
使用 MySQL 官方工具 `mysqldump` 进行导出，优势：
- 标准化工具，兼容性最佳
- 性能优秀，适合大数据库
- 生成的 SQL 文件通用性强

### 字符集处理
- **字符集**: utf8mb4（支持完整 Unicode，包括 emoji）
- **排序规则**: utf8mb4_general_ci
- **客户端字符集**: utf8mb4

关键措施：
1. mysqldump 命令添加 `--default-character-set=utf8mb4` 参数
2. SQL 文件头部添加字符集声明语句
3. 导入时指定字符集参数
4. 导入后验证中文数据正确性

## 导出设计

### 文件组织
```
ccdi/
├── export_database.sh          # 自动化脚本
├── db_config.conf.template     # 配置模板
├── db_config.conf             # 实际配置（不纳入版本控制）
└── doc/
    └── database/
        └── backup/
            ├── ccdi_structure.sql  # 表结构文件
            ├── ccdi_data.sql       # 数据文件
            └── export_guide.md     # 操作指南
```

### 表结构导出命令
```bash
mysqldump -h 116.62.17.81 -P 3306 -u root -p \
  --no-data \
  --skip-triggers \
  --skip-add-drop-table \
  --default-character-set=utf8mb4 \
  --single-transaction \
  ccdi > ccdi_structure.sql
```

**参数说明**:
- `--no-data`: 只导出表结构，不导出数据
- `--skip-triggers`: 跳过触发器
- `--skip-add-drop-table`: 不添加 DROP TABLE 语句（避免误删）
- `--default-character-set=utf8mb4`: 指定字符集
- `--single-transaction`: InnoDB 表一致性导出，不锁表

### 数据导出命令
```bash
mysqldump -h 116.62.17.81 -P 3306 -u root -p \
  --no-create-info \
  --skip-triggers \
  --default-character-set=utf8mb4 \
  --single-transaction \
  --complete-insert \
  --extended-insert \
  ccdi > ccdi_data.sql
```

**参数说明**:
- `--no-create-info`: 只导出数据，不导出表结构
- `--complete-insert`: INSERT 语句包含列名
- `--extended-insert`: 使用多行 INSERT，提高导入效率

### SQL 文件字符集声明
```sql
SET NAMES utf8mb4;
SET CHARACTER SET utf8mb4;
SET GLOBAL character_set_client=utf8mb4;
SET GLOBAL character_set_connection=utf8mb4;
SET GLOBAL character_set_results=utf8mb4;
```

## 导入设计

### 导入顺序
1. 先导入表结构：`ccdi_structure.sql`
2. 再导入数据：`ccdi_data.sql`

### 导入命令
```bash
# 导入表结构
mysql -h 生产环境IP -P 3306 -u 用户名 -p \
  --default-character-set=utf8mb4 \
  数据库名 < ccdi_structure.sql

# 导入数据
mysql -h 生产环境IP -P 3306 -u 用户名 -p \
  --default-character-set=utf8mb4 \
  数据库名 < ccdi_data.sql
```

### 前置条件
1. 目标数据库已创建（如：`CREATE DATABASE ccdi CHARACTER SET utf8mb4;`）
2. 目标用户有足够权限
3. 磁盘空间充足

## 自动化脚本设计

### 脚本功能
- **导出模式**: `./export_database.sh export`
  - 检查 mysqldump 命令可用性
  - 创建备份目录
  - 执行结构导出和数据导出
  - 添加字符集声明到文件头部
  - 验证文件生成
  - 记录操作日志

- **导入模式**: `./export_database.sh import [production|test]`
  - 读取配置文件获取目标环境信息
  - 检查目标数据库连接
  - 依次导入结构和数据文件
  - 验证导入结果
  - 记录操作日志

### 配置文件设计
```bash
# 源数据库配置（开发环境）
SOURCE_DB_HOST=116.62.17.81
SOURCE_DB_PORT=3306
SOURCE_DB_USER=root
SOURCE_DB_PASS=Kfcx@1234
SOURCE_DB_NAME=ccdi

# 生产环境数据库配置
PROD_DB_HOST=生产环境IP
PROD_DB_PORT=3306
PROD_DB_USER=生产环境用户名
PROD_DB_PASS=生产环境密码
PROD_DB_NAME=ccdi

# 测试环境数据库配置（可选）
TEST_DB_HOST=测试环境IP
TEST_DB_PORT=3306
TEST_DB_USER=测试环境用户名
TEST_DB_PASS=测试环境密码
TEST_DB_NAME=ccdi

# 导出文件配置
BACKUP_DIR=doc/database/backup
STRUCTURE_FILE=ccdi_structure.sql
DATA_FILE=ccdi_data.sql
```

### 安全措施
1. `db_config.conf` 添加到 `.gitignore`
2. 提供 `db_config.conf.template` 模板文件
3. 首次运行时检测配置文件，提示用户填写

## 验证测试

### 导出验证
1. 检查生成的 SQL 文件大小是否合理
2. 检查文件头部是否包含字符集声明
3. 随机抽取数据检查是否有乱码
4. 统计表数量和数据行数

### 导入验证
1. 在测试环境先进行导入测试
2. 对比源数据库和目标数据库的表数量
3. 抽查关键表的数据行数
4. 查询包含中文的数据验证编码正确性
5. 使用 `SHOW CREATE TABLE` 检查表字符集

### 验证命令
```sql
-- 查看数据库字符集
SHOW CREATE DATABASE ccdi;

-- 查看表数量
SELECT COUNT(*) FROM information_schema.tables
WHERE table_schema='ccdi';

-- 查看各表行数
SELECT table_name, table_rows
FROM information_schema.tables
WHERE table_schema='ccdi'
ORDER BY table_rows DESC;

-- 检查表字符集
SHOW CREATE TABLE sys_user;
```

## 错误处理

### 常见问题
1. **字符集乱码**
   - 原因：未指定字符集参数
   - 解决：确保所有命令都添加 `--default-character-set=utf8mb4`

2. **导入失败**
   - 原因：外键约束冲突
   - 解决：导入前临时禁用外键检查 `SET FOREIGN_KEY_CHECKS=0;`

3. **连接超时**
   - 原因：数据库过大或网络慢
   - 解决：添加 `--max_allowed_packet=512M` 参数

4. **权限不足**
   - 原因：用户权限不够
   - 解决：使用 root 用户或授予足够权限

## 操作流程

### 完整迁移流程
1. 配置 `db_config.conf` 文件
2. 执行导出：`./export_database.sh export`
3. 验证导出文件正确性
4. 在测试环境验证导入：`./export_database.sh import test`
5. 验证测试环境数据完整性
6. 在生产环境执行导入：`./export_database.sh import production`
7. 验证生产环境数据完整性
8. 应用程序连接测试

### 回滚方案
保留源数据库，如迁移失败可继续使用源数据库，重新执行迁移流程。

## 交付物

1. **自动化脚本**: `export_database.sh`
2. **配置模板**: `db_config.conf.template`
3. **表结构文件**: `doc/database/backup/ccdi_structure.sql`
4. **数据文件**: `doc/database/backup/ccdi_data.sql`
5. **操作指南**: `doc/database/backup/export_guide.md`
6. **设计文档**: `docs/plans/2026-02-28-database-migration-design.md`

## 时间估算

- 脚本开发：30分钟
- 导出执行：10-30分钟（取决于数据量）
- 测试环境导入验证：10-30分钟
- 生产环境导入：10-30分钟
- 验证测试：10分钟

**总计**: 约1.5-2小时

## 风险评估

| 风险项 | 等级 | 缓解措施 |
|--------|------|----------|
| 数据量过大导致超时 | 中 | 添加 max_allowed_packet 参数，分批导出 |
| 字符集乱码 | 高 | 严格遵循字符集规范，导入后验证 |
| 网络中断 | 低 | 本地保存SQL文件，可重复导入 |
| 生产环境数据冲突 | 无 | 全新空库，无冲突风险 |
| 权限问题 | 低 | 使用 root 用户或确保权限充足 |

## 成功标准

1. ✅ 所有表结构成功导出，无遗漏
2. ✅ 所有表数据成功导出，无丢失
3. ✅ SQL 文件字符集正确，无乱码
4. ✅ 测试环境导入成功，数据完整
5. ✅ 生产环境导入成功，数据完整
6. ✅ 中文数据正确显示，编码无误
7. ✅ 应用程序可正常连接和操作数据库