QDAirPortBackend0122/doc/work/20250110_配置文件重构说明.md

配置文件重构说明

日期: 2025-01-10 版本: v1.0 状态: 🔄 配置文件已完成，启动脚本待更新 目的: 分离开发和生产环境配置，支持环境变量管理

---

✅ 已完成的工作

配置文件重构

1. ✅ 备份原配置: application-prod.yml.backup, application-deploy.yml.backup
2. ✅ 创建开发环境配置: application-dev.yml (新建)
3. ✅ 重构公共配置: application.yml (只保留公共配置)
4. ✅ 重写生产环境配置: application-prod.yml (支持环境变量)
5. ✅ 更新数据源配置: application-druid.yml (支持环境变量)
6. ✅ 创建环境变量模板: .env.example
7. ✅ 编写配置文档: 本文档 + 环境变量配置方案

⚠️ 待完成的工作

1. ❌ 更新启动脚本: qaup.sh 需要添加环境变量加载功能
2. ❌ 测试验证: 开发环境和生产环境启动测试
3. ❌ 更新项目文档: README.md, CLAUDE.md 等

---

📋 重构概述

重构前的问题

1. 配置重复: application.yml 和 application-prod.yml 存在大量重复配置
2. 职责不清: application.yml 既有公共配置，又有开发环境特定配置
3. 缺少独立的开发环境配置: 没有 application-dev.yml
4. 生产环境修改不便: 修改配置需要重新打包jar

重构后的改进

1. ✅ 清晰的配置分层: 公共配置、开发环境、生产环境完全分离
2. ✅ 环境变量支持: 生产环境关键配置支持环境变量覆盖
3. ✅ 无需重新打包: 修改 .env 文件即可更新配置（需要先更新 qaup.sh）
4. ✅ 便于维护: 配置职责清晰，减少重复

---

📁 新的配置文件结构

qaup-admin/src/main/resources/
├── application.yml                    # 公共配置（所有环境共享）
├── application-dev.yml                # 开发环境配置（新建）
├── application-prod.yml               # 生产环境配置（重写，支持环境变量）
├── application-druid.yml              # Druid数据源配置（更新，支持环境变量）
├── application-prod.yml.backup        # 原配置备份
├── application-deploy.yml.backup      # 原配置备份
└── application-test.yml               # 测试环境配置（可选，未创建）

项目根目录/
└── .env.example                       # 环境变量模板（新建）

---

🔧 各配置文件职责

1. application.yml（公共配置）

职责: 所有环境共享的基础配置

包含内容:

• 项目信息（qaup.name, version等）
• 用户配置（user.password）
• Token配置（token.header, secret等）
• MyBatis配置
• PageHelper配置
• SpringDoc配置
• XSS防护配置
• Flyway配置
• JPA配置
• 数据采集端点配置（固定的API端点路径）
• 红绿灯系统配置（固定部分）
• 坐标系统配置
• 管理端点配置

不包含:

• 服务器配置（port, threads等）
• 数据库连接信息
• Redis连接信息
• API基础URL和认证信息
• 日志级别
• 环境特定功能（如热部署）

默认激活profile: dev,druid

---

2. application-dev.yml（开发环境配置）

职责: 本地开发环境专属配置

包含内容:

• 服务器配置
  • port: 8080
  • threads.max: 2000（虚拟线程）
• 热部署配置（devtools）
• Redis配置（localhost:6379）
• 日志级别（debug）
• 数据采集配置
  • interval: 250ms
  • airport-api.base-url: http://localhost:8090
  • vehicle-api.base-url: http://localhost:8091

使用方式:

# IDEA中默认启动即可（application.yml中默认激活dev）
# 或显式指定
-Dspring.profiles.active=dev,druid

---

3. application-prod.yml（生产环境配置）

职责: 生产环境专属配置 + 环境变量支持

包含内容（所有关键配置支持环境变量）:

• 服务器配置
  • port: ${SERVER_PORT:8080}
  • threads.max: 800（生产环境优化）
• Redis配置（环境变量）
  • host: ${REDIS_HOST:localhost}
  • port: ${REDIS_PORT:6379}
  • password: ${REDIS_PASSWORD:}
• 日志级别（环境变量）
  • com.qaup: ${LOG_LEVEL_QAUP:info}
• 数据采集配置（环境变量）
  • airport-api.base-url: ${AIRPORT_API_BASE_URL:http://localhost:8090}
  • airport-api.auth.username: ${AIRPORT_API_USERNAME:dianxin}
  • airport-api.auth.password: ${AIRPORT_API_PASSWORD:dianxin@123}
  • vehicle-api.base-url: ${VEHICLE_API_BASE_URL:http://localhost:8091}

使用方式:

# 启动时指定profile
java -jar qaup-admin.jar --spring.profiles.active=prod,druid

# 或在 qaup.sh 中配置
nohup java $JVM_OPTS -jar $AppName --spring.profiles.active=prod,druid > /dev/null 2>&1 &

---

4. application-druid.yml（Druid数据源配置）

职责: Druid连接池配置

更新内容: 主库数据源支持环境变量

master:
  url: jdbc:postgresql://${DB_HOST:localhost}:${DB_PORT:5432}/${DB_NAME:qaup}?...
  username: ${DB_USERNAME:postgres}
  password: ${DB_PASSWORD:123456}

其他配置保持不变:

• 连接池参数
• Druid监控配置
• SQL监控配置

---

5. .env.example（环境变量模板）

职责: 环境变量配置模板

使用流程:

# 1. 复制模板
cp .env.example .env

# 2. 修改配置
vim .env

# 3. 启动应用（qaup.sh会自动加载.env）
./qaup.sh start

包含的环境变量:

• 数据库配置（DB_HOST, DB_PORT, DB_NAME, DB_USERNAME, DB_PASSWORD）
• Redis配置（REDIS_HOST, REDIS_PORT, REDIS_PASSWORD）
• API配置（AIRPORT_API_BASE_URL, VEHICLE_API_BASE_URL等）
• 日志配置（LOG_LEVEL_QAUP, LOG_LEVEL_SPRING）
• 其他可选配置

---

🚀 使用指南

开发环境

方式1: 默认启动（推荐）

# 在IDEA中直接启动，自动使用dev配置
# application.yml 默认激活: dev,druid

方式2: 显式指定

# IDEA Run/Debug Configurations
VM options: -Dspring.profiles.active=dev,druid

方式3: 命令行启动

cd qaup-admin
mvn spring-boot:run -Dspring-boot.run.profiles=dev,druid

---

生产环境

Step 1: 创建环境变量文件

# 在jar包部署目录
cp .env.example .env

# 编辑配置
vim .env

示例 .env 文件:

# 数据库配置
DB_HOST=192.168.1.100
DB_PORT=5432
DB_NAME=qaup_prod
DB_USERNAME=qaup_user
DB_PASSWORD=SecurePassword123

# Redis配置
REDIS_HOST=192.168.1.101
REDIS_PORT=6379
REDIS_PASSWORD=redis_password

# API配置
AIRPORT_API_BASE_URL=http://192.168.1.102:8090
AIRPORT_API_USERNAME=prod_user
AIRPORT_API_PASSWORD=prod_pass

VEHICLE_API_BASE_URL=http://192.168.1.103:8091

Step 2: 更新启动脚本（待实施）

⚠️ 重要: 目前 qaup.sh 还未更新，需要手动添加环境变量加载功能。

完整的启动脚本更新方案请参考：环境变量配置方案

关键修改点：

# 在 qaup.sh 开头添加
ENV_FILE=$APP_HOME/.env

# 在 start() 函数中添加环境变量加载
if [ -f "$ENV_FILE" ]; then
    echo "Loading environment variables from $ENV_FILE"
    export $(cat $ENV_FILE | grep -v '^#' | grep -v '^$' | xargs)
    echo "Environment variables loaded successfully"
else
    echo "Warning: $ENV_FILE not found, using default configuration"
fi

Step 3: 启动应用

# 方式1: 使用更新后的 qaup.sh（推荐）
./qaup.sh start

# qaup.sh 需要在启动命令中指定 profile
nohup java $JVM_OPTS -jar $AppName --spring.profiles.active=prod,druid > /dev/null 2>&1 &

# 方式2: 手动指定（用于测试）
java -jar qaup-admin.jar --spring.profiles.active=prod,druid

Step 4: 修改配置

# 1. 编辑 .env
vim .env

# 2. 重启应用
./qaup.sh restart

# 完成！无需重新打包jar

---

📊 配置加载优先级

Spring Boot配置加载优先级（从高到低）:

1. 命令行参数 - 最高优先级
2. 操作系统环境变量 ⭐ 本方案使用
3. config/application-{profile}.yml（外部）
4. config/application.yml（外部）
5. classpath:application-{profile}.yml（jar内） ⭐ 本方案使用
6. classpath:application.yml（jar内） ⭐ 本方案使用

实际加载顺序示例

开发环境:

1. application.yml (公共配置)
2. application-dev.yml (开发环境配置，覆盖公共配置)
3. application-druid.yml (Druid配置，合并)

生产环境:

1. application.yml (公共配置)
2. application-prod.yml (生产环境配置，覆盖公共配置)
3. application-druid.yml (Druid配置，合并)
4. 环境变量 (覆盖配置文件中的${VAR:default}值)

---

✅ 验证配置

验证开发环境

# 启动应用
cd qaup-admin
mvn spring-boot:run

# 检查日志
# 应该看到: The following 2 profiles are active: "dev", "druid"

# 验证配置值
# 数据库: localhost:5432
# Redis: localhost:6379
# API: http://localhost:8090, http://localhost:8091
# 日志级别: debug

验证生产环境

# 1. 查看环境变量加载
./qaup.sh start
# 应该看到: Loading environment variables from /path/to/.env

# 2. 检查应用日志
tail -f logs/qaup-admin.jar.log | grep "profiles are active"
# 应该看到: The following 2 profiles are active: "prod", "druid"

# 3. 验证配置值（查看日志中的连接信息）
tail -f logs/qaup-admin.jar.log | grep -E "airport|vehicle|jdbc"

---

🔄 配置迁移对比

迁移前后对比

配置项	重构前	重构后
开发环境配置	application.yml	application-dev.yml
生产环境配置	application-prod.yml	application-prod.yml（重写）
公共配置	分散在各文件	application.yml（集中）
环境变量支持	❌ 无	✅ 有
配置修改	❌ 需重新打包	✅ 修改.env即可
配置重复	❌ 大量重复	✅ 无重复
环境切换	❌ 修改文件	✅ 切换profile

---

🔒 安全建议

1. 保护敏感信息

# .env文件权限（只有owner可读写）
chmod 600 .env

# Git忽略
echo ".env" >> .gitignore
echo "*.env" >> .gitignore
echo "!.env.example" >> .gitignore

2. 配置备份

# 备份当前配置
cp .env .env.backup-$(date +%Y%m%d-%H%M%S)

# 定期备份（添加到crontab）
0 2 * * * cp /app/.env /app/config/.env.backup-$(date +\%Y\%m\%d)

3. 配置审计

# 记录配置变更
cat > config/CHANGELOG.md << EOF
# 配置变更记录

## 2025-01-10 14:00
- 初始化生产环境配置
- 操作人: xxx
- 原因: 配置重构
EOF

---

🆚 环境对比表

配置项	开发环境(dev)	生产环境(prod)
Server Port	8080	${SERVER_PORT:8080}
Threads	2000	800
数据库	localhost:5432	${DB_HOST}:${DB_PORT}
Redis	localhost:6379	${REDIS_HOST}:${REDIS_PORT}
Airport API	localhost:8090	${AIRPORT_API_BASE_URL}
Vehicle API	localhost:8091	${VEHICLE_API_BASE_URL}
日志级别	debug	info
热部署	✅ enabled	❌ disabled
SQL打印	✅ 打印	❌ 不打印

---

📝 常见问题

Q1: 为什么开发环境配置值保持不变？

A: 为了确保现有开发流程不受影响，application-dev.yml 的所有配置值与原 application.yml 完全一致。开发人员无需修改任何配置即可正常工作。

---

Q2: 环境变量未生效怎么办？

A: 检查以下几点：

1. .env 文件格式是否正确（无空格、无引号）
2. 是否执行了 ./qaup.sh restart
3. qaup.sh 是否已更新（包含加载环境变量的代码）
4. 查看启动日志确认是否加载了 .env

---

Q3: 如何回滚配置？

A:

# 方式1: 恢复备份的.env
cp .env.backup-20250110-120000 .env
./qaup.sh restart

# 方式2: 恢复原配置文件（需要重新打包）
cp application-prod.yml.backup application-prod.yml
# 重新打包部署

---

Q4: 如何添加新的环境变量？

A:

# 1. 在 application-prod.yml 中添加占位符
new-config:
  value: ${NEW_CONFIG_VALUE:default}

# 2. 在 .env 中添加变量
NEW_CONFIG_VALUE=actual_value

# 3. 更新 .env.example
NEW_CONFIG_VALUE=default_value

# 4. 重启应用
./qaup.sh restart

---

Q5: 可以继续使用原来的配置吗？

A: 可以，原配置已备份为 .backup 文件：

• application-prod.yml.backup
• application-deploy.yml.backup

如需恢复:

cp application-prod.yml.backup application-prod.yml

---

⚠️ 下一步工作（必须完成）

1. 更新启动脚本 qaup.sh

当前状态: ❌ 未完成

任务: 为 qaup.sh 添加环境变量加载功能和 profile 指定

参考文档: 环境变量配置方案 - Step 2

关键修改:

1. 添加 ENV_FILE 变量定义
2. 在 start() 函数中加载 .env 文件
3. 在启动命令中添加 --spring.profiles.active=prod,druid

2. 测试验证

开发环境测试:

# 1. 在IDEA中启动应用
# 2. 检查启动日志确认使用 dev profile
# 3. 验证配置值正确（localhost:8090/8091）

生产环境测试（打包后）:

# 1. 打包应用
mvn clean package -DskipTests

# 2. 创建 .env 文件
cp .env.example .env

# 3. 测试启动（需要先更新 qaup.sh）
./qaup.sh start

# 4. 验证配置加载正确

3. 更新项目文档

需要更新的文件:

• README.md - 添加配置管理说明
• CLAUDE.md - 更新配置文件说明
• 部署文档 - 添加环境变量配置步骤

---

🎯 后续优化建议

短期优化

1. 配置校验: 添加启动前配置校验脚本
2. 配置加密: 敏感信息使用加密存储
3. 配置文档: 完善各环境配置说明
4. CI/CD集成: 在部署流程中自动生成 .env 文件

长期规划

1. 配置中心: 引入Nacos/Apollo实现配置热更新
2. 多环境扩展: 添加测试环境、预发布环境配置
3. 配置版本管理: 建立配置变更审批流程
4. 配置审计: 记录所有配置变更历史

---

📚 相关文档

• 环境变量配置方案
• Spring Boot配置文档
• CLAUDE.md - 项目说明

---

📞 支持

如有问题，请联系：

• 开发团队
• 查看项目文档：doc/working/

---

文档结束

最后更新: 2025-01-10 文档版本: v1.0 维护者: QAUP Team