通用后台管理系统，前后端分离架构，基于 Spring Boot 4.0.5 + Vue 3 构建，提供开箱即用的后台管理基础能力。

技术	版本	说明
Java	25	运行环境
Spring Boot	4.0.5	基础框架
Spring Security	(parent)	认证与授权
Spring Validation	(parent)	参数校验（JSR 380）
Spring Data Redis	(parent)	缓存与会话管理
Spring Actuator	(parent)	健康检查与监控端点
MyBatis-Plus	3.5.16	ORM 框架
Flyway	(parent)	数据库版本迁移
MySQL Connector	9.6.0	关系型数据库驱动
JWT (jjwt)	0.13.0	无状态认证
SpringDoc OpenAPI	3.0.2	API 文档（Swagger UI）
Hutool	5.8.44	工具类库
Lombok	(parent)	简化代码
Jackson	3.x (parent)	JSON 序列化

*(parent)* 表示版本由 spring-boot-starter-parent:4.0.5 统一管理，无需手动指定。

技术	版本	说明
Vue	3.4	渐进式 JavaScript 框架
TypeScript	5.4	类型安全的 JavaScript 超集
Vite	5.2	前端构建工具
Element Plus	2.7	UI 组件库
Pinia	2.1	状态管理
Vue Router	4.3	路由管理
Axios	1.7	HTTP 请求库
Vitest	4.1	单元测试框架
ESLint	9.0	代码检查工具
Prettier	3.3	代码格式化工具

• 用户管理 — 用户的增删改查、分页查询
• 角色管理 — 角色定义与权限分配
• 菜单管理 — 菜单树维护（目录/菜单/按钮）
• 部门管理 — 组织架构树管理
• 岗位管理 — 岗位编码与排序
• 字典管理 — 系统字典类型与字典数据维护
• 参数配置 — 系统级配置项管理

• 登录/登出 — 用户名密码登录，支持验证码
• JWT Token — 基于 Token 的无状态认证
• 权限控制 — 基于 RBAC 的接口级权限校验

• 在线用户 — 当前在线用户管理
• 服务监控 — 服务器运行状态信息（CPU、内存、磁盘等）
• 缓存监控 — Redis 缓存信息查看与管理

• 操作日志 — 系统操作审计日志
• 登录日志 — 用户登录记录查询

• 通知公告 — 系统公告发布与管理
• 文件管理 — 文件上传与记录管理

src/main/java/com/blacshade/baseadmin/
├── BaseAdminApplication.java          # 启动类
├── auth/                              # 认证模块
│   ├── controller/AuthController.java
│   ├── dto/                           # 登录请求/响应、验证码 VO
│   └── service/AuthService.java
├── common/                            # 通用模块
│   ├── annotation/                    # 自定义注解（@Log, @RateLimiter）
│   ├── aspect/                        # AOP 切面（日志、限流）
│   ├── base/                          # 基础类（BaseEntity, BaseMapper, BaseService）
│   ├── config/                        # 配置类（CORS, Security, Redis, MyBatis-Plus 等）
│   ├── constant/                      # 常量定义
│   ├── enums/                         # 枚举（BusinessType, UserStatus）
│   ├── exception/                     # 全局异常处理
│   ├── filter/                        # JWT 认证过滤器
│   ├── result/R.java                  # 统一响应封装
│   └── util/                          # 工具类（JWT, Redis, IP, Tree）
├── file/                              # 文件管理模块
├── log/                               # 日志模块（操作日志 + 登录日志）
├── monitor/                           # 系统监控模块
├── notice/                            # 通知公告模块
└── system/                            # 系统管理模块（用户/角色/菜单/部门/岗位/字典/配置）

src/main/resources/
├── application.yml                    # 主配置
├── application-dev.yml                # 开发环境配置
├── application-prod.yml               # 生产环境配置
├── db/
│   ├── migration/                     # Flyway 数据库迁移脚本
│   │   ├── V1__init_schema.sql        #   V1: 建表语句
│   │   └── V2__init_data.sql          #   V2: 初始数据
│   ├── schema.sql                     # 原始建表脚本（仅供参考）
│   └── data.sql                       # 原始数据脚本（仅供参考）
└── mapper/system/                     # MyBatis XML 映射文件

web/
├── src/
│   ├── main.ts                        # 应用入口
│   ├── App.vue                        # 根组件
│   ├── api/                           # API 接口层（按模块划分）
│   │   ├── auth.ts                    #   认证相关接口
│   │   ├── user.ts                    #   用户管理接口
│   │   └── ...                        #   其他模块接口
│   ├── layout/                        # 布局组件
│   │   ├── index.vue                  #   主布局
│   │   └── components/                #   布局子组件（Header, Sidebar, TabsView）
│   ├── router/                        # 路由配置
│   ├── stores/                        # Pinia 状态管理
│   │   ├── user.ts                    #   用户状态
│   │   ├── app.ts                     #   应用状态
│   │   └── tabs.ts                    #   标签页状态
│   ├── styles/                        # 全局样式
│   │   ├── global.css                 #   全局样式
│   │   └── variables.css              # CSS 变量
│   ├── types/                         # TypeScript 类型定义
│   ├── utils/                         # 工具函数（request, auth）
│   ├── views/                         # 页面组件（按模块划分）
│   │   ├── login/                     #   登录页
│   │   ├── dashboard/                 #   仪表盘
│   │   ├── system/                    #   系统管理页面
│   │   ├── log/                       #   日志页面
│   │   ├── monitor/                   #   监控页面
│   │   └── ...                        #   其他模块页面
│   └── __tests__/                     # 前端单元测试
├── index.html                         # HTML 入口
├── vite.config.ts                     # Vite 配置
├── tsconfig.json                      # TypeScript 配置
├── eslint.config.js                   # ESLint 配置
├── .prettierrc.json                   # Prettier 配置
└── Dockerfile                         # 前端 Docker 构建

工具	版本	说明
JDK	25+	后端运行环境
Maven	3.8+	后端构建工具
Node.js	20+	前端运行环境
npm	9+	前端包管理器
MySQL	8.0+	关系型数据库
Redis	6.0+	缓存服务

创建数据库 base_admin（字符集 utf8mb4），表结构将在应用首次启动时由 Flyway 自动创建并初始化。

Flyway 会自动执行 src/main/resources/db/migration/ 下的迁移脚本，无需手动导入 SQL。

如需手动初始化，可执行原始 SQL 文件：

mysql -u root -p < src/main/resources/db/schema.sql
mysql -u root -p base_admin < src/main/resources/db/data.sql

编辑 src/main/resources/application-dev.yml，修改数据库和 Redis 连接信息：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/base_admin?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: your_username
    password: your_password
  data:
    redis:
      host: localhost
      port: 6379

mvn spring-boot:run

启动成功后访问：

• 接口文档：http://localhost:8080/swagger-ui.html
• API 文档 JSON：http://localhost:8080/v3/api-docs

# 进入前端目录
cd web

# 安装依赖
npm install

# 启动开发服务器
npm run dev

启动成功后访问：http://localhost:3000

前端开发服务器会自动代理 API 请求到后端（http://localhost:8080），无需额外配置跨域。

# 1. 复制环境变量配置并填写实际值
cp .env.example .env
# 编辑 .env 文件，设置 JWT_SECRET、DB_PASSWORD、REDIS_PASSWORD 等

# 2. 一键启动所有服务
docker compose up -d

# 3. 查看服务状态
docker compose ps
docker compose logs -f backend

部署成功后访问：

• 前端页面：http://yourdomain.com
• 后端 API：http://yourdomain.com/api/

生产环境请确保通过反向代理（如 Nginx）配置 HTTPS，并设置正确的 CORS_ALLOWED_ORIGINS。

使用 Docker 部署前，请务必修改 .env 文件中的以下配置：

配置项	说明	安全建议
JWT_SECRET	JWT 签名密钥	使用随机字符串，至少 32 个字符
DB_PASSWORD	MySQL root 密码	使用强密码，不要使用默认值
REDIS_PASSWORD	Redis 密码	使用强密码
CORS_ALLOWED_ORIGINS	CORS 允许域名	设置为你的实际域名

可以使用 openssl rand -hex 32 生成安全的随机密钥。

• 通过反向代理（Nginx）配置 HTTPS 证书
• 定期备份数据库（docker exec base-admin-mysql mysqldump -u root -p base_admin > backup.sql）
• 修改默认管理员密码（默认 admin / admin123）

以下列出 pom.xml 中声明的 全部依赖，包含完整的 Maven 坐标、版本和作用域，供上线部署核对。

父 POM：

属性	值
groupId	org.springframework.boot
artifactId	spring-boot-starter-parent
version	4.0.5

版本属性（properties）：

属性名	版本	说明
java.version	25	JDK 版本
mybatis-plus.version	3.5.16	MyBatis-Plus ORM
jjwt.version	0.13.0	JWT 认证库
springdoc.version	3.0.2	OpenAPI 文档
hutool.version	5.8.44	工具类库
mysql.version	9.6.0	MySQL 驱动

编译依赖（scope: compile）：

#	groupId	artifactId	版本	说明
1	org.springframework.boot	spring-boot-starter-web	(parent)	Web/REST 框架（内嵌 Tomcat）
2	org.springframework.boot	spring-boot-starter-security	(parent)	认证与授权框架
3	io.jsonwebtoken	jjwt-api	0.13.0	JWT API 接口定义
4	com.baomidou	mybatis-plus-spring-boot4-starter	3.5.16	MyBatis-Plus ORM（适配 Spring Boot 4.x）
5	org.springframework.boot	spring-boot-starter-data-redis	(parent)	Redis 缓存集成（Lettuce 客户端）
6	org.springframework.boot	spring-boot-starter-validation	(parent)	Bean 参数校验（Hibernate Validator）
7	org.springdoc	springdoc-openapi-starter-webmvc-ui	3.0.2	OpenAPI 3.0 / Swagger UI
8	org.springframework.boot	spring-boot-starter-actuator	(parent)	健康检查、指标暴露、监控端点
9	cn.hutool	hutool-all	5.8.44	通用工具类库（包含 IO、加密、HTTP 等）
10	org.projectlombok	lombok	(parent)	代码生成（@Data, @Getter 等），optional
11	org.springframework.boot	spring-boot-starter-flyway	(parent)	数据库版本迁移（Flyway）

运行时依赖（scope: runtime）：

#	groupId	artifactId	版本	说明
11	io.jsonwebtoken	jjwt-impl	0.13.0	JWT 运行时实现
12	io.jsonwebtoken	jjwt-jackson	0.13.0	JWT Jackson 序列化支持
13	com.mysql	mysql-connector-j	9.6.0	MySQL JDBC 驱动

测试依赖（scope: test）：

#	groupId	artifactId	版本	说明
14	org.springframework.boot	spring-boot-starter-test	(parent)	测试框架（JUnit 5, Mockito, AssertJ）
15	org.springframework.security	spring-security-test	(parent)	Security 测试工具

运行时依赖（dependencies）：

#	包名	版本	说明
1	vue	^3.4.0	渐进式 JavaScript 框架
2	vue-router	^4.3.0	客户端路由管理
3	pinia	^2.1.0	状态管理
4	element-plus	^2.7.0	UI 组件库
5	@element-plus/icons-vue	^2.3.0	Element Plus 图标集
6	axios	^1.7.0	HTTP 请求库

开发依赖（devDependencies）：

#	包名	版本	说明
7	typescript	^5.4.0	TypeScript 编译器
8	vite	^5.2.0	前端构建工具
9	vue-tsc	^2.0.0	Vue TypeScript 类型检查
10	@vitejs/plugin-vue	^5.0.0	Vite Vue 插件
11	vitest	^4.1.2	单元测试框架
12	@vue/test-utils	^2.4.6	Vue 组件测试工具
13	eslint	^9.0.0	代码检查
14	@eslint/js	^9.0.0	ESLint JS 规则
15	@typescript-eslint/parser	^8.0.0	TypeScript ESLint 解析器
16	eslint-plugin-vue	^9.28.0	Vue ESLint 规则
17	eslint-config-prettier	^10.0.0	ESLint + Prettier 兼容配置
18	prettier	^3.3.0	代码格式化
19	jsdom	^29.0.1	DOM 模拟（测试环境）
20	happy-dom	^20.8.9	DOM 模拟（测试环境，轻量替代）

模块	路径	说明
认证	POST /auth/login	用户登录
认证	POST /auth/logout	用户登出
认证	GET /auth/captcha	获取验证码
用户	GET /system/user/list	用户列表（分页）
用户	GET /system/user/{id}	用户详情
用户	POST /system/user	新增用户
用户	PUT /system/user	修改用户
用户	DELETE /system/user/{ids}	删除用户
角色	/system/role/**	角色管理
菜单	/system/menu/**	菜单管理
部门	/system/dept/**	部门管理
岗位	/system/post/**	岗位管理
字典	/system/dict/**	字典管理
字典项	/system/dict-item/**	字典数据管理
配置	/system/config/**	参数配置管理
操作日志	/log/oper/**	操作日志查询
登录日志	/log/login/**	登录日志查询
通知公告	/notice/**	公告管理
文件	/file/**	文件上传与管理
监控	/monitor/**	系统监控

采用 JWT + Spring Security 实现无状态认证：

• 登录成功后返回 JWT Token
• 请求头携带 Authorization: Bearer <token> 进行身份校验
• Token 存储于 Redis 中，支持主动失效

所有接口统一返回 R<T> 格式：

{
  "code": 200,
  "message": "操作成功",
  "data": {}
}

使用 MyBatis-Plus 逻辑删除功能，deleted 字段：

• 0 — 未删除
• 1 — 已删除

所有实体表统一包含审计字段：create_time、update_time、create_by、update_by，通过 MyBatis-Plus MetaHandler 自动填充。

• @Log — 操作日志记录，自动记录业务操作类型
• @RateLimiter — 接口限流，防止恶意请求

变量名	默认值	说明
JWT_SECRET	（无默认值，必须设置）	JWT 签名密钥，至少 32 个字符
JWT_EXPIRATION	86400000	Token 过期时间（毫秒），默认 24 小时
CORS_ALLOWED_ORIGINS	https://yourdomain.com	CORS 允许的域名（逗号分隔）
REDIS_PASSWORD	（无默认值，必须设置）	Redis 密码

MIT