# yao-admin-backend

**Repository Path**: yao-coder/yao-admin-backend

## Basic Information

- **Project Name**: yao-admin-backend
- **Description**: yao-admin-backend 后台系统
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://yao-admin.com
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Yao Admin 后端

![Java](https://img.shields.io/badge/Java-21-orange?logo=openjdk)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.2-green?logo=springboot)
![MySQL](https://img.shields.io/badge/MySQL-8.0+-blue?logo=mysql)
![Redis](https://img.shields.io/badge/Redis-6%2F7-red?logo=redis)
![License](https://img.shields.io/badge/License-MIT-yellow)

**Yao Admin** 后端基于 Spring Boot 的 Maven 多模块单体（modular monolith）设计：运行时由 `yao-admin-server` 聚合启动，构建上按领域拆分子模块，便于边界清晰与后续演进。涵盖用户权限、组织管理、系统监控、IM 聊天、AI 能力、文件管理、支付集成等完整后台功能。

---

## 1. 技术栈与版本

| 技术 | 版本 | 说明 |
| --- | --- | --- |
| Java | 21 | 语言版本（父 `pom` 中 `java.version`） |
| Spring Boot | 3.2.2 | 基础框架 |
| MyBatis-Plus | 3.5.5 | ORM |
| Sa-Token | 1.37.0 | 登录态与权限 |
| MySQL | 8.x | 主库（驱动由 Spring Boot 管理） |
| Redis | 常用 6/7 | 会话等（见 `spring.data.redis`） |
| Hutool | 5.8.25 | 工具类 |
| SpringDoc OpenAPI | 2.8.16 | OpenAPI 3 + Scalar UI |
| Lombok | 1.18.30 | 注解处理 |
| EasyExcel | 3.3.4 | Excel 导入导出 |
| IP2Region | 3.3.7 | IP 归属地查询 |
| Aliyun OSS | 3.17.4 | 阿里云对象存储 |
| MinIO | 8.5.7 | MinIO 对象存储 |
| jsoup | 1.18.3 | HTML 解析（AI 模块） |

其他能力按模块引入（如 Quartz、文件存储客户端等），详见各子模块 `pom.xml`。

---

## 2. 功能模块

### 系统管理

- **用户管理** - 用户增删改查、角色分配、审核、导入导出、密码重置、账号解锁
- **角色管理** - 角色定义、菜单权限分配、数据权限范围
- **菜单管理** - 三级菜单配置（目录/菜单/按钮）、权限标识
- **字典管理** - 数据字典类型与字典项维护
- **系统配置** - 系统基础、注册、登录、密码策略、邮件、短信、支付、安全、日志等全局配置

### 组织管理

- **部门管理** - 树形部门结构、部门负责人
- **岗位管理** - 岗位编码与名称管理

### 系统日志

- **操作日志** - 全量业务操作审计追踪
- **登录日志** - 登录记录与 IP 归属地解析
- **日志审计** - 多维度日志统计与清理

### 系统监控

- **在线用户** - 实时在线会话监控、强制退出
- **定时任务** - Cron 定时任务管理与执行日志
- **缓存监控** - Redis 内存使用与键值分布
- **服务监控** - JVM、线程池、系统资源
- **SQL 监控** - 慢查询追踪、SQL 性能分析、AI 辅助诊断
- **警告/错误监控** - 实时错误日志、链路分析、AI 诊断建议
- **API 访问统计** - 请求量、响应时间、状态码分析

### 前沿新闻

- **每日新闻** - AI 自动聚合 AI/科技资讯（RSS 订阅源），支持正文精简与收藏

### 文件管理

- **文件列表** - 多存储后端（本地/阿里云 OSS/MinIO），支持分片上传

### 消息中心

- **系统消息** - 多渠道推送（站内信/邮件），支持指定用户/部门/全体推送
- **即时聊天** - 私聊与群聊、SSE 实时推送、消息撤回、群组管理

### 开发工具

- **接口文档** - OpenAPI 3.0 + Scalar UI，在线 API 调试

### 认证与安全

- **多方式登录** - 用户名密码 / 手机验证码 / 邮箱验证码 / OAuth (Gitee、Google)
- **用户注册** - 开放注册、邀请码、审核流
- **权限控制** - 基于 RBAC 的菜单 + 按钮级权限
- **数据权限** - 全部/自定义/本部门/本部门及以下/仅本人

### 其他

- **个人中心** - 个人资料、登录设备、OAuth 绑定管理
- **邮件服务** - SMTP 邮件模板、测试发送
- **短信服务** - 阿里云 SMS 验证码、通知
- **支付集成** - 支付宝当面付测试

---

## 3. Maven 模块一览

父工程：`com.yao.admin:yao-admin:1.0.0-SNAPSHOT`（`packaging: pom`）。

| 模块 | 说明 |
| --- | --- |
| **yao-common** | 通用返回体、异常、工具、基础枚举等 |
| **yao-security** | Sa-Token 集成、权限模型、安全相关配置 |
| **yao-auth** | 登录、验证码、认证相关接口 |
| **yao-ai** | AI 能力（如文本翻译等，对接可配置的大模型 HTTP API） |
| **yao-system** | 用户、角色、菜单、字典、部门、岗位、通知、Dashboard、个人中心等 |
| **yao-log** | 操作日志、登录日志、日志审计、请求追踪与访问日志写入、IP 归属地解析等 |
| **yao-monitor** | 在线用户、缓存、服务监控、SQL 执行日志、API 访问统计等 |
| **yao-file** | 文件上传与元数据 |
| **yao-scheduler** | Quartz 定时任务 |
| **yao-message** | 消息/通知等业务能力 |
| **yao-chat** | IM 即时聊天（私聊/群聊、SSE 实时推送、群组管理、在线状态） |
| **yao-mail** | 邮件服务（SMTP 配置、模板管理、测试发送） |
| **yao-pay** | 支付集成（支付宝当面付、沙箱测试） |
| **yao-admin-server** | **唯一启动模块**：`SpringBoot` 入口、全局装配、数据源、第三方文档等 |

扫描包：`com.yao.admin`（见 `YaoAdminApplication`）。

---

## 4. 目录与分层（约定）

各业务模块源码根路径一般为：

```text
yao-xxx/src/main/java/com/yao/admin/xxx/
├── controller/      # HTTP 接口
├── dto/
│   ├── request/
│   └── response/
├── entity/          # 持久化实体（若使用）
├── mapper/          # MyBatis Mapper
├── service/         # 业务服务
│   └── impl/
├── config/          # 模块级配置（可选）
└── support/         # 辅助类型（可选）
```

---

## 5. 模块依赖原则（简述）

- `yao-common` 不依赖任何业务模块。
- 业务模块通常依赖 `yao-common`，鉴权相关依赖 `yao-security`。
- `yao-admin-server` 依赖全部需要对外暴露能力的业务模块，并完成 Bean 装配。
- 避免业务模块间循环依赖；公共能力优先下沉到 `yao-common` 或通过接口 + 启动模块装配。

---

## 6. 本地运行

### 6.1 环境要求

| 环境 | 版本要求 |
|------|---------|
| JDK | 21+ |
| MySQL | 8.0+ |
| Redis | 6.0+ |
| Maven | 3.8+ |

### 6.2 数据库初始化

```bash
# 创建数据库并执行初始化脚本
mysql -u root -p < sql/init.sql
```

脚本会自动创建 `yao_admin` 数据库及全部表结构、初始数据。

### 6.3 编译

```bash
mvn clean compile
# 或只编译启动模块及其依赖
mvn -pl yao-admin-server -am compile
```

### 6.4 启动

```bash
mvn -pl yao-admin-server -am spring-boot:run
```

默认 HTTP 端口：**8080**（`server.port`）。

### 6.5 打包

```bash
mvn -pl yao-admin-server -am package -DskipTests
```

可执行 jar 位于 `yao-admin-server/target/`。

### 6.6 默认管理员账号

| 用户名 | 密码 |
|--------|------|
| `admin` | `admin123456` |

---

## 7. 配置说明

主配置：`yao-admin-server/src/main/resources/application.yml`。

### 7.1 数据源与 Redis

- `spring.datasource.*`：MySQL 连接、账号密码（**生产环境务必用环境变量或外部配置覆盖，勿将真实密码提交仓库**）。
- `spring.data.redis.*`：Redis 连接。

### 7.2 Sa-Token

- `sa-token.token-name` / `token-prefix`：与前端 `Authorization: Bearer <token>` 对齐。
- `timeout` / `active-timeout`：会话与活跃超时。

### 7.3 业务自定义（`yao.*` 前缀示例）

| 配置前缀 | 含义 |
| --- | --- |
| `yao.ai.*` | AI 服务地址、API Key、模型名等（可用环境变量 `YAO_AI_BASE_URL`、`YAO_AI_API_KEY`、`YAO_AI_MODEL` 覆盖） |
| `yao.log.ip-location.*` | 登录日志等 IP 归属地解析（第三方 HTTP、缓存 TTL 等） |
| `yao.monitor.sql.*` | SQL 监控开关、慢 SQL 阈值、落库模式、排除路径等 |

### 7.4 API 文档（Scalar）

- `springdoc.api-docs.path`：OpenAPI JSON 路径（默认 `/v3/api-docs`）。
- `scalar.*`：Scalar 文档 UI（路径、标题等）。

启动后可在浏览器访问 Scalar 文档页（具体路径以 `scalar.path` 为准，如 `/scalar`）。

### 7.5 日志

- `logging.level`：根日志与 `com.yao.admin` 包级别；SQL 相关可包含 `com.yao.admin.sql` 等。

---

## 8. 数据库与脚本

| 位置 | 说明 |
| --- | --- |
| `sql/init.sql` | 库表与基础数据初始化（首次建库使用） |

`init.sql` 包含全部表结构（45 张表）、菜单权限、字典数据、系统配置、日志表月度分区、自动分区维护事件等。新环境执行此脚本即可完成初始化。

涉及数据库变更时，请直接更新 `init.sql`，确保新环境可一键初始化。

---

## 9. API 约定（摘要）

### 9.1 路径前缀

- 对外 REST 接口统一前缀：**`/api/v1`**（具体资源路径见各 `Controller`）。

### 9.2 统一返回体

业务成功时，响应 JSON 中通常包含：

- `code`：**0** 表示业务成功；**非 0** 表示业务失败。
- `message`：提示信息。
- `data`：业务数据。
- `traceId`（若启用）：链路追踪 ID。

分页常见结构：`data.list`、`data.page`、`data.pageSize`、`data.total`。

### 9.3 权限码（示例）

建议形式：`模块:资源:动作`，例如 `system:user:list`、`monitor:sql:list`。

---

## 10. 系统截图

> 截图文件存放于 `docs/screenshots/` 目录，后续逐步补充。

### 登录与注册

| 页面 | 截图 |
|------|------|
| 登录页 | ![登录页](docs/screenshots/login.png) |
| 注册页 | ![注册页](docs/screenshots/register.png) |

### 首页

| 页面 | 截图 |
|------|------|
| 工作台 | ![工作台](docs/screenshots/dashboard.png) |

### 系统管理

| 页面 | 截图 |
|------|------|
| 用户管理 | ![用户管理](docs/screenshots/users.png) |
| 角色管理 | ![角色管理](docs/screenshots/roles.png) |
| 菜单管理 | ![菜单管理](docs/screenshots/menus.png) |
| 字典管理 | ![字典管理](docs/screenshots/dict.png) |

### 组织管理

| 页面 | 截图 |
|------|------|
| 部门管理 | ![部门管理](docs/screenshots/depts.png) |
| 岗位管理 | ![岗位管理](docs/screenshots/posts.png) |

### 系统日志

| 页面 | 截图 |
|------|------|
| 操作日志 | ![操作日志](docs/screenshots/oplog.png) |
| 登录日志 | ![登录日志](docs/screenshots/loginlog.png) |
| 日志审计 | ![日志审计](docs/screenshots/log-audit.png) |

### 系统监控

| 页面 | 截图 |
|------|------|
| 在线用户 | ![在线用户](docs/screenshots/online.png) |
| 定时任务 | ![定时任务](docs/screenshots/tasks.png) |
| 缓存监控 | ![缓存监控](docs/screenshots/cache.png) |
| 服务监控 | ![服务监控](docs/screenshots/service.png) |
| SQL 监控 | ![SQL 监控](docs/screenshots/sql.png) |
| 警告/错误监控 | ![警告/错误监控](docs/screenshots/server.png) |
| API 访问统计 | ![API 访问统计](docs/screenshots/api-stats.png) |

### 前沿新闻

| 页面 | 截图 |
|------|------|
| 每日新闻 | ![每日新闻](docs/screenshots/frontier-news-daily.png) |

### 文件管理

| 页面 | 截图 |
|------|------|
| 文件列表 | ![文件列表](docs/screenshots/files.png) |

### 消息中心

| 页面 | 截图 |
|------|------|
| 系统消息 | ![系统消息](docs/screenshots/notifications.png) |
| 即时聊天 | ![即时聊天](docs/screenshots/chat.png) |

### 系统配置

| 页面 | 截图 |
|------|------|
| 系统配置 | ![系统配置](docs/screenshots/settings-system.png) |
| 安全配置 | ![安全配置](docs/screenshots/settings-security.png) |
| 登录配置 | ![登录配置](docs/screenshots/settings-login.png) |
| 密码配置 | ![密码配置](docs/screenshots/settings-password.png) |
| 注册配置 | ![注册配置](docs/screenshots/settings-register.png) |
| 邮件配置 | ![邮件配置](docs/screenshots/settings-mail.png) |
| 短信配置 | ![短信配置](docs/screenshots/settings-sms.png) |
| 日志配置 | ![日志配置](docs/screenshots/settings-log.png) |
| 文件存储配置 | ![文件存储配置](docs/screenshots/settings-file-storage.png) |
| 支付配置 | ![支付配置](docs/screenshots/settings-payment.png) |

### 个人中心与开发工具

| 页面 | 截图 |
|------|------|
| 个人中心 | ![个人中心](docs/screenshots/profile.png) |
| 修改密码 | ![修改密码](docs/screenshots/change-password.png) |

---

## 11. Git 忽略（后端）

在 **`.gitignore`** 中已忽略：

- `*.class`、`target/`（Maven 编译与构建产物）
- `*.log`（日志文件）

若历史提交中已包含上述文件，需从索引中移除后再提交。

---

## 12. 前端联调

- 前端开发环境通常将 API 代理到本机 **8080**（以实际前端配置为准）。
- 登录后请求头携带 **`Authorization: Bearer <token>`**，与 Sa-Token 配置一致。

---

## 13. 参考

- 父 POM：`pom.xml`
- 启动类：`yao-admin-server/src/main/java/com/yao/admin/YaoAdminApplication.java`
- OpenAPI 与 Scalar：`application.yml` 中 `springdoc`、`scalar` 节点
- [Spring Boot 文档](https://docs.spring.io/spring-boot/docs/current/reference/html/)
- [Sa-Token 文档](https://sa-token.cc/)
- [MyBatis-Plus 文档](https://baomidou.com/)

若需扩展新领域，优先新增子模块并在 `yao-admin-server` 中声明依赖，保持与现有分层一致。