niuniu/wenzi

Fork 0

Files

Your Name 2ef0f17961 chore: sync local latest state and repository cleanup

2026-03-23 13:02:36 +08:00

17 KiB

Raw Permalink Blame History

⚙️ 配置指南

版本: 1.0 更新时间: 2026-03-04

📋 目录

配置文件结构
环境配置
数据库配置
Redis配置
安全配置
性能配置
日志配置
环境变量

📁 配置文件结构

src/main/resources/
├── application.properties          # 主配置文件
├── application-dev.yml            # 开发环境配置
├── application-test.yml           # 测试环境配置
├── application-prod.yml           # 生产环境配置
├── application-e2e.properties     # E2E测试配置
└── logback-spring.xml             # 日志配置

配置优先级

命令行参数 (--spring.datasource.url=...)
环境变量 (SPRING_DATASOURCE_URL)
外部配置文件 (/opt/mosquito/application-prod.yml)
内部配置文件 (classpath:application-prod.yml)
默认配置 (application.properties)

🌍 环境配置

开发环境 (dev)

application-dev.yml:

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:

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:

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连接池

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迁移配置

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配置

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配置

基础配置

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

缓存配置

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配置（高可用）

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配置（集群）

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白名单配置

系统对回调API请求进行IP白名单验证，确保只有受信任的服务器才能调用回调接口。

回调白名单配置项

app:
  callback:
    # IP白名单列表，用逗号分隔
    # 生产环境必须配置，否则启动会失败（fail-fast）
    whitelist:
      ips: "203.0.113.1,198.51.100.1,10.0.0.0/8"

    # 宽松模式（仅用于开发/测试环境）
    # 设为true时跳过IP白名单验证
    whitelist:
      permissive: false

环境变量配置

# 方式1：直接配置IP白名单（推荐生产环境使用）
export MOSQUITO_CALLBACK_WHITELIST_IPS="203.0.113.1,198.51.100.1"

# 方式2：启用宽松模式（仅用于开发/测试）
export MOSQUITO_CALLBACK_WHITELIST_PERMISSIVE="true"

# Spring配置方式
export MOSQUITO_CALLBACK_WHITELIST_IPS="203.0.113.1,198.51.100.1"

生产环境配置示例

# application-prod.yml
app:
  callback:
    whitelist:
      ips: "${MOSQUITO_CALLBACK_WHITELIST_IPS}"
      permissive: false

生产环境启动前检查清单：

确认已配置IP白名单

# 检查环境变量
echo $MOSQUITO_CALLBACK_WHITELIST_IPS

# 如果未配置，启动会失败并报错：
# "生产环境回调白名单配置缺失！请配置 mosquito.callback.whitelist.ips 或启用 permissive 模式。"

配置CIDR格式IP段

# 支持CIDR格式（但需注意：系统使用简单字符串分割，不支持严格的CIDR解析）
# 推荐列出所有具体IP或使用云服务商的弹性IP
export MOSQUITO_CALLBACK_WHITELIST_IPS="203.0.113.1,198.51.100.10,198.51.100.20"

常见云服务商IP段

# 阿里云ECS（需要根据实际配置）
export MOSQUITO_CALLBACK_WHITELIST_IPS="10.0.0.0/8,172.16.0.0/12"

# AWS EC2
export MOSQUITO_CALLBACK_WHITELIST_IPS="3.0.0.0/8,18.0.0.0/8"

开发/测试环境配置

# application-dev.yml
app:
  callback:
    whitelist:
      permissive: true  # 跳过白名单验证

或通过环境变量：

# 开发环境
export MOSQUITO_CALLBACK_WHITELIST_PERMISSIVE="true"

# 测试环境（使用测试配置）
export SPRING_PROFILES_ACTIVE=test

故障排查

错误信息	原因	解决方案
"生产环境回调白名单配置缺失"	未配置`mosquito.callback.whitelist.ips`	配置IP白名单或启用permissive模式
"来源IP不在白名单中"	回调请求IP不在白名单中	将该IP添加到白名单
"启动失败"	生产环境未配置白名单	配置`MOSQUITO_CALLBACK_WHITELIST_IPS`

白名单验证逻辑

系统启动时如果permissive=false且ips为空，会抛出异常阻止启动（fail-fast）
每个回调请求都会验证来源IP是否在白名单中
不在白名单中的请求会被拒绝并返回IP_NOT_WHITELISTED错误

API密钥加密

app:
  api-key:
    # 加密密钥（必须32字符）
    encryption-key: ${API_KEY_ENCRYPTION_KEY}

    # PBKDF2迭代次数
    pbkdf2-iterations: 10000

    # 密钥长度
    key-length: 256

生成加密密钥：

# 生成32字符随机密钥
openssl rand -base64 24 | head -c 32

速率限制

app:
  rate-limit:
    # 每分钟请求限制
    per-minute: ${RATE_LIMIT_PER_MINUTE:100}

    # 限流键前缀
    key-prefix: "rate_limit:"

    # 限流窗口（秒）
    window-seconds: 60

CORS配置

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

⚡ 性能配置

线程池配置

spring:
  task:
    execution:
      pool:
        # 核心线程数
        core-size: 8

        # 最大线程数
        max-size: 16

        # 队列容量
        queue-capacity: 100

        # 线程名前缀
        thread-name-prefix: "async-"

        # 空闲线程存活时间（秒）
        keep-alive: 60s

HTTP客户端配置

app:
  http-client:
    # 连接超时（毫秒）
    connect-timeout: 5000

    # 读取超时（毫秒）
    read-timeout: 10000

    # 最大连接数
    max-connections: 100

    # 每个路由的最大连接数
    max-connections-per-route: 20

海报生成配置

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 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>

日志级别

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

🌐 环境变量

必需环境变量

# 数据库配置
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"

可选环境变量

# 速率限制
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）：

# .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

加载环境变量：

# 使用source加载
source .env

# 或使用export
export $(cat .env | xargs)

🔧 配置验证

启动时验证

@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"
            );
        }
    }
}

配置检查命令

# 检查配置文件语法
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

📚 相关资源

部署指南 - 部署说明
API文档 - API接口文档
开发指南 - 开发环境搭建

文档版本: 1.0 最后更新: 2026-03-04

17 KiB Raw Permalink Blame History Unescape Escape