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