user-system/docs/guides/ADMIN_GUIDE.md

管理员操作手册

本文档面向系统管理员，描述用户管理系统的日常运维操作。

---

1. 管理员账号

1.1 默认管理员

系统初始化后，通过以下方式创建第一个管理员：

# 调用 bootstrap 接口创建管理员
curl -X POST http://localhost:8080/api/v1/auth/bootstrap-admin \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "Admin@123456",
    "email": "admin@example.com"
  }'

注意：首次启动后必须立即修改默认密码。

1.2 管理员角色

管理员拥有系统所有权限：

• 用户管理（创建、编辑、删除、启用/禁用）
• 角色与权限管理
• 设备管理
• 登录日志查看
• 操作日志查看
• Webhook 管理
• 主题设置

---

2. 用户管理

2.1 用户列表

路径：GET /api/v1/users

参数	类型	说明
page	int	页码（默认 1）
page_size	int	每页数量（默认 20，最大 100）
keyword	string	按用户名/邮箱/手机号搜索
status	int	状态筛选（1=正常，0=禁用）

2.2 创建用户

路径：POST /api/v1/users

{
  "username": "john",
  "email": "john@example.com",
  "password": "SecurePass123!",
  "nickname": "John Doe",
  "phone": "13800138000"
}

2.3 编辑用户

路径：PUT /api/v1/users/:id

可更新字段：nickname、phone、status、email

2.4 重置用户密码

路径：PUT /api/v1/users/:id/password

{
  "new_password": "NewSecurePass123!"
}

管理员重置密码不需要原密码。

2.5 删除用户

路径：DELETE /api/v1/users/:id

用户删除后不可恢复。

---

3. 角色与权限管理

3.1 预定义角色

系统预定义了以下角色：

角色代码	说明
admin	系统管理员，拥有全部权限
user	普通用户，仅有基础权限
operator	运营人员，可管理用户和查看日志

3.2 创建自定义角色

路径：POST /api/v1/roles

{
  "name": "内容审核员",
  "code": "content_moderator",
  "description": "负责内容审核",
  "permissions": ["user:read", "user:update", "content:moderate"]
}

3.3 赋权

路径：POST /api/v1/users/:id/roles

{
  "role_ids": [3, 5]
}

---

4. 设备管理

4.1 查看设备列表

路径：GET /api/v1/admin/devices

参数	类型	说明
page	int	页码
page_size	int	每页数量
user_id	int	按用户筛选
status	int	设备状态（0=禁用，1=启用）

4.2 设备信任管理

管理员可为用户信任设备：

• 信任设备在有效期内免二次验证（TOTP）
• 可设置信任时长（30d / 90d / 180d）

路径：POST /api/v1/devices/:id/trust

{
  "trust_duration": "30d"
}

4.3 登出用户设备

路径：POST /api/v1/devices/logout-others

通过 X-Device-ID header 指定当前设备，其他设备全部登出。

---

5. 日志查看

5.1 登录日志

路径：GET /api/v1/logs/login

参数	类型	说明
page	int	页码
page_size	int	每页数量
user_id	int	筛选用户
start_time	string	开始时间（RFC3339）
end_time	string	结束时间（RFC3339）

5.2 操作日志

路径：GET /api/v1/logs/operations

记录所有变更操作的审计日志。

---

6. 系统安全配置

6.1 密码策略

可通过 PUT /api/v1/admin/settings 修改：

配置项	说明	默认值
password_min_length	最小长度	8
password_require_uppercase	必须包含大写	true
password_require_lowercase	必须包含小写	true
password_require_digit	必须包含数字	true
password_require_special	必须包含特殊字符	true

6.2 登录安全

配置项	说明	默认值
max_login_attempts	连续失败锁定次数	5
lockout_duration	锁定时长（分钟）	30
session_timeout	会话超时（小时）	24

6.3 TOTP 两步验证

系统支持 TOTP 方式的二次验证（Google Authenticator 等）。

管理员可强制要求用户启用 TOTP。

---

7. 常见运维操作

7.1 禁用用户登录

# 禁用用户
curl -X PUT http://localhost:8080/api/v1/users/123 \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"status": 0}'

7.2 查看系统健康状态

# 健康检查
curl http://localhost:8080/health
# 就绪检查
curl http://localhost:8080/health/ready
# 存活检查
curl http://localhost:8080/health/live

7.3 强制登出用户

删除用户的会话令牌，使其中断当前会话。

---

8. 监控指标

系统暴露以下 Prometheus 格式指标：

指标名	说明
http_requests_total	HTTP 请求总数
http_request_duration_seconds	请求延迟分布
login_attempts_total	登录尝试次数
active_sessions_total	当前活跃会话数
db_query_duration_seconds	数据库查询延迟

---

9. 备份策略

参考 Runbook：docs/runbooks/05-备份恢复.md

---

最后更新：2026-05-10