luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
17 Commits
1 Branch
0 Tags
403 MiB
Tree: f0f70c6137
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'f0f70c6137'
${ noResults }
crm-backend-matt/.qoder/repowiki/zh/content/配置指南/配置指南.md

392 lines
20 KiB
Raw Normal View History

first-commit
1 month ago
# 配置指南
<cite>
**本文引用的文件**
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.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)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本指南面向运维与开发人员，提供 CRM 后端项目的完整配置说明。内容覆盖：
- 所有关键配置项的含义、默认值、环境变量覆盖方式
- 动态配置更新机制（如适用）
- 数据库连接、Redis 缓存、MinIO 文件存储、JWT 安全、日志级别等核心配置
- 不同环境的配置模板（开发、测试、生产）
- 配置验证规则、热更新机制、最佳实践、性能调优参数与故障排查
## 项目结构
本项目采用多模块 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/>通用配置与工具"]
end
APP --> AUTH
APP --> FILE
AUTH --> BASE
FILE --> BASE
```
**图表来源**
- [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)
**章节来源**
- [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.yml](file://crm-auth/src/main/resources/application.yml)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.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)
- [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)
- [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)
- [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)
## 架构总览
下图展示了配置加载与运行时依赖关系：应用启动时读取 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 --> 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)"]
```
**图表来源**
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)
- [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java)
- [FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.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)
- [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)
- [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.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)
### 数据库连接配置（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 的一致性
```mermaid
classDiagram
class RedisConfig {
+createRedisTemplate()
+configureSerializer()
}
class FileProperties {
+redis相关字段
}
RedisConfig <.. FileProperties : "使用Redis进行会话/缓存"
```
**图表来源**
- [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)
**章节来源**
- [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 初始化客户端
```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 : 返回可用客户端
```
**图表来源**
- [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)
**章节来源**
- [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 : 放行或拒绝
```
**图表来源**
- [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](file://crm-auth/src/main/resources/application.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)
## 依赖关系分析
- 配置类之间低耦合，主要通过 application.yml 解耦
- 安全模块依赖 Redis（可选用于黑名单/限流）、JWT（无状态）
- 文件模块依赖 MinIO 与 Redis（分片会话）
- 数据访问模块依赖 MyBatis-Plus 与数据库
```mermaid
graph TB
SEC["安全模块"] --> REDIS["Redis"]
SEC --> JWT["JWT"]
FILE["文件模块"] --> MINIO["MinIO"]
FILE --> REDIS
DB["数据访问模块"] --> MP["MyBatis-Plus"]
MP --> MYSQL["数据库"]
```
**图表来源**
- [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)
**章节来源**
- [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 瓶颈
- 调度：避免高频任务导致资源争用
[本节为通用指导，不直接分析具体文件]
## 故障排查指南
- 数据库连接失败：检查 URL、用户名、密码、驱动、网络连通性；查看连接池报错
- Redis 连接异常：核对主机、端口、密码、防火墙；确认序列化兼容性
- MinIO 上传失败：校验端点、AccessKey/SecretKey、Bucket 权限；检查网络与代理
- JWT 鉴权失败：检查密钥一致性、过期时间、白名单配置；查看过滤器日志
- 日志过多：临时提升日志级别定位问题，恢复后回退到生产级别
**章节来源**
- [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)
## 结论
通过统一的 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：短过期时间，宽松白名单
- 日志：DEBUG
- 测试环境
- 数据库：独立测试库，隔离数据
- Redis：测试集群，禁用持久化
- MinIO：测试桶，预置样例文件
- JWT：中等过期时间，严格白名单
- 日志：INFO
- 生产环境
- 数据库：高可用集群，连接池优化，慢查询日志
- Redis：生产集群，连接池与序列化优化
- MinIO：生产桶，CDN 加速，访问审计
- JWT：长过期时间+刷新机制，强校验
- 日志：WARN/ERROR，集中采集
[本节为概念性说明，不直接分析具体文件]
### 配置验证规则
- 必填项校验：数据库 URL、用户名、密码；MinIO 端点、密钥、Bucket；JWT 密钥
- 类型校验：端口为整数、超时时间为正数、布尔开关合法
- 范围校验：连接池大小、分片大小、过期时间区间
- 建议：在启动阶段进行配置校验，失败则快速失败并给出明确错误信息
[本节为概念性说明，不直接分析具体文件]
### 配置热更新机制（扩展建议）
- 引入配置中心：Nacos/Apollo/Spring Cloud Config
- 使用 @RefreshScope 刷新 Bean 或监听配置变更事件
- 对敏感配置（密钥）采用加密存储与动态轮换
[本节为概念性说明，不直接分析具体文件]
### 最佳实践
- 分离敏感配置：使用环境变量或密钥管理服务
- 最小权限原则：数据库、Redis、MinIO 账号仅授予必要权限
- 版本化管理：配置文件纳入版本控制，变更留痕
- 监控与告警：连接失败、超时、鉴权失败等指标接入监控
- 灰度发布：先小流量验证配置变更效果
[本节为概念性说明，不直接分析具体文件]