acp-admin-cloud

v6.7.3 版本更新日志

• 使用Application Construction Platform 应用构建平台作为脚手架
• 基于 Spring Cloud 的微服务版本，基于 Spring Boot 的单机版请查看这里
• 该项目是前后端分离架构中的“后端部分”。前端工程

相关组件版本

• Spring Boot 3.4.4
• Spring Boot Admin 3.4.5
• Acp 2025.2.1
• sensitive

技术栈

• camunda
• joda-time
• netty
• hibernate
• jackson
• sensitive
• knife4j
• junit5
• spring-boot
  • spring-boot-starter-webflux
  • spring-boot-starter-undertow
  • spring-boot-starter-actuator
  • spring-boot-starter-validation
  • spring-boot-starter-aop
  • spring-boot-starter-websocket
  • spring-boot-starter-security
  • spring-boot-starter-data-jpa
  • spring-boot-starter-data-redis
  • spring-boot-starter-data-redis-reactive
  • spring-boot-starter-oauth2-resource-server
  • spring-boot-starter-oauth2-authorization-server
• spring-boot-admin-server
• spring-cloud-alibaba
  • spring-cloud-starter-alibaba-nacos-discovery
  • spring-cloud-starter-alibaba-nacos-config
  • spring-cloud-starter-alibaba-sentinel
  • sentinel-datasource-nacos
• spring-cloud
  • spring-cloud-starter-loadbalancer
  • spring-cloud-starter-gateway
  • spring-cloud-starter-stream-kafka
  • spring-cloud-stream-binder-kafka-streams
  • spring-cloud-starter-bus-kafka
  • spring-cloud-starter-openfeign
• feign-hc5
• micrometer-tracing-bridge-otel
• opentelemetry-exporter-zipkin

总体架构

说明

• 各服务在 Nacos 上进行注册，gateway 和其他各个服务通过 Nacos 发现和查找目标服务进行访问
• 各服务将互相调用的断路信息通过 admin server 进行监控
• 【依赖中间件 redis】 gateway server 根据制定的策略路由到指定服务；路由定义从 Redis 获取，缓存至本地；基于动态路由配置可根据实际情况扩展实现灰度发布
• 【依赖中间件 redis】 oauth server 存储 token 至 Redis
• 【依赖中间件 redis、kafka】 route server 修改路由信息后更新至 Redis ，通过 Kafka 通知 gateway server 动态更新路由
• 【依赖中间件 kafka】 发布和订阅 Bus 总线事件 server** 更新缓存
• 【依赖中间件 kafka】 各深度定制开发的服务通过 kafka 发送日志消息，log server 从 Kafka 中消费消息并进行日志的统一记录
• 【依赖中间件 kafka、logstash、elasticsearch】 日志收集 logstash 从 Kafka 中消费日志消息并存储到 elasticsearch 中
• 【依赖中间件 zookeeper】 分布式锁，实现 io.gitee.zhangbinhub.acp.cloud.lock.DistributedLock 接口，并注册为Spring Bean ，包路径中包含 curator-recipes 时，默认配置一个基于 zookeeper 的分布式锁实现
• 需要进行防重请求的 controller 方法上增加注解 io.gitee.zhangbinhub.acp.cloud.annotation.AcpCloudDuplicateSubmission ，默认30秒过期
• 前后端交互 HttpStatus Code 说明

一、环境要求

• java 17+
• gradle 8.6+
• kotlin 2.1+

二、gradle 脚本配置及使用

（一）配置文件

1.gradle/application.gradle

应用模块公共配置

2.gradle/commonTask.gradle

公共自定义任务配置，适用于所有项目模块

3.gradle/dependencies.gradle

定义外部依赖版本号

4.gradle/globalTask.gradle

全局自定义任务配置，适用于顶层项目

5.gradle/moduleVersion.gradle

各子模块版本号

6.gradle/publish.gradle

发布任务配置，适用于所有项目模块

7.settings.gradle

定义项目/模块结构

8.project.properties

gradle全局参数：

• gradleVersion：gradle版本号
• group：对应打包时的最外层groupid，最终的groupid还会加上模块路径，例如groupid.acp.core
• version：版本号
• encoding：编译字符集
• mavenCentralUrl：maven中央仓库地址
• javaVersion：jdk版本号

5.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
  • docker部署
  • k8s部署
• swagger url : /doc.html

四、启停 SpringBoot 应用

• 启停脚本模板(Linux)
• 启停脚本(windows)：根据实际情况修改第1行末尾需要执行的 jar 名称，和SpringBoot应用的 .jar 放在同一路径下
• windows：修改server.bat内相关参数后，直接运行即可
• Linux 命令：

五、基础中间件环境搭建（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

• 基于SpringBootAdmin的可视化监控，监控服务状态
• 依赖acp-spring-cloud-starter
• 其他依赖，请查看build.gradle

（五）gateway-server

• 网关服务
• 依赖acp-spring-cloud-starter
• 其他依赖，请查看build.gradle
• 动态路由信息保存在 redis

（六）deploy-server

• 部署服务
• 依赖acp-spring-cloud-starter-resource-server
• 其他依赖，请查看build.gradle

（七）log-server

• 统一日志服务
• 依赖acp-spring-cloud-starter-resource-server
• 其他依赖，请查看build.gradle
• 通过 kafka 收集其余服务的日志信息，统一进行记录
• 通过 kafka 收集网关消息，记录路由日志
• 根据配置中心参数，压缩备份日志文件
• 根据配置中心参数，记录操作日志和登录日志
• 每日将路由日志、操作日志、登录日志迁移至历史库
• 根据 oauth 服务中运行参数配置的策略，压缩备份日志文件
• 提供备份的日志文件查询、下载接口，只有超级管理员有权限访问

（八）oauth-server

• 统一认证服务
• 依赖acp-spring-cloud-starter-resource-server
• 其他依赖，请查看build.gradle
• 提供全套权限体系服务，包含客户端应用管理、用户管理、机构管理、角色管理、权限管理、token管理、运行参数管理等

（九）route-server

• 路由服务
• 依赖acp-spring-cloud-starter-resource-server
• 其他依赖，请查看build.gradle
• 提供动态路由策略配置及刷新

（十）workflow-server

• 工作流引擎服务
• 依赖acp-spring-cloud-starter-resource-server
• 其他依赖，请查看build.gradle
• 提供工作流相关接口服务

（十一）其他自定义服务

• 不需要统一认证，依赖acp-spring-cloud-starter
• 需要统一认证，依赖acp-spring-cloud-starter-resource-server

八、Sentinel 动态数据源配置

九、公共配置信息

十、环境变量及启动参数

十一、打包OCI镜像

• 单个模块
  • 打包：buildImage
  • 打包并上传：pushImage
• 批量
  • 打包：buildImageAll
  • 打包并上传：pushImageAll

十二、容器部署

• docker部署
• k8s部署