# 配置文件重构说明

**日期**: 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

**使用方式**:
```bash
# 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}

**使用方式**:
```bash
# 启动时指定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连接池配置

**更新内容**: 主库数据源支持环境变量
```yaml
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（环境变量模板）

**职责**: 环境变量配置模板

**使用流程**:
```bash
# 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: 默认启动（推荐）
```bash
# 在IDEA中直接启动，自动使用dev配置
# application.yml 默认激活: dev,druid
```

#### 方式2: 显式指定
```bash
# IDEA Run/Debug Configurations
VM options: -Dspring.profiles.active=dev,druid
```

#### 方式3: 命令行启动
```bash
cd qaup-admin
mvn spring-boot:run -Dspring-boot.run.profiles=dev,druid
```

---

### 生产环境

#### Step 1: 创建环境变量文件

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

# 编辑配置
vim .env
```

示例 `.env` 文件:
```bash
# 数据库配置
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` 还未更新，需要手动添加环境变量加载功能。

完整的启动脚本更新方案请参考：[环境变量配置方案](./20250110_环境变量配置方案.md#step-2-修改启动脚本-qaupsh)

**关键修改点**：
```bash
# 在 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: 启动应用

```bash
# 方式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: 修改配置

```bash
# 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}值)
```

---

## ✅ 验证配置

### 验证开发环境

```bash
# 启动应用
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
```

### 验证生产环境

```bash
# 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. 保护敏感信息

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

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

### 2. 配置备份

```bash
# 备份当前配置
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. 配置审计

```bash
# 记录配置变更
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**:
```bash
# 方式1: 恢复备份的.env
cp .env.backup-20250110-120000 .env
./qaup.sh restart

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

---

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

**A**:
```bash
# 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`

如需恢复:
```bash
cp application-prod.yml.backup application-prod.yml
```

---

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

### 1. 更新启动脚本 qaup.sh

**当前状态**: ❌ 未完成

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

**参考文档**: [环境变量配置方案 - Step 2](./20250110_环境变量配置方案.md#step-2-修改启动脚本-qaupsh)

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

### 2. 测试验证

**开发环境测试**:
```bash
# 1. 在IDEA中启动应用
# 2. 检查启动日志确认使用 dev profile
# 3. 验证配置值正确（localhost:8090/8091）
```

**生产环境测试**（打包后）:
```bash
# 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. **配置审计**: 记录所有配置变更历史

---

## 📚 相关文档

- [环境变量配置方案](./20250110_环境变量配置方案.md)
- [Spring Boot配置文档](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.external-config)
- [CLAUDE.md - 项目说明](../../CLAUDE.md)

---

## 📞 支持

如有问题，请联系：
- 开发团队
- 查看项目文档：`doc/working/`

---

**文档结束**

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