# cs-springcloud-admin

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

## Basic Information

- **Project Name**: cs-springcloud-admin
- **Description**: 基础的RBAC权限微服务管理系统，前后端分离项目
后端项目基于Spring Cloud、OAuth2、Nacos、Spring Boot、Spring MVC、MyBatis
前端项目基于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**: 72
- **Forks**: 25
- **Created**: 2019-12-10
- **Last Updated**: 2026-06-21

## Categories & Tags

**Categories**: authority-management

**Tags**: None

## README

# cs-springcloud-admin

<p align="left">
  <a href="https://gitee.com/xhbug_cs4380/cs-springcloud-admin" target="_blank">
    <img src="https://img.shields.io/badge/version-1.4.0-blue.svg" alt="version">
  </a>
  <a href="https://www.oracle.com/java/" target="_blank">
    <img src="https://img.shields.io/badge/Java-21-orange.svg" alt="Java">
  </a>
  <a href="https://spring.io/projects/spring-boot" target="_blank">
    <img src="https://img.shields.io/badge/Spring%20Boot-3.5.15-brightgreen.svg" alt="Spring Boot">
  </a>
  <a href="https://spring.io/projects/spring-cloud" target="_blank">
    <img src="https://img.shields.io/badge/Spring%20Cloud-2025.0.2-brightgreen.svg" alt="Spring Cloud">
  </a>
  <a href="https://github.com/alibaba/nacos" target="_blank">
    <img src="https://img.shields.io/badge/Nacos-3.2.2-ff69b4.svg" alt="Nacos">
  </a>
  <a href="https://github.com/alibaba/p3c" target="_blank">
    <img src="https://img.shields.io/badge/code%20style-Alibaba%20p3c-orange.svg" alt="code style">
  </a>
</p>

## 项目简介

基于 **Spring Cloud 2025 + Spring Boot 3.5** 的微服务 RBAC 权限管理系统，采用前后端分离架构，提供开箱即用的后台管理解决方案。

> 欢迎感兴趣的小伙伴参与交流学习！

---

## 目录结构

```text
cs-springcloud-admin
├── cs-admin                   # 后台管理服务
│   ├── cs-admin-api           # 公共 API 模块（DTO、VO、Model）
│   └── cs-admin-server        # 业务服务端（Controller、Service、Mapper）
├── cs-auth                    # 认证授权服务
│   ├── cs-auth-client         # 认证客户端 SDK（注解、过滤器）
│   └── cs-auth-server         # 认证服务端
├── cs-base                    # 基础公共模块
│   ├── cs-base-common         # 公共工具包（常量、异常、工具类）
│   └── cs-base-core           # 核心业务基类（Biz 基类、配置）
├── cs-gateway                 # 网关服务（Spring Cloud Gateway）
├── cs-admin-ui                # 前端项目（React 19 + Vite 5）
└── doc                        # 项目文档与数据库脚本
    └── db                     # SQL 脚本（建表 + 初始化数据）
```

---

## 技术栈

### 后端技术

| 分类 | 技术 | 版本 |
|------|------|------|
| 核心框架 | Spring Boot | 3.5.15 |
| 微服务 | Spring Cloud | 2025.0.2 |
| 注册配置中心 | Spring Cloud Alibaba + Nacos | 2025.0.0.0 / 3.2.2 |
| 认证授权 | OAuth2 + JWT（java-jwt） | 4.5.0 |
| ORM 框架 | MyBatis-Plus | 3.5.12 |
| 数据库连接池 | Druid | 1.2.28 |
| 数据库 | MySQL | 8.0+ |
| 缓存 | Redis | 6.0+ |
| API 文档 | Knife4j（OpenAPI 3） | 4.4.0 |
| JSON 处理 | FastJSON2 / Gson | 2.0.61 / 2.13.1 |
| 配置加密 | Jasypt | 3.0.4 |
| 构建工具 | Maven + flatten-maven-plugin | 3.14.0 + |
| 运行环境 | OpenJDK | 21 |

### 前端技术

| 分类 | 技术 | 版本 |
|------|------|------|
| 框架 | React | 19.x |
| 构建工具 | Vite | 5.x |
| 语言 | TypeScript | 5.x |
| UI 组件库 | Ant Design | 6.x |
| 状态管理 | Redux Toolkit + redux-persist | 2.x |
| 路由 | React Router DOM | 6.x |
| 图表 | ECharts | 6.x |
| 国际化 | i18next + react-i18next | 26.x / 14.x |
| 富文本 | wangEditor | 5.x |
| HTTP 请求 | Axios | 1.x |
| 包管理器 | pnpm | - |

---

## 功能特性

### 后端服务

- **cs-admin（后台管理）**
  - 用户管理：账号增删改查、状态管理
  - 组织机构：树形组织结构管理
  - 角色权限管理：基于 RBAC 的角色分配与权限控制
  - 菜单管理：动态菜单树配置，支持按钮级权限
  - 数据字典：系统字典数据维护

- **cs-auth（认证授权）**
  - 登录验证：支持验证码、JWT Token 签发
  - Token 验证：网关层统一鉴权，下游服务信任透传
  - 注解支持：`@EnableAuthFilter` 注解式鉴权配置

- **cs-gateway（网关服务）**
  - 统一入口：请求路由、负载均衡
  - 全局鉴权：JWT Token 校验与用户信息透传

### 前端管理界面

- 四种布局模式（经典、纵向、横向、分栏）
- 暗黑模式切换
- 国际化支持（中/英）
- 动态权限菜单
- 按钮级权限控制

---

## 开发环境搭建

### 环境要求

| 工具 | 版本要求 |
|------|---------|
| OpenJDK | 21+ |
| Node.js | 20+ |
| pnpm | 最新稳定版 |
| MySQL | 8.0+ |
| Redis | 6.0+ |
| Nacos | 3.2.2 |
| Maven | 3.9+ |

### 快速开始

#### 1. 初始化数据库

```shell
# 1. 创建数据库（MySQL 8.0+）
# 2. 执行建表脚本
mysql -u root -p < doc/db/cs_admin.sql
mysql -u root -p < doc/db/cs_auth.sql

# 3. 导入 Nacos 配置库
mysql -u root -p < doc/db/cs_nacos.sql

# 4. 执行初始化数据
mysql -u root -p < doc/db/init/init_admin.sql
mysql -u root -p < doc/db/init/init_auth.sql
mysql -u root -p < doc/db/init/init_nacos.sql
```

#### 2. 启动 Nacos

推荐使用 Nacos 3.2.2 稳定版，启动后通过 Web 控制台修改各服务的数据库配置。

#### 3. 打包项目

```shell
# 在项目根目录执行，下载依赖并本地安装
mvn clean install
```

#### 4. 启动服务

按以下顺序依次启动：

1. **nacos** — 注册配置中心
2. **cs-admin** — 后台管理服务
3. **cs-auth** — 认证授权服务
4. **cs-gateway** — 网关服务

> **默认账号密码**：admin / 123456

#### 5. 启动前端

```shell
cd cs-admin-ui
pnpm install
pnpm dev
```

### IDEA 配置

- 安装 **Lombok** 插件（注解处理）
- 配置外部依赖：通过环境变量 `NACOS_SERVER_ADDR`、`NACOS_SERVER_PORT` 等方式覆盖默认配置

---

## 服务配置

各服务默认配置可通过环境变量覆盖：

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `MYSQL_HOST` | MySQL 地址 | 127.0.0.1 |
| `MYSQL_PORT` | MySQL 端口 | 3306 |
| `MYSQL_NAME` | 数据库名 | cs_admin |
| `MYSQL_USER_NAME` | 数据库用户名 | root |
| `MYSQL_PASS` | 数据库密码 | 123456 |
| `REDIS_HOST` | Redis 地址 | 127.0.0.1 |
| `REDIS_PORT` | Redis 端口 | 6379 |
| `REDIS_PASSWORD` | Redis 密码 | 123456 |
| `REDIS_DATABASE` | Redis 数据库编号 | 1 |
| `NACOS_SERVER_ADDR` | Nacos 地址 | localhost |
| `NACOS_SERVER_PORT` | Nacos 端口 | 8848 |
| `NACOS_NAMESPACE` | Nacos 配置命名空间 | dev |
| `SERVER_PORT` | 服务端口（cs-admin） | 3522 |

---

## 项目部署

### 后端部署

```shell
# Maven 打包
mvn clean install -DskipTests

# 启动（以 cs-admin 为例）
nohup java -jar ./cs-admin/target/cs-admin.jar > ./logs/nohup.out 2>&1 &
```

### 前端部署

```shell
cd cs-admin-ui
pnpm build:prod
```

将 `dist` 目录部署至 Nginx：

```nginx
server {
    listen       80;
    server_name  www.example.com;

    location /api/ {
        proxy_pass http://localhost:8081;
        proxy_connect_timeout 500s;
        proxy_read_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 / {
        root /html/cs-admin-ui/;
        index  index.html index.htm;
    }
}
```

### 配置加密

使用 Jasypt 加密敏感配置：

```java
BasicTextEncryptor textEncryptor = new BasicTextEncryptor();
textEncryptor.setPassword("your-salt");
System.out.println("ENC(" + textEncryptor.encrypt("123456") + ")");
```

```yaml
jasypt:
  encryptor:
    password: your-salt
    algorithm: PBEWithMD5AndDES
    iv-generator-classname: org.jasypt.iv.NoIvGenerator
```

```yaml
spring:
  datasource:
    password: ENC(encrypted-value)
```

---

## 更新记录

### 1.4.0（当前版本）

- Spring Boot 升级至 3.5.15
- Spring Cloud 升级至 2025.0.2
- Spring Cloud Alibaba 升级至 2025.0.0.0
- OpenJDK 升级至 21
- MyBatis-Plus 升级至 3.5.12
- Druid 升级至 1.2.28
- mysql-connector-j 升级至 9.2.0
- 前端 React 升级至 19.x、Ant Design 升级至 6.x、Vite 升级至 5.x

### 更早版本

- [查看完整更新记录](https://gitee.com/xhbug_cs4380/cs-springcloud-admin/releases)

---

## 代码规范

本项目采用 [阿里巴巴 Java 开发手册（p3c）](https://github.com/alibaba/p3c/)，建议开发时安装对应 IDE 插件检查代码。

---

## 项目预览

<table>
    <tr>
        <td><img src="https://gitee.com/xhbug_cs4380/cs-documentation/raw/master/images/preview/index.png" alt="首页"/></td>
        <td><img src="https://gitee.com/xhbug_cs4380/cs-documentation/raw/master/images/preview/user_info.png" alt="用户信息"/></td>
    </tr>
    <tr>
        <td><img src="https://gitee.com/xhbug_cs4380/cs-documentation/raw/master/images/preview/role.png" alt="角色管理"/></td>
        <td><img src="https://gitee.com/xhbug_cs4380/cs-documentation/raw/master/images/preview/menus.png" alt="菜单管理"/></td>
    </tr>
    <tr>
        <td><img src="https://gitee.com/xhbug_cs4380/cs-documentation/raw/master/images/preview/api.png" alt="API文档"/></td>
        <td><img src="https://gitee.com/xhbug_cs4380/cs-documentation/raw/master/images/preview/user_list.png" alt="用户列表"/></td>
    </tr>
</table>

---

## 交流与贡献

- 作者：cs4380（cs4380@163.com）
- 仓库：[https://gitee.com/xhbug_cs4380/cs-springcloud-admin](https://gitee.com/xhbug_cs4380/cs-springcloud-admin)
- 欢迎提交 [Issue](https://gitee.com/xhbug_cs4380/cs-springcloud-admin/issues) 或 Pull Request

---

## License

[Apache License 2.0](LICENSE)