docs: 完善项目文档并清理过时文件
新增文档： - API_INTEGRATION_GUIDE.md: API集成指南（快速开始、SDK示例、常见场景） - DEPLOYMENT_GUIDE.md: 部署指南（环境要求、生产部署、Docker部署） - CONFIGURATION_GUIDE.md: 配置指南（环境配置、数据库、Redis、安全） - DEVELOPMENT_GUIDE.md: 开发指南（环境搭建、项目结构、开发规范） 文档更新： - api.md: 补充8个缺失的API端点（分享跟踪、回调、用户奖励） 文档清理： - 归档18个过时文档到 docs/archive/2026-03-04-cleanup/ - 删除3个调试文档（ralph-loop-*） 代码清理： - 删除4个.bak备份文件 - 删除1个.disabled测试文件 文档结构优化： - 从~40个文档精简到12个核心文档 - 建立清晰的文档导航体系 - 完善文档间的交叉引用
This commit is contained in:
Your Name
721
docs/CONFIGURATION_GUIDE.md
Normal file
721
docs/CONFIGURATION_GUIDE.md
Normal file
@@ -0,0 +1,721 @@
|
||||
# ⚙️ 配置指南
|
||||
|
||||
> 版本: 1.0
|
||||
> 更新时间: 2026-03-04
|
||||
|
||||
## 📋 目录
|
||||
|
||||
1. [配置文件结构](#配置文件结构)
|
||||
2. [环境配置](#环境配置)
|
||||
3. [数据库配置](#数据库配置)
|
||||
4. [Redis配置](#redis配置)
|
||||
5. [安全配置](#安全配置)
|
||||
6. [性能配置](#性能配置)
|
||||
7. [日志配置](#日志配置)
|
||||
8. [环境变量](#环境变量)
|
||||
|
||||
## 📁 配置文件结构
|
||||
|
||||
```
|
||||
src/main/resources/
|
||||
├── application.properties # 主配置文件
|
||||
├── application-dev.yml # 开发环境配置
|
||||
├── application-test.yml # 测试环境配置
|
||||
├── application-prod.yml # 生产环境配置
|
||||
├── application-e2e.properties # E2E测试配置
|
||||
└── logback-spring.xml # 日志配置
|
||||
```
|
||||
|
||||
### 配置优先级
|
||||
|
||||
1. 命令行参数 (`--spring.datasource.url=...`)
|
||||
2. 环境变量 (`SPRING_DATASOURCE_URL`)
|
||||
3. 外部配置文件 (`/opt/mosquito/application-prod.yml`)
|
||||
4. 内部配置文件 (`classpath:application-prod.yml`)
|
||||
5. 默认配置 (`application.properties`)
|
||||
|
||||
## 🌍 环境配置
|
||||
|
||||
### 开发环境 (dev)
|
||||
|
||||
`application-dev.yml`:
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
datasource:
|
||||
url: jdbc:postgresql://localhost:5432/mosquito_dev
|
||||
username: mosquito
|
||||
password: dev_password
|
||||
hikari:
|
||||
maximum-pool-size: 10
|
||||
minimum-idle: 2
|
||||
|
||||
data:
|
||||
redis:
|
||||
host: localhost
|
||||
port: 6379
|
||||
password: dev_redis_password
|
||||
|
||||
flyway:
|
||||
enabled: true
|
||||
baseline-on-migrate: true
|
||||
|
||||
jpa:
|
||||
show-sql: true
|
||||
properties:
|
||||
hibernate:
|
||||
format_sql: true
|
||||
|
||||
app:
|
||||
api-key:
|
||||
encryption-key: dev_32_char_encryption_key_12
|
||||
rate-limit:
|
||||
per-minute: 1000
|
||||
poster:
|
||||
cache-enabled: false
|
||||
|
||||
logging:
|
||||
level:
|
||||
root: INFO
|
||||
com.mosquito.project: DEBUG
|
||||
org.springframework.web: DEBUG
|
||||
```
|
||||
|
||||
### 测试环境 (test)
|
||||
|
||||
`application-test.yml`:
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
datasource:
|
||||
url: jdbc:h2:mem:testdb
|
||||
driver-class-name: org.h2.Driver
|
||||
username: sa
|
||||
password:
|
||||
|
||||
data:
|
||||
redis:
|
||||
host: localhost
|
||||
port: 6379
|
||||
|
||||
flyway:
|
||||
enabled: true
|
||||
|
||||
jpa:
|
||||
hibernate:
|
||||
ddl-auto: validate
|
||||
|
||||
app:
|
||||
api-key:
|
||||
encryption-key: test_32_char_encryption_key_12
|
||||
rate-limit:
|
||||
per-minute: 10000
|
||||
poster:
|
||||
cache-enabled: false
|
||||
|
||||
logging:
|
||||
level:
|
||||
root: WARN
|
||||
com.mosquito.project: INFO
|
||||
```
|
||||
|
||||
### 生产环境 (prod)
|
||||
|
||||
`application-prod.yml`:
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
datasource:
|
||||
url: ${DB_URL:jdbc:postgresql://localhost:5432/mosquito_prod}
|
||||
username: ${DB_USERNAME:mosquito_prod}
|
||||
password: ${DB_PASSWORD}
|
||||
hikari:
|
||||
maximum-pool-size: 20
|
||||
minimum-idle: 5
|
||||
connection-timeout: 30000
|
||||
idle-timeout: 600000
|
||||
max-lifetime: 1800000
|
||||
leak-detection-threshold: 60000
|
||||
|
||||
data:
|
||||
redis:
|
||||
host: ${REDIS_HOST:localhost}
|
||||
port: ${REDIS_PORT:6379}
|
||||
password: ${REDIS_PASSWORD}
|
||||
timeout: 3000ms
|
||||
lettuce:
|
||||
pool:
|
||||
max-active: 20
|
||||
max-idle: 10
|
||||
min-idle: 5
|
||||
max-wait: 3000ms
|
||||
|
||||
flyway:
|
||||
enabled: true
|
||||
baseline-on-migrate: true
|
||||
validate-on-migrate: true
|
||||
|
||||
jpa:
|
||||
show-sql: false
|
||||
properties:
|
||||
hibernate:
|
||||
jdbc:
|
||||
batch_size: 20
|
||||
order_inserts: true
|
||||
order_updates: true
|
||||
|
||||
app:
|
||||
api-key:
|
||||
encryption-key: ${API_KEY_ENCRYPTION_KEY}
|
||||
rate-limit:
|
||||
per-minute: ${RATE_LIMIT_PER_MINUTE:100}
|
||||
poster:
|
||||
cache-enabled: true
|
||||
cache-ttl: 3600
|
||||
|
||||
logging:
|
||||
level:
|
||||
root: INFO
|
||||
com.mosquito.project: INFO
|
||||
file:
|
||||
name: /var/log/mosquito/application.log
|
||||
max-size: 100MB
|
||||
max-history: 30
|
||||
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: health,info,metrics,prometheus
|
||||
endpoint:
|
||||
health:
|
||||
show-details: when-authorized
|
||||
```
|
||||
|
||||
## 🗄️ 数据库配置
|
||||
|
||||
### PostgreSQL连接池
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
datasource:
|
||||
hikari:
|
||||
# 最大连接数（推荐：CPU核心数 * 2 + 磁盘数）
|
||||
maximum-pool-size: 20
|
||||
|
||||
# 最小空闲连接数
|
||||
minimum-idle: 5
|
||||
|
||||
# 连接超时（毫秒）
|
||||
connection-timeout: 30000
|
||||
|
||||
# 空闲超时（毫秒）
|
||||
idle-timeout: 600000
|
||||
|
||||
# 连接最大生命周期（毫秒）
|
||||
max-lifetime: 1800000
|
||||
|
||||
# 连接泄漏检测阈值（毫秒）
|
||||
leak-detection-threshold: 60000
|
||||
|
||||
# 连接测试查询
|
||||
connection-test-query: SELECT 1
|
||||
```
|
||||
|
||||
### Flyway迁移配置
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
flyway:
|
||||
# 启用Flyway
|
||||
enabled: true
|
||||
|
||||
# 迁移脚本位置
|
||||
locations: classpath:db/migration
|
||||
|
||||
# 基线版本
|
||||
baseline-version: 1
|
||||
|
||||
# 在迁移时创建基线
|
||||
baseline-on-migrate: true
|
||||
|
||||
# 验证迁移
|
||||
validate-on-migrate: true
|
||||
|
||||
# 清理数据库（生产环境禁用）
|
||||
clean-disabled: true
|
||||
|
||||
# 占位符
|
||||
placeholders:
|
||||
schema: public
|
||||
```
|
||||
|
||||
### JPA/Hibernate配置
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
jpa:
|
||||
# 显示SQL（仅开发环境）
|
||||
show-sql: false
|
||||
|
||||
# DDL策略（生产环境使用validate）
|
||||
hibernate:
|
||||
ddl-auto: validate
|
||||
|
||||
properties:
|
||||
hibernate:
|
||||
# SQL格式化
|
||||
format_sql: true
|
||||
|
||||
# 批量操作
|
||||
jdbc:
|
||||
batch_size: 20
|
||||
order_inserts: true
|
||||
order_updates: true
|
||||
|
||||
# 二级缓存
|
||||
cache:
|
||||
use_second_level_cache: true
|
||||
region:
|
||||
factory_class: org.hibernate.cache.jcache.JCacheRegionFactory
|
||||
|
||||
# 查询缓存
|
||||
cache:
|
||||
use_query_cache: true
|
||||
```
|
||||
|
||||
## 🔴 Redis配置
|
||||
|
||||
### 基础配置
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
data:
|
||||
redis:
|
||||
# Redis服务器地址
|
||||
host: ${REDIS_HOST:localhost}
|
||||
|
||||
# Redis端口
|
||||
port: ${REDIS_PORT:6379}
|
||||
|
||||
# Redis密码
|
||||
password: ${REDIS_PASSWORD}
|
||||
|
||||
# 数据库索引
|
||||
database: 0
|
||||
|
||||
# 连接超时
|
||||
timeout: 3000ms
|
||||
|
||||
# Lettuce连接池
|
||||
lettuce:
|
||||
pool:
|
||||
max-active: 20
|
||||
max-idle: 10
|
||||
min-idle: 5
|
||||
max-wait: 3000ms
|
||||
|
||||
# 关闭超时
|
||||
shutdown-timeout: 100ms
|
||||
```
|
||||
|
||||
### 缓存配置
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
cache:
|
||||
type: redis
|
||||
redis:
|
||||
# 缓存TTL（毫秒）
|
||||
time-to-live: 3600000
|
||||
|
||||
# 缓存null值
|
||||
cache-null-values: false
|
||||
|
||||
# 键前缀
|
||||
key-prefix: "mosquito:"
|
||||
|
||||
# 使用键前缀
|
||||
use-key-prefix: true
|
||||
|
||||
app:
|
||||
cache:
|
||||
# 活动缓存TTL（秒）
|
||||
activity-ttl: 3600
|
||||
|
||||
# 统计缓存TTL（秒）
|
||||
stats-ttl: 300
|
||||
|
||||
# 排行榜缓存TTL（秒）
|
||||
leaderboard-ttl: 60
|
||||
```
|
||||
|
||||
### Redis Sentinel配置（高可用）
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
data:
|
||||
redis:
|
||||
sentinel:
|
||||
master: mymaster
|
||||
nodes:
|
||||
- 192.168.1.10:26379
|
||||
- 192.168.1.11:26379
|
||||
- 192.168.1.12:26379
|
||||
password: ${REDIS_PASSWORD}
|
||||
```
|
||||
|
||||
### Redis Cluster配置（集群）
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
data:
|
||||
redis:
|
||||
cluster:
|
||||
nodes:
|
||||
- 192.168.1.10:6379
|
||||
- 192.168.1.11:6379
|
||||
- 192.168.1.12:6379
|
||||
- 192.168.1.13:6379
|
||||
- 192.168.1.14:6379
|
||||
- 192.168.1.15:6379
|
||||
max-redirects: 3
|
||||
password: ${REDIS_PASSWORD}
|
||||
```
|
||||
|
||||
## 🔐 安全配置
|
||||
|
||||
### API密钥加密
|
||||
|
||||
```yaml
|
||||
app:
|
||||
api-key:
|
||||
# 加密密钥（必须32字符）
|
||||
encryption-key: ${API_KEY_ENCRYPTION_KEY}
|
||||
|
||||
# PBKDF2迭代次数
|
||||
pbkdf2-iterations: 10000
|
||||
|
||||
# 密钥长度
|
||||
key-length: 256
|
||||
```
|
||||
|
||||
生成加密密钥：
|
||||
|
||||
```bash
|
||||
# 生成32字符随机密钥
|
||||
openssl rand -base64 24 | head -c 32
|
||||
```
|
||||
|
||||
### 速率限制
|
||||
|
||||
```yaml
|
||||
app:
|
||||
rate-limit:
|
||||
# 每分钟请求限制
|
||||
per-minute: ${RATE_LIMIT_PER_MINUTE:100}
|
||||
|
||||
# 限流键前缀
|
||||
key-prefix: "rate_limit:"
|
||||
|
||||
# 限流窗口（秒）
|
||||
window-seconds: 60
|
||||
```
|
||||
|
||||
### CORS配置
|
||||
|
||||
```yaml
|
||||
app:
|
||||
cors:
|
||||
# 允许的源
|
||||
allowed-origins:
|
||||
- https://example.com
|
||||
- https://www.example.com
|
||||
|
||||
# 允许的方法
|
||||
allowed-methods:
|
||||
- GET
|
||||
- POST
|
||||
- PUT
|
||||
- DELETE
|
||||
- OPTIONS
|
||||
|
||||
# 允许的头
|
||||
allowed-headers:
|
||||
- "*"
|
||||
|
||||
# 暴露的头
|
||||
exposed-headers:
|
||||
- X-API-Version
|
||||
- X-RateLimit-Remaining
|
||||
|
||||
# 允许凭证
|
||||
allow-credentials: true
|
||||
|
||||
# 预检请求缓存时间（秒）
|
||||
max-age: 3600
|
||||
```
|
||||
|
||||
## ⚡ 性能配置
|
||||
|
||||
### 线程池配置
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
task:
|
||||
execution:
|
||||
pool:
|
||||
# 核心线程数
|
||||
core-size: 8
|
||||
|
||||
# 最大线程数
|
||||
max-size: 16
|
||||
|
||||
# 队列容量
|
||||
queue-capacity: 100
|
||||
|
||||
# 线程名前缀
|
||||
thread-name-prefix: "async-"
|
||||
|
||||
# 空闲线程存活时间（秒）
|
||||
keep-alive: 60s
|
||||
```
|
||||
|
||||
### HTTP客户端配置
|
||||
|
||||
```yaml
|
||||
app:
|
||||
http-client:
|
||||
# 连接超时（毫秒）
|
||||
connect-timeout: 5000
|
||||
|
||||
# 读取超时（毫秒）
|
||||
read-timeout: 10000
|
||||
|
||||
# 最大连接数
|
||||
max-connections: 100
|
||||
|
||||
# 每个路由的最大连接数
|
||||
max-connections-per-route: 20
|
||||
```
|
||||
|
||||
### 海报生成配置
|
||||
|
||||
```yaml
|
||||
app:
|
||||
poster:
|
||||
# 启用缓存
|
||||
cache-enabled: true
|
||||
|
||||
# 缓存TTL（秒）
|
||||
cache-ttl: 3600
|
||||
|
||||
# 图片质量（0.0-1.0）
|
||||
image-quality: 0.9
|
||||
|
||||
# 图片格式
|
||||
image-format: PNG
|
||||
|
||||
# 最大宽度
|
||||
max-width: 1080
|
||||
|
||||
# 最大高度
|
||||
max-height: 1920
|
||||
```
|
||||
|
||||
## 📝 日志配置
|
||||
|
||||
### Logback配置
|
||||
|
||||
`logback-spring.xml`:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<configuration>
|
||||
<!-- 开发环境 -->
|
||||
<springProfile name="dev">
|
||||
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
|
||||
<encoder>
|
||||
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
|
||||
</encoder>
|
||||
</appender>
|
||||
|
||||
<root level="INFO">
|
||||
<appender-ref ref="CONSOLE" />
|
||||
</root>
|
||||
|
||||
<logger name="com.mosquito.project" level="DEBUG" />
|
||||
<logger name="org.springframework.web" level="DEBUG" />
|
||||
</springProfile>
|
||||
|
||||
<!-- 生产环境 -->
|
||||
<springProfile name="prod">
|
||||
<!-- 文件输出 -->
|
||||
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
|
||||
<file>/var/log/mosquito/application.log</file>
|
||||
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
|
||||
<fileNamePattern>/var/log/mosquito/application.%d{yyyy-MM-dd}.log</fileNamePattern>
|
||||
<maxHistory>30</maxHistory>
|
||||
<totalSizeCap>10GB</totalSizeCap>
|
||||
</rollingPolicy>
|
||||
<encoder>
|
||||
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
|
||||
</encoder>
|
||||
</appender>
|
||||
|
||||
<!-- 错误日志单独输出 -->
|
||||
<appender name="ERROR_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
|
||||
<file>/var/log/mosquito/error.log</file>
|
||||
<filter class="ch.qos.logback.classic.filter.ThresholdFilter">
|
||||
<level>ERROR</level>
|
||||
</filter>
|
||||
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
|
||||
<fileNamePattern>/var/log/mosquito/error.%d{yyyy-MM-dd}.log</fileNamePattern>
|
||||
<maxHistory>90</maxHistory>
|
||||
</rollingPolicy>
|
||||
<encoder>
|
||||
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
|
||||
</encoder>
|
||||
</appender>
|
||||
|
||||
<root level="INFO">
|
||||
<appender-ref ref="FILE" />
|
||||
<appender-ref ref="ERROR_FILE" />
|
||||
</root>
|
||||
|
||||
<logger name="com.mosquito.project" level="INFO" />
|
||||
</springProfile>
|
||||
</configuration>
|
||||
```
|
||||
|
||||
### 日志级别
|
||||
|
||||
```yaml
|
||||
logging:
|
||||
level:
|
||||
# 根日志级别
|
||||
root: INFO
|
||||
|
||||
# 应用日志
|
||||
com.mosquito.project: INFO
|
||||
|
||||
# Spring框架
|
||||
org.springframework: INFO
|
||||
org.springframework.web: INFO
|
||||
org.springframework.security: INFO
|
||||
|
||||
# Hibernate
|
||||
org.hibernate: INFO
|
||||
org.hibernate.SQL: DEBUG
|
||||
org.hibernate.type.descriptor.sql.BasicBinder: TRACE
|
||||
|
||||
# Redis
|
||||
org.springframework.data.redis: INFO
|
||||
|
||||
# Flyway
|
||||
org.flywaydb: INFO
|
||||
```
|
||||
|
||||
## 🌐 环境变量
|
||||
|
||||
### 必需环境变量
|
||||
|
||||
```bash
|
||||
# 数据库配置
|
||||
export DB_URL="jdbc:postgresql://localhost:5432/mosquito_prod"
|
||||
export DB_USERNAME="mosquito_prod"
|
||||
export DB_PASSWORD="your_secure_password"
|
||||
|
||||
# Redis配置
|
||||
export REDIS_HOST="localhost"
|
||||
export REDIS_PORT="6379"
|
||||
export REDIS_PASSWORD="your_redis_password"
|
||||
|
||||
# 安全配置
|
||||
export API_KEY_ENCRYPTION_KEY="your_32_char_encryption_key_12"
|
||||
```
|
||||
|
||||
### 可选环境变量
|
||||
|
||||
```bash
|
||||
# 速率限制
|
||||
export RATE_LIMIT_PER_MINUTE="100"
|
||||
|
||||
# 日志配置
|
||||
export LOG_LEVEL="INFO"
|
||||
export LOG_FILE="/var/log/mosquito/application.log"
|
||||
|
||||
# JVM配置
|
||||
export JAVA_OPTS="-Xms2g -Xmx4g -XX:+UseG1GC"
|
||||
|
||||
# Spring配置
|
||||
export SPRING_PROFILES_ACTIVE="prod"
|
||||
export SERVER_PORT="8080"
|
||||
```
|
||||
|
||||
### 环境变量文件
|
||||
|
||||
创建 `.env` 文件（不要提交到Git）：
|
||||
|
||||
```bash
|
||||
# .env
|
||||
DB_PASSWORD=your_secure_password
|
||||
REDIS_PASSWORD=your_redis_password
|
||||
API_KEY_ENCRYPTION_KEY=your_32_char_encryption_key_12
|
||||
RATE_LIMIT_PER_MINUTE=100
|
||||
```
|
||||
|
||||
加载环境变量：
|
||||
|
||||
```bash
|
||||
# 使用source加载
|
||||
source .env
|
||||
|
||||
# 或使用export
|
||||
export $(cat .env | xargs)
|
||||
```
|
||||
|
||||
## 🔧 配置验证
|
||||
|
||||
### 启动时验证
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class ConfigValidation {
|
||||
|
||||
@Value("${app.api-key.encryption-key}")
|
||||
private String encryptionKey;
|
||||
|
||||
@PostConstruct
|
||||
public void validate() {
|
||||
if (encryptionKey.length() != 32) {
|
||||
throw new IllegalStateException(
|
||||
"API key encryption key must be exactly 32 characters"
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 配置检查命令
|
||||
|
||||
```bash
|
||||
# 检查配置文件语法
|
||||
java -jar mosquito-1.0.0.jar --spring.config.location=application-prod.yml --spring.profiles.active=prod --debug
|
||||
|
||||
# 查看实际配置
|
||||
java -jar mosquito-1.0.0.jar --spring.profiles.active=prod \
|
||||
--spring.boot.admin.client.enabled=false \
|
||||
org.springframework.boot.autoconfigure.logging.ConditionEvaluationReportLoggingListener
|
||||
```
|
||||
|
||||
## 📚 相关资源
|
||||
|
||||
- [部署指南](./DEPLOYMENT_GUIDE.md) - 部署说明
|
||||
- [API文档](./api.md) - API接口文档
|
||||
- [开发指南](./DEVELOPMENT_GUIDE.md) - 开发环境搭建
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: 1.0
|
||||
**最后更新**: 2026-03-04
|
||||
Reference in New Issue
Block a user