# acp-admin-cloud
**Repository Path**: zhangbinhub/acp-admin-cloud
## Basic Information
- **Project Name**: acp-admin-cloud
- **Description**: 使用 Kotlin 语言编写,基于 Spring Cloud 的微服务架构。该项目是前后端分离中的"后端部分"
- **Primary Language**: Kotlin
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 22
- **Forks**: 6
- **Created**: 2021-08-27
- **Last Updated**: 2025-08-27
## Categories & Tags
**Categories**: backend
**Tags**: Kotlin, SpringBoot, SpringCloud, SpringCloudAlibaba, java17
## README
# acp-admin-cloud
###### v7.0.2 [版本更新日志](doc/version_history.md)
- 使用Application Construction Platform 应用构建平台作为脚手架
- 基于 Spring Cloud 的微服务版本,基于 Spring Boot
的单机版请查看[这里](https://gitee.com/zhangbinhub/acp-admin-standalone)
- 该项目是前后端分离架构中的“后端部分”。[前端工程](https://gitee.com/zhangbinhub/acp-admin-cloud-web)
## 相关组件版本
- [Spring Boot 3.5.4](https://projects.spring.io/spring-boot)
- [Spring Boot Admin 3.5.2](https://github.com/codecentric/spring-boot-admin)
- [Acp 2025.8.0](https://gitee.com/zhangbinhub/acp)
- [sensitive](https://github.com/houbb/sensitive)
## 技术栈
| 分类 | 组件 | Spring技术栈 |
|-------|-----------|-----------------------------------------------------------------------------------------------------------------------------|
| 构建工具 | - | Gradle 8.6+ |
| 开发语言 | JVM | 17+ |
| | Java | 17+ |
| | Kotlin | 2.1+ |
| Core | 日期时间处理 | Joda Time |
| | UUID | [uuid-creator](https://github.com/f4b6a3/uuid-creator) |
| | 加解密库 | bouncycastle |
| | PDF处理 | itextpdf
html2pdf |
| | 文件压缩 | Zip4j |
| Boot | WEB服务 | Undertow |
| | http工具类 | RestClient
WebClient |
| | 日志框架 | slf4j
logback |
| | Json处理 | Jackson |
| | Xml处理 | Jackson |
| | ORM框架 | Hibernate (JPA) |
| | Api文档 | [Knife4j(国产)](https://doc.xiaominfo.com/)
Openapi3 |
| | 安全框架 | [Sa-Token(国产)](https://sa-token.cc/index.html) |
| | 资源服务 | [Sa-Token(国产)](https://sa-token.cc/index.html)
sa-token-oauth2 |
| | 认证服务 | [Sa-Token(国产)](https://sa-token.cc/index.html)
sa-token-oauth2 |
| | 认证协议 | Oauth 2.0 |
| | WebSocket | spring-boot-starter-websocket |
| | TCP/UDP | Netty |
| | 校验 | spring-boot-starter-validation |
| | Redis | spring-boot-starter-data-redis
spring-boot-starter-data-redis-reactive |
| | 工作流引擎 | [warm-flow(国产)](https://warm-flow.dromara.org/) |
| Cloud | 监控 | spring-boot-admin-server |
| | 注册中心 | [Nacos(国产)](https://nacos.io/)
spring-cloud-starter-alibaba-nacos-discovery |
| | 配置中心 | [Nacos(国产)](https://nacos.io/)
spring-cloud-starter-alibaba-nacos-config |
| | 熔断/限流 | [Sentinel(国产)](http://sentinelguard.io/zh-cn/)
spring-cloud-starter-alibaba-sentinel
sentinel-datasource-nacos |
| | 服务间调用 | spring-cloud-starter-openfeign
feign-hc5 |
| | 负载均衡 | spring-cloud-starter-loadbalancer |
| | 消息总线 | Kafka
spring-cloud-starter-stream-kafka
spring-cloud-stream-binder-kafka-streams
spring-cloud-starter-bus-kafka |
| | 日志收集 | Kafka
spring-cloud-starter-stream-kafka
spring-cloud-stream-binder-kafka-streams |
| | 网关 | spring-cloud-starter-gateway |
| | 分布式锁 | 默认集成Redisson,需要自定义时实现`io.gitee.zhangbinhub.acp.cloud.lock.DistributedLock`接口即可 |
| | 链路追踪 | `opentelemetry` |
## 总体架构

#### 说明
- 各服务在 **Nacos** 上进行注册,**gateway** 和其他各个服务通过 **Nacos** 发现和查找目标服务进行访问
- 各服务将互相调用的断路信息通过 **admin server** 进行监控
- **【依赖中间件 redis】 gateway server** 根据制定的策略路由到指定服务;
- **【依赖中间件 redis】 oauth server** 存储 **token** 至 **Redis**
- **【依赖中间件 kafka】** 发布和订阅 **Bus** 总线事件
server** 更新缓存
- **【依赖中间件 kafka】** 各深度定制开发的服务通过 **kafka** 发送日志消息,**log server** 从 **Kafka** 中消费消息并进行日志的统一记录
- **【依赖中间件 kafka、logstash、elasticsearch】** 日志收集
**logstash** 从 **Kafka** 中消费日志消息并存储到 **elasticsearch** 中
- 需要进行防重请求的 controller 方法上增加注解 **io.gitee.zhangbinhub.acp.cloud.annotation.AcpCloudDuplicateSubmission**
,默认30秒过期
- 前后端交互 **HttpStatus Code** 说明
| HttpStatus | 描述 |
|------------|-------------|
| 200 | 请求成功 |
| 201 | 资源创建成功 |
| 400 | 业务错误 |
| 401 | token(登录)失效 |
| 403 | 权限不足 |
| 404 | 找不到资源 |
| 500 | 系统异常 |
## 一、环境要求
- java 17+
- gradle 8.6+
- kotlin 2.1+
## 二、gradle 脚本配置及使用
### (一)配置文件
##### 1.[gradle/application.gradle](gradle/application.gradle)
应用模块公共配置
##### 2.[gradle/commonTask.gradle](gradle/commonTask.gradle)
公共自定义任务配置,适用于所有项目模块
##### 3.[gradle/libs.versions.toml](gradle/libs.versions.toml)
定义外部依赖版本号
##### 4.[gradle/globalTask.gradle](gradle/globalTask.gradle)
全局自定义任务配置,适用于顶层项目
##### 5.[gradle/moduleVersion.gradle](gradle/moduleVersion.gradle)
各子模块版本号
##### 6.[gradle/publishJar.gradle](gradle/publishJar.gradle)
发布任务配置,适用于所有项目模块
##### 7.[settings.gradle](settings.gradle)
定义项目/模块结构
##### 8.[project.properties](project.properties)
gradle全局参数:
- gradleVersion:gradle版本号
- group:对应打包时的最外层groupid,最终的groupid还会加上模块路径,例如`groupid.acp.core`
- version:版本号
- encoding:编译字符集
- mavenCentralUrl:maven中央仓库地址
- javaVersion:jdk版本号
##### 5.[build.gradle](build.gradle)
公共构建脚本
### (二)自定义任务
- 全局自定义任务
- publishAll 发布所有构建至maven中央仓库
- publishToMavenLocalAll 发布所有构建至maven本地仓库
- buildImageAll 所有模块打包镜像(Dockerfile模式)
- bootBuildImageAll 所有模块打包镜像(Spring模式)
- 公共自定义任务
- clearPj 清理所有输出文件
- release 编译、打包并输出
- 如需编译打包对应环境,命令中使用参数```active```,例如
```
gradlew project:release -Pactive=test
```
- buildImage 通过```Dockerfile```打包镜像
- pushImage 通过```Dockerfile```打包镜像并上传
### (三)发布至maven仓库
##### 1、发布至本地仓库
- 执行 publishToMavenLocal 任务
- publishToMavenLocalAll
##### 2、发布至私服
- 项目根路径下创建 gradle.properties 并添加如下参数(参数值根据实际情况修改)
```
mavenUploadUrlRelease=https://maven.com/repositories/releases/
mavenUploadUrlSnapshot=https://maven.com/repositories/snapshot/
mavenUserName=username
mavenPassword=password
```
- 执行 publish 任务
- publishAll
##### 3、发布至中央仓库
- 项目根路径下创建 gradle.properties 并添加如下参数(参数值根据实际情况修改)
```
mavenUploadUrlRelease=https://maven.com/repositories/releases/
mavenUploadUrlSnapshot=https://maven.com/repositories/snapshot/
mavenUserName=username
mavenPassword=password
signing.keyId=shortId
signing.password=keyPassword
signing.secretKeyRingFile=keyFile
```
- 执行 publish 任务
- publishAll
### (四)升级命令
```
gradlew wrapper --gradle-distribution-url=https://mirrors.cloud.tencent.com/gradle/gradle-8.13-all.zip
```
## 三、工程说明
- 工程全局默认使用 UTF-8 字符集
- 工程结构
```
acp-admin-cloud -------工程根目录,root模块
├─ common -------公共模块
├─ deploy -------部署脚本
├─ doc -------文档
├─ gradle -------gradle脚本
└─ modules -------子模块路径
```
- deploy 部署文件
- nacos数据库初始化脚本 [nacos-mysql-2.0.sql](deploy/init/nacos-mysql-2.0.sql)
- [docker部署](deploy/docker/README.md)
- [k8s部署](deploy/k8s-demo/README.md)
- swagger url : /doc.html
## 四、启停 SpringBoot 应用
- [启停脚本模板(Linux)](doc/script/server.model)
- [启停脚本(windows)](doc/script/server.bat):根据实际情况修改第1行末尾需要执行的 jar 名称,和SpringBoot应用的 .jar
放在同一路径下
- windows:修改[server.bat](doc/script/server.bat)内相关参数后,直接运行即可
- Linux 命令:
| 命令 | 描述 |
|---------------------|----------|
| ./server.sh | 查看可用参数 |
| ./server.sh status | 查看系统运行状态 |
| ./server.sh start | 启动应用 |
| ./server.sh stop | 停止应用 |
| ./server.sh restart | 重启应用 |
## 五、基础中间件环境搭建(docker)
- 启动服务
命令模式依次进入```deploy/docker/middleware deploy/docker/elk```目录,执行启动命令
```
docker-compose up -d
```
- 停止服务
```
docker-compose stop
```
- 停止并删除容器实例
```
docker-compose down
```
## 六、系统初始化
### (一)数据库
- 服务首次启动时,必要资源数据会自动进行初始化
## 七、服务列表
### (一)acp-admin-cloud-constant
全局静态常量定义 定义服务间内部访问restful路径 定义角色编码 定义功能权限编码 定义路由相关常量 定义token相关常量
### (二)acp-admin-cloud-dependencies
- 普通服务依赖模块
- 分布式锁实现
- 全局流水号生成实现
- 自动配置相关组件
- 依赖`acp-admin-cloud-constant`
### (三)acp-admin-cloud-dependencies-resource-server
- 纳入统一认证的服务依赖模块
- 依赖`acp-admin-cloud-dependencies`
### (四)[admin-server](modules/admin-server/README.md)
- 基于SpringBootAdmin的可视化监控,监控服务状态
- 依赖`acp-spring-cloud-starter`
- 其他依赖,请查看[build.gradle](modules/admin-server/build.gradle)
### (五)[gateway-server](modules/gateway-server/README.md)
- 网关服务
- 依赖`acp-spring-cloud-starter`
- 其他依赖,请查看[build.gradle](modules/gateway-server/build.gradle)
- 动态路由信息保存在 redis
### (六)[deploy-server](modules/deploy-server/README.md)
- 部署服务
- 依赖`acp-spring-cloud-starter-resource-server`
- 其他依赖,请查看[build.gradle](modules/deploy-server/build.gradle)
### (七)[log-server](modules/log-server/README.md)
- 统一日志服务
- 依赖`acp-spring-cloud-starter-resource-server`
- 其他依赖,请查看[build.gradle](modules/log-server/build.gradle)
- 通过 kafka 收集其余服务的日志信息,统一进行记录
- 通过 kafka 收集网关消息,记录路由日志
- 根据配置中心参数,压缩备份日志文件
- 根据配置中心参数,记录操作日志和登录日志
- 每日将路由日志、操作日志、登录日志迁移至历史库
- 根据 oauth 服务中运行参数配置的策略,压缩备份日志文件
- 提供备份的日志文件查询、下载接口,只有超级管理员有权限访问
### (八)[oauth-server](modules/oauth-server/README.md)
- 统一认证服务
- 依赖`acp-spring-cloud-starter-resource-server`
- 其他依赖,请查看[build.gradle](modules/oauth-server/build.gradle)
- 提供全套权限体系服务,包含客户端应用管理、用户管理、机构管理、角色管理、权限管理、token管理、运行参数管理等
### (九)[route-server](modules/route-server/README.md)
- 路由服务
- 依赖`acp-spring-cloud-starter-resource-server`
- 其他依赖,请查看[build.gradle](modules/route-server/build.gradle)
- 提供动态路由策略配置及刷新
### (十)[workflow-server](modules/workflow-server/README.md)
- 工作流引擎服务
- 依赖`acp-spring-cloud-starter-resource-server`
- 其他依赖,请查看[build.gradle](modules/workflow-server/build.gradle)
- 提供工作流相关接口服务
### (十一)其他自定义服务
- 不需要统一认证,依赖`acp-spring-cloud-starter`
- 需要统一认证,依赖`acp-spring-cloud-starter-resource-server`
## 八、[Sentinel 动态数据源配置](doc/sentinel.md)
## 九、[公共配置信息](doc/atom-server-common-dev.yaml)
## 十、环境变量及启动参数
| 变量名 | 描述 | 默认值 | 说明 |
|---------------------|-----------|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| JAVA_TOOL_OPTIONS | JVM启动参数 | | 该环境变量在容器部署时使用 |
| acp_profile_active | 激活的配置环境 | dev | 服务器部署时建议java启动命令加入参数 -Dacp_profile_active 或 --acp_profile_active;容器部署时指定环境变量即可 |
| acp_server_port | 服务启动端口 | 0(随机端口) | 服务器部署时建议java启动命令加入参数 -Dacp_server_port 或 --acp_server_port;容器部署时指定环境变量即可。服务不需要外部直接访问时,建议保持默认值。注:admin-server默认值:9099,gateway-server默认值:8771 |
| acp_log_path | 日志路径 | logs/${spring.application.name} | 服务器部署时建议java启动命令加入参数 -Dacp_log_path 或 --acp_log_path;容器部署时指定环境变量即可 |
| acp_nacos_addr | nacos地址 | 127.0.0.1:8848 | nacos服务地址,ip:port |
| acp_nacos_username | nacos用户名 | nacos | nacos用户名,默认nacos,可自行在nacos管理端添加用户 |
| acp_nacos_password | nacos密码 | nacos | nacos用户密码,默认nacos,可自行在nacos管理端添加用户 |
| acp_nacos_namespace | nacos命名空间 | acp-cloud-admin | nacos命名空间,默认nacos,可自行在nacos管理端配置 |
## 十一、打包OCI镜像
- 单个模块
- 打包:`buildImage`
- 打包并上传:`pushImage`
- 批量
- 打包:`buildImageAll`
- 打包并上传:`pushImageAll`
## 十二、容器部署
- [docker部署](deploy/docker/README.md)
- [k8s部署](deploy/k8s-demo/README.md)