long-agent/user-system
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f91b5d1cefa66599f10fd1c3a489f2147bb081f4
user-system/docs/guides/CONFIG_REFERENCE.md
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

332 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 配置参考手册
本文档描述 `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*
Reference in New Issue View Git Blame Copy Permalink