deploy-ease-platform/backend/README.md
dengqichen 329cb955d8 1
2025-10-21 16:25:51 +08:00

661 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Deploy Ease Platform
Deploy Ease Platform 是一个基于Spring Boot 3.x和Flowable 7.x的现代化部署管理平台提供工作流驱动的自动化部署解决方案。
## 技术栈
### 后端
- **Java 21** + **Spring Boot 3.2.0**
- **Spring Security 6.2.0** + JWT认证
- **Spring Data JPA** + Hibernate
- **Flowable 7.2.0** - 工作流引擎
- **MySQL 8.0+** + Flyway数据库版本控制
- **MapStruct 1.5.5** - 对象映射
- **QueryDSL 5.0.0** - 类型安全查询
- **OpenAPI/Swagger** - API文档
- **Lombok** - 代码简化
- **Hutool** - 工具类库
### 构建工具
- **Maven 3.8+**
## 核心功能模块
### ✅ 1. 系统管理(已完成)
#### 1.1 用户管理
- [x] 用户注册和登录
- [x] JWT Token认证
- [x] 密码重置
- [x] 用户信息维护
- [x] 用户状态管理(启用/禁用)
- [x] 部门分配
- [x] 基础CRUD操作分页查询、创建、更新、删除
**主要接口:**
```
POST /api/v1/user/login - 用户登录
GET /api/v1/user/current - 获取当前用户信息
POST /api/v1/user/{id}/reset-password - 重置密码
PUT /api/v1/user/{id}/department - 分配部门
```
#### 1.2 角色管理
- [x] 角色创建与维护
- [x] 角色标签管理
- [x] 角色权限分配
- [x] 用户角色分配
- [x] 角色权限查询
**主要接口:**
```
POST /api/v1/role - 创建角色
POST /api/v1/role/{id}/tags - 分配标签
POST /api/v1/role/{userId}/assignRoles - 分配角色
GET /api/v1/role/{id}/permissions - 获取角色权限
POST /api/v1/role/{id}/permissions - 分配权限
```
#### 1.3 权限管理
- [x] 权限创建与维护
- [x] 权限分类管理(菜单权限、按钮权限)
- [x] 权限与菜单关联
- [x] 基于权限的访问控制
#### 1.4 菜单管理
- [x] 菜单树维护
- [x] 菜单排序
- [x] 菜单显示控制
- [x] 动态菜单加载
- [x] 菜单权限配置
- [x] 权限树查询
**主要接口:**
```
GET /api/v1/menu/current - 获取当前用户菜单
GET /api/v1/menu/tree - 获取菜单树
GET /api/v1/menu/permission-tree - 获取权限树
```
#### 1.5 部门管理
- [x] 部门树形结构维护
- [x] 部门编码管理
- [x] 部门负责人设置
- [x] 部门人员管理
- [x] 部门排序
#### 1.6 租户管理
- [x] 多租户支持
- [x] 租户信息管理
- [x] 租户状态控制
**实体统计:** 9个核心实体
- User用户
- Role角色
- RoleTag角色标签
- Permission权限
- PermissionTemplate权限模板
- Menu菜单
- Department部门
- Tenant租户
- SysParam系统参数
---
### ✅ 2. 外部系统集成(已完成)
#### 2.1 外部系统管理
- [x] 外部系统统一管理Jenkins、Git等
- [x] 多种认证方式支持
- 用户名密码认证
- Token认证
- SSH密钥认证
- [x] 连接测试
- [x] 同步状态追踪
**主要接口:**
```
POST /api/v1/external-system - 创建外部系统
GET /api/v1/external-system/{id}/test-connection - 测试连接
POST /api/v1/external-system/{id}/sync - 同步数据
GET /api/v1/external-system/{id}/status - 获取同步状态
```
#### 2.2 Jenkins集成
- [x] Jenkins实例管理
- [x] 视图(View)同步
- [x] 任务(Job)同步
- [x] 构建(Build)信息同步
- [x] 构建历史记录
- [x] 同步历史追踪
**主要接口:**
```
POST /api/v1/jenkins-manager/{externalSystemId}/sync-all - 同步所有数据
POST /api/v1/jenkins-manager/{externalSystemId}/sync-views - 同步视图
POST /api/v1/jenkins-manager/{externalSystemId}/sync-jobs - 同步任务
POST /api/v1/jenkins-manager/{externalSystemId}/sync-builds - 同步构建
GET /api/v1/jenkins-manager/{externalSystemId}/instance - 获取实例信息
```
**相关实体:**
- JenkinsViewJenkins视图
- JenkinsJobJenkins任务
- JenkinsBuildJenkins构建
- JenkinsSyncHistory同步历史
#### 2.3 Git仓库集成
- [x] Git仓库组(Group)管理
- [x] Git项目(Project)管理
- [x] Git分支(Branch)管理
- [x] 多级同步(组 → 项目 → 分支)
- [x] 同步历史记录
**主要接口:**
```
POST /api/v1/repository-manager/{externalSystemId}/sync-groups - 同步仓库组
POST /api/v1/repository-manager/{externalSystemId}/groups/sync-projects - 同步项目
POST /api/v1/repository-manager/{externalSystemId}/projects/sync-branches - 同步分支
GET /api/v1/repository-manager/{externalSystemId}/instance - 获取实例信息
```
**相关实体:**
- RepositoryGroup仓库组
- RepositoryProject仓库项目
- RepositoryBranch仓库分支
- RepositorySyncHistory同步历史
---
### ✅ 3. 部署管理(已完成)
#### 3.1 应用管理
- [x] 应用创建与维护
- [x] 应用编码管理
- [x] 开发语言类型支持Java、Python、Node.js等
- [x] 应用与仓库关联
- [x] 应用分组管理
**主要接口:**
```
POST /api/v1/applications - 创建应用
GET /api/v1/applications/development-languages - 获取开发语言列表
```
**相关实体:**
- Application应用
- ProjectGroup项目组
#### 3.2 环境管理
- [x] 环境配置管理(开发、测试、生产等)
- [x] 环境编码管理
- [x] 构建类型配置Jenkins、GitLab Runner、GitHub Action
- [x] 部署方式配置K8S、Docker、VM
- [x] 项目组与环境关联
**相关实体:**
- Environment环境
#### 3.3 部署配置
- [x] 应用部署配置管理
- [x] 构建配置Schema定义
- [x] 部署操作
- [x] 部署日志记录
**主要接口:**
```
POST /api/v1/deploy-app-config - 创建部署配置
GET /api/v1/deploy-app-config/defined - 获取构建类型Schema
POST /api/v1/deploy-app-config/deploy - 执行部署
```
**相关实体:**
- DeployAppConfig部署配置
- DeployLog部署日志
---
### ✅ 4. 工作流引擎已完成基于Flowable
#### 4.1 工作流定义
- [x] 工作流设计和保存
- [x] 工作流发布管理
- [x] 工作流启用/禁用
- [x] 工作流状态管理(草稿、已发布、已禁用)
- [x] 图形化配置GraphJSON
- [x] BPMN XML自动生成
- [x] 工作流分类管理
**主要接口:**
```
POST /api/v1/workflow/definition/design - 保存工作流设计
GET /api/v1/workflow/definition/published - 查询已发布工作流
POST /api/v1/workflow/definition/{id}/published - 发布工作流
POST /api/v1/workflow/definition/{id}/disable - 禁用工作流
POST /api/v1/workflow/definition/{id}/enable - 启用工作流
GET /api/v1/workflow/definition/categories - 获取工作流分类
```
#### 4.2 工作流实例
- [x] 工作流实例启动
- [x] 工作流实例挂起
- [x] 工作流实例恢复
- [x] 工作流执行状态查询
- [x] 历史实例查询
- [x] 实例与模板关联查询
**主要接口:**
```
POST /api/v1/workflow/instance/start - 启动工作流
GET /api/v1/workflow/instance/templates-with-instances - 查询模板及实例
GET /api/v1/workflow/instance/historical-instances - 查询历史实例
POST /api/v1/workflow/definition/{processInstanceId}/suspend - 挂起实例
POST /api/v1/workflow/definition/{processInstanceId}/resume - 恢复实例
```
#### 4.3 节点定义与执行
- [x] 节点类型管理
- [x] 节点配置Schema
- [x] 节点实例状态追踪
- [x] 节点重试机制
- [x] 节点跳过机制
**主要接口:**
```
POST /api/v1/workflow/node-instance/{id}/retry - 重试节点
POST /api/v1/workflow/node-instance/{id}/skip - 跳过节点
```
#### 4.4 节点类型实现Delegate
- [x] **ShellNodeDelegate** - Shell脚本执行
- [x] **DeployNodeDelegate** - 部署节点执行
- [x] **ApprovalNodeDelegate** - 审批节点
- [x] **NotificationNodeDelegate** - 通知节点
- [x] **BaseNodeDelegate** - 基础节点抽象
#### 4.5 工作流日志
- [x] 实时日志记录
- [x] 节点级日志
- [x] 日志查询
**相关实体:**
- WorkflowDefinition工作流定义
- WorkflowNodeDefinition节点定义
- WorkflowInstance工作流实例
- WorkflowNodeInstance节点实例
- WorkflowLog工作流日志
---
### ✅ 5. 基础框架(已完成)
#### 5.1 通用CRUD框架
- [x] BaseController - 统一REST控制器
- [x] BaseServiceImpl - 通用服务实现
- [x] IBaseRepository - 通用数据访问接口
- [x] BaseConverter - 对象转换抽象
- [x] 统一响应格式Response<T>
- [x] 统一分页格式Page<T>
**标准CRUD接口所有Controller继承**
```
POST /{resource} - 创建
PUT /{resource}/{id} - 更新
DELETE /{resource}/{id} - 删除
GET /{resource}/{id} - 查询详情
GET /{resource} - 查询列表
GET /{resource}/page - 分页查询
GET /{resource}/list - 条件查询
POST /{resource}/batch - 批量处理
GET /{resource}/export - 导出数据
```
#### 5.2 查询框架
- [x] 基于QueryDSL的类型安全查询
- [x] 动态查询条件构建
- [x] @QueryField注解支持
- [x] 多种查询类型EQUAL、LIKE、BETWEEN、IN等
- [x] 软删除查询支持
#### 5.3 安全框架
- [x] Spring Security集成
- [x] JWT Token认证
- [x] 权限拦截器
- [x] 自定义认证入口点
- [x] JWT过滤器
#### 5.4 审计框架
- [x] 审计注解(@Audited
- [x] 自动记录创建人/创建时间
- [x] 自动记录更新人/更新时间
- [x] 乐观锁版本控制
- [x] 审计事件监听
#### 5.5 异常处理
- [x] 统一异常处理GlobalExceptionHandler
- [x] 业务异常BusinessException
- [x] 系统异常SystemException
- [x] 唯一约束异常UniqueConstraintException
- [x] 实体未找到异常EntityNotFoundException
- [x] 国际化错误消息
#### 5.6 数据库版本控制
- [x] Flyway集成
- [x] 表结构版本管理V1.0.0__init_schema.sql
- [x] 初始数据管理V1.0.1__init_data.sql
- [x] 28个数据库表
#### 5.7 其他框架功能
- [x] 国际化支持i18n
- [x] JSON序列化配置
- [x] 租户过滤器
- [x] 逻辑删除支持(@LogicDelete
- [x] 依赖注入后处理器
- [x] Formily Schema生成用于前端表单
---
## 数据库表结构28张表
### 系统管理表7张
1. `sys_tenant` - 租户表
2. `sys_department` - 部门表
3. `sys_user` - 用户表
4. `sys_param` - 系统参数表
5. `sys_role` - 角色表
6. `sys_role_tag` - 角色标签表
7. `sys_menu` - 菜单表
### 权限管理表5张
8. `sys_role_tag_relation` - 角色标签关系表
9. `sys_user_role` - 用户角色关系表
10. `sys_role_menu` - 角色菜单关系表
11. `sys_permission_template` - 权限模板表
12. `sys_template_menu` - 模板菜单关系表
13. `sys_permission` - 权限表
### 外部系统表1张
14. `sys_external_system` - 外部系统表
### Git仓库表3张
15. `deploy_repo_group` - 仓库组表
16. `deploy_repo_project` - 仓库项目表
17. `deploy_repo_branch` - 仓库分支表
### Jenkins表4张
18. Jenkins相关表通过代码推断未在SQL中完整展示
### 工作流表5张
19. `workflow_definition` - 工作流定义表
20. `workflow_node_definition` - 节点定义表
21. `workflow_instance` - 工作流实例表
22. `workflow_node_instance` - 节点实例表
23. `workflow_log` - 工作流日志表
### 部署管理表6张
24. `deploy_project_group` - 项目组表
25. `deploy_application` - 应用表
26. `deploy_environment` - 环境表
27. `deploy_project_group_environment` - 项目组环境关系表
28. `deploy_log` - 部署日志表
29. `deploy_app_config` - 应用部署配置表
---
## API接口统计
### Controller统计26个
**系统管理7个**
- UserApiController
- RoleApiController
- RoleTagApiController
- PermissionApiController
- MenuApiController
- DepartmentApiController
- TenantApiController
**部署管理8个**
- ApplicationApiController
- ProjectGroupApiController
- EnvironmentApiController
- DeployAppConfigApiController
- DeployLogApiController
- ExternalSystemApiController
- RepositoryManagerApiController
- RepositoryProjectApiController
- RepositoryGroupApiController
- RepositoryBranchApiController
**Jenkins管理5个**
- JenkinsManagerApiController
- JenkinsViewApiController
- JenkinsJobApiController
- JenkinsBuildApiController
- JenkinsSyncHistoryApiController
**工作流管理4个**
- WorkflowDefinitionApiController
- WorkflowNodeDefinitionApiController
- WorkflowInstanceApiController
- WorkflowNodeInstanceApiController
**接口方法统计:**
- 约49个自定义@Operation接口方法
- 每个Controller继承BaseController获得9个标准CRUD方法
- **总计约280+个API接口**
---
## 🚧 待完善功能
### 1. 测试覆盖
- [ ] Service层单元测试
- [ ] Controller层集成测试
- [ ] Repository层数据访问测试
- [ ] 工作流引擎测试
- **当前测试覆盖率约1%仅1个测试类**
### 2. 缓存机制
- [ ] Redis集成
- [ ] 工作流定义缓存
- [ ] 权限数据缓存
- [ ] 菜单数据缓存
- **当前状态已引入Caffeine依赖但未使用**
### 3. 监控和运维
- [ ] 健康检查端点完善
- [ ] 性能监控APM集成
- [ ] 日志聚合ELK
- [ ] 告警机制
- [ ] 链路追踪
### 4. 部署和DevOps
- [ ] Docker镜像构建
- [ ] Kubernetes部署配置
- [ ] CI/CD Pipeline
- [ ] 环境配置分离dev/test/prod
- **当前配置application.yml包含硬编码数据库密码和JWT密钥**
### 5. 文档完善
- [ ] API文档完善Swagger注释
- [ ] 架构图和流程图
- [ ] 部署手册
- [ ] 运维手册
- [ ] 最佳实践指南
### 6. 代码质量
- [ ] 代码质量检查工具集成Checkstyle、PMD、SonarQube
- [ ] TODO注释处理14处待处理
- [ ] System.out.println清理14处
- [ ] 泛化异常处理优化95处catch Exception
### 7. 安全加固
- [ ] 敏感配置外部化
- [ ] JWT密钥加密存储
- [ ] 数据库连接加密
- [ ] API访问频率限制
- [ ] SQL注入防护验证
- [ ] XSS攻击防护
### 8. 性能优化
- [ ] 数据库索引优化
- [ ] N+1查询问题排查
- [ ] 连接池配置优化当前仅10个
- [ ] 大数据量分页优化
- [ ] 异步任务处理
---
## 快速开始
### 环境要求
- JDK 21+
- Maven 3.8+
- MySQL 8.0+
- Node.js 16+(前端)
### 1. 数据库准备
```sql
CREATE DATABASE `deploy-ease-platform`
DEFAULT CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
```
### 2. 配置修改
编辑 `src/main/resources/application.yml`
```yaml
spring:
datasource:
url: jdbc:mysql://localhost:3306/deploy-ease-platform?...
username: your_username
password: your_password
jwt:
secret: 'your_secret_key' # 建议使用环境变量
```
⚠️ **安全提示:** 生产环境请使用环境变量或配置中心管理敏感信息!
### 3. 启动项目
```bash
# 编译项目
mvn clean package -DskipTests
# 启动服务
mvn spring-boot:run
# 或直接运行
java -jar target/deploy-cd-1.0-SNAPSHOT.jar
```
### 4. 访问服务
- **API文档** http://localhost:8080/swagger-ui.html
- **健康检查:** http://localhost:8080/actuator/health
### 5. 默认用户需通过初始化SQL配置
```
用户名admin
密码请查看V1.0.1__init_data.sql
```
---
## 项目规范
### 代码规范
详见项目根目录下的规范文件:
- `.cursor/rules/project.mdc` - 完整开发规范
- `frontend.rules` - 前端开发规范
### 核心规范要点
#### 包结构
```
com.qqchen.deploy.backend
├── framework/ # 框架核心
│ ├── annotation/ # 注解定义
│ ├── controller/ # 基础控制器
│ ├── service/ # 基础服务
│ ├── repository/ # 基础仓库
│ └── ...
├── system/ # 系统模块
│ ├── api/ # REST接口
│ ├── entity/ # 实体类
│ ├── service/ # 业务服务
│ └── ...
├── deploy/ # 部署模块
└── workflow/ # 工作流模块
```
#### 命名规范
- **Entity** 名词如User、Role
- **DTO** 实体名+DTO如UserDTO
- **Service接口** I+实体名+Service如IUserService
- **Service实现** 实体名+ServiceImpl如UserServiceImpl
- **Controller** 实体名+ApiController如UserApiController
- **Repository** I+实体名+Repository如IUserRepository
#### 注解使用
- **@ServiceType(DATABASE)** - 数据库服务
- **@ServiceType(INTEGRATION)** - 集成服务(禁用数据库操作)
- **@LogicDelete** - 启用逻辑删除
- **@Audited** - 启用审计
- **@QueryField** - 查询字段映射
---
## 贡献指南
### 提交规范
```
feat: 新功能
fix: Bug修复
docs: 文档更新
style: 代码格式调整
refactor: 重构
perf: 性能优化
test: 测试相关
chore: 构建/工具变动
```
### 分支管理
- `master` - 生产环境分支
- `develop` - 开发分支
- `feature/*` - 功能分支
- `bugfix/*` - Bug修复分支
- `hotfix/*` - 热修复分支
---
## 许可证
MIT License
---
## 联系方式
项目维护者Deploy Ease Team
---
## 更新日志
### v1.0.0(当前版本)
- ✅ 完成系统管理核心功能
- ✅ 完成Jenkins和Git集成
- ✅ 完成工作流引擎基础功能
- ✅ 完成部署管理框架
- ✅ 完成28张数据库表设计
- ✅ 完成280+个API接口
- ⚠️ 测试覆盖率待提升
- ⚠️ 缓存机制待实现
- ⚠️ 生产环境配置待优化
---
**注意事项:**
1. 本项目处于开发阶段,部分功能仍在完善中
2. 生产环境使用前请务必完成安全加固
3. 建议补充完整的单元测试和集成测试
4. 数据库配置和JWT密钥需要外部化管理
5. 建议集成专业的日志分析和监控方案