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