user-system/docs/guides/CONFIG_REFERENCE.md

# 配置参考手册

本文档描述 `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*