# ueadmin-api-drogon

**Repository Path**: uesoft/ueadmin-api-drogon

## Basic Information

- **Project Name**: ueadmin-api-drogon
- **Description**: ueadmin-api-drogon 是基于 Drogon 框架的 OAuth2 授权服务器，可以实现身份识别、授权、权限管理等功能，例如为 UESOFT 全产品线（AIBuddy、llama.cpp、billing、UEStudio、AutoPDMS 等）提供统一的身份认证和授权服务。
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: main
- **Homepage**: http://www.uesoft.com
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ueadmin-api-drogon

> 曾用名: **UEAdminAPI-drogon** (2026-06-16 起更名为 ueadmin-api-drogon)

## 项目简介

ueadmin-api-drogon 是基于 [Drogon](https://github.com/drogonframework/drogon) 框架的 **OAuth2 授权服务器**，可以实现身份识别、授权、权限管理等功能，例如为 UESOFT 全产品线（AIBuddy、llama.cpp、billing、UEStudio、AutoPDMS 等）提供统一的身份认证和授权服务。

作为 [oauth2-shared](https://gitee.com/uesoft/oauth2-shared) 的上游服务器，它签发 JWT Token，其他服务通过 oauth2-shared 的 `UeadminTokenValidator` 进行本地验证。

## 核心功能

### 认证
| 功能 | 说明 |
|------|------|
| **密码登录** | 用户名/密码 + HMAC-SHA512 哈希验证 |
| **邮箱登录** | 邮箱 + 验证码 |
| **手机号登录** | 手机号 + 短信验证码 |
| **FlashToken 登录** | 长效令牌刷新 |
| **第三方登录** | QQ / 微信 OAuth2 授权码登录 |

### 授权
| 功能 | 说明 |
|------|------|
| **JWT 签发** | RS256 非对称签名 (优先) + HS512 (fallback) |
| **JWKS 端点** | `GET /.well-known/jwks.json` — 供客户端本地验证 |
| **Token Introspection** | `POST /oauth2/introspect` (RFC 7662) |
| **Token Revocation** | `POST /oauth2/revoke` (RFC 7009) |
| **ActionToken** | 敏感操作的二次授权令牌 |
| **AuthFilter** | 请求级 JWT 验证中间件 |

### 安全
| 功能 | 说明 |
|------|------|
| **MFA 多因素认证** | 邮件验证码 + 短信验证码 |
| **密码哈希** | HMAC-SHA512 + 随机 salt |
| **RSA 密钥** | 自动生成 2048 位密钥对，支持配置文件注入 |

### 集成
| 功能 | 说明 |
|------|------|
| **GitLab** | 用户创建/删除/令牌管理的自动同步 |
| **腾讯云短信** | 短信验证码发送 |
| **SMTP 邮件** | 邮件验证码发送 |

## 系统架构

```
┌──────────────────────────────────────────────┐
│   ueadmin-api-drogon (OAuth2 授权服务器)      │
│                                              │
│  ┌────────────────┐  ┌───────────────────┐   │
│  │ AuthService    │  │ ThirdPartyLogin   │   │
│  │ JWT签发/验证    │  │  QQ / 微信 OAuth2 │   │
│  │ RS256 / HS512  │  └───────────────────┘   │
│  └────────────────┘                           │
│  ┌────────────────┐  ┌───────────────────┐   │
│  │ MFAService     │  │ ActionTokenService│   │
│  │ 邮件/短信验证码  │  │ 操作授权令牌       │   │
│  └────────────────┘  └───────────────────┘   │
│  ┌────────────────┐  ┌───────────────────┐   │
│  │ OAuth2Controller │  │ GitlabService   │   │
│  │ JWKS/Introspect │  │ GitLab 自动同步   │   │
│  │ Revoke          │  │                  │   │
│  └────────────────┘  └───────────────────┘   │
│                                              │
│  数据库: PostgreSQL (Drogon ORM)              │
└──────────────────────────────────────────────┘
         │ Bearer Token (JWT)
         ▼
┌──────────────────────────────────────────────┐
│  oauth2-shared (客户端验证库)                  │
│  UeadminTokenValidator 本地验证 / Introspect  │
└──────────────────────────────────────────────┘
```

## 编译指南

### 依赖

| 依赖 | 版本要求 | 用途 |
|------|---------|------|
| Drogon | >= 1.9 | Web 框架 + ORM |
| jwt-cpp | >= 0.7 | JWT 创建/验证 |
| OpenSSL | >= 1.1 | RSA/HMAC 加密 |
| jsoncpp | >= 1.9 | JSON 处理 |
| Tencent SDK | — | 短信服务 (可选) |

### 编译

```bash
# 安装依赖 (Ubuntu)
sudo apt install libdrogon-dev libjwt-cpp-dev libssl-dev libjsoncpp-dev

# 编译
cd ~/ueadmin-api-drogon
mkdir build && cd build
cmake ..
make -j$(nproc)
```

### 配置

`config.yaml` 示例:
```yaml
UserManage:
  jwt_secret: your-hs512-secret
  jwt_issuer: https://ueadmin.example.com
  rsa_private_key: /etc/ueadmin/rsa-private.pem   # 可选，不配置则自动生成
  rsa_public_key:  /etc/ueadmin/rsa-public.pem
```

## API 路由

### 认证
| 方法 | 路由 | 说明 |
|------|------|------|
| GET | `/user/login/pwd` | 密码登录 |
| GET | `/user/login/email` | 邮箱验证码登录 |
| GET | `/user/login/phone` | 手机号验证码登录 |
| GET | `/user/login/flashtoken` | FlashToken 登录 |
| POST | `/user/logout` | 注销 |

### OAuth2 标准端点
| 方法 | 路由 | 说明 |
|------|------|------|
| GET | `/.well-known/jwks.json` | JWKS 公钥列表 |
| POST | `/oauth2/introspect` | Token 状态查询 (RFC 7662) |
| POST | `/oauth2/revoke` | Token 撤销 (RFC 7009) |

### 第三方登录
| 方法 | 路由 | 说明 |
|------|------|------|
| GET | `/api/third/authorization_url` | 获取第三方登录 URL |
| GET | `/api/third/{platform}` | 第三方回调 |
| GET | `/api/third/login` | 第三方登录 |
| POST | `/api/third/bind` | 绑定第三方账号 |
| POST | `/api/third/unbind` | 解绑 |

### 用户管理
| 方法 | 路由 | 鉴权 | 说明 |
|------|------|------|------|
| POST | `/user/create` | ActionToken | 邮箱注册 |
| GET | `/user/self` | Bearer Token | 获取个人信息 |
| POST | `/user/update` | Bearer + ActionToken | 修改信息 |
| DELETE | `/user/delete` | Bearer + ActionToken | 删除账号 |

## 与 oauth2-shared 的配合

ueadmin-api-drogon 是 OAuth2 授权服务器，oauth2-shared 是客户端验证库：

```
ueadmin 签发 Token (RS256)  →  资源服务用 oauth2-shared 本地验证
     ↓                                  ↑
  JWKS 端点 ←──────── 缓存公钥 ──────── 
     ↓                                  ↑
  Introspect 端点 ←── fallback 验证 ────
```

## 开发历史

| 日期 | 事件 |
|------|------|
| 2026-06-16 | 更名为 `ueadmin-api-drogon`，新增 RS256 签名 + JWKS/Introspect/Revoke 端点 |
| 2026-05 | 引入 ActionToken 二次授权机制 |
| 2026-04 | 接入 oauth2-shared 统一 Provider 体系 |
| 2026-03 | 新增 QQ/微信第三方登录 |
| 2026-01 | 初始版本，基础认证 + MFA |

## 许可证

MIT