# amaake-auth

**Repository Path**: sirius/amaake-auth

## Basic Information

- **Project Name**: amaake-auth
- **Description**: 开箱即用的 OAuth2 认证中心与授权管理后台。后端基于 Sa-Token OAuth2 + magic-api + Spring Boot 3.4.9 + Java 21，支持四种授权模式、令牌全生命周期管理、令牌内省；前端基于 Vue 3 + Vben Admin v5，内置用户、角色、客户端、接口与系统参数管理，菜单与路由由服务端动态下发。配套SDK 与 magic-api 插件。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# amaake-auth

微服务架构的 **OAuth2 认证中心** 及其 **授权管理后台**。

认证中心基于 Sa-Token OAuth2（v1.46.0）+ magic-api（v2.2.2）+ Spring Boot 3.4.9 + Java 21；管理后台基于 Vue 3 + Vben Admin v5 + antdv-next。

## 一、仓库结构

```
amaake-auth/
├─ amaake-auth/          # 后端（Maven 多模块，OAuth2 认证中心）
│  ├─ amaake-auth-server/                # 授权服务器（登录授权/令牌/内省/magic-api 运行时）
│  ├─ magic-api-plugin-oauth2-starter/   # magic-api 鉴权插件（Redis 共享方案）
│  ├─ amaake-oauth2-client-sdk/          # 资源服务器 SDK（HTTP 内省方案）
│  └─ sql/
│     ├─ init.sql            # ★ 数据库统一初始化脚本（权威）
│     └─ amaake-auth.sql     # 线上库原始备份（对账用）
│
├─ amaake-auth-ui/      # 前端（Vben Admin v5 单仓多应用）
│  ├─ apps/web-antdv-next/               # ★ 授权管理后台（antdv-next 版本）
│  ├─ magic-api-import/system-scripts/    # magic-api 接口脚本源文件（已随 init.sql 入库）
│  ├─ packages/ docs/ ...                # Vben 框架包与上游文档
│  └─ README.md / README.zh-CN.md        # Vben 上游说明（非本项目文档）
│
└─ docs/                # ★ 项目文档（见第四节）
```

## 二、能力概览

| 模块 | 能力 |
|---|---|
| 认证中心 | 授权码 / 隐式 / 密码 / 客户端凭证 四种模式，令牌签发·刷新·吊销、RFC 7662 内省、用户信息端点 |
| 接入方式 | magic-api 插件（共享 Redis，撤销实时生效） / `SaOAuth2Util` / HTTP 内省 SDK |
| 管理后台 | 用户、角色、客户端、操作日志、接口管理（内嵌 magic-api 编辑器）、系统参数 |
| 权限模型 | 应用 → 资源（菜单/按钮/接口）→ 角色 / 用户，菜单与前端路由由 `sys_resource` 动态下发 |
| 系统参数 | `sys_config` 统一管理 sa-token / Cookie / OAuth2 / 前端偏好，支持「恢复默认」与前端优先级策略 |

## 三、快速开始

```bash
# 1) 数据库：建库并执行统一初始化脚本
psql -U postgres -c 'CREATE DATABASE "amaake-auth";'
psql -U postgres -d "amaake-auth" -f amaake-auth/sql/init.sql

# 2) 后端：打包启动（默认端口 9999）
cd amaake-auth
./mvnw.cmd clean package -DskipTests
java -jar amaake-auth-server/target/amaake-auth-0.0.1-SNAPSHOT.jar

# 3) magic-api 接口脚本已随 init.sql 写入 magic_api_file_v2（65 条），无需手工导入；
#    如需按源文件重建：http://localhost:9999/magic/web（管理员登录）→ 导入
#    amaake-auth-ui/magic-api-import/system-scripts/ 下的 *.ms

# 4) 前端：安装并启动（默认端口 5999）
cd ../amaake-auth-ui
pnpm install
pnpm dev
```

默认管理员账号：**`sa` / `123456`**（生产环境务必修改）。

> 数据库初始化细节、magic-api 接口脚本、与线上库的差异说明，见 [docs/01-数据库初始化说明.md](docs/01-数据库初始化说明.md)。

## 四、项目文档

| 文档 | 内容 |
|---|---|
| [docs/01-数据库初始化说明.md](docs/01-数据库初始化说明.md) | 数据库初始化脚本、表结构、magic-api 导入、SQL 整理说明 |
| [docs/02-项目扫描报告.md](docs/02-项目扫描报告.md) | 前后端代码结构扫描与问题清单 |
| [docs/03-系统参数设置方案.md](docs/03-系统参数设置方案.md) | `sys_config` 系统参数设计方案与落地记录 |
| [docs/04-系统管理CRUD检查修复.md](docs/04-系统管理CRUD检查修复.md) | 系统管理模块页面与 magic-api 脚本的检查与补齐记录 |
| [docs/05-后端使用文档.md](docs/05-后端使用文档.md) | 认证中心部署、插件/SDK 接入、端点与安全说明 |
| [docs/06-开源发布检查报告.md](docs/06-开源发布检查报告.md) | 开源前的合规、密钥与仓库卫生检查清单 |
| [docs/07-架构与流程图.md](docs/07-架构与流程图.md) | 分层架构、认证/授权/登出时序、OAuth2 四种模式与 RBAC 模型图 |

## 五、安全注意事项（生产必改）

1. `sys_user` 默认密码、各客户端 `client_secret`（管理后台内置客户端密钥可用环境变量 `ADMIN_CLIENT_SECRET` 覆盖）；
2. PostgreSQL / Redis 账号密码：通过 `DB_PASSWORD`、`REDIS_PASSWORD` 等环境变量注入，**不要把真实口令写进配置文件**；
3. `sa_oauth2_client.allow_redirect_uris` 建议收紧为精确回调地址（当前为 `'*'`）；
4. 认证中心不要暴露在公网；magic-api 编辑器 `/magic/web` 具备脚本执行能力，必须鉴权 + 网关双重限制。

## 六、开源许可与致谢

- 后端（`amaake-auth/`）采用 [Apache-2.0](LICENSE) 许可。
- 前端（`amaake-auth-ui/`）基于 [Vue Vben Admin](https://github.com/vbenjs/vue-vben-admin)（MIT）二次开发，已保留其原始 `LICENSE` 与版权声明。
- 主要第三方：Sa-Token、magic-api、BouncyCastle、Spring Boot。
- 开源发布前请按 [docs/06-开源发布检查报告.md](docs/06-开源发布检查报告.md) 完成处置清单（尤其密钥轮换与 Git 历史清理）。