# 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**: 20 - **Forks**: 5 - **Created**: 2021-08-27 - **Last Updated**: 2025-06-12 ## Categories & Tags **Categories**: backend **Tags**: Kotlin, SpringBoot, SpringCloud, SpringCloudAlibaba, java17 ## README # acp-admin-cloud ###### v6.8.1 [版本更新日志](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.4.6](https://projects.spring.io/spring-boot) - [Spring Boot Admin 3.4.7](https://github.com/codecentric/spring-boot-admin) - [Acp 2025.4.1](https://gitee.com/zhangbinhub/acp) - [sensitive](https://github.com/houbb/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 ## 总体架构 ![Architecture diagram](doc/images/总体架构.jpg) #### 说明 - 各服务在 **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** 说明 | 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/dependencies.gradle](gradle/dependencies.gradle) 定义外部依赖版本号 ##### 4.[gradle/globalTask.gradle](gradle/globalTask.gradle) 全局自定义任务配置，适用于顶层项目 ##### 5.[gradle/moduleVersion.gradle](gradle/moduleVersion.gradle) 各子模块版本号 ##### 6.[gradle/publish.gradle](gradle/publish.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)