254 lines
4.3 KiB
Markdown
254 lines
4.3 KiB
Markdown
|
# 用户操作手册
|
|||
|
|
|
|||
|
|
本文档面向普通用户，描述用户管理系统的使用方法。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 注册与登录
|
|||
|
|
|
|||
|
|
### 1.1 注册账号
|
|||
|
|
|
|||
|
|
**路径**：`POST /api/v1/auth/register`
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"username": "yourname",
|
|||
|
|
"password": "SecurePass123!",
|
|||
|
|
"email": "you@example.com"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**密码要求**：
|
|||
|
|
- 最少 8 位
|
|||
|
|
- 必须包含大写字母
|
|||
|
|
- 必须包含小写字母
|
|||
|
|
- 必须包含数字
|
|||
|
|
- 必须包含特殊字符（`!@#$%^&*` 等）
|
|||
|
|
|
|||
|
|
### 1.2 登录
|
|||
|
|
|
|||
|
|
**路径**：`POST /api/v1/auth/login`
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"account": "yourname",
|
|||
|
|
"password": "SecurePass123!",
|
|||
|
|
"device_id": "your-device-id"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
返回的响应中包含：
|
|||
|
|
- `access_token` — API 访问令牌（内存存储，不要持久化）
|
|||
|
|
- `refresh_token` — 刷新令牌（用于续期 access_token）
|
|||
|
|
- `expires_in` — access_token 有效期（秒）
|
|||
|
|
|
|||
|
|
### 1.3 登录安全验证
|
|||
|
|
|
|||
|
|
如果账户开启了 TOTP 两步验证，登录后会返回：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"requires_totp": true,
|
|||
|
|
"temp_token": "xxx",
|
|||
|
|
"user_id": 123
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
此时需要完成 TOTP 验证：
|
|||
|
|
|
|||
|
|
**路径**：`POST /api/v1/auth/login/totp-verify`
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"user_id": 123,
|
|||
|
|
"code": "123456",
|
|||
|
|
"device_id": "your-device-id",
|
|||
|
|
"temp_token": "xxx"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 账户安全
|
|||
|
|
|
|||
|
|
### 2.1 修改密码
|
|||
|
|
|
|||
|
|
**路径**：`PUT /api/v1/auth/password`
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"old_password": "OldPass123!",
|
|||
|
|
"new_password": "NewPass456!"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**注意**：修改密码会使除当前设备外的所有会话失效。
|
|||
|
|
|
|||
|
|
### 2.2 忘记密码
|
|||
|
|
|
|||
|
|
**路径**：`POST /api/v1/auth/password/forgot`
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"email": "you@example.com"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
系统会向邮箱发送重置链接。
|
|||
|
|
|
|||
|
|
### 2.3 设置 TOTP 两步验证
|
|||
|
|
|
|||
|
|
**步骤 1**：请求 TOTP 绑定信息
|
|||
|
|
**路径**：`POST /api/v1/auth/totp/setup`
|
|||
|
|
|
|||
|
|
返回二维码和密钥。使用 Google Authenticator 或其他 TOTP 应用扫描。
|
|||
|
|
|
|||
|
|
**步骤 2**：启用 TOTP
|
|||
|
|
**路径**：`POST /api/v1/auth/totp/enable`
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": "123456"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
启用后，下次登录需要输入 TOTP 验证码。
|
|||
|
|
|
|||
|
|
### 2.4 禁用 TOTP
|
|||
|
|
|
|||
|
|
**路径**：`POST /api/v1/auth/totp/disable`
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": "123456"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.5 恢复码
|
|||
|
|
|
|||
|
|
首次启用 TOPT 时，系统会提供一组恢复码。
|
|||
|
|
|
|||
|
|
**用途**：当 TOTP 设备丢失时，使用恢复码恢复登录。
|
|||
|
|
|
|||
|
|
**保存建议**：将恢复码打印或手写保存到安全位置，切勿截图或保存到云端。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 设备管理
|
|||
|
|
|
|||
|
|
### 3.1 查看我的设备
|
|||
|
|
|
|||
|
|
**路径**：`GET /api/v1/devices`
|
|||
|
|
|
|||
|
|
返回当前账户下所有已登录设备列表。
|
|||
|
|
|
|||
|
|
### 3.2 查看信任设备
|
|||
|
|
|
|||
|
|
**路径**：`GET /api/v1/devices/trusted`
|
|||
|
|
|
|||
|
|
返回已标记为信任的设备列表。信任设备在有效期内免 TOTP 验证。
|
|||
|
|
|
|||
|
|
### 3.3 信任当前设备
|
|||
|
|
|
|||
|
|
**路径**：`POST /api/v1/devices/trust`
|
|||
|
|
|
|||
|
|
将当前设备标记为信任设备。
|
|||
|
|
|
|||
|
|
**注意**：需要在设备详情中查看设备 ID。
|
|||
|
|
|
|||
|
|
### 3.4 取消设备信任
|
|||
|
|
|
|||
|
|
**路径**：`DELETE /api/v1/devices/:id/trust`
|
|||
|
|
|
|||
|
|
### 3.5 登出其他设备
|
|||
|
|
|
|||
|
|
**路径**：`POST /api/v1/devices/logout-others`
|
|||
|
|
|
|||
|
|
将除当前设备外的所有其他设备登出。
|
|||
|
|
|
|||
|
|
Header 中需要指定当前设备：`X-Device-ID: your-device-id`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 个人资料
|
|||
|
|
|
|||
|
|
### 4.1 查看个人资料
|
|||
|
|
|
|||
|
|
**路径**：`GET /api/v1/auth/userinfo`
|
|||
|
|
|
|||
|
|
### 4.2 更新个人资料
|
|||
|
|
|
|||
|
|
**路径**：`PUT /api/v1/users/profile`
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"nickname": "Your Name",
|
|||
|
|
"phone": "13800138000"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4.3 上传头像
|
|||
|
|
|
|||
|
|
**路径**：`POST /api/v1/users/:id/avatar`
|
|||
|
|
|
|||
|
|
支持的格式：JPEG、PNG、GIF、WebP
|
|||
|
|
最大文件大小：5MB
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. Token 刷新
|
|||
|
|
|
|||
|
|
Access Token 有效期较短，过期后需要使用 Refresh Token 续期：
|
|||
|
|
|
|||
|
|
**路径**：`POST /api/v1/auth/refresh`
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"refresh_token": "your_refresh_token"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
返回新的 access_token 和 refresh_token。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. 账户注销
|
|||
|
|
|
|||
|
|
**路径**：`DELETE /api/v1/users/account`
|
|||
|
|
|
|||
|
|
注销后所有数据将被永久删除，不可恢复。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. API 认证
|
|||
|
|
|
|||
|
|
所有需要认证的 API，在请求 Header 中添加：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
Authorization: Bearer <access_token>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
示例：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl http://localhost:8080/api/v1/auth/userinfo \
|
|||
|
|
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. 错误代码
|
|||
|
|
|
|||
|
|
| 代码 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| 400 | 请求参数错误 |
|
|||
|
|
| 401 | 未认证或 Token 已过期 |
|
|||
|
|
| 403 | 无权限 |
|
|||
|
|
| 404 | 资源不存在 |
|
|||
|
|
| 429 | 请求过于频繁（触发限流） |
|
|||
|
|
| 500 | 服务器内部错误 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
*最后更新：2026-05-10*
|