lingyue-zhibao/backend/CONFIG_GUIDE.md

配置文件指南

配置文件说明

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

配置文件结构

1. 公共配置 (Common Module)

位于 common/src/main/resources/

application-common.properties

公共的数据库、MyBatis Plus、日志配置，所有服务共享。

# 数据库连接池配置
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。

# 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

主配置文件，包含所有基础配置。

# 引入公共配置
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

开发环境配置，覆盖主配置。

# 开发环境日志级别
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

生产环境配置，使用环境变量。

# 生产环境日志级别
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

环境变量配置

开发环境

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

生产环境

# 方式一: 设置环境变量
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

# 方式二: 使用 .env 文件配合 Docker
# 见 .env.example 文件
docker-compose up -d

常用环境变量列表

环境变量	说明	默认值	必需
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. 检查配置文件是否生效

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

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

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

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

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

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

3. 验证数据库连接

访问 Druid 监控页面:

• URL: http://localhost:8000/druid/
• 用户名: admin
• 密码: admin123

常见问题

1. 配置文件不生效

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

解决方案:

# 清理编译缓存
mvn clean

# 重新编译
mvn package -DskipTests

# 重启应用

2. 环境变量不生效

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

解决方案:

# 检查环境变量是否正确设置
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. 数据库连接失败

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

解决方案:

# 检查 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 密钥不安全。

解决方案:

# 生成随机密钥（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. Docker 部署: 使用 .env 文件管理环境变量
4. 敏感信息: 永远不要把密码、密钥提交到 Git 仓库
5. 配置分离: 公共配置放在 application-common.properties，特定配置放在各服务配置文件

配置文件变更历史

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