# 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` | ## 总体架构 ![Architecture diagram](doc/images/Acp%20Admin%20Cloud总体架构图.png) #### 说明 - 各服务在 **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)