From f050c60a094225e7259a4a0a8d3bf11ae433a914 Mon Sep 17 00:00:00 2001 From: long-agent Date: Sun, 10 May 2026 13:22:51 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E8=BF=90=E7=BB=B4?= =?UTF-8?q?=E5=92=8C=E4=BD=BF=E7=94=A8=E6=8C=87=E5=8D=97=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增文档： - guides/ADMIN_GUIDE.md — 管理员操作手册（用户/角色/设备/日志管理） - guides/USER_GUIDE.md — 普通用户操作手册（注册/登录/TOTP/设备管理） - guides/CONFIG_REFERENCE.md — 配置文件参考手册（含全部配置项说明） - guides/MONITORING.md — 健康检查、Prometheus 指标和告警规则 同步更新： - docs/README.md 文档索引，加入新增文档链接 --- docs/README.md | 14 ++ docs/guides/ADMIN_GUIDE.md | 265 +++++++++++++++++++++++++ docs/guides/CONFIG_REFERENCE.md | 331 ++++++++++++++++++++++++++++++++ docs/guides/MONITORING.md | 318 ++++++++++++++++++++++++++++++ docs/guides/USER_GUIDE.md | 253 ++++++++++++++++++++++++ 5 files changed, 1181 insertions(+) create mode 100644 docs/guides/ADMIN_GUIDE.md create mode 100644 docs/guides/CONFIG_REFERENCE.md create mode 100644 docs/guides/MONITORING.md create mode 100644 docs/guides/USER_GUIDE.md diff --git a/docs/README.md b/docs/README.md index db456b9..57225ff 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,6 +24,20 @@ | `API.md` | 当前 API 合同。 | | `PROJECT_REVIEW_REPORT.md` | 当前 review 报告。 | +## 运维与使用指南（guides/） + +| 路径 | 说明 | +|------|------| +| `guides/ADMIN_GUIDE.md` | 管理员操作手册（用户/角色/设备/日志管理）。 | +| `guides/USER_GUIDE.md` | 普通用户操作手册（注册/登录/TOTP/设备管理）。 | +| `guides/CONFIG_REFERENCE.md` | 配置文件参考手册（含全部配置项说明）。 | +| `guides/MONITORING.md` | 健康检查、Prometheus 指标和告警规则。 | +| `guides/ALERTING_ONCALL_RUNBOOK.md` | 告警响应和值班 Runbook。 | +| `guides/ROLLBACK_RUNBOOK.md` | 回滚操作 Runbook。 | +| `guides/TESTING.md` | 测试执行指南。 | +| `guides/GO_TROUBLESHOOTING.md` | Go 问题排查指南。 | +| `DEPLOYMENT.md` | 部署和运维指南（容器化部署、集群方案）。 | + ## 归档说明 - 已被新状态、新规则或新结论替代的历史文档，应移动到 `docs/archive/`。 diff --git a/docs/guides/ADMIN_GUIDE.md b/docs/guides/ADMIN_GUIDE.md new file mode 100644 index 0000000..15b0a8d --- /dev/null +++ b/docs/guides/ADMIN_GUIDE.md @@ -0,0 +1,265 @@ +# 管理员操作手册 + +本文档面向系统管理员，描述用户管理系统的日常运维操作。 + +--- + +## 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 " \ + -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* diff --git a/docs/guides/CONFIG_REFERENCE.md b/docs/guides/CONFIG_REFERENCE.md new file mode 100644 index 0000000..f637562 --- /dev/null +++ b/docs/guides/CONFIG_REFERENCE.md @@ -0,0 +1,331 @@ +# 配置参考手册 + +本文档描述 `configs/config.yaml` 各配置项的含义、默认值和生产环境建议。 + +--- + +## 1. server — 服务配置 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `port` | int | 8080 | HTTP 服务监听端口 | +| `mode` | string | release | 运行模式：`debug` / `release` | +| `read_timeout` | duration | 30s | 读取请求体的超时 | +| `read_header_timeout` | duration | 10s | 读取请求头的超时 | +| `write_timeout` | duration | 30s | 写入响应的超时 | +| `idle_timeout` | duration | 60s | 空闲连接保持时间 | +| `shutdown_timeout` | duration | 15s | 优雅停机的最大等待时间 | +| `max_header_bytes` | int | 1048576 | 请求头最大字节数 | + +**生产建议**：若前端 CDN 缓存较多，可将 `cache-control` 等头设置较长，减少回源。 + +--- + +## 2. database — 数据库配置 + +### 2.1 通用 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `type` | string | sqlite | 数据库类型：`sqlite` / `postgresql` / `mysql` | + +> ⚠️ 当前生产环境推荐使用 `postgresql`，SQLite 仅适用于开发和小规模部署。 + +### 2.2 SQLite + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `path` | string | ./data/user_management.db | 数据库文件路径（相对于工作目录） | + +### 2.3 PostgreSQL + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `host` | string | localhost | 数据库主机 | +| `port` | int | 5432 | 数据库端口 | +| `database` | string | user_management | 数据库名 | +| `username` | string | postgres | 用户名 | +| `password` | string | "" | 密码（生产必须通过环境变量设置） | +| `ssl_mode` | string | disable | SSL 模式：`disable` / `require` / `verify-ca` / `verify-full` | +| `max_open_conns` | int | 100 | 最大打开连接数 | +| `max_idle_conns` | int | 10 | 最大空闲连接数 | + +**生产建议**： +- `ssl_mode` 至少设为 `require` +- 生产密码必须通过 `DB_PASSWORD` 环境变量注入，不要写在配置文件中 +- 高并发场景建议 `max_open_conns = 200~500` + +### 2.4 MySQL + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `host` | string | localhost | 数据库主机 | +| `port` | int | 3306 | 数据库端口 | +| `database` | string | user_management | 数据库名 | +| `username` | string | root | 用户名 | +| `password` | string | "" | 密码（生产必须通过环境变量） | +| `charset` | string | utf8mb4 | 字符集（必须使用 utf8mb4） | +| `max_open_conns` | int | 100 | 最大打开连接数 | +| `max_idle_conns` | int | 10 | 最大空闲连接数 | + +--- + +## 3. cache — 缓存配置 + +### 3.1 L1 缓存（内存） + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `enabled` | bool | true | 是否启用 L1 缓存 | +| `max_size` | int | 10000 | 最大缓存条目数 | +| `ttl` | duration | 5m | 缓存条目 TTL | + +### 3.2 L2 缓存（Redis） + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `enabled` | bool | false | 是否启用 Redis L2 缓存 | +| `type` | string | redis | 缓存类型（仅支持 redis） | +| `redis.addr` | string | localhost:6379 | Redis 地址 | +| `redis.password` | string | "" | Redis 密码 | +| `redis.db` | int | 0 | Redis DB 编号 | +| `redis.pool_size` | int | 50 | 连接池大小 | +| `redis.ttl` | duration | 30m | 缓存 TTL | + +**生产建议**：高并发场景建议启用 Redis L2 缓存，并设置合理的 `pool_size`。 + +--- + +## 4. jwt — JWT 配置 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `algorithm` | string | HS256 | 签名算法：`HS256`（debug）/ `RS256`（生产推荐） | +| `secret` | string | "" | HMAC 签名密钥（生产必须设置） | +| `access_token_expire_minutes` | int | 120 | Access Token 有效期（分钟） | +| `refresh_token_expire_days` | int | 7 | Refresh Token 有效期（天） | + +**生产建议**： +- 生产环境建议使用 `RS256`（RSA 密钥对），不要使用共享密钥 +- `JWT_SECRET` 环境变量必须设置强随机字符串（至少 32 字节） +- Access Token 建议 30~120 分钟 +- Refresh Token 建议 7~30 天 + +--- + +## 5. security — 安全配置 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `password_min_length` | int | 8 | 密码最小长度 | +| `password_require_special` | bool | true | 必须包含特殊字符 | +| `password_require_number` | bool | true | 必须包含数字 | +| `login_max_attempts` | int | 5 | 连续登录失败锁定次数 | +| `login_lock_duration` | duration | 30m | 账户锁定时长 | + +--- + +## 6. ratelimit — 限流配置 + +所有限流均可独立开启/关闭。算法说明： +- `token_bucket`：令牌桶，适合突发流量 +- `leaky_bucket`：漏桶，输出速率恒定 +- `sliding_window`：滑动窗口，统计最平滑 + +### 6.1 登录限流 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `enabled` | bool | true | 是否启用 | +| `algorithm` | string | token_bucket | 限流算法 | +| `capacity` | int | 5 | 令牌桶容量（即 burst 上限） | +| `rate` | int | 1 | 每窗口补充令牌数 | +| `window` | duration | 1m | 统计窗口 | + +### 6.2 注册限流 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `enabled` | bool | true | 是否启用 | +| `algorithm` | string | leaky_bucket | 限流算法 | +| `capacity` | int | 3 | 桶容量 | +| `rate` | int | 1 | 输出速率 | +| `window` | duration | 1h | 统计窗口 | + +### 6.3 API 通用限流 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `enabled` | bool | true | 是否启用 | +| `algorithm` | string | sliding_window | 限流算法 | +| `capacity` | int | 1000 | 窗口内最大请求数 | +| `window` | duration | 1m | 统计窗口 | + +--- + +## 7. monitoring — 监控配置 + +### 7.1 Prometheus 指标 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `enabled` | bool | true | 是否启用 Prometheus 指标 | +| `path` | string | /metrics | 指标暴露路径 | + +### 7.2 分布式追踪 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `enabled` | bool | false | 是否启用追踪 | +| `endpoint` | string | localhost:4318 | OTLP gRPC 接收端点 | +| `service_name` | string | user-management-system | 服务名（用于链路关联） | + +**生产建议**：接入 Jaeger 或 Zipkin 时启用追踪。 + +--- + +## 8. logging — 日志配置 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `level` | string | info | 日志级别：`debug` / `info` / `warn` / `error` | +| `format` | string | json | 日志格式：`json`（生产）/ `text`（开发） | +| `output` | []string | stdout, ./logs/app.log | 日志输出目标 | +| `rotation.max_size` | int | 100 | 单文件最大 MB | +| `rotation.max_age` | int | 30 | 保留天数 | +| `rotation.max_backups` | int | 10 | 保留文件数 | + +--- + +## 9. cors — 跨域配置 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `enabled` | bool | true | 是否启用 CORS | +| `allowed_origins` | []string | localhost:3000 | 允许的来源（生产必须精确配置） | +| `allowed_methods` | []string | GET,POST,PUT,DELETE,OPTIONS | 允许的方法 | +| `allowed_headers` | []string | 见 config.yaml | 允许的请求头 | +| `allow_credentials` | bool | true | 是否允许携带凭证 | +| `max_age` | int | 3600 | 预检请求缓存时间（秒） | + +> ⚠️ **生产禁止**将 `*` 与 `allow_credentials: true` 同时使用（CORS 规范不允许，会被浏览器拒绝）。 + +--- + +## 10. email — 邮件配置 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `host` | string | "" | SMTP 主机 | +| `port` | int | 587 | SMTP 端口（TLS：587，SSL：465） | +| `username` | string | "" | 用户名 | +| `password` | string | "" | 密码（生产通过环境变量） | +| `from_email` | string | "" | 发件人地址 | +| `from_name` | string | 用户管理系统 | 发件人名称 | + +**生产建议**：使用企业邮箱（如 SendGrid、Mailgun）或自建 SMTP。 + +--- + +## 11. sms — 短信配置 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `enabled` | bool | false | 是否启用短信功能 | +| `provider` | string | "" | 提供商：`aliyun` / `tencent`，留空禁用 | +| `code_ttl` | duration | 5m | 验证码有效期 | +| `resend_cooldown` | duration | 1m | 再次发送的冷却时间 | +| `max_daily_limit` | int | 10 | 单号码每日发送上限 | + +### 11.1 阿里云 + +| 配置项 | 说明 | +|--------|------| +| `access_key_id` | 阿里云 AccessKey ID | +| `access_key_secret` | 阿里云 AccessKey Secret | +| `sign_name` | 短信签名 | +| `template_code` | 短信模板 CODE | + +### 11.2 腾讯云 + +| 配置项 | 说明 | +|--------|------| +| `secret_id` | 腾讯云 Secret ID | +| `secret_key` | 腾讯云 Secret Key | +| `app_id` | 短信 SDK App ID | +| `sign_name` | 短信签名 | +| `template_id` | 模板 ID | + +--- + +## 12. oauth — 社交登录配置 + +| Provider | 配置项 | 说明 | +|----------|--------|------| +| 通用 | `client_id` | 应用 Client ID | +| 通用 | `client_secret` | 应用 Client Secret（生产通过环境变量） | +| 通用 | `redirect_url` | OAuth 回调地址（生产必须使用 HTTPS） | +| Google | — | 支持 Google 账号登录 | +| GitHub | — | 支持 GitHub 账号登录 | +| WeChat | — | 支持微信账号登录 | +| QQ | — | 支持 QQ 账号登录 | +| 支付宝 | — | 支持支付宝账号登录 | +| 抖音 | — | 支持抖音账号登录 | + +> ⚠️ 所有 OAuth 回调地址必须使用 HTTPS，禁止在生产环境使用 HTTP。 + +--- + +## 13. webhook — Webhook 配置 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `enabled` | bool | true | 是否启用 Webhook | +| `secret_header` | string | X-Webhook-Signature | 签名验证 Header 名 | +| `timeout_sec` | int | 30 | 单次投递超时（秒） | +| `max_retries` | int | 3 | 最大重试次数 | +| `retry_backoff` | string | exponential | 退避策略：`exponential` / `fixed` | +| `worker_count` | int | 4 | 后台投递协程数 | +| `queue_size` | int | 1000 | 投递队列大小 | + +--- + +## 14. ip_security — IP 安全配置 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `auto_block_enabled` | bool | true | 是否启用自动封禁 | +| `auto_block_duration` | duration | 30m | 封禁时长 | +| `brute_force_threshold` | int | 10 | 暴力破解判定阈值（窗口内失败次数） | +| `detection_window` | duration | 15m | 检测时间窗口 | + +--- + +## 15. password_reset — 密码重置配置 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `token_ttl` | duration | 15m | 重置令牌有效期 | +| `site_url` | string | http://localhost:8080 | 前端站点 URL（用于构造邮件链接） | + +--- + +## 环境变量优先级 + +配置项中包含敏感信息的字段，支持通过环境变量覆盖： + +| 配置项 | 环境变量 | +|--------|----------| +| `jwt.secret` | `JWT_SECRET` | +| `database.postgresql.password` | `DB_PASSWORD` | +| `database.mysql.password` | `DB_PASSWORD` | +| `redis.password` | `REDIS_PASSWORD` | +| `email.password` | `SMTP_PASSWORD` | +| `jwt.algorithm`（生产） | `JWT_ALGORITHM` | +| `oauth.*.client_secret` | 各 Provider 的 `CLIENT_SECRET` | + +> 环境变量优先级高于配置文件，用于生产密钥注入。 + +--- + +*最后更新：2026-05-10* diff --git a/docs/guides/MONITORING.md b/docs/guides/MONITORING.md new file mode 100644 index 0000000..9b965c4 --- /dev/null +++ b/docs/guides/MONITORING.md @@ -0,0 +1,318 @@ +# 健康检查与监控指南 + +本文档描述系统健康检查端点、Prometheus 监控指标和告警规则。 + +--- + +## 1. 健康检查端点 + +系统提供三个健康检查端点，适用于不同场景： + +| 端点 | 路径 | 说明 | 使用场景 | +|------|------|------|----------| +| 存活探针 | `/health/live` | 确认进程存活 | Kubernetes `livenessProbe` | +| 就绪探针 | `/health/ready` | 确认服务就绪 | Kubernetes `readinessProbe` | +| 健康检查 | `/health` | 综合健康状态 | 负载均衡器、健康检查脚本 | + +### 1.1 响应格式 + +```json +{ + "status": "ok", + "timestamp": "2026-05-10T13:00:00Z", + "version": "1.0.0" +} +``` + +### 1.2 响应码 + +| 状态 | HTTP 响应码 | 说明 | +|------|-------------|------| +| ok | 200 | 服务正常 | +| degraded | 200 | 服务降级（部分依赖不可用，如 Redis） | +| unhealthy | 503 | 服务不健康（如数据库不可达） | + +--- + +## 2. Prometheus 监控指标 + +### 2.1 暴露方式 + +指标端点：`GET /metrics` + +返回 Prometheus 格式文本。 + +### 2.2 核心指标 + +#### HTTP 指标 + +| 指标名 | 类型 | 标签 | 说明 | +|--------|------|------|------| +| `http_requests_total` | Counter | method, path, status | HTTP 请求总数 | +| `http_request_duration_seconds` | Histogram | method, path | 请求延迟分布 | + +#### 认证指标 + +| 指标名 | 类型 | 标签 | 说明 | +|--------|------|------|------| +| `login_attempts_total` | Counter | result, method | 登录尝试次数（成功/失败） | +| `active_sessions_total` | Gauge | — | 当前活跃会话数 | +| `refresh_tokens_total` | Counter | — | Token 刷新次数 | + +#### 数据库指标 + +| 指标名 | 类型 | 标签 | 说明 | +|--------|------|------|------| +| `db_query_duration_seconds` | Histogram | operation, table | 数据库查询延迟 | +| `db_connections_open` | Gauge | type | 当前打开的连接数 | +| `db_connections_in_use` | Gauge | type | 使用中的连接数 | + +#### 缓存指标 + +| 指标名 | 类型 | 标签 | 说明 | +|--------|------|------|------| +| `cache_hits_total` | Counter | cache_level | 缓存命中次数 | +| `cache_misses_total` | Counter | cache_level | 缓存未命中次数 | +| `cache_operations_total` | Counter | operation | 缓存操作总数 | + +#### 限流指标 + +| 指标名 | 类型 | 标签 | 说明 | +|--------|------|------|------| +| `ratelimit_rejections_total` | Counter | endpoint, algorithm | 限流拦截次数 | + +### 2.3 查看当前指标 + +```bash +curl http://localhost:8080/metrics +``` + +--- + +## 3. 告警规则 + +### 3.1 建议的告警规则（Prometheus / Alertmanager 格式） + +```yaml +groups: + - name: user-management + rules: + # 服务不可用 + - alert: ServiceDown + expr: up{job="user-management"} == 0 + for: 1m + labels: + severity: critical + annotations: + summary: "用户管理服务不可用" + + # 错误率过高 + - alert: HighErrorRate + expr: | + rate(http_requests_total{status=~"5.."}[5m]) / + rate(http_requests_total[5m]) > 0.05 + for: 5m + labels: + severity: warning + annotations: + summary: "HTTP 5xx 错误率超过 5%" + + # 登录失败率过高（可能暴力破解） + - alert: HighLoginFailureRate + expr: | + rate(login_attempts_total{result="fail"}[5m]) / + rate(login_attempts_total[5m]) > 0.8 + for: 5m + labels: + severity: warning + annotations: + summary: "登录失败率超过 80%，可能存在暴力破解" + + # 响应延迟过高 + - alert: HighLatency + expr: | + histogram_quantile(0.99, + rate(http_request_duration_seconds_bucket[5m])) > 1 + for: 5m + labels: + severity: warning + annotations: + summary: "P99 响应延迟超过 1 秒" + + # 数据库连接池耗尽 + - alert: DatabaseConnectionPoolExhausted + expr: db_connections_in_use / db_connections_open > 0.9 + for: 5m + labels: + severity: critical + annotations: + summary: "数据库连接池使用率超过 90%" + + # 活跃会话数异常下降 + - alert: ActiveSessionsDropped + expr: | + active_sessions_total < 10 + and + delta(active_sessions_total[10m]) < -5 + for: 5m + labels: + severity: warning + annotations: + summary: "活跃会话数急剧下降" + + # 限流拦截频繁 + - alert: RateLimitRejectionsHigh + expr: | + rate(ratelimit_rejections_total[5m]) > 10 + for: 5m + labels: + severity: warning + annotations: + summary: "限流拦截频率过高" +``` + +--- + +## 4. Grafana 看板 + +建议导入以下看板配置： + +### 4.1 核心看板指标 + +**Overview 看板**： +- 请求率（QPS） +- P50/P90/P99 延迟 +- 错误率 +- 活跃会话数 + +**Auth 看板**： +- 登录尝试（成功/失败） +- Token 刷新次数 +- 活跃会话趋势 +- TOTP 启用率 + +**Database 看板**： +- 查询延迟 P99 +- 连接池使用率 +- 慢查询数量 + +**Cache 看板**： +- 命中率 +- 未命中率 +- L1/L2 缓存对比 + +--- + +## 5. 日志关键字监控 + +建议在日志收集系统（如 Loki/ELK）中配置以下关键字告警： + +| 关键字 | 严重程度 | 说明 | +|--------|----------|------| +| `auth: increment login attempts failed` | warning | Redis/L1 缓存不可用 | +| `goroutine leak` | critical | 潜在的 goroutine 泄漏 | +| `token blacklisted but refresh failed` | critical | Token 黑名单写入失败 | +| `password reset code replay` | warning | 可能存在验证码重放 | +| `temporary login token cleanup failed` | warning | 临时令牌清理失败 | +| `cache.Set failed` | warning | 缓存写入失败 | +| `failed to send email` | warning | 邮件发送失败 | + +--- + +## 6. 健康检查脚本示例 + +```bash +#!/bin/bash +# health_check.sh — 服务健康检查脚本 + +HEALTH_URL="http://localhost:8080/health" +READY_URL="http://localhost:8080/health/ready" +METRICS_URL="http://localhost:8080/metrics" + +check_endpoint() { + local url=$1 + local name=$2 + local status=$(curl -s -o /dev/null -w "%{http_code}" "$url") + + if [ "$status" -eq 200 ]; then + echo "[OK] $name: $status" + return 0 + else + echo "[FAIL] $name: $status" + return 1 + fi +} + +# 执行检查 +failed=0 + +check_endpoint "$HEALTH_URL" "Health" || failed=$((failed + 1)) +check_endpoint "$READY_URL" "Ready" || failed=$((failed + 1)) + +# 检查 Prometheus 指标端点 +status=$(curl -s -o /dev/null -w "%{http_code}" "$METRICS_URL") +if [ "$status" -eq 200 ]; then + echo "[OK] Metrics: $status" +else + echo "[WARN] Metrics: $status" +fi + +# 检查数据库连接（通过日志） +if grep -q "database opened" logs/app.log 2>/dev/null; then + echo "[OK] Database: connected" +else + echo "[FAIL] Database: not connected" + failed=$((failed + 1)) +fi + +exit $failed +``` + +--- + +## 7. Kubernetes 部署配置示例 + +```yaml +apiVersion: apps/v1 +kind: Deployment +spec: + template: + spec: + containers: + - name: user-management + livenessProbe: + httpGet: + path: /health/live + port: 8080 + initialDelaySeconds: 10 + periodSeconds: 15 + timeoutSeconds: 5 + failureThreshold: 3 + + readinessProbe: + httpGet: + path: /health/ready + port: 8080 + initialDelaySeconds: 5 + periodSeconds: 10 + timeoutSeconds: 3 + failureThreshold: 3 + + ports: + - name: http + containerPort: 8080 + - name: metrics + containerPort: 9090 + + resources: + requests: + memory: "256Mi" + cpu: "200m" + limits: + memory: "1Gi" + cpu: "1000m" +``` + +--- + +*最后更新：2026-05-10* diff --git a/docs/guides/USER_GUIDE.md b/docs/guides/USER_GUIDE.md new file mode 100644 index 0000000..3f8d70f --- /dev/null +++ b/docs/guides/USER_GUIDE.md @@ -0,0 +1,253 @@ +# 用户操作手册 + +本文档面向普通用户，描述用户管理系统的使用方法。 + +--- + +## 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 +``` + +示例： + +```bash +curl http://localhost:8080/api/v1/auth/userinfo \ + -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." +``` + +--- + +## 8. 错误代码 + +| 代码 | 说明 | +|------|------| +| 400 | 请求参数错误 | +| 401 | 未认证或 Token 已过期 | +| 403 | 无权限 | +| 404 | 资源不存在 | +| 429 | 请求过于频繁（触发限流） | +| 500 | 服务器内部错误 | + +--- + +*最后更新：2026-05-10*