long-agent
f050c60a09
新增文档： - guides/ADMIN_GUIDE.md — 管理员操作手册（用户/角色/设备/日志管理） - guides/USER_GUIDE.md — 普通用户操作手册（注册/登录/TOTP/设备管理） - guides/CONFIG_REFERENCE.md — 配置文件参考手册（含全部配置项说明） - guides/MONITORING.md — 健康检查、Prometheus 指标和告警规则 同步更新： - docs/README.md 文档索引，加入新增文档链接
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*
|