# 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**: 23
- **Forks**: 6
- **Created**: 2021-08-27
- **Last Updated**: 2025-09-27

## Categories & Tags

**Categories**: backend

**Tags**: Kotlin, SpringBoot, SpringCloud, SpringCloudAlibaba, java17

## README

# acp-admin-cloud

###### v7.0.4 [版本更新日志](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.6](https://projects.spring.io/spring-boot)
- [Spring Boot Admin 3.5.5](https://github.com/codecentric/spring-boot-admin)
- [Acp 2025.8.6](https://gitee.com/zhangbinhub/acp)
- [sensitive](https://github.com/houbb/sensitive)

## 技术栈

| 分类    | 组件        | Spring技术栈                                                                                                                   |
|-------|-----------|-----------------------------------------------------------------------------------------------------------------------------|
| 构建工具  | -         | Gradle 9.0+                                                                                                                 |
| 开发语言  | JVM       | 17+                                                                                                                         |
|       | Java      | 17+                                                                                                                         |
|       | Kotlin    | 2.2+                                                                                                                        |
| Core  | 日期时间处理    | Joda Time                                                                                                                   |
|       | UUID      | [uuid-creator](https://github.com/f4b6a3/uuid-creator)                                                                      |
|       | 加解密库      | bouncycastle                                                                                                                |
|       | PDF处理     | itextpdf<br/>html2pdf                                                                                                       |
|       | 文件压缩      | Zip4j                                                                                                                       |
| Boot  | WEB服务     | Undertow                                                                                                                    |
|       | http工具类   | RestClient<br/>WebClient                                                                                                    |
|       | 日志框架      | slf4j<br/>logback                                                                                                           |
|       | Json处理    | Jackson                                                                                                                     |
|       | Xml处理     | Jackson                                                                                                                     |
|       | ORM框架     | Hibernate (JPA)                                                                                                             |
|       | Api文档     | [Knife4j（国产）](https://doc.xiaominfo.com/)<br/>Openapi3                                                                      |
|       | 安全框架      | [Sa-Token（国产）](https://sa-token.cc/index.html)                                                                              |
|       | 资源服务      | [Sa-Token（国产）](https://sa-token.cc/index.html) <br/>sa-token-oauth2                                                         |
|       | 认证服务      | [Sa-Token（国产）](https://sa-token.cc/index.html) <br/>sa-token-oauth2                                                         |
|       | 认证协议      | Oauth 2.0                                                                                                                   |
|       | WebSocket | spring-boot-starter-websocket                                                                                               |
|       | TCP/UDP   | Netty                                                                                                                       |
|       | 校验        | spring-boot-starter-validation                                                                                              |
|       | Redis     | spring-boot-starter-data-redis<br/>spring-boot-starter-data-redis-reactive                                                  |
|       | 工作流引擎     | [warm-flow（国产）](https://warm-flow.dromara.org/)                                                                             |
| Cloud | 监控        | spring-boot-admin-server                                                                                                    |
|       | 注册中心      | [Nacos（国产）](https://nacos.io/)<br/>spring-cloud-starter-alibaba-nacos-discovery                                             |
|       | 配置中心      | [Nacos（国产）](https://nacos.io/)<br/>spring-cloud-starter-alibaba-nacos-config                                                |
|       | 熔断/限流     | [Sentinel（国产）](http://sentinelguard.io/zh-cn/)<br/>spring-cloud-starter-alibaba-sentinel<br/>sentinel-datasource-nacos      |
|       | 服务间调用     | spring-cloud-starter-openfeign<br/>feign-hc5                                                                                |
|       | 负载均衡      | spring-cloud-starter-loadbalancer                                                                                           |
|       | 消息总线      | Kafka<br/>spring-cloud-starter-stream-kafka<br/>spring-cloud-stream-binder-kafka-streams<br/>spring-cloud-starter-bus-kafka |
|       | 日志收集      | Kafka<br/>spring-cloud-starter-stream-kafka<br/>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-9.0.0-all.zip
```

## 三、工程说明

- 工程全局默认使用 UTF-8 字符集
- 工程结构

```
acp-admin-cloud         -------工程根目录，root模块
├─ common               -------公共模块
├─ deploy               -------部署脚本
├─ doc                  -------文档
├─ gradle               -------gradle脚本
└─ modules              -------子模块路径
```

- deploy 部署文件
    - nacos数据库初始化脚本 [nacos-mysql-3.0.sql](deploy/init/nacos-mysql-3.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)