# 2.3 配置文件与环境变量

:::tip 概述
配置以 `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 配置项速查](/zh/appendix/config-reference.html)。

## 环境变量覆盖规则

键名 = **配置路径大写、点换下划线、加 `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_` 规范键）。

:::warning 硬检查
新增配置键必须同步更新 `.env.example`——`make check-config`（`cmd/api -check-config`）会硬检查两者的键一致性，不一致直接失败。
:::

## 生产模式要点

`app.prod=true` 时启动校验将拒绝：

- 默认或过短的 JWT 密钥
- 非空的验证码万能码（captcha.bypassCode）
- 未关闭的代码生成器（generator.enable）

生产部署必须开启 prod 并关闭文档端点（`api.docs=false`）。详见 [11.8 安全加固清单](/zh/deploy/security.html)。

## 下一步

→ [2.4 后端服务启动](/zh/quickstart/backend-start.html)