QAUP_Management/deploy/docs/数据文件说明.md

QAUP 数据库初始数据文件说明

文件结构

deploy/docker/postgres/
├── qaup_database_schema.sql          # 数据库表结构（必需）
├── initial_data.template.sql         # 默认初始数据模板
├── initial_data.sql                  # 实际使用的初始数据（优先级最高）
├── 01_system_data.sql                # 系统配置数据（导出生成）
├── 02_business_data.sql              # 业务基础数据（导出生成）
├── 03_sample_data.sql                # 示例数据（导出生成）
├── db-manager.sh                     # 统一数据库管理工具
├── init-db.sh                        # 数据库初始化脚本
└── postgresql.conf                   # PostgreSQL 配置文件

数据文件优先级

数据库初始化脚本 init-db.sh 按以下优先级加载数据：

1. initial_data.sql - 如果存在，优先使用（通常是从现有系统导出的完整数据）
2. 分层数据文件 - 如果 initial_data.sql 不存在，按顺序加载：
   • 01_system_data.sql - 系统基础配置
   • 02_business_data.sql - 业务基础数据
   • 03_sample_data.sql - 示例数据

使用场景

场景1：全新部署（使用默认数据）

# 复制模板文件
cp initial_data.template.sql initial_data.sql

# 启动部署
./deploy.sh install

场景2：从现有系统迁移

# 1. 从现有数据库导出并准备数据（一步完成）
./db-manager.sh prepare-export

# 2. 启动部署
./deploy.sh install

场景3：选择性数据导入

# 1. 从现有数据库导出分层数据
./db-manager.sh export-initial

# 2. 自定义数据组合
./db-manager.sh prepare-custom

# 3. 启动部署
./deploy.sh install

场景4：自定义数据组合

# 1. 创建自定义的 initial_data.sql
cat > initial_data.sql << 'EOF'
-- 自定义初始数据组合
EOF

# 2. 添加系统基础数据
cat export/01_system_data.sql >> initial_data.sql

# 3. 可选：添加业务数据
cat export/02_business_data.sql >> initial_data.sql

# 4. 启动部署
./deploy.sh install

数据文件内容说明

initial_data.template.sql

• 用途: 默认初始数据模板
• 内容: 系统运行的最小数据集
• 特点: 包含默认管理员账号、基础菜单、示例配置
• 适用: 全新部署、演示环境

01_system_data.sql（导出生成）

• 用途: 系统基础配置数据
• 内容: 配置、字典、菜单、角色、用户等
• 特点: 从现有系统导出的实际配置
• 适用: 生产环境迁移

02_business_data.sql（导出生成）

• 用途: 业务基础数据
• 内容: 车辆类型、机场区域、空间规则等
• 特点: 业务相关的配置数据
• 适用: 保留业务配置的迁移

03_sample_data.sql（导出生成）

• 用途: 示例数据
• 内容: 示例车辆信息等
• 特点: 用于测试和演示
• 适用: 开发、测试环境

注意事项

1. 文件优先级: initial_data.sql 存在时，分层文件会被忽略
2. 数据冲突: 确保导入的数据不会产生主键冲突
3. 序列更新: 所有数据文件都包含序列值更新语句
4. 备份建议: 导入前备份现有数据
5. 权限检查: 确保数据库用户有足够的导入权限

故障排除

问题1：数据导入失败

# 检查数据文件语法
psql -U postgres -d qaup --dry-run -f initial_data.sql

# 查看详细错误信息
docker logs qaup-postgres

问题2：序列值错误

-- 手动更新序列值
SELECT setval('table_id_seq', (SELECT MAX(id) FROM table_name));

问题3：权限不足

-- 授予必要权限
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO qaup_app;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO qaup_app;

最佳实践

1. 版本控制: 将使用的 initial_data.sql 纳入版本控制
2. 环境隔离: 不同环境使用不同的数据文件
3. 定期导出: 定期从生产环境导出最新配置
4. 测试验证: 在测试环境验证数据导入过程
5. 文档更新: 及时更新数据结构变更文档