Become a sponsor
2.3 配置文件与环境变量
概述
配置以 config/config.yaml 为基，任意键可被环境变量覆盖（12-Factor 风格）。开发期改 YAML，生产期用环境变量注入敏感项。
配置节总览
| 配置节 | 职责 |
|---|---|
| server | 监听地址（默认 :8000） |
| logger | 日志级别、控制台开关、文件目录 |
| database | GORM 连接（driver/host/port/username/password/dbname/params/连接池） |
| redis | 缓存连接（为空降级内存） |
| jwt | 密钥、签发者、双令牌有效期 |
| captcha | 验证码字符集、尺寸、干扰参数、万能码 |
| rateLimit | 限流开关、窗口、普通/认证接口配额 |
| operationLog | 操作日志总开关与查询类记录开关 |
| job | 日志保留天数、执行锁 TTL |
| tenant | 超管新增租户级数据的默认归属 |
| app | 时区、演示模式 demo、生产模式 prod |
| api | 受信代理、请求体上限、文档/指标端点开关 |
| cors | 允许来源 |
| file | 上传根目录、访问域名、扩展名与大小限制 |
| generator | 生成器开关、菜单挂载父级、覆盖策略 |
| ip2region | 归属地库文件路径 |
完整键值说明见 附录 C 配置项速查。
环境变量覆盖规则
键名 = 配置路径大写、点换下划线、加 APP_ 前缀，仅覆盖 YAML 中已存在的键，空值视为未设置：
text
database.default.host → APP_DATABASE_DEFAULT_HOST
redis.default.pass → APP_REDIS_DEFAULT_PASS
jwt.secret → APP_JWT_SECRET
app.prod → APP_APP_PROD覆盖在启动时由 utility/config 叠加生效。
.env.example
根目录 .env.example 是环境变量样例，复制为 .env 后按需修改：
bash
cp .env.example .env样例包含数据库、Redis、JWT 密钥、文件域名等友好名映射（docker-compose 经 environment 块把友好名转成 APP_ 规范键）。
硬检查
新增配置键必须同步更新 .env.example——make check-config（cmd/api -check-config）会硬检查两者的键一致性，不一致直接失败。
生产模式要点
app.prod=true 时启动校验将拒绝：
- 默认或过短的 JWT 密钥
- 非空的验证码万能码（captcha.bypassCode）
- 未关闭的代码生成器（generator.enable）
生产部署必须开启 prod 并关闭文档端点（api.docs=false）。详见 11.8 安全加固清单。