# acp-admin-standalone

**Repository Path**: zhangbinhub/acp-admin-standalone

## Basic Information

- **Project Name**: acp-admin-standalone
- **Description**: 使用 Kotlin 语言编写，基于 Spring Boot 的微服务架构（单机版）。该项目是前后端分离中的"后端部分"
- **Primary Language**: Kotlin
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 10
- **Forks**: 2
- **Created**: 2022-03-04
- **Last Updated**: 2025-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Kotlin, SpringBoot, java17

## README

# acp-admin-standalone

###### v2.8.1 [版本更新日志](doc/version_history.md)

- 使用Application Construction Platform 应用构建平台作为脚手架
- 基于 Spring Boot 的单机版，基于 Spring Cloud 版本请查看[这里](https://gitee.com/zhangbinhub/acp-admin-cloud)
- 该项目是前后端分离架构中的“后端部分”。[前端工程](https://gitee.com/zhangbinhub/acp-admin-standalone-web)

## 相关组件版本

- [Spring Boot 3.4.6](https://projects.spring.io/spring-boot)
- [Acp 2025.4.1](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<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 |
|      | 安全框架      | Spring Security                                        |
|      | 资源服务      | spring-boot-starter-oauth2-resource-server             |
|      | 认证服务      | spring-boot-starter-oauth2-authorization-server        |
|      | 认证协议      | Oauth 2.0/2.1                                          |
|      | WebSocket | spring-boot-starter-websocket                          |
|      | TCP/UDP   | Netty                                                  |
|      | 校验        | spring-boot-starter-validation                         |
|      | 工作流引擎     | [warm-flow（国产）](https://warm-flow.dromara.org/)        |

## 一、gradle 脚本配置及使用

### （一）配置文件

##### 1.[gradle/dependencies.gradle](gradle/dependencies.gradle)

定义外部依赖版本号

##### 2.[gradle/commonTask.gradle](gradle/commonTask.gradle)

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

##### 3.[gradle/application.gradle](gradle/application.gradle)

应用模块公共配置

##### 4.[settings.gradle](settings.gradle)

定义项目/模块结构

##### 5.[project.properties](project.properties)

gradle全局参数：

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

##### 5.[build.gradle](build.gradle)

公共构建脚本

### （二）自定义任务

- clearPj 清理所有输出文件
- release 编译、打包并输出
    - 如需编译打包对应环境，命令中使用参数 active，例如
  ```
  gradlew project:release -Pactive=test
  ```
- buildImage 通过```Dockerfile```打包镜像
- pushImage 通过```Dockerfile```打包镜像并上传

### （三）升级命令

```
gradlew wrapper --gradle-distribution-url=https://mirrors.cloud.tencent.com/gradle/gradle-8.13-all.zip
```

## 二、工程说明

- 工程全局默认使用 UTF-8 字符集
- gradle 目录下为相关配置文件
- deploy 部署文件
    - 服务[docker/docker-compose.yaml](deploy/docker/docker-compose.yaml)
    - web[web/docker-compose.yaml](deploy/web/docker-compose.yaml)
- 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 | 重启应用     |

## 四、说明

- 统一认证服务，集成 oauth2
- 提供全套权限体系服务，包含客户端应用管理、用户管理、机构管理、角色管理、权限管理、token管理、运行参数管理等

| url           | 描述            |
|---------------|---------------|
| /server/token | 获取token，无认证保护 |

[查看认证过程](doc/auth/oauth认证.md)

##### （一）数据初始化

首次启动时，如果必要的系统资源和超级管理员数据不存在，则会自动进行初始化

##### （二）接口功能

提供生成token、验证token、应用管理、机构管理、参数管理、角色管理、用户管理、菜单管理、权限功能管理等接口，接口详情请在浏览器中访问
/doc.html 页面

##### （三）运行参数

| 名称                            | 值          | 描述                                                                    | 备注                     |
|-------------------------------|------------|-----------------------------------------------------------------------|------------------------|
| PASSWORD_COMPLEXITY_POLICY    | 0          | 密码复杂度策略；0：不限制，1：数字+字母，2：数字+字母+英文特殊符号`~!@#$%^&*()+=&#124;{}':;,\"[].<> | 默认0                    |
| PASSWORD_UPDATE_INTERVAL_TIME | 7776000000 | 修改密码间隔时间，单位：毫秒                                                        | 密码过期之后，会要求强制修改密码；默认90天 |

##### （四）自定义认证方式

- 1、新建
  AuthenticationToken，参考参考[OauthUserPasswordAuthenticationRequest](src/main/kotlin/io/gitee/zhangbinhub/admin/authentication/OauthUserPasswordAuthenticationRequest.kt)
- 2、新建转换器
  AuthenticationConverter，参考[OauthUserPasswordAuthenticationConverter](src/main/kotlin/io/gitee/zhangbinhub/admin/authentication/OauthUserPasswordAuthenticationConverter.kt)
- 3、新建提供者
  AuthenticationProvider，参考[OauthUserPasswordAuthenticationProvider](src/main/kotlin/io/gitee/zhangbinhub/admin/authentication/OauthUserPasswordAuthenticationProvider.kt)
- 4、AuthorizationServerConfiguration 中加入对应配置

## 五、环境变量及启动参数

| 变量名                | 描述      | 默认值                             | 说明                                                                                             |
|--------------------|---------|---------------------------------|------------------------------------------------------------------------------------------------|
| JAVA_TOOL_OPTIONS  | JVM启动参数 |                                 | 该环境变量在容器部署时使用                                                                                  |
| acp_profile_active | 激活的配置环境 | dev                             | 服务器部署时建议java启动命令加入参数 -Dacp_profile_active 或 --acp_profile_active；容器部署时指定环境变量即可                 |
| acp_server_port    | 服务启动端口  | 9090                            | 服务器部署时建议java启动命令加入参数 -Dacp_server_port 或 --acp_server_port；容器部署时指定环境变量即可。服务不需要外部直接访问时，建议保持默认值。 |
| acp_log_path       | 日志路径    | logs/${spring.application.name} | 服务器部署时建议java启动命令加入参数 -Dacp_log_path 或 --acp_log_path；容器部署时指定环境变量即可                             |
| db_url             | 数据库连接   |                                 |                                                                                                |
| db_username        | 数据库用户名  |                                 |                                                                                                |
| db_password        | 数据库密码   |                                 |                                                                                                |

## 六、打包OCI镜像

- buildImage
- bootBuildImage(实验阶段)
- pushImage

## 七、工作流引擎

##### （一）固定必要的流程变量，自定义变量不能与之重复

- startUserId - 流程发起人
- title - 流程标题
- description - 流程描述

##### （二）自定义待办通知开发

###### 待办生成通知

新建通知处理类，包名io.gitee.zhangbinhub.admin.workflow.notify，继承
```io.gitee.zhangbinhub.admin.base.PendingCreatedNotify```
，实现方法

```
  @Throws(WebException::class)
  fun doTaskNotify(definition: Definition, instance: Instance, task: Task, userIdList: List<String>)
```

参考[LogPendingCreatedNotify](src/main/kotlin/io/gitee/zhangbinhub/admin/workflow/notify/LogPendingCreatedNotify.kt)

###### 待办完成通知

新建通知处理类，包名io.gitee.zhangbinhub.admin.workflow.notify，继承
```io.gitee.zhangbinhub.admin.base.PendingFinishedNotify```
，实现方法

```
  @Throws(WebException::class)
  fun doTaskNotify(definition: Definition, instance: Instance, task: Task, userIdList: List<String>)
```

参考[LogPendingFinishedNotify](src/main/kotlin/io/gitee/zhangbinhub/admin/workflow/notify/LogPendingFinishedNotify.kt)