# 部署指南

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

[本节为通用指导，不直接引用具体文件]