user-system/docs/guides/ADMIN_GUIDE.md

# 管理员操作手册

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

---

## 1. 管理员账号

### 1.1 默认管理员

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

```bash
# 调用 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`

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

```json
{
  "new_password": "NewSecurePass123!"
}
```

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

### 2.5 删除用户

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

用户删除后不可恢复。

---

## 3. 角色与权限管理

### 3.1 预定义角色

系统预定义了以下角色：

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

### 3.2 创建自定义角色

**路径**：`POST /api/v1/roles`

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

### 3.3 赋权

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

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

```json
{
  "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 禁用用户登录

```bash
# 禁用用户
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 查看系统健康状态

```bash
# 健康检查
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*