# cs-springboot-admin

**Repository Path**: xhbug_cs4380/cs-springboot-admin

## Basic Information

- **Project Name**: cs-springboot-admin
- **Description**: cs-springboot-admin基础权限单体架构，前后端分离项目
后端项目基于Spring Boot、Spring、Spring MVC、MyBatis、Shiro等主流后端技术开发
前端项目基于react 19 + Vite 5 + TypeScript5 + antd 6、axios等主流后端技术开发
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 33
- **Forks**: 9
- **Created**: 2019-04-24
- **Last Updated**: 2026-06-21

## Categories & Tags

**Categories**: backend

**Tags**: None

## README

# cs-admin 基础权限管理系统

cs-admin 是一套企业级基础权限单体架构系统，采用前后端分离设计。  
后端基于 Spring Boot 3、Spring MVC、MyBatis-Plus、Shiro 等主流技术栈开发。  
前端基于 React 19 + Vite 5 + TypeScript 5 + Ant Design 6 构建。  
支持多租户数据隔离、角色权限细粒度控制（菜单级 + 按钮级）、数据字典、消息中心等核心功能。

> 当前版本：**1.2.0.RELEASE**

联系方式: cs4380@163.com

## 一. 系统说明

### 1. 目录模块说明

```
cs-springboot-admin
├── cs-admin-ui/       # 前端项目（React 19 + Vite 5 + TypeScript 5 + Ant Design 6）
├── cs-admin/          # 管理模块 - 提供后台管理基础功能（用户/角色/菜单/字典/租户等）
├── cs-auth/           # 认证模块 - 统一认证授权、JWT Token、Shiro 鉴权
├── cs-common/         # 公共模块 - 通用工具类、异常处理、常量定义、公共 VO
├── cs-biz/            # 业务模块 - 主程序入口（BizBootstrap），通过 POM 依赖聚合其他模块
├── cs-tool/           # 工具模块 - 文件存储、微信支付等扩展能力
├── cs-generator/      # 代码生成器 - 可视化操作数据库表，一键生成前后端代码
└── doc/               # 项目文档 - 数据库脚本、字体库、代码模板
```

#### 各模块职责

| 模块 | 职责说明 |
|------|----------|
| **cs-admin** | 用户管理、组织机构管理、角色权限管理、数据字典管理、系统菜单管理、系统租户管理 |
| **cs-auth** | 认证授权服务，基于 Shiro + JWT 的登录验证与权限校验 |
| **cs-common** | 系统公共基础工具包（注解、切面、异常、常量、分页、统一返回等） |
| **cs-biz** | 业务主服务，启动入口，其他模块通过 Maven 依赖注入 |
| **cs-tool** | 扩展工具服务（云文件存储 OSS、微信支付等） |
| **cs-generator** | 独立代码生成器项目，可视化配置数据库表生成前后端代码 |

### 2. 技术架构

#### 后端技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| JDK | 21 | 开启全局虚拟线程 |
| Spring Boot | 3.3.6 | 基础框架 |
| MyBatis-Plus | 3.5.6 | ORM 持久层增强 |
| Apache Shiro | 1.11.0（Jakarta） | 认证授权框架 |
| Druid | 1.2.9 | 数据库连接池（含 SQL 监控与防火墙） |
| MySQL Connector | 8.0.33 | 数据库驱动 |
| Redis（spring-boot-starter-data-redis） | 3.2.5 | 缓存中间件 |
| Caffeine | 3.1.8 | 本地内存缓存 |
| JWT（java-jwt） | 4.0.0 | Token 令牌 |
| Jasypt | 3.0.5 | 配置文件密码加密 |
| Knife4j + SpringDoc | 4.4.0 | 接口文档（OpenAPI 3） |
| Fastjson | 2.0.12 | JSON 序列化 |
| Lombok | 1.18.32 | 代码简化 |
| Guava | 33.2.0-jre | Google 工具库 |

#### 前端技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| React | 19 | UI 框架 |
| TypeScript | 5.5 | 类型安全 |
| Vite | 5.3 | 构建工具 |
| Ant Design | 6.4 | UI 组件库 |
| Redux Toolkit | 2.2 | 状态管理 |
| React Router | 6.24 | 路由管理 |
| Axios | 1.17 | HTTP 请求 |
| ECharts | 6.1 | 图表可视化 |
| i18next | 26.3 | 国际化 |
| Less | 4.2 | CSS 预处理器 |

#### 基础设施

| 组件 | 版本 |
|------|------|
| MySQL | 8.x |
| Redis | 6.x |
| Node.js | >= 20.0.0 |

### 3. 功能清单

- **权限体系管理**
  - 组织机构管理（部门树形结构、部门人员维护）
  - 用户管理（用户信息、用户权限查询、密码修改）
  - 角色管理（角色增删改查）
  - 菜单管理（菜单树形结构、目录/菜单/按钮三级）
  - 按钮管理（菜单按钮配置，细粒度接口权限控制）
  - 权限授权（角色菜单授权、角色按钮授权）
- **基础配置管理**
  - 数据字典管理（字典类型维护、字典值管理）
  - 系统租户管理（多租户数据隔离）
- **消息中心**
  - 系统消息管理（消息发布、分页查询、详情查看）
  - 用户消息（消息已读/未读）
- **通用能力服务**
  - 统一认证服务（图形验证码、账号密码登录、微信授权登录）
  - 云文件存储（多云适配、文件上传下载）
  - 代码生成器（数据库表解析、前后端代码生成）

### 4. 代码规范（推荐）

本项目基于 <a href="https://github.com/alibaba/p3c/" target="_blank">阿里代码规范</a>，采用了常见的代码规范

- 表单验证采用 Hibernate-Validator，前端做表单验证，后台只做验证不做提示
- 插件：Lombok、Swagger（Knife4j）、MyBatis-Plus、PageHelper

## 二、开发环境搭建

### 1. 环境要求

| 环境 | 版本要求 |
|------|----------|
| JDK | 21+ |
| Node.js | >= 20.0.0（推荐 24） |
| MySQL | 8.x |
| Redis | 6.x |
| Maven | 3.x+ |
| pnpm / npm | 最新稳定版 |

### 2. 后端项目环境搭建

#### 2.1 编辑器插件

- **Lombok 插件**：需要手动下载并安装到 IDE 中
- **Maven 插件**：一般编辑器都自带，只需和本地 Maven 关联配置即可

#### 2.2 数据库初始化

1. 执行建表 SQL 脚本：`/doc/db/base_db.sql`（含建库、建表、初始数据）
2. 数据库名称：`base_db`，字符集：`utf8`

#### 2.3 Maven 打包

在项目根目录执行，下载依赖并打基础包：

```bash
mvn clean install
```

#### 2.4 配置说明

后端配置文件位于 `cs-biz/src/main/resources/` 目录：

| 文件 | 说明 |
|------|------|
| `application.yml` | 主配置文件（通用配置） |
| `application-dev.yml` | 开发环境配置 |
| `application-prod.yml` | 生产环境配置 |
| `application-test.yml` | 测试环境配置 |

配置项均支持通过环境变量覆盖，格式为 `${ENV_VAR:默认值}`，核心配置项：

```yaml
# 数据库配置
MYSQL_HOST: 127.0.0.1
MYSQL_PORT: 3306
MYSQL_NAME: base_db
MYSQL_USER_NAME: root
MYSQL_PASS: 123456

# Redis 配置
REDIS_HOST: 127.0.0.1
REDIS_PORT: 6379
REDIS_PASSWORD: 123456
REDIS_DATABASE: 0

# 服务端口
SERVER_PORT: 8080
```

**外部配置文件加载方式**（推荐）：

Spring Boot 支持通过外部 YAML 文件覆盖默认配置，在 IDEA 中配置 VM 参数：

```
-Dspring.config.additional-location=/path/to/your/dev.yml
```

> **注意**：外部配置文件必须是合法的 YAML 格式（键值对使用 `:` 分隔），不要使用 `.env` 风格的 `=` 语法。

#### 2.5 启动服务

运行主启动类 `com.cs.biz.BizBootstrap`，启动成功后访问：

- 接口地址：`http://localhost:8080/api/`
- 接口文档：`http://localhost:8080/api/doc.html`
- 默认账号：**admin** / 密码：**123456**

### 3. 前端项目环境搭建

前端项目位于 `cs-admin-ui/` 目录：

```bash
# 进入前端目录
cd cs-admin-ui

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev
```

前端环境变量配置（`.env.development`）：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `VITE_API_URL` | 接口请求前缀 | `/api` |
| `VITE_PROXY` | 跨域代理目标地址 | `http://127.0.0.1:8080/api` |
| `VITE_ROUTER_MODE` | 路由模式（hash / history） | `hash` |

前端构建：

```bash
# 生产环境打包
pnpm run build:prod
```

[前端项目 admin-ui 详细说明](https://gitee.com/xhbug_cs4380/cs-springcloud-admin/tree/master/cs-admin-ui)

## 三、项目部署

服务器环境要求：JDK 21、Nginx 最新版

### 3.1 后端部署

通过 Maven 打包业务项目，生成 `cs-springboot-admin-server.jar` 部署到云服务器：

```bash
mvn clean install -P prod
```

在 jar 包同级目录创建启动脚本 `start.sh`：

```bash
#!/bin/bash
nohup java -server -Xms256m -Xmx1024m -jar ./cs-springboot-admin-server.jar --spring.profiles.active=prod --spring.config.additional-location=./config.yml >./logs/nohup.out 2>&1 &
```

- 启动：执行 `start.sh`
- 关闭：`kill -9 <PID>`

`config.yml` 为生产环境外部配置文件，覆盖 `application.yml` 中的默认值（如数据库地址、密码等）。

### 3.2 前端部署

在 Nginx 配置文件 `nginx.conf` 中添加以下配置：

```nginx
server {
    listen       80;
    # 公网域名或 IP 地址
    server_name  www.xxxxx.cn;

    location ^~ /api/ {
       # 后端服务地址
       proxy_pass http://localhost:8080;
       proxy_connect_timeout 500s;
       proxy_read_timeout 500s;
       proxy_send_timeout 500s;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location / {
        # 前端项目部署目录（pnpm run build:prod 产物）
        root   /html/cs-admin-ui/;
        index  index.html index.htm;
        try_files $uri $uri/ /index.html;
    }
}
```

### 3.3 密码加密（Jasypt）

项目中敏感配置（如数据库密码）支持使用 Jasypt 加密存储，配置值格式为 `ENC(密文)`。

#### 3.3.1 生成密文

```java
public static void main(String[] args) {
    BasicTextEncryptor textEncryptor = new BasicTextEncryptor();
    // 加密所需的 salt（需与配置文件中 jasypt.encryptor.password 一致）
    textEncryptor.setPassword("xxxxxxxx");
    // 输出加密后的密文，使用 ENC(xxx) 包裹
    System.out.println("ENC(" + textEncryptor.encrypt("123456") + ")");
}
```

#### 3.3.2 Jasypt 配置

```yaml
jasypt:
  encryptor:
    password: xxxxxxxx  # 自定义盐值
    algorithm: PBEWithMD5AndDES
    iv-generator-classname: org.jasypt.iv.NoIvGenerator
```

#### 3.3.3 使用示例

```yaml
spring:
  datasource:
    password: ENC(加密后的密文)
```

## 四、多租户说明

系统内置多租户数据隔离能力，通过 `tenant_id` 字段实现行级隔离。

```yaml
tenant:
  enable: true          # 是否开启多租户
  column: tenant_id     # 租户字段名
  ignoreTables:         # 不参与租户隔离的表
    - base_user
    - base_user_role
    - base_dept
    - sys_dict_type
    - sys_dict_value
    - sys_role
    - sys_menu
    - sys_menu_button
    - sys_tenant
    # ... 其他全局表
```

- 系统表（用户、角色、菜单、字典、租户等）不参与租户隔离，全局共享
- 业务表默认添加 `tenant_id` 字段，自动按租户过滤数据

## 五、项目环境推荐

### 5.1 本地开发工具

- [VSCode 官网下载地址](https://code.visualstudio.com/)
- [IDEA 官网下载地址](https://www.jetbrains.com/idea/download/#section=windows)
- [Node.js 官网下载地址](https://nodejs.org/en/)
- [Maven 安装指南](https://maven.apache.org/download.cgi)

### 5.2 服务器环境

- [CentOS 7 安装 Docker](https://blog.csdn.net/cs4380/article/details/85777416)
- [Docker 中安装 MySQL](https://blog.csdn.net/cs4380/article/details/89928514)
- [Docker 中安装 Redis](https://blog.csdn.net/cs4380/article/details/86582569)
- [CentOS 7 安装 Nginx](https://blog.csdn.net/cs4380/article/details/104551530)

### 5.3 其他推荐

- [OpenJDK 21 安装](https://blog.csdn.net/cs4380/article/details/97497455) 服务器和本地推荐安装一致的 JDK 版本
- [IDEA 配置外部依赖](https://blog.csdn.net/cs4380/article/details/108937132)
  Spring Boot 支持依赖外部文件配置，在 IDEA 中配置 VM 参数 `-Dspring.config.additional-location` 即可

## 六、项目预览图

<table>
    <tr>
        <td><img src="https://gitee.com/xhbug_cs4380/cslc-documentation/raw/master/images/preview/index.png"/></td>
        <td><img src="https://gitee.com/xhbug_cs4380/cslc-documentation/raw/master/images/preview/user_info.png"/></td>
    </tr>
    <tr>
        <td><img src="https://gitee.com/xhbug_cs4380/cslc-documentation/raw/master/images/preview/role.png"/></td>
        <td><img src="https://gitee.com/xhbug_cs4380/cslc-documentation/raw/master/images/preview/menus.png"/></td>
    </tr>
    <tr>
        <td><img src="https://gitee.com/xhbug_cs4380/cslc-documentation/raw/master/images/preview/api.png"/></td>
        <td><img src="https://gitee.com/xhbug_cs4380/cslc-documentation/raw/master/images/preview/user_list.png"/></td>
    </tr>
</table>

## 七、开源协议

本项目采用 [MIT License](LICENSE) 开源协议。