28 KiB

Raw Blame History

配置指南

**本文引用的文件** - [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)

更新摘要

变更内容

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

简介

本指南面向运维与开发人员，提供 CRM 后端项目的完整配置说明。内容覆盖：

所有关键配置项的含义、默认值、环境变量覆盖方式
动态配置更新机制（如适用）
数据库连接、Redis 缓存、MinIO 文件存储、JWT 安全、日志级别等核心配置
新增：缩略图生成配置（尺寸、格式、重试策略、LibreOffice路径）
新增：验证环境专用配置（调试接口、权限豁免）
不同环境的配置模板（开发、测试、生产、验证）
配置验证规则、热更新机制、最佳实践、性能调优参数与故障排查

项目结构

本项目采用多模块 Maven 工程，按功能划分模块：

crm-app：应用启动入口与全局应用配置
crm-auth：认证授权与安全相关配置
crm-base：公共基础配置（Redis、Jackson、MyBatis-Plus、跨域、接口文档等）
crm-file：文件服务（MinIO、分片上传、缩略图生成、定时清理任务）

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
AuthApplication.java
FileProperties.java

章节来源

CrmAppApplication.java
AuthApplication.java

核心组件

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

章节来源

application.yml
application-verify.yml
FileProperties.java
ThumbnailGenerationTask.java
ThumbnailRetryTask.java

架构总览

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

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
application-verify.yml
FileProperties.java
ThumbnailGenerationTask.java
OfficeThumbnailRenderer.java

详细组件分析

应用与模块入口

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

章节来源

CrmAppApplication.java
AuthApplication.java
application-verify.yml

数据库连接配置（MyBatis-Plus）

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

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

图表来源

MybatisPlusConfig.java
MetaObjectFillHandler.java
CustomIdGenerator.java
InsertBatchOnDuplicateKeyUpdate.java

章节来源

application.yml
application.yml
MybatisPlusConfig.java
MetaObjectFillHandler.java
CustomIdGenerator.java
InsertBatchOnDuplicateKeyUpdate.java

Redis 缓存配置

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

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

图表来源

RedisConfig.java
FileProperties.java
ThumbnailGenerationTask.java

章节来源

application.yml
application.yml
RedisConfig.java

MinIO 文件存储配置

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

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
MinioConfig.java
FileConstants.java

章节来源

application.yml
application.yml
FileProperties.java
MinioConfig.java

JWT 安全配置

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

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
JwtAuthenticationFilter.java
TokenService.java
AuthProperties.java
application-verify.yml

章节来源

application.yml
application-verify.yml
SecurityConfig.java
JwtAuthenticationFilter.java
TokenService.java
AuthProperties.java

日志级别配置

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

章节来源

application.yml
application.yml

其他基础配置

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

章节来源

JacksonConfig.java
CorsConfig.java
Knife4jConfig.java
SchedulingConfig.java
ScheduledTaskProperties.java
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秒

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
ThumbnailGenerationTask.java
ThumbnailRetryTask.java
ImageThumbnailRenderer.java
PdfThumbnailRenderer.java
OfficeThumbnailRenderer.java

章节来源

FileProperties.java
ThumbnailGenerationTask.java
ThumbnailRetryTask.java
ImageThumbnailRenderer.java
PdfThumbnailRenderer.java
OfficeThumbnailRenderer.java
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
DebugTokenController.java

依赖关系分析

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

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
JwtAuthenticationFilter.java
TokenService.java
MinioConfig.java
RedisConfig.java
MybatisPlusConfig.java
ThumbnailGenerationTask.java
OfficeThumbnailRenderer.java

章节来源

application.yml
application.yml

性能考虑

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

故障排查指南

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

章节来源

application.yml
application.yml
JwtAuthenticationFilter.java
TokenService.java
RedisConfig.java
MinioConfig.java
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
application.yml

验证环境配置详解

更新验证环境专用配置说明：

环境特性

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

部署说明

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

章节来源

application-verify.yml
DebugTokenController.java

28 KiB Raw Blame History

配置指南

更新摘要

目录

简介

项目结构

核心组件

架构总览

详细组件分析

应用与模块入口

数据库连接配置（MyBatis-Plus）

Redis 缓存配置

MinIO 文件存储配置

JWT 安全配置

日志级别配置

其他基础配置

缩略图配置系统（新增）

缩略图基本配置

缩略图重试策略

LibreOffice 配置

验证环境配置（新增）

验证环境特性

安全护栏

依赖关系分析

性能考虑

故障排查指南

结论

附录

环境变量覆盖与动态配置

配置模板（开发、测试、生产、验证）

配置验证规则

配置热更新机制（扩展建议）

最佳实践

缩略图配置详解

基本配置项

重试策略配置

LibreOffice 配置

验证环境配置详解

环境特性

部署说明

28 KiB

Raw Blame History