206 lines
6.1 KiB
Markdown
206 lines
6.1 KiB
Markdown
# Auth Worker 插件 — 用户管理
|
||
|
||
auth 域拆分后的**用户管理插件**（可替换的业务部分）。
|
||
登录 / token 签发 / admin 种子已**内置在网关**（管理平面底线，不依赖本插件是否
|
||
加载，本插件缩容到 0 或全部副本故障时登录与 admin API 仍可用）。
|
||
|
||
共享契约归 `chongming-auth` 包（`utils/auth/`）：Users 模型（唯一权威定义）、
|
||
建库、登录校验、JWT 签发。本插件与网关内置登录**共用同一张 users 表**。
|
||
|
||
---
|
||
|
||
## 功能
|
||
|
||
- **用户注册**：用户名 + 邮箱 + 密码注册，自动校验唯一性
|
||
- **获取用户信息**：根据 JWT Token 获取完整用户档案
|
||
- **修改密码**：旧密码验证 + 新密码更新
|
||
- **更新资料**：更新全名、邮箱、头像、手机号等信息
|
||
|
||
（登录 `POST /auth/login` 由网关内置提供，路径与响应 shape 不变）
|
||
|
||
---
|
||
|
||
## 数据库
|
||
|
||
使用 SQLite（通过 `chongming-database` 异步封装），数据库文件位于
|
||
`data/auth.db`（`[workers.config].data_dir` 下）；配置 `database.url` 时走
|
||
PostgreSQL。库位置与网关内置登录读同一份配置（本插件 `config.toml` 的
|
||
`[workers.config]`），指向同一张 users 表。
|
||
|
||
### Users 表结构
|
||
|
||
权威定义见 `chongming_auth.models.Users`（本仓库 `models/auth.py` 仅为 re-export）：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| ----------------- | ----------------- | --------------------------------- |
|
||
| `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/login` — 登录（网关内置）
|
||
|
||
无需认证。由网关核心 `chongming/app/routes/auth.py` 提供（非本插件），
|
||
路径与响应 shape 与拆分前一致。JWT claims 契约见 `chongming-auth` 包 README。
|
||
|
||
```json
|
||
// 请求
|
||
{
|
||
"username": "admin",
|
||
"password": "admin"
|
||
}
|
||
|
||
// 响应
|
||
{
|
||
"result": "success",
|
||
"token": "eyJhbGciOiJIUzI1NiIs...",
|
||
"message": "登录成功",
|
||
"timestamp": 1720000000.123
|
||
}
|
||
```
|
||
|
||
### `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
|
||
}
|
||
```
|
||
|
||
### `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
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 默认管理员账户
|
||
|
||
admin 种子逻辑随登录一并内置到网关（网关 lifespan 的 `setup_auth_store`
|
||
→ `chongming_auth.seed_admin`，幂等，多进程并发启动安全），不再依赖本插件。
|
||
数据库 `auth.db` 本插件仍由 `Plugin` 基类统一初始化并在 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-auth` | Users 模型 / 建库 / 登录校验 / 签发（共享契约） |
|
||
| `chongming-database` | 异步 SQLite 数据库操作 |
|
||
| `chongming-config` | 全局配置加载 |
|
||
| `chongming-worker` | `@rpc_method` 装饰器 + Worker 运行时 |
|