crm-backend-matt/.qoder/repowiki/zh/content/配置指南/配置指南.md

# 配置指南

<cite>
**本文引用的文件**   
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application-verify.yml](file://crm-app/src/main/resources/application-verify.yml)
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [ScheduledTaskProperties.java](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java)
- [SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [JacksonConfig.java](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [CorsConfig.java](file://crm-base/src/main/java/com/crm/base/config/CorsConfig.java)
- [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java)
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java)
- [PermissionConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.java)
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [ThumbnailRetryTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailRetryTask.java)
- [ImageThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/ImageThumbnailRenderer.java)
- [OfficeThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/OfficeThumbnailRenderer.java)
- [PdfThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/PdfThumbnailRenderer.java)
- [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)
</cite>

## 更新摘要
**变更内容**   
- 新增缩略图配置类 FileProperties.Thumbnail，包含完整的缩略图生成配置选项
- 新增 application-verify.yml 验证环境配置文件，支持调试和测试场景
- 完善缩略图渲染器配置（图片、PDF、Office文档）
- 增强定时任务配置（缩略图生成、失败重试）
- 扩展环境变量覆盖机制

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向运维与开发人员，提供 CRM 后端项目的完整配置说明。内容覆盖：
- 所有关键配置项的含义、默认值、环境变量覆盖方式
- 动态配置更新机制（如适用）
- 数据库连接、Redis 缓存、MinIO 文件存储、JWT 安全、日志级别等核心配置
- **新增：缩略图生成配置（尺寸、格式、重试策略、LibreOffice路径）**
- **新增：验证环境专用配置（调试接口、权限豁免）**
- 不同环境的配置模板（开发、测试、生产、验证）
- 配置验证规则、热更新机制、最佳实践、性能调优参数与故障排查

## 项目结构
本项目采用多模块 Maven 工程，按功能划分模块：
- crm-app：应用启动入口与全局应用配置
- crm-auth：认证授权与安全相关配置
- crm-base：公共基础配置（Redis、Jackson、MyBatis-Plus、跨域、接口文档等）
- crm-file：文件服务（MinIO、分片上传、缩略图生成、定时清理任务）

```mermaid
graph TB
subgraph "应用层"
APP["crm-app<br/>应用入口"]
AUTH["crm-auth<br/>认证授权"]
FILE["crm-file<br/>文件服务"]
end
subgraph "基础能力"
BASE["crm-base<br/>通用配置与工具"]
THUMB["缩略图系统<br/>渲染器+任务调度"]
end
APP --> AUTH
APP --> FILE
AUTH --> BASE
FILE --> BASE
FILE --> THUMB
```

**图表来源** 
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)

**章节来源**
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)

## 核心组件
- 应用配置中心：Spring Boot 的 application.yml 作为统一配置源，支持多环境 profile 切换与环境变量覆盖
- 数据访问：MyBatis-Plus 配置、元对象填充、自定义 ID 生成器
- 缓存：Redis 客户端配置与序列化策略
- 文件存储：MinIO 客户端与文件属性绑定
- **缩略图系统：缩略图生成配置、渲染器、异步任务、失败重试**
- 安全：Spring Security + JWT 过滤器与令牌服务
- 调度：任务调度开关与属性
- 接口文档：Knife4j 配置
- 跨域：CORS 配置
- JSON：Jackson 序列化配置

**章节来源**
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application-verify.yml](file://crm-app/src/main/resources/application-verify.yml)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [ThumbnailRetryTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailRetryTask.java)

## 架构总览
下图展示了配置加载与运行时依赖关系：应用启动时读取 application.yml，注入各配置类；业务组件通过 @ConfigurationProperties 或 @Value 获取配置；安全、缓存、文件、调度、缩略图等子系统按配置初始化。

```mermaid
graph LR
YML["application.yml<br/>配置文件"] --> BOOT["Spring Boot 容器"]
BOOT --> PROPS_AUTH["AuthProperties<br/>认证属性"]
BOOT --> PROPS_FILE["FileProperties<br/>文件属性"]
BOOT --> PROPS_THUMB["Thumbnail<br/>缩略图配置"]
BOOT --> CFG_BASE["Base 配置集合<br/>Redis/MyBatis-Plus/Jackson/CORS/Knife4j"]
BOOT --> CFG_SEC["SecurityConfig<br/>安全配置"]
BOOT --> CFG_MINIO["MinioConfig<br/>MinIO 客户端"]
BOOT --> CFG_SCHED["SchedulingConfig<br/>调度开关"]
CFG_SEC --> FILTER["JwtAuthenticationFilter<br/>JWT 过滤器"]
FILTER --> TOKEN["TokenService<br/>令牌服务"]
CFG_MINIO --> FILE_SVC["文件服务"]
CFG_BASE --> REDIS["Redis 缓存"]
CFG_BASE --> DB["数据库(MyBatis-Plus)"]
PROPS_THUMB --> THUMB_TASK["缩略图任务<br/>生成+重试"]
THUMB_TASK --> RENDERERS["渲染器<br/>图片/PDF/Office"]
RENDERERS --> LIBREOFFICE["LibreOffice<br/>文档转换"]
```

**图表来源** 
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application-verify.yml](file://crm-app/src/main/resources/application-verify.yml)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [OfficeThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/OfficeThumbnailRenderer.java)

## 详细组件分析

### 应用与模块入口
- 应用启动类负责扫描包与启用自动配置，确保各模块的配置类被加载
- 多模块共享 application.yml，可按模块拆分 profile
- **新增：验证环境专用配置，支持调试接口和权限豁免**

**章节来源**
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
- [application-verify.yml](file://crm-app/src/main/resources/application-verify.yml)

### 数据库连接配置（MyBatis-Plus）
- 数据源 URL、用户名、密码、驱动、连接池参数由 application.yml 提供
- MyBatis-Plus 配置包括主键策略、逻辑删除、分页插件、元对象填充处理器、批量插入策略等
- 自定义 ID 生成器用于分布式唯一 ID

```mermaid
flowchart TD
Start(["应用启动"]) --> LoadDB["加载数据源配置"]
LoadDB --> InitMP["初始化 MyBatis-Plus"]
InitMP --> SetIDGen["设置自定义 ID 生成器"]
SetIDGen --> EnablePlugins["启用分页/填充/批量策略"]
EnablePlugins --> Ready(["就绪"])
```

**图表来源** 
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java)

**章节来源**
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java)

### Redis 缓存配置
- Redis 主机、端口、密码、数据库索引、超时时间、序列化策略在 application.yml 中定义
- RedisConfig 负责创建 RedisTemplate 并配置序列化器，保证与 JSON 的一致性
- **缩略图分布式锁使用 Redis 实现，TTL 配置需大于最慢渲染时间**

```mermaid
classDiagram
class RedisConfig {
+createRedisTemplate()
+configureSerializer()
}
class FileProperties {
+redis相关字段
+thumbnail.lockTtl : Duration
}
class ThumbnailGenerationTask {
+generateWithLock(fileId)
+lockTtl配置
}
RedisConfig <.. FileProperties : "使用Redis进行会话/缓存"
RedisConfig <.. ThumbnailGenerationTask : "分布式锁"
```

**图表来源** 
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)

**章节来源**
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)

### MinIO 文件存储配置
- MinIO 端点、AccessKey、SecretKey、Bucket 名称、URL 前缀等由 application.yml 提供
- FileProperties 绑定文件相关配置（如分片大小、路径策略），MinioConfig 初始化客户端
- **缩略图存储在 thumbnails/{fileId}.jpg 路径下**

```mermaid
sequenceDiagram
participant App as "应用"
participant Props as "FileProperties"
participant Minio as "MinioConfig"
participant Client as "MinIO 客户端"
App->>Props : 读取文件配置
App->>Minio : 初始化客户端
Minio->>Client : 构建连接(端点/密钥/Bucket)
Client-->>Minio : 客户端实例
Minio-->>App : 返回可用客户端
Note over Client : 缩略图存储 : thumbnails/{fileId}.jpg
```

**图表来源** 
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)

**章节来源**
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)

### JWT 安全配置
- Spring Security 与 JWT 过滤器协同工作，TokenService 负责令牌签发、校验与刷新
- AuthProperties 可能包含 JWT 密钥、过期时间、白名单等
- **验证环境支持调试接口和缩略图接口权限豁免**

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Filter as "JwtAuthenticationFilter"
participant Token as "TokenService"
participant Sec as "SecurityConfig"
Client->>Filter : 携带 Authorization 请求
Filter->>Token : 解析并校验令牌
Token-->>Filter : 校验结果
Filter->>Sec : 设置认证上下文
Sec-->>Client : 放行或拒绝
Note over Sec : 验证环境 : /api/file/thumbnail 豁免鉴权
```

**图表来源** 
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java)
- [application-verify.yml](file://crm-app/src/main/resources/application-verify.yml)

**章节来源**
- [application.yml](file://crm-auth/src/main/resources/application.yml)
- [application-verify.yml](file://crm-app/src/main/resources/application-verify.yml)
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java)

### 日志级别配置
- 通过 application.yml 的 logging.level 控制各包日志级别
- 建议开发环境开启 DEBUG，生产环境 INFO/WARN

**章节来源**
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)

### 其他基础配置
- Jackson：日期格式、空值处理、忽略未知字段等
- CORS：允许的来源、方法、头、凭证
- Knife4j：API 文档开关、分组、路径
- 调度：任务开关与 Cron 表达式
- Snowflake：雪花算法节点 ID 与数据中心 ID

**章节来源**
- [JacksonConfig.java](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java)
- [CorsConfig.java](file://crm-base/src/main/java/com/crm/base/config/CorsConfig.java)
- [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
- [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java)
- [ScheduledTaskProperties.java](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java)
- [SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)

### 缩略图配置系统（新增）
**更新** 新增完整的缩略图配置类，支持多种文件类型的缩略图生成

#### 缩略图基本配置
- **width**: 缩略图固定宽度（px），默认 200，等比缩放
- **maxHeight**: 缩略图等比缩放上限高度（px），防止超长截图，默认 400
- **format**: 输出格式（jpeg/png），默认 jpeg
- **syncWaitTimeout**: 同步兜底等待超时，PENDING 状态获锁失败后的轮询上限，默认 10秒

#### 缩略图重试策略
- **retryLimit**: 最大重试次数，达到后标记 FAILED，默认 3次
- **retryCron**: FAILED 重试扫描周期（cron），默认每天凌晨 4点
- **lockTtl**: 生成分布式锁 TTL，必须大于 officeConvertTimeout，默认 150秒

#### LibreOffice 配置
- **libreofficePath**: LibreOffice 可执行文件路径，默认 soffice
- **officeConvertTimeout**: LibreOffice 单次转换超时（大文档首页渲染可能较慢），默认 120秒

```mermaid
flowchart TD
Upload["文件上传"] --> CheckType{"文件类型检查"}
CheckType --> |图片| ImgThumb["图片缩略图<br/>ImageThumbnailRenderer"]
CheckType --> |PDF| PdfThumb["PDF缩略图<br/>PdfThumbnailRenderer"]
CheckType --> |Office| OfficeThumb["Office缩略图<br/>OfficeThumbnailRenderer"]
CheckType --> |不支持| Unsupported["UNSUPPORTED<br/>跳过生成"]
ImgThumb --> AsyncGen["异步生成<br/>ThumbnailGenerationTask"]
PdfThumb --> AsyncGen
OfficeThumb --> AsyncGen
AsyncGen --> Success{"生成成功?"}
Success --> |是| Ready["READY<br/>存储到MinIO"]
Success --> |否| RetryCount{"重试次数<br/>未达上限?"}
RetryCount --> |是| Pending["PENDING<br/>等待下次重试"]
RetryCount --> |否| Failed["FAILED<br/>标记失败"]
Pending --> RetryTask["ThumbnailRetryTask<br/>定时重试"]
RetryTask --> AsyncGen
```

**图表来源** 
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [ThumbnailRetryTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailRetryTask.java)
- [ImageThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/ImageThumbnailRenderer.java)
- [PdfThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/PdfThumbnailRenderer.java)
- [OfficeThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/OfficeThumbnailRenderer.java)

**章节来源**
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [ThumbnailRetryTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailRetryTask.java)
- [ImageThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/ImageThumbnailRenderer.java)
- [PdfThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/PdfThumbnailRenderer.java)
- [OfficeThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/OfficeThumbnailRenderer.java)
- [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)

### 验证环境配置（新增）
**更新** 新增 application-verify.yml 验证环境专用配置

#### 验证环境特性
- **Profile**: verify 专用环境，严禁用于生产
- **调试接口**: /api/auth/debug/token 直接签发 JWT，绕过钉钉扫码
- **权限豁免**: /api/file/thumbnail 缩略图接口无需鉴权
- **部署环境**: 内网验证环境 172.16.204.61 的 docker-compose

#### 安全护栏
- @Profile("verify") 注解确保生产环境不激活
- 启动期打印 WARN 日志留审计痕迹
- 端点在 ignore-urls 中明确放行

**章节来源**
- [application-verify.yml](file://crm-app/src/main/resources/application-verify.yml)
- [DebugTokenController.java](file://crm-auth/src/main/java/com/crm/auth/controller/DebugTokenController.java)

## 依赖关系分析
- 配置类之间低耦合，主要通过 application.yml 解耦
- 安全模块依赖 Redis（可选用于黑名单/限流）、JWT（无状态）
- 文件模块依赖 MinIO 与 Redis（分片会话、缩略图锁）
- 数据访问模块依赖 MyBatis-Plus 与数据库
- **缩略图系统依赖渲染器列表、Redis 分布式锁、MinIO 存储**

```mermaid
graph TB
SEC["安全模块"] --> REDIS["Redis"]
SEC --> JWT["JWT"]
FILE["文件模块"] --> MINIO["MinIO"]
FILE --> REDIS
DB["数据访问模块"] --> MP["MyBatis-Plus"]
MP --> MYSQL["数据库"]
THUMB["缩略图系统"] --> RENDERERS["渲染器"]
THUMB --> REDIS
THUMB --> MINIO
RENDERERS --> LIBREOFFICE["LibreOffice"]
```

**图表来源** 
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [ThumbnailGenerationTask.java](file://crm-file/src/main/java/com/crm/file/task/ThumbnailGenerationTask.java)
- [OfficeThumbnailRenderer.java](file://crm-file/src/main/java/com/crm/file/service/impl/OfficeThumbnailRenderer.java)

**章节来源**
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)

## 性能考虑
- 数据库连接池：合理设置最大连接数、空闲超时、最大生命周期
- Redis：调整连接池大小、序列化开销、缓存命中率
- MinIO：分片大小与并发上传数量平衡，避免内存峰值
- Jackson：关闭不必要的序列化特性，减少 CPU 消耗
- 日志：生产环境降低日志级别，避免 I/O 瓶颈
- 调度：避免高频任务导致资源争用
- **缩略图：合理设置 width/maxHeight 平衡清晰度与性能，调整 retryLimit 避免无限重试，优化 lockTtl 防止重复生成**

## 故障排查指南
- 数据库连接失败：检查 URL、用户名、密码、驱动、网络连通性；查看连接池报错
- Redis 连接异常：核对主机、端口、密码、防火墙；确认序列化兼容性
- MinIO 上传失败：校验端点、AccessKey/SecretKey、Bucket 权限；检查网络与代理
- JWT 鉴权失败：检查密钥一致性、过期时间、白名单配置；查看过滤器日志
- 日志过多：临时提升日志级别定位问题，恢复后回退到生产级别
- **缩略图生成失败：检查 LibreOffice 路径配置、文件格式支持、渲染器可用性；查看重试计数和失败状态**

**章节来源**
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)

## 结论
通过统一的 application.yml 与各模块配置类，本项目实现了可维护、可扩展的配置管理。**新增的缩略图配置系统提供了完整的文件预览能力，支持多种文件格式的智能生成和重试机制**。结合环境变量覆盖与合理的默认值，可在不同环境中快速部署与调优。建议在生产环境严格校验配置、限制敏感信息暴露，并结合监控告警保障稳定性。

## 附录

### 环境变量覆盖与动态配置
- 环境变量覆盖：Spring Boot 支持将 application.yml 中的 key 以大写形式映射为环境变量（例如 DATABASE_URL -> DATABASE_URL），无需修改代码即可生效
- 动态配置：若需运行时热更新，可引入 Spring Cloud Config / Nacos / Apollo 等配置中心，并通过 @RefreshScope 或监听器刷新 Bean；当前仓库未内置此类实现，可按需扩展

[本节为概念性说明，不直接分析具体文件]

### 配置模板（开发、测试、生产、验证）
以下为推荐的环境模板要点（示例，非代码片段）：
- 开发环境
  - 数据库：本地 MySQL，调试模式开启，SQL 打印
  - Redis：本地或开发集群，连接池较小
  - MinIO：本地 MinIO，Bucket 自动创建
  - JWT：短过期时间，宽松白名单
  - 缩略图：LibreOffice 本地安装，宽度和高度适中
  - 日志：DEBUG
- 测试环境
  - 数据库：独立测试库，隔离数据
  - Redis：测试集群，禁用持久化
  - MinIO：测试桶，预置样例文件
  - JWT：中等过期时间，严格白名单
  - 缩略图：LibreOffice 容器化部署，优化转换超时
  - 日志：INFO
- 生产环境
  - 数据库：高可用集群，连接池优化，慢查询日志
  - Redis：生产集群，连接池与序列化优化
  - MinIO：生产桶，CDN 加速，访问审计
  - JWT：长过期时间+刷新机制，强校验
  - 缩略图：LibreOffice 集群部署，合理配置重试和超时
  - 日志：WARN/ERROR，集中采集
- **验证环境**
  - Profile：verify 专用环境
  - 调试接口：启用 /api/auth/debug/token
  - 权限豁免：缩略图接口无需鉴权
  - 部署：docker-compose 一键部署
  - 安全：仅限内网验证环境使用

[本节为概念性说明，不直接分析具体文件]

### 配置验证规则
- 必填项校验：数据库 URL、用户名、密码；MinIO 端点、密钥、Bucket；JWT 密钥
- 类型校验：端口为整数、超时时间为正数、布尔开关合法
- 范围校验：连接池大小、分片大小、过期时间区间
- **缩略图校验：width/maxHeight 为正数、retryLimit ≥ 1、lockTtl > officeConvertTimeout**
- 建议：在启动阶段进行配置校验，失败则快速失败并给出明确错误信息

[本节为概念性说明，不直接分析具体文件]

### 配置热更新机制（扩展建议）
- 引入配置中心：Nacos/Apollo/Spring Cloud Config
- 使用 @RefreshScope 刷新 Bean 或监听配置变更事件
- 对敏感配置（密钥）采用加密存储与动态轮换
- **缩略图配置热更新：支持运行时调整生成参数和重试策略**

[本节为概念性说明，不直接分析具体文件]

### 最佳实践
- 分离敏感配置：使用环境变量或密钥管理服务
- 最小权限原则：数据库、Redis、MinIO 账号仅授予必要权限
- 版本化管理：配置文件纳入版本控制，变更留痕
- 监控与告警：连接失败、超时、鉴权失败等指标接入监控
- 灰度发布：先小流量验证配置变更效果
- **缩略图最佳实践：根据业务需求调整尺寸和格式，合理配置重试策略，监控 LibreOffice 资源使用情况**

[本节为概念性说明，不直接分析具体文件]

### 缩略图配置详解
**更新** 详细的缩略图配置项说明：

#### 基本配置项
- `crm.file.thumbnail.width`: 缩略图宽度（像素），默认 200
- `crm.file.thumbnail.maxHeight`: 最大高度（像素），默认 400  
- `crm.file.thumbnail.format`: 输出格式，支持 jpeg/png，默认 jpeg
- `crm.file.thumbnail.syncWaitTimeout`: 同步等待超时，默认 10秒

#### 重试策略配置
- `crm.file.thumbnail.retryLimit`: 最大重试次数，默认 3
- `crm.file.thumbnail.retryCron`: 重试任务 cron 表达式，默认 "0 0 4 * * ?"
- `crm.file.thumbnail.lockTtl`: 分布式锁 TTL，默认 150秒

#### LibreOffice 配置
- `crm.file.thumbnail.libreofficePath`: LibreOffice 路径，默认 soffice
- `crm.file.thumbnail.officeConvertTimeout`: 转换超时，默认 120秒

**章节来源**
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

### 验证环境配置详解
**更新** 验证环境专用配置说明：

#### 环境特性
- 激活方式：SPRING_PROFILES_ACTIVE=verify
- 调试接口：/api/auth/debug/token 直接签发 JWT
- 权限豁免：/api/file/thumbnail 无需鉴权
- 安全警告：启动期打印 WARN 日志

#### 部署说明
- 目标环境：172.16.204.61 内网验证环境
- 部署方式：docker-compose 一键部署
- 数据安全：验证完毕后可清理容器和数据卷

**章节来源**
- [application-verify.yml](file://crm-app/src/main/resources/application-verify.yml)
- [DebugTokenController.java](file://crm-auth/src/main/java/com/crm/auth/controller/DebugTokenController.java)