Files

long-agent f050c60a09 docs: 新增运维和使用指南文档

新增文档：
- guides/ADMIN_GUIDE.md — 管理员操作手册（用户/角色/设备/日志管理）
- guides/USER_GUIDE.md — 普通用户操作手册（注册/登录/TOTP/设备管理）
- guides/CONFIG_REFERENCE.md — 配置文件参考手册（含全部配置项说明）
- guides/MONITORING.md — 健康检查、Prometheus 指标和告警规则

同步更新：
- docs/README.md 文档索引，加入新增文档链接

2026-05-10 13:22:51 +08:00

4.3 KiB

Raw Blame History

用户操作手册

本文档面向普通用户，描述用户管理系统的使用方法。

1. 注册与登录

1.1 注册账号

路径：POST /api/v1/auth/register

{
  "username": "yourname",
  "password": "SecurePass123!",
  "email": "you@example.com"
}

密码要求：

最少 8 位
必须包含大写字母
必须包含小写字母
必须包含数字
必须包含特殊字符（!@#$%^&* 等）

1.2 登录

路径：POST /api/v1/auth/login

{
  "account": "yourname",
  "password": "SecurePass123!",
  "device_id": "your-device-id"
}

返回的响应中包含：

access_token — API 访问令牌（内存存储，不要持久化）
refresh_token — 刷新令牌（用于续期 access_token）
expires_in — access_token 有效期（秒）

1.3 登录安全验证

如果账户开启了 TOTP 两步验证，登录后会返回：

{
  "requires_totp": true,
  "temp_token": "xxx",
  "user_id": 123
}

此时需要完成 TOTP 验证：

路径：POST /api/v1/auth/login/totp-verify

{
  "user_id": 123,
  "code": "123456",
  "device_id": "your-device-id",
  "temp_token": "xxx"
}

2. 账户安全

2.1 修改密码

路径：PUT /api/v1/auth/password

{
  "old_password": "OldPass123!",
  "new_password": "NewPass456!"
}

注意：修改密码会使除当前设备外的所有会话失效。

2.2 忘记密码

路径：POST /api/v1/auth/password/forgot

{
  "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

{
  "code": "123456"
}

启用后，下次登录需要输入 TOTP 验证码。

2.4 禁用 TOTP

路径：POST /api/v1/auth/totp/disable

{
  "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

{
  "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

{
  "refresh_token": "your_refresh_token"
}

返回新的 access_token 和 refresh_token。

6. 账户注销

路径：DELETE /api/v1/users/account

注销后所有数据将被永久删除，不可恢复。

7. API 认证

所有需要认证的 API，在请求 Header 中添加：

Authorization: Bearer <access_token>

示例：

curl http://localhost:8080/api/v1/auth/userinfo \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

8. 错误代码

代码	说明
400	请求参数错误
401	未认证或 Token 已过期
403	无权限
404	资源不存在
429	请求过于频繁（触发限流）
500	服务器内部错误

最后更新：2026-05-10

4.3 KiB Raw Blame History Unescape Escape