|
@@ -0,0 +1,326 @@
|
|
|
|
|
+# 配置文件指南
|
|
|
|
|
+
|
|
|
|
|
+## 配置文件说明
|
|
|
|
|
+
|
|
|
|
|
+项目统一使用 **`.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
|
|
|
|
|
+
|
|
|
|
|
+# 方式二: 使用 .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. 检查配置文件是否生效
|
|
|
|
|
+
|
|
|
|
|
+启动应用后,查看日志中的配置信息:
|
|
|
|
|
+
|
|
|
|
|
+```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. **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 环境配置
|