figmar
187 lines
7.7 KiB
Markdown
187 lines
7.7 KiB
Markdown
# apes-Authon-Server — 账权独立服务后端
|
||
|
||
> Spring Boot 独立账权服务平台 — 认证 / 授权 / 用户 / 角色 / 权限 / 多租户 / SSO
|
||
> **已通过编译验证**，可作为独立微服务运行
|
||
|
||
## 项目背景
|
||
|
||
apes-Authon 是一套从单体应用中提取的纯净认证授权服务，包含完整的用户管理、角色权限、菜单体系、多租户、客户套餐和 SSO 单点登录能力。本服务与业务系统零直接耦合，通过 Token + Redis 会话实现独立认证。
|
||
|
||
### 核心特性
|
||
|
||
- **多租户架构**：基于 `@TenantSource` AOP 切面 + dynamic-datasource 实现运行时数据源切换
|
||
- **认证体系**：`@Login` 注解 + `AuthContext` ThreadLocal + Redis 会话，业务代码无感知
|
||
- **权限模型**：菜单 → 权限码 → 角色 → 成员角色的四级权限体系
|
||
- **SSO 集成**：内置伙伴云单点登录 Token 交换
|
||
- **外部 API 鉴权**：AccessToken 机制，支持 Bearer / X-Access-Token 两种方式
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Spring Boot | 2.2.1.RELEASE | Web 框架 |
|
||
| Java | 11 | 运行时 |
|
||
| MyBatis Plus | 3.5.7 | ORM |
|
||
| dynamic-datasource | 3.6.1 | 多租户数据源切换 |
|
||
| Redisson | 3.35.0 | Redis 客户端 / 分布式锁 |
|
||
| Hutool | 5.8.16 | 通用工具 |
|
||
| Lombok | 1.18.40 | 代码简化 |
|
||
|
||
## 代码结构
|
||
|
||
```
|
||
src/main/java/cn/apes/
|
||
├── AuthonApplication.java # 主启动类
|
||
├── commons/ # apes-commons 内联实现（原外部 JAR）
|
||
│ ├── Res.java # 统一 API 响应封装
|
||
│ ├── auth/
|
||
│ │ ├── AuthContext.java # ThreadLocal 认证上下文
|
||
│ │ ├── Login.java # @Login 注解
|
||
│ │ ├── LoginAspect.java # 登录认证 AOP 切面
|
||
│ │ ├── LoginUser.java # 登录用户信息
|
||
│ │ ├── LoginCustomer.java # 登录客户/企业信息
|
||
│ │ └── UserSession.java # 会话对象
|
||
│ └── domain/
|
||
│ └── DbEntity.java # 基础实体（id/createTime/updateTime/isDel）
|
||
└── authon/ # 账权业务代码
|
||
├── controller/ # 11 个 Controller
|
||
│ ├── UserController.java # 用户认证（登录/注册/改密/多企业切换）
|
||
│ ├── PermissionController.java # 权限管理（菜单/权限码/角色/成员角色）
|
||
│ ├── AccessTokenController.java # 外部 API Token 管理
|
||
│ ├── CustomerController.java # 客户/企业管理
|
||
│ ├── CustomerPackageController.java # 客户套餐管理
|
||
│ ├── AppController.java # 应用管理
|
||
│ ├── SysOrganizationController.java # 组织架构
|
||
│ ├── SysPackagePlanController.java # 套餐方案
|
||
│ ├── SysQuotaController.java # 配额模板
|
||
│ ├── SysOperationLogController.java # 操作日志
|
||
│ └── UserPreferenceController.java # 用户偏好
|
||
├── domain/
|
||
│ ├── entity/ # 23 个实体类
|
||
│ ├── dto/ # 12 个 DTO（含公共 PageDTO）
|
||
│ ├── vo/ # 3 个 VO
|
||
│ └── huoban/ # 11 个伙伴云 API 模型（SSO 依赖）
|
||
├── service/ # 7 个 Service 接口
|
||
│ └── impl/ # 18 个 Service 实现
|
||
├── mapper/ # 23 个 Mapper
|
||
├── config/ # 5 个配置类
|
||
│ ├── AccessTokenFilterConfig.java # Token 过滤器注册
|
||
│ ├── DataSourceHeaderAspect.java # 多租户数据源 AOP 切面
|
||
│ ├── TenantSource.java # @TenantSource 注解
|
||
│ ├── HbTokenContext.java # 伙伴云 Token ThreadLocal
|
||
│ └── SiteConfig.java # 站点配置
|
||
├── filter/
|
||
│ └── AccessTokenFilter.java # 外部 API 鉴权过滤器
|
||
└── util/
|
||
├── OperationLogUtil.java # 操作日志工具
|
||
└── RsaUtil.java # RSA 加解密工具
|
||
```
|
||
|
||
## apes-commons 内联说明
|
||
|
||
原 `apes-commons 0.0.7-SNAPSHOT` 外部 JAR 已内联为 `cn.apes.commons` 包，共 8 个类：
|
||
|
||
| 类 | 说明 |
|
||
|----|------|
|
||
| `Res` | 统一 API 响应包装（success/fail/error/get） |
|
||
| `AuthContext` | ThreadLocal 认证上下文，存储 UserSession |
|
||
| `UserSession` | 会话对象（LoginUser + LoginCustomer + token） |
|
||
| `LoginUser` | 登录用户信息（id/nickName/phone/portrait/email） |
|
||
| `LoginCustomer` | 登录客户/企业信息（id/customerName/customerType...） |
|
||
| `@Login` | 方法/类级注解，AOP 自动注入登录信息 |
|
||
| `LoginAspect` | 登录认证 AOP 切面（从 Redis 读取会话 → 写入 AuthContext） |
|
||
| `DbEntity` | 基础实体（id / createTime / updateTime / isDel） |
|
||
|
||
**LoginAspect 工作流程**：
|
||
1. 拦截 `@Login` 注解的 Controller 类/方法
|
||
2. 从请求头读取 `token`
|
||
3. 查 Redis 获取用户信息（key=token）和客户信息（key=token:customer）
|
||
4. 组装 `UserSession` 写入 `AuthContext` ThreadLocal
|
||
5. 业务方法执行完毕后清理 `AuthContext`
|
||
|
||
## 已完成的阶段
|
||
|
||
### Phase 1: apes-commons 内联 ✅
|
||
- 反推 7 个核心类接口（AuthContext/Login/LoginUser/LoginCustomer/UserSession/Res/DbEntity）
|
||
- 实现 LoginAspect AOP 切面
|
||
- 移除外部 JAR 依赖，pom.xml 无需手动安装
|
||
|
||
### Phase 2: 包名重构 ✅
|
||
- `cn.apes.cloud` → `cn.apes.authon` 全局包名重构
|
||
- `@MapperScan` 路径更新
|
||
- application.yml 配置更新
|
||
- 零 `cn.apes.cloud` 残留
|
||
|
||
### Phase 3: 编译验证 ✅
|
||
- maven-compiler-plugin 升级至 3.13.0（兼容 Java 24）
|
||
- Lombok 升级至 1.18.40（兼容 Java 24）
|
||
- 移除 `syncAllTenantsToHuoban()` 伙伴云同步（业务集成，非账权核心）
|
||
- 创建 `IpLocationService` 接口 + 桩实现
|
||
- **124 个源文件编译通过**
|
||
|
||
### Phase 4: 提交推送 ✅
|
||
- 代码推送到 Gitea 组织仓库
|
||
|
||
## 待完成事项
|
||
|
||
### Phase 5: 模块补充
|
||
- [ ] AI 助手/LLM 模块提取（~54 Java 文件）
|
||
- [ ] 伙伴云表单配置模块提取（5 Controller + 7 .vue + 1 API）
|
||
|
||
### Phase 6: SDK 化
|
||
- [ ] 将 `AuthContext` 改造为可远程调用的 SDK
|
||
- [ ] 提供 `authon-sdk` 模块供业务系统引用
|
||
- [ ] Token 校验改为 HTTP API 调用
|
||
|
||
### Phase 7: 网关集成
|
||
- [ ] 接入 API 网关（Spring Cloud Gateway / Nginx）
|
||
- [ ] 请求头注入认证信息（替代 ThreadLocal）
|
||
- [ ] 多租户数据源改为网关路由模式
|
||
|
||
## 从原项目提取的文件清单
|
||
|
||
共 **124 个 Java 文件**（含 8 个内联 commons 类 + 2 个新增桩实现）：
|
||
|
||
| 类型 | 数量 |
|
||
|------|------|
|
||
| Controller | 11 |
|
||
| Entity | 23 |
|
||
| DTO | 12 |
|
||
| VO | 3 |
|
||
| Service 接口 | 7 |
|
||
| Service 实现 | 18 |
|
||
| Mapper | 23 |
|
||
| Config | 5 |
|
||
| Filter | 1 |
|
||
| Util | 2 |
|
||
| Huoban DTO | 11 |
|
||
| commons 内联 | 8 |
|
||
| 主启动类 | 1 |
|
||
|
||
## 编译方式
|
||
|
||
```bash
|
||
# 直接编译（无需安装外部 JAR）
|
||
mvn clean compile
|
||
|
||
# 打包
|
||
mvn clean package -DskipTests
|
||
|
||
# 运行
|
||
java -jar target/apes-authon.jar
|
||
```
|
||
|
||
服务默认端口 `8090`，context-path `/authon`。
|
||
|
||
## 关联仓库
|
||
|
||
| 仓库 | 说明 | 地址 |
|
||
|------|------|------|
|
||
| apes-Authon-Server | 后端账权服务（本仓库） | https://gitea.apescale.com/apes-Arise/apes-Authon-Server |
|
||
| apes-Authon-Web | 前端账权管理 | https://gitea.apescale.com/apes-Arise/apes-Authon-Web |
|
||
| apes-Authon-history | 剥离历史与分析归档 | https://gitea.apescale.com/apes-Arise/apes-Authon-history |
|
||
|
||
## License
|
||
|
||
MIT
|