ccdi/doc/database/数据库迁移操作指南.md

CCDI 数据库迁移操作指南

概述

本文档提供 CCDI 纪检初核系统数据库迁移的详细操作步骤，包括从开发环境导出数据库和导入到生产/测试环境。

脚本说明

项目提供两个独立的脚本：

1. export_database.sh - 数据库导出脚本

   • 从开发环境导出数据库
   • 生成表结构和数据文件到 doc/database/backup/ 文件夹

2. import_database.sh - 数据库导入脚本

   • 从 doc/database/backup/ 文件夹读取备份文件
   • 导入到指定的目标环境（dev/test/prod）

文件结构

项目根目录/
├── export_database.sh              # 导出脚本
├── import_database.sh              # 导入脚本
├── db_config.conf.template         # 配置模板
├── db_config.conf                  # 实际配置（不提交到 Git）
└── doc/
    └── database/
        ├── backup/                 # 备份文件夹
        │   ├── .gitkeep
        │   ├── ccdi_structure.sql  # 表结构（~60KB）
        │   └── ccdi_data.sql       # 数据文件（~5.7MB）
        └── alter_collation_to_general_ci.sql  # 排序规则修改脚本

前置条件

必需工具

• MySQL 客户端工具（包含 mysqldump 和 mysql 命令）
• Bash shell 环境（Windows 用户可使用 Git Bash）
• 网络访问权限（能连接源数据库和目标数据库）

检查工具是否安装

mysqldump --version
mysql --version

如果未安装，请根据操作系统安装 MySQL 客户端：

• Windows: 安装 MySQL Community Server
• Linux (Ubuntu/Debian): sudo apt-get install mysql-client
• Linux (CentOS/RHEL): sudo yum install mysql
• macOS: brew install mysql-client

配置步骤

1. 创建配置文件

# 复制配置模板
cp db_config.conf.template db_config.conf

# 编辑配置文件
nano db_config.conf  # 或使用其他编辑器

2. 填写配置信息

编辑 db_config.conf 文件，填写以下信息：

源数据库（开发环境）:

• SOURCE_DB_HOST: 开发环境数据库地址
• SOURCE_DB_PORT: 数据库端口（默认 3306）
• SOURCE_DB_USER: 数据库用户名
• SOURCE_DB_PASS: 数据库密码
• SOURCE_DB_NAME: 数据库名称（ccdi）

生产环境数据库:

• PROD_DB_HOST: 生产环境数据库地址
• PROD_DB_PORT: 数据库端口
• PROD_DB_USER: 生产环境数据库用户名
• PROD_DB_PASS: 生产环境数据库密码
• PROD_DB_NAME: 数据库名称（ccdi）

测试环境数据库（可选）:

• TEST_DB_HOST: 测试环境数据库地址
• TEST_DB_PORT: 数据库端口
• TEST_DB_USER: 测试环境数据库用户名
• TEST_DB_PASS: 测试环境数据库密码
• TEST_DB_NAME: 数据库名称（ccdi）

3. 验证配置

检查配置文件格式：

cat db_config.conf | grep -E "^[A-Z]"

确保所有必需的配置项都已填写。

数据库导出

执行导出

# 方式1: 使用默认命令
./export_database.sh

# 方式2: 显式指定命令
./export_database.sh export

预期输出

[INFO] ========== 开始导出数据库 ==========
[INFO] 配置文件加载成功
[INFO] mysqldump 命令检查通过
[INFO] 开始导出表结构...
[INFO] 表结构导出成功: doc/database/backup/ccdi_structure.sql
[INFO] 文件大小: 60K
[INFO] 开始导出数据...
[INFO] 数据导出成功: doc/database/backup/ccdi_data.sql
[INFO] 文件大小: 5.7M
[INFO] 验证导出文件...
[INFO] 导出文件验证通过
[INFO] 表结构文件: doc/database/backup/ccdi_structure.sql (60K)
[INFO] 数据文件: doc/database/backup/ccdi_data.sql (5.7M)
[INFO] ========== 数据库导出完成 ==========
[INFO] 使用 ./import_database.sh <env> 导入到目标环境

验证导出文件

1. 检查文件是否存在

ls -lh doc/database/backup/

应该看到：

• ccdi_structure.sql - 表结构文件（~60KB）
• ccdi_data.sql - 数据文件（~5.7MB）

2. 检查字符集声明

head -20 doc/database/backup/ccdi_structure.sql

应该包含：

SET NAMES utf8mb4;
SET CHARACTER SET utf8mb4;

3. 检查文件内容

# 查看表数量
grep "CREATE TABLE" doc/database/backup/ccdi_structure.sql | wc -l

# 查看数据量（INSERT 语句数量）
grep "INSERT" doc/database/backup/ccdi_data.sql | wc -l

数据库导入

准备工作

1. 确认目标数据库已创建

连接到目标数据库服务器：

mysql -h 目标IP -P 3306 -u 用户名 -p

创建数据库（如果不存在）：

CREATE DATABASE ccdi CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

2. 确认用户权限

目标数据库用户需要以下权限：

• CREATE、ALTER、DROP（创建和修改表）
• INSERT、UPDATE、DELETE（数据操作）
• INDEX（创建索引）
• REFERENCES（外键约束）

导入到测试环境

./import_database.sh test

导入到生产环境

./import_database.sh production

或简写：

./import_database.sh prod

导入到开发环境

./import_database.sh dev

预期输出

[INFO] ========== 开始导入数据库到 test 环境 ==========
[INFO] 配置文件加载成功
[INFO] mysql 命令检查通过
[INFO] 检查备份文件...
[INFO] 备份文件检查通过
[INFO] 表结构文件: doc/database/backup/ccdi_structure.sql (60K)
[INFO] 数据文件: doc/database/backup/ccdi_data.sql (5.7M)
[INFO] 导入表结构到 test 环境: XXX:3306/ccdi
[INFO] 表结构导入成功
[INFO] 导入数据到 test 环境: XXX:3306/ccdi
[INFO] 数据导入成功
[INFO] 验证导入结果...
[INFO] 目标数据库表数量: 42
[INFO] sys_user 表数据行数: XX
[INFO] 数据库字符集: utf8mb4
[INFO] ========== 数据库导入完成 ==========

导入后验证

1. 验证表数量

连接到目标数据库：

mysql -h 目标IP -P 3306 -u 用户名 -p ccdi

查询表数量：

SELECT COUNT(*) FROM information_schema.tables
WHERE table_schema='ccdi';

对比源数据库和目标数据库的表数量是否一致。

2. 验证数据行数

查询各表数据行数：

SELECT table_name, table_rows
FROM information_schema.tables
WHERE table_schema='ccdi'
ORDER BY table_rows DESC
LIMIT 20;

对比源数据库和目标数据库的关键表行数。

3. 验证字符集

检查数据库字符集：

SHOW CREATE DATABASE ccdi;

应该显示：DEFAULT CHARACTER SET utf8mb4

检查表字符集：

SHOW CREATE TABLE sys_user;

应该显示：ENGINE=InnoDB DEFAULT CHARSET=utf8mb4

4. 验证中文数据

查询包含中文的数据：

-- 查询用户表
SELECT user_name, nick_name FROM sys_user LIMIT 10;

-- 查询字典数据
SELECT dict_label, dict_value FROM sys_dict_data LIMIT 10;

-- 查询业务表
SELECT name, person_type FROM ccdi_biz_intermediary LIMIT 10;

确保中文字符显示正常，无乱码。

5. 应用程序连接测试

修改应用程序配置文件连接到目标数据库，启动应用程序进行功能测试。

完整迁移流程示例

场景：从开发环境迁移到生产环境

1. 配置数据库连接

cp db_config.conf.template db_config.conf
nano db_config.conf
# 填写开发环境和生产环境数据库信息

2. 导出数据库

./export_database.sh

3. 验证导出文件

ls -lh doc/database/backup/
head -20 doc/database/backup/ccdi_structure.sql

4. 先在测试环境验证

./import_database.sh test

5. 验证测试环境

• 连接测试数据库验证数据
• 应用程序连接测试环境进行功能测试

6. 导入到生产环境

./import_database.sh prod

7. 验证生产环境

• 连接生产数据库验证数据
• 应用程序连接生产环境进行功能测试

8. 完成迁移

常见问题

1. mysqldump: command not found

原因: MySQL 客户端未安装或未添加到 PATH

解决:

• 安装 MySQL 客户端工具
• 或使用完整路径：/usr/bin/mysqldump

2. 配置文件不存在

错误信息: 配置文件不存在: db_config.conf

解决:

cp db_config.conf.template db_config.conf
# 编辑 db_config.conf 填写实际配置

3. 连接数据库失败

可能原因:

• 数据库地址、端口、用户名或密码错误
• 防火墙阻止连接
• 数据库服务未启动

解决:

• 检查配置文件中的连接信息
• 使用 mysql 命令手动测试连接
• 检查防火墙规则

4. 导入时字符集乱码

原因: 未正确指定字符集

解决:

• 确保导出文件包含字符集声明
• 导入命令添加 --default-character-set=utf8mb4 参数
• 脚本已自动处理，如仍有问题请检查数据库默认字符集

5. 外键约束失败

错误信息: ERROR 1452 (23000): Cannot add or update a child row: a foreign key constraint fails

解决:

• 脚本已自动添加 SET FOREIGN_KEY_CHECKS=0; 和 SET FOREIGN_KEY_CHECKS=1;
• 如仍有问题，请检查数据完整性

6. 数据包过大

错误信息: ERROR 1153 (08S01): Got a packet bigger than 'max_allowed_packet' bytes

解决:

• 配置文件中的 MAX_ALLOWED_PACKET=512M 已处理此问题
• 如数据量特别大，可增大此值

7. 权限不足

错误信息: ERROR 1044 (42000): Access denied for user

解决:

• 使用具有足够权限的用户（如 root）
• 或授予用户必要权限

8. 备份文件不存在

错误信息: 表结构文件不存在: doc/database/backup/ccdi_structure.sql

解决:

• 先执行导出：./export_database.sh
• 检查 backup 文件夹中是否有 SQL 文件

回滚方案

如果迁移失败或出现问题：

1. 保留源数据库: 不要删除开发环境数据库
2. 重新迁移: 修复问题后重新执行迁移流程
3. 从备份恢复: 如生产环境有备份，可从备份恢复

注意事项

1. 安全性:

   • db_config.conf 包含敏感信息，已添加到 .gitignore
   • 不要将配置文件提交到版本控制系统
   • 迁移完成后建议删除配置文件中的密码

2. 性能:

   • 大数据库导出/导入可能需要较长时间
   • 建议在低峰期执行迁移
   • 确保有足够的磁盘空间

3. 数据一致性:

   • 导出期间源数据库应避免写入操作
   • 或使用 --single-transaction 参数（已包含）

4. 字符集:

   • 确保所有步骤都使用 utf8mb4 字符集
   • 验证阶段重点检查中文数据
   • 表结构文件不再包含显式的 COLLATE 配置（使用默认 utf8mb4_general_ci）

技术支持

如遇到问题：

1. 检查本文档的常见问题部分
2. 查看脚本执行的错误信息
3. 检查数据库连接和权限
4. 查看数据库日志

相关文件

• 导出脚本: export_database.sh
• 导入脚本: import_database.sh
• 配置模板: db_config.conf.template
• 实际配置: db_config.conf
• 表结构文件: doc/database/backup/ccdi_structure.sql
• 数据文件: doc/database/backup/ccdi_data.sql
• 排序规则修改脚本: doc/database/alter_collation_to_general_ci.sql
• 设计文档: docs/plans/2026-02-28-database-migration-design.md