chongming-plugins/auth/README.md

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 — 用户注册

无需认证。

// 请求
{
  "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 — 登录

无需认证。

// 请求
{
  "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>）。

// 响应
{
  "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 鉴权。

// 请求
{
  "user_id": "a1b2c3d4_12345_1720000000.123",
  "old_password": "secret123",
  "new_password": "newSecret456"
}

// 响应
{
  "result": "success",
  "message": "密码修改成功",
  "timestamp": 1720000000.123
}

POST /auth/update_profile — 更新用户资料

需要 JWT 鉴权。仅更新非空字段。

// 请求
{
  "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 运行时