70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
# 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)
|