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
401 MiB
Tree: f0f70c6137
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'f0f70c6137'
${ noResults }
crm-backend-matt/.qoder/repowiki/zh/content/部署指南.md

462 lines
20 KiB
Raw Normal View History

first-commit
1 month ago
# 部署指南
<cite>
**本文引用的文件**
- [pom.xml](file://pom.xml)
- [crm-app/pom.xml](file://crm-app/pom.xml)
- [crm-auth/pom.xml](file://crm-auth/pom.xml)
- [crm-base/pom.xml](file://crm-base/pom.xml)
- [crm-file/pom.xml](file://crm-file/pom.xml)
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/java/com/crm/auth/AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java](file://crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java)
- [crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [crm-auth/src/main/java/com/crm/auth/security/TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [crm-base/src/main/java/com/crm/base/config/CorsConfig.java](file://crm-base/src/main/java/com/crm/base/config/CorsConfig.java)
- [crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能与容量规划](#性能与容量规划)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本指南面向运维与交付团队，提供CRM后端系统的完整部署与运维手册。内容覆盖：
- 环境准备与依赖服务安装（MySQL、Redis、MinIO）
- 多模块构建与打包
- Docker容器化部署
- Kubernetes集群部署
- 传统服务器部署
- 配置文件管理、数据库初始化与服务启动顺序
- 生产优化、监控告警、日志收集
- 备份恢复策略
- 负载均衡、SSL证书与域名绑定
目标：确保系统在生产环境中稳定、可靠、可观测、可回滚地运行。
## 项目结构
本项目为多模块Spring Boot应用，包含以下关键模块：
- crm-base：公共基础能力（安全、数据访问、通用配置等）
- crm-auth：认证授权与权限控制
- crm-file：文件服务（上传、分片、预览、清理任务）
- crm-app：应用入口与聚合配置
```mermaid
graph TB
subgraph "应用模块"
APP["crm-app<br/>应用入口"]
AUTH["crm-auth<br/>认证与权限"]
FILE["crm-file<br/>文件服务"]
BASE["crm-base<br/>公共基础"]
end
subgraph "外部依赖"
DB["MySQL"]
REDIS["Redis"]
MINIO["MinIO 对象存储"]
end
APP --> AUTH
APP --> FILE
AUTH --> BASE
FILE --> BASE
AUTH --> DB
AUTH --> REDIS
FILE --> DB
FILE --> REDIS
FILE --> MINIO
```
图表来源
- [pom.xml:1-200](file://pom.xml#L1-L200)
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java:1-50](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java#L1-L50)
- [crm-auth/src/main/java/com/crm/auth/AuthApplication.java:1-50](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java#L1-L50)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java:1-80](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java#L1-L80)
章节来源
- [pom.xml:1-200](file://pom.xml#L1-L200)
- [crm-app/pom.xml:1-100](file://crm-app/pom.xml#L1-L100)
- [crm-auth/pom.xml:1-100](file://crm-auth/pom.xml#L1-L100)
- [crm-base/pom.xml:1-100](file://crm-base/pom.xml#L1-L100)
- [crm-file/pom.xml:1-100](file://crm-file/pom.xml#L1-L100)
## 核心组件
- 应用入口与装配
- crm-app：聚合配置与统一入口
- crm-auth：认证、鉴权、JWT、第三方登录集成
- crm-file：文件上传、分片、预览、孤儿分片清理任务
- 基础设施
- MySQL：持久化用户、角色、菜单、部门、文件信息等
- Redis：会话、缓存、分布式锁、限流等
- MinIO：对象存储，用于文件与附件存储
章节来源
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java:1-50](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java#L1-L50)
- [crm-auth/src/main/java/com/crm/auth/AuthApplication.java:1-50](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java#L1-L50)
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java:1-80](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java#L1-L80)
- [crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java:1-80](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java#L1-L80)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java:1-80](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java#L1-L80)
## 架构总览
下图展示典型部署拓扑：前端通过网关/反向代理接入，后端由多个服务实例组成，共享MySQL、Redis与MinIO。
```mermaid
graph TB
Client["客户端/浏览器"] --> Gateway["Nginx/网关"]
Gateway --> AuthSrv["crm-auth 实例 x N"]
Gateway --> FileSrv["crm-file 实例 x M"]
AuthSrv --> DB["MySQL"]
AuthSrv --> Cache["Redis"]
FileSrv --> DB
FileSrv --> Cache
FileSrv --> OSS["MinIO"]
```
图表来源
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java:1-120](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java#L1-L120)
- [crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java:1-120](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java#L1-L120)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java:1-80](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java#L1-L80)
## 详细组件分析
### 认证与权限（crm-auth）
- 功能要点
- JWT签发与校验、过滤器链、异常处理
- 数据权限拦截器与表级过滤
- 第三方登录（如钉钉）客户端与工厂
- 初始数据加载（角色、菜单、默认用户等）
- 关键类与职责
- SecurityConfig：安全配置、跨域、接口文档开关
- JwtAuthenticationFilter：请求鉴权、令牌解析
- TokenService：令牌生成、刷新、校验
- DataInitializer：启动时初始化基础数据
- 启动顺序建议
- 先完成数据库与Redis连接
- 执行DataInitializer进行基础数据初始化
- 再暴露HTTP端口对外提供服务
```mermaid
sequenceDiagram
participant C as "客户端"
participant G as "网关/Nginx"
participant A as "Auth服务"
participant F as "Jwt过滤器"
participant S as "Token服务"
participant R as "Redis"
participant D as "MySQL"
C->>G : "HTTP 请求"
G->>A : "转发到认证服务"
A->>F : "进入鉴权过滤器"
F->>S : "解析并校验JWT"
S->>R : "读取/校验会话或黑名单"
S-->>F : "返回鉴权结果"
F-->>A : "放行或拒绝"
A->>D : "业务查询(可选)"
A-->>C : "响应"
```
图表来源
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java:1-120](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java#L1-L120)
- [crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java:1-120](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java#L1-L120)
- [crm-auth/src/main/java/com/crm/auth/security/TokenService.java:1-120](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java#L1-L120)
- [crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java:1-120](file://crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java#L1-L120)
章节来源
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java:1-120](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java#L1-L120)
- [crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java:1-120](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java#L1-L120)
- [crm-auth/src/main/java/com/crm/auth/security/TokenService.java:1-120](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java#L1-L120)
- [crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java:1-120](file://crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java#L1-L120)
### 文件服务（crm-file）
- 功能要点
- 文件上传（支持分片）、下载、预览
- MinIO对象存储集成
- 定时任务清理孤儿分片
- 关键类与职责
- FileProperties：文件相关配置项
- MinioConfig：MinIO客户端配置
- OrphanChunkCleanupTask：定时清理未完成的分片
- 依赖
- MySQL：文件元数据
- Redis：分片会话、临时状态
- MinIO：实际文件存储
```mermaid
flowchart TD
Start(["开始"]) --> Upload["接收上传请求"]
Upload --> CheckSession{"是否存在分片会话?"}
CheckSession --> |否| Init["创建分片会话"]
CheckSession --> |是| Append["追加分片"]
Init --> Append
Append --> Complete{"是否全部分片完成?"}
Complete --> |否| Wait["等待后续分片"]
Complete --> |是| Merge["合并分片成文件"]
Merge --> SaveMeta["保存文件元数据到DB"]
SaveMeta --> Done(["结束"])
Wait --> Done
```
图表来源
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java:1-80](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java#L1-L80)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java:1-80](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java#L1-L80)
- [crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java:1-80](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java#L1-L80)
章节来源
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java:1-80](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java#L1-L80)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java:1-80](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java#L1-L80)
- [crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java:1-80](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java#L1-L80)
### 公共基础（crm-base）
- 关键配置
- RedisConfig：Redis连接池、序列化、超时等
- MybatisPlusConfig：分页、SQL注入器、填充策略
- SnowflakeProperties：分布式ID配置
- CorsConfig：跨域配置
- Knife4jConfig：API文档开关与路径
- 作用
- 为各业务模块提供统一的配置、工具与安全能力
章节来源
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java:1-80](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java#L1-L80)
- [crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java:1-80](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java#L1-L80)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java:1-80](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java#L1-L80)
- [crm-base/src/main/java/com/crm/base/config/CorsConfig.java:1-80](file://crm-base/src/main/java/com/crm/base/config/CorsConfig.java#L1-L80)
- [crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java:1-80](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java#L1-L80)
## 依赖关系分析
- 模块内聚与耦合
- crm-base为底层依赖，被其他模块复用
- crm-auth与crm-file均依赖crm-base提供的安全、数据访问与工具
- 外部依赖
- MySQL：所有持久化数据
- Redis：缓存、会话、分布式锁
- MinIO：文件对象存储
- 启动顺序
- 数据库与中间件就绪 → 应用启动 → 数据初始化 → 暴露端口
```mermaid
graph LR
BASE["crm-base"] --> AUTH["crm-auth"]
BASE --> FILE["crm-file"]
AUTH --> APP["crm-app"]
FILE --> APP
AUTH --> DB["MySQL"]
AUTH --> REDIS["Redis"]
FILE --> DB
FILE --> REDIS
FILE --> MINIO["MinIO"]
```
图表来源
- [pom.xml:1-200](file://pom.xml#L1-L200)
- [crm-app/pom.xml:1-100](file://crm-app/pom.xml#L1-L100)
- [crm-auth/pom.xml:1-100](file://crm-auth/pom.xml#L1-L100)
- [crm-base/pom.xml:1-100](file://crm-base/pom.xml#L1-L100)
- [crm-file/pom.xml:1-100](file://crm-file/pom.xml#L1-L100)
章节来源
- [pom.xml:1-200](file://pom.xml#L1-L200)
## 性能与容量规划
- JVM与运行时
- 根据实例规格设置堆大小、GC策略；启用JIT预热
- 合理设置线程池、连接池参数（数据库、Redis、HTTP客户端）
- 数据库
- 连接池上限、慢查询阈值、索引优化
- 读写分离与分库分表预留
- 缓存
- Redis内存上限、淘汰策略、热点Key保护
- 文件服务
- MinIO节点数与磁盘容量规划
- 分片大小与并发上传限制
- 水平扩展
- 无状态服务多副本部署
- 会话与缓存一致性保障
[本节为通用指导，不直接引用具体文件]
## 故障排查指南
- 常见问题定位
- 认证失败：检查JWT密钥、Redis连通性、过滤器链配置
- 文件上传失败：检查MinIO连通性、分片会话、磁盘空间
- 数据库连接异常：检查连接池、账号权限、网络ACL
- 日志与指标
- 应用日志：按模块与TraceId聚合
- 中间件日志：MySQL慢查询、Redis命中率、MinIO访问日志
- 指标采集：JVM、GC、连接池、QPS、延迟
- 快速恢复
- 健康检查与自动重启
- 灰度发布与快速回滚
- 数据快照与增量备份
章节来源
- [crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java:1-120](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java#L1-L120)
- [crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java:1-80](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java#L1-L80)
## 结论
通过模块化设计与清晰的依赖边界，结合容器化与Kubernetes编排，可实现高可用、易扩展的CRM后端部署。配合完善的监控、日志与备份策略，能够保障生产环境的稳定性与可恢复性。
[本节为总结性内容，不直接引用具体文件]
## 附录
### 一、环境准备与依赖服务安装
- 操作系统与运行时
- Linux发行版（推荐CentOS/RHEL/Ubuntu LTS）
- JDK版本与版本锁定（参考构建脚本与依赖声明）
- 依赖服务
- MySQL：创建数据库与字符集、用户与权限
- Redis：设置密码、最大内存、持久化策略
- MinIO：创建桶、访问密钥、网络可达性
章节来源
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java:1-80](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java#L1-L80)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java:1-80](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java#L1-L80)
### 二、构建与打包
- Maven多模块构建
- 在根目录执行构建命令，生成各模块JAR包
- 产物位置与命名规则
- 构建优化
- 并行构建、跳过测试、依赖缓存
章节来源
- [pom.xml:1-200](file://pom.xml#L1-L200)
- [crm-app/pom.xml:1-100](file://crm-app/pom.xml#L1-L100)
- [crm-auth/pom.xml:1-100](file://crm-auth/pom.xml#L1-L100)
- [crm-base/pom.xml:1-100](file://crm-base/pom.xml#L1-L100)
- [crm-file/pom.xml:1-100](file://crm-file/pom.xml#L1-L100)
### 三、配置文件管理
- 配置分层
- 应用级application.yml
- 环境级配置（dev/test/prod）
- 外部化配置（环境变量、配置中心）
- 关键配置项
- 数据库连接、Redis连接、MinIO端点与凭据
- JWT密钥、跨域、接口文档开关
- 文件分片大小、超时、重试策略
章节来源
- [crm-app/src/main/resources/application.yml:1-200](file://crm-app/src/main/resources/application.yml#L1-L200)
- [crm-auth/src/main/resources/application.yml:1-200](file://crm-auth/src/main/resources/application.yml#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java:1-120](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java#L1-L120)
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java:1-80](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java#L1-L80)
### 四、数据库初始化与服务启动顺序
- 初始化步骤
- 建库建表、导入基础数据
- 执行DataInitializer中的初始化逻辑
- 启动顺序
- 先启动依赖服务（MySQL、Redis、MinIO）
- 再启动crm-auth与crm-file
- 最后启动crm-app（若作为聚合入口）
章节来源
- [crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java:1-120](file://crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java#L1-L120)
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java:1-50](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java#L1-L50)
- [crm-auth/src/main/java/com/crm/auth/AuthApplication.java:1-50](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java#L1-L50)
### 五、Docker容器化部署
- 镜像构建
- 使用多阶段构建减小镜像体积
- 将JAR包与外部配置分离
- 容器编排
- 定义环境变量、挂载卷（日志、配置）
- 健康检查与资源限制
- 示例流程
- 构建镜像 → 推送仓库 → 拉取运行 → 验证健康
[本节为通用指导，不直接引用具体文件]
### 六、Kubernetes集群部署
- 部署清单
- Deployment：副本数、滚动更新、探针
- Service：ClusterIP/NodePort/LoadBalancer
- ConfigMap/Secret：配置与敏感信息
- Ingress：域名、TLS、路由
- 扩缩容与弹性
- HPA基于CPU/内存或自定义指标
- 存储与持久化
- 日志落盘与远端收集
- 文件服务对接MinIO PVC或外部存储
[本节为通用指导，不直接引用具体文件]
### 七、传统服务器部署
- 进程管理
- 使用systemd或supervisor管理服务生命周期
- 启动脚本
- 设置JVM参数、环境变量、工作目录
- 日志轮转
- logrotate配置，保留策略与压缩
[本节为通用指导，不直接引用具体文件]
### 八、生产环境优化配置
- JVM调优
- 堆大小、GC选择、元空间、线程栈大小
- 连接池与线程池
- 数据库连接池、Redis连接池、HTTP客户端线程池
- 缓存与限流
- Redis缓存策略、热点Key保护、接口限流
- 文件服务优化
- MinIO节点横向扩展、分片大小与并发限制
[本节为通用指导，不直接引用具体文件]
### 九、监控告警设置
- 指标采集
- JVM、GC、线程、连接池、QPS、延迟
- 中间件指标（MySQL、Redis、MinIO）
- 告警规则
- 错误率、延迟P99、资源水位、磁盘空间
- 可视化
- 仪表盘与告警通知渠道
[本节为通用指导，不直接引用具体文件]
### 十、日志收集方案
- 应用日志
- 结构化输出、TraceId贯穿、分级输出
- 集中式收集
- Filebeat/Fluent Bit采集 → Kafka/消息队列 → 存储与检索
- 日志策略
- 保留周期、脱敏、采样与压缩
[本节为通用指导，不直接引用具体文件]
### 十一、备份恢复策略
- 数据库备份
- 全量+增量、异地备份、加密与校验
- 文件备份
- MinIO快照、跨地域复制
- 恢复演练
- 定期演练恢复流程，验证RTO/RPO
[本节为通用指导，不直接引用具体文件]
### 十二、负载均衡、SSL证书与域名绑定
- 负载均衡
- Nginx/Ingress分发、健康检查、权重与灰度
- SSL证书
- 证书申请、自动续期、HTTPS强制
- 域名绑定
- DNS解析、CDN加速、WAF防护
[本节为通用指导，不直接引用具体文件]