# 配置文件指南

## 配置文件说明

项目统一使用 **`.properties`** 格式的配置文件，已删除所有 `.yml` 配置文件以避免混淆。

## 配置文件结构

### 1. 公共配置 (Common Module)

位于 `common/src/main/resources/`

#### `application-common.properties`
公共的数据库、MyBatis Plus、日志配置，所有服务共享。

```properties
# 数据库连接池配置
spring.datasource.type=com.alibaba.druid.pool.DruidDataSource
spring.datasource.druid.driver-class-name=org.postgresql.Driver
spring.datasource.druid.url=jdbc:postgresql://localhost:5432/lingyue_zhibao
spring.datasource.druid.username=${DB_USERNAME:postgres}
spring.datasource.druid.password=${DB_PASSWORD:postgres}

# MyBatis Plus配置
mybatis-plus.mapper-locations=classpath*:mapper/**/*Mapper.xml
mybatis-plus.configuration.map-underscore-to-camel-case=true
mybatis-plus.global-config.db-config.id-type=assign_uuid

# 日志配置
logging.level.root=INFO
logging.level.com.lingyue=DEBUG
```

#### `application-infra.properties`
基础设施配置，包括 Nacos、RabbitMQ、Redis。

```properties
# Nacos服务发现
spring.cloud.nacos.discovery.server-addr=${NACOS_SERVER_ADDR:localhost:8848}

# RabbitMQ配置
spring.rabbitmq.host=${RABBITMQ_HOST:localhost}
spring.rabbitmq.port=${RABBITMQ_PORT:5672}

# Redis配置
spring.data.redis.host=${REDIS_HOST:localhost}
spring.data.redis.port=${REDIS_PORT:6379}
```

### 2. 各服务配置

每个微服务都有自己的 `application.properties`:

```
backend/
├── auth-service/src/main/resources/
│   └── application.properties          # Auth 服务特定配置
├── document-service/src/main/resources/
│   └── application.properties          # Document 服务特定配置
├── parse-service/src/main/resources/
│   └── application.properties          # Parse 服务特定配置
├── ai-service/src/main/resources/
│   └── application.properties          # AI 服务特定配置
├── graph-service/src/main/resources/
│   └── application.properties          # Graph 服务特定配置
├── notification-service/src/main/resources/
│   └── application.properties          # Notification 服务特定配置
└── lingyue-starter/src/main/resources/
    ├── application.properties          # 单体应用主配置
    ├── application-dev.properties      # 开发环境配置
    └── application-prod.properties     # 生产环境配置
```

### 3. 单体应用配置 (Lingyue Starter)

这是最重要的配置文件，用于单体应用部署。

#### `application.properties`
主配置文件，包含所有基础配置。

```properties
# 引入公共配置
spring.config.import=classpath:application-common.properties,classpath:application-infra.properties

# 服务端口
server.port=8000

# 应用名称
spring.application.name=lingyue-zhibao

# 激活的环境
spring.profiles.active=dev

# 文件上传
spring.servlet.multipart.max-file-size=20MB
spring.servlet.multipart.max-request-size=100MB

# JWT配置
jwt.secret=${JWT_SECRET:lingyue-zhibao-secret-key-2024-please-change-in-production}
jwt.expiration=604800000

# SpringDoc API文档
springdoc.swagger-ui.enabled=true
springdoc.swagger-ui.path=/swagger-ui.html

# PaddleOCR配置
paddleocr.server-url=${PADDLEOCR_SERVER_URL:http://localhost:8866}

# DeepSeek API配置
deepseek.api-key=${DEEPSEEK_API_KEY:}
```

#### `application-dev.properties`
开发环境配置，覆盖主配置。

```properties
# 开发环境日志级别
logging.level.com.lingyue=DEBUG
logging.level.org.springframework.web=DEBUG

# 热部署
spring.devtools.restart.enabled=true

# SQL日志
mybatis-plus.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl
```

#### `application-prod.properties`
生产环境配置，使用环境变量。

```properties
# 生产环境日志级别
logging.level.com.lingyue=INFO
logging.level.org.springframework.web=WARN

# 数据库（使用环境变量）
spring.datasource.druid.url=jdbc:postgresql://${DB_HOST}:${DB_PORT}/${DB_NAME}
spring.datasource.druid.username=${DB_USERNAME}
spring.datasource.druid.password=${DB_PASSWORD}

# 禁用热部署
spring.devtools.restart.enabled=false

# 禁用API文档（可选）
springdoc.api-docs.enabled=false
springdoc.swagger-ui.enabled=false
```

## 配置优先级

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

1. **命令行参数**: `java -jar app.jar --server.port=8080`
2. **环境变量**: `export SERVER_PORT=8080`
3. **application-{profile}.properties**: 如 `application-prod.properties`
4. **application.properties**: 主配置文件
5. **引入的配置文件**: `application-common.properties`, `application-infra.properties`

## 环境变量配置

### 开发环境

```bash
# 使用默认配置，无需设置环境变量
java -jar lingyue-starter.jar
```

### 生产环境

```bash
# 方式一: 设置环境变量
export SPRING_PROFILES_ACTIVE=prod
export DB_HOST=db.example.com
export DB_PORT=5432
export DB_NAME=lingyue_zhibao
export DB_USERNAME=lingyue
export DB_PASSWORD=your-secure-password
export REDIS_HOST=redis.example.com
export REDIS_PASSWORD=your-redis-password
export RABBITMQ_HOST=rabbitmq.example.com
export RABBITMQ_USERNAME=admin
export RABBITMQ_PASSWORD=your-rabbitmq-password
export JWT_SECRET=your-very-long-random-secret-key-at-least-32-characters
export DEEPSEEK_API_KEY=your-deepseek-api-key

java -jar lingyue-starter.jar

# 方式二: 后台运行
nohup java -jar lingyue-starter.jar > app.log 2>&1 &
```

### 常用环境变量列表

| 环境变量 | 说明 | 默认值 | 必需 |
|---------|------|--------|------|
| `SPRING_PROFILES_ACTIVE` | 激活的配置文件 | dev | 否 |
| `DB_HOST` | 数据库主机 | localhost | 生产环境必需 |
| `DB_PORT` | 数据库端口 | 5432 | 否 |
| `DB_NAME` | 数据库名称 | lingyue_zhibao | 否 |
| `DB_USERNAME` | 数据库用户名 | postgres | 是 |
| `DB_PASSWORD` | 数据库密码 | postgres | 是 |
| `REDIS_HOST` | Redis主机 | localhost | 是 |
| `REDIS_PORT` | Redis端口 | 6379 | 否 |
| `REDIS_PASSWORD` | Redis密码 | (空) | 否 |
| `RABBITMQ_HOST` | RabbitMQ主机 | localhost | 是 |
| `RABBITMQ_PORT` | RabbitMQ端口 | 5672 | 否 |
| `RABBITMQ_USERNAME` | RabbitMQ用户名 | guest | 是 |
| `RABBITMQ_PASSWORD` | RabbitMQ密码 | guest | 是 |
| `JWT_SECRET` | JWT密钥 | (默认值) | **强烈建议设置** |
| `PADDLEOCR_SERVER_URL` | OCR服务地址 | http://localhost:8866 | 如需OCR功能 |
| `DEEPSEEK_API_KEY` | DeepSeek API密钥 | (空) | 如需AI功能 |
| `DEEPSEEK_API_URL` | DeepSeek API地址 | https://api.deepseek.com | 否 |

## 配置验证

### 1. 检查配置文件是否生效

启动应用后，查看日志中的配置信息:

```bash
# 启动应用
java -jar lingyue-starter.jar

# 日志中会显示:
# - 激活的配置文件: spring.profiles.active
# - 数据源连接信息
# - 服务端口
```

### 2. 访问配置端点（需要启用 Actuator）

```bash
# 查看所有配置
curl http://localhost:8000/actuator/configprops

# 查看环境变量
curl http://localhost:8000/actuator/env
```

### 3. 验证数据库连接

访问 Druid 监控页面:
- URL: http://localhost:8000/druid/
- 用户名: admin
- 密码: admin123

## 常见问题

### 1. 配置文件不生效

**问题**: 修改了配置文件，但应用没有使用新配置。

**解决方案**:
```bash
# 清理编译缓存
mvn clean

# 重新编译
mvn package -DskipTests

# 重启应用
```

### 2. 环境变量不生效

**问题**: 设置了环境变量，但应用仍使用默认值。

**解决方案**:
```bash
# 检查环境变量是否正确设置
echo $DB_USERNAME
echo $JWT_SECRET

# 使用 -D 参数传递配置
java -jar lingyue-starter.jar -Dspring.datasource.druid.username=lingyue

# 或使用 Spring Boot 的环境变量格式
export SPRING_DATASOURCE_DRUID_USERNAME=lingyue
```

### 3. 数据库连接失败

**问题**: 应用启动时报数据库连接错误。

**解决方案**:
```properties
# 检查 application.properties 中的配置
spring.datasource.druid.url=jdbc:postgresql://localhost:5432/lingyue_zhibao
spring.datasource.druid.username=postgres
spring.datasource.druid.password=postgres

# 或设置环境变量
export DB_USERNAME=postgres
export DB_PASSWORD=postgres
```

### 4. JWT 密钥警告

**问题**: 日志中提示使用默认 JWT 密钥不安全。

**解决方案**:
```bash
# 生成随机密钥（Linux/Mac）
openssl rand -base64 48

# 设置环境变量
export JWT_SECRET=your-generated-secret-key

# 或在 application.properties 中直接设置
jwt.secret=your-generated-secret-key
```

## 最佳实践

1. **开发环境**: 使用 `application-dev.properties`，配置写在文件中
2. **生产环境**: 使用 `application-prod.properties`，敏感配置用环境变量
3. **敏感信息**: 永远不要把密码、密钥提交到 Git 仓库
4. **配置分离**: 公共配置放在 `application-common.properties`，特定配置放在各服务配置文件

## 配置文件变更历史

- **2026-01-15**: 统一使用 `.properties` 格式，删除所有 `.yml` 文件
- **2026-01-15**: 创建 `application-common.properties` 和 `application-infra.properties` 公共配置
- **2026-01-15**: 为 `lingyue-starter` 创建 dev 和 prod 环境配置