198 lines
5.5 KiB
Markdown
198 lines
5.5 KiB
Markdown
# Auth Worker 插件
|
||
|
||
用户认证与授权插件，提供完整的用户管理系统。
|
||
|
||
---
|
||
|
||
## 功能
|
||
|
||
- **用户注册**：用户名 + 邮箱 + 密码注册，自动校验唯一性
|
||
- **用户登录**：JWT Token 签发，有效期 3 小时
|
||
- **获取用户信息**：根据 JWT Token 获取完整用户档案
|
||
- **修改密码**：旧密码验证 + 新密码更新
|
||
- **更新资料**：更新全名、邮箱、头像、手机号等信息
|
||
- **自动初始化**：首次启动自动创建 `admin` 管理员账户
|
||
|
||
---
|
||
|
||
## 数据库
|
||
|
||
使用 SQLite（通过 `chongming-database` 异步封装），数据库文件位于 `data/storage/chongming/auth.db`。
|
||
|
||
### Users 表结构
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| ----------------- | ----------------- | --------------------------------- |
|
||
| `id` | `str` (PK) | UUID 格式主键 |
|
||
| `username` | `str(50)` UNIQUE | 登录用户名 |
|
||
| `email` | `str(255)` UNIQUE | 电子邮箱 |
|
||
| `hashed_password` | `str(255)` | Argon2id 加密密码 |
|
||
| `full_name` | `str(100)` | 用户全名（可选） |
|
||
| `avatar_url` | `str(500)` | 头像链接（可选） |
|
||
| `phone` | `str(20)` | 手机号码（可选） |
|
||
| `is_active` | `bool` | 账户启用状态（默认 `true`） |
|
||
| `is_verified` | `bool` | 邮箱/手机验证状态（默认 `false`） |
|
||
| `is_superuser` | `bool` | 超级管理员标识（默认 `false`） |
|
||
| `created_at` | `datetime` | 创建时间 |
|
||
| `updated_at` | `datetime` | 最后更新时间 |
|
||
| `last_login_at` | `datetime` | 最后登录时间（可选） |
|
||
|
||
密码使用 Rust 实现的 **Argon2id** 哈希，内存成本 19456 KiB，迭代 2 次，并行度 1。
|
||
|
||
---
|
||
|
||
## API 端点
|
||
|
||
所有端点路由前缀为 `/auth`。
|
||
|
||
### `POST /auth/register` — 用户注册
|
||
|
||
无需认证。
|
||
|
||
```json
|
||
// 请求
|
||
{
|
||
"username": "john",
|
||
"password": "secret123",
|
||
"email": "john@example.com",
|
||
"full_name": "John Doe",
|
||
"phone": "13800138000"
|
||
}
|
||
|
||
// 响应
|
||
{
|
||
"result": "success",
|
||
"message": "注册成功",
|
||
"user_id": "a1b2c3d4_12345_1720000000.123",
|
||
"timestamp": 1720000000.123
|
||
}
|
||
```
|
||
|
||
### `POST /auth/login` — 登录
|
||
|
||
无需认证。
|
||
|
||
```json
|
||
// 请求
|
||
{
|
||
"username": "admin",
|
||
"password": "admin"
|
||
}
|
||
|
||
// 响应
|
||
{
|
||
"result": "success",
|
||
"token": "eyJhbGciOiJIUzI1NiIs...",
|
||
"message": "登录成功",
|
||
"timestamp": 1720000000.123
|
||
}
|
||
```
|
||
|
||
JWT Token 有效期 3 小时，载荷包含：`sub`（用户ID）、`username`、`email`、`full_name`、`is_superuser` 等。
|
||
|
||
### `GET /auth/me?user_id=<id>` — 获取用户信息
|
||
|
||
需要 JWT 鉴权（`Authorization: Bearer <token>`）。
|
||
|
||
```json
|
||
// 响应
|
||
{
|
||
"result": "success",
|
||
"id": "a1b2c3d4_12345_1720000000.123",
|
||
"username": "john",
|
||
"email": "john@example.com",
|
||
"full_name": "John Doe",
|
||
"avatar_url": null,
|
||
"phone": "13800138000",
|
||
"is_active": true,
|
||
"is_verified": false,
|
||
"is_superuser": false,
|
||
"created_at": "2024-01-01T00:00:00+00:00",
|
||
"updated_at": "2024-01-01T00:00:00+00:00",
|
||
"last_login_at": null
|
||
}
|
||
```
|
||
|
||
### `POST /auth/change_password` — 修改密码
|
||
|
||
需要 JWT 鉴权。
|
||
|
||
```json
|
||
// 请求
|
||
{
|
||
"user_id": "a1b2c3d4_12345_1720000000.123",
|
||
"old_password": "secret123",
|
||
"new_password": "newSecret456"
|
||
}
|
||
|
||
// 响应
|
||
{
|
||
"result": "success",
|
||
"message": "密码修改成功",
|
||
"timestamp": 1720000000.123
|
||
}
|
||
```
|
||
|
||
### `POST /auth/update_profile` — 更新用户资料
|
||
|
||
需要 JWT 鉴权。仅更新非空字段。
|
||
|
||
```json
|
||
// 请求
|
||
{
|
||
"user_id": "a1b2c3d4_12345_1720000000.123",
|
||
"full_name": "John Updated",
|
||
"email": "",
|
||
"avatar_url": "https://example.com/avatar.png",
|
||
"phone": ""
|
||
}
|
||
|
||
// 响应
|
||
{
|
||
"result": "success",
|
||
"message": "资料更新成功",
|
||
"timestamp": 1720000000.123
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 默认管理员账户
|
||
|
||
插件基于 `Plugin` 基类统一生命周期：`on_init` 中执行管理员种子逻辑
|
||
（先按用户名、再按邮箱兜底查询；多进程并发启动时靠唯一约束 + `IntegrityError` 回滚保证幂等），
|
||
数据库 `auth.db` 由基类统一初始化并在 cleanup 时释放。
|
||
|
||
首次启动时自动创建：
|
||
|
||
| 字段 | 值 |
|
||
| ------------ | --------------------- |
|
||
| **用户名** | `admin` |
|
||
| **密码** | `admin` |
|
||
| **邮箱** | `admin@example.com` |
|
||
| **超管权限** | `is_superuser = true` |
|
||
|
||
> ⚠️ **生产环境务必修改默认密码！**
|
||
|
||
---
|
||
|
||
## 安全说明
|
||
|
||
- 密码使用 **Argon2id**（Rust 实现），对抗 GPU/ASIC 暴力破解
|
||
- JWT 使用 **HS256** 算法，密钥在 `config.toml` 的 `[security]` 节配置
|
||
- JWT 有效期 3 小时，过期后需重新登录
|
||
- 支持用户软禁用（`is_active = false`）
|
||
- 接口级鉴权控制：每个端点可通过 TOML 的 `auth_required` 独立配置
|
||
|
||
---
|
||
|
||
## 依赖
|
||
|
||
| 工具包 | 用途 |
|
||
| -------------------- | ------------------------------------ |
|
||
| `chongming-database` | 异步 SQLite 数据库操作 |
|
||
| `chongming-jwt` | Rust JWT 编码/验证 |
|
||
| `chongming-password` | Rust Argon2id 密码哈希 |
|
||
| `chongming-config` | 全局配置加载 |
|
||
| `chongming-worker` | `@rpc_method` 装饰器 + Worker 运行时 |
|