配置体系
一句话:配置是 yaml + 环境变量两层,所有相对路径在加载期钉成绝对路径, 所有"漏配"都被显式处理成"照常跑"而不是"静默变弱"。
配置从哪来
configs/config.yaml ← 本地配置(gitignore,含密码 / AK-SK)
↓ viper
环境变量 ← 优先级更高,用于注入密钥
↓ config.Load()
config.Server ← 内存里的强类型结构体
- 加载入口:
config.Load(path)—— 只认-config指向的那个 yaml 文件。 - 全局单例:
config.Get()返回*config.Server,config.AppViper是底层 viper。 - 热重载:yaml 改了会重新 Unmarshal 并重新解析路径。
⚠️ Windows 上改 yaml 不会热生效。viper 的热重载依赖 fsnotify,而 Windows
上编辑器的"原子替换"(写临时文件再 rename)会把 watcher 打瞎。改配置请重启进程。
三个必须知道的概念
① 相对路径一律相对 rootDir,不是相对 cwd
config.Root() // 根目录:APP_ROOT 环境变量 > 进程 cwd
config.ConfigFile() // 实际加载的配置文件绝对路径
同一个 server 从不同目录启动(go run / VSCode F5 / systemd WorkingDirectory),
落盘位置必须一样 —— 所以 logger.dir、casbin.model_path、database.sqlite.path
这些都在 Load() 里被钉成绝对路径。
想显式指定根目录:
APP_ROOT=/opt/rapid-admin go run ./cmd/server -c configs/config.yaml
② 环境变量覆盖:${VAR} 与自动映射
database:
mysql:
password: ${MYSQL_PASSWORD}
- yaml 里的
${VAR}会被 viper 展开成环境变量的值。 AutomaticEnv()+SetEnvKeyReplacer("." → "_")让每个配置键都能被环境变量覆盖:database.mysql.password→ 环境变量DATABASE_MYSQL_PASSWORD。- 密钥建议一律走环境变量,别写进 yaml(yaml 会被复制、会被备份、会被提交)。
③ "漏配"必须等于"照常跑"
这是本框架配置层的第一纪律,也是最容易踩的地方。
Go 的 bool 零值是 false。如果"没配"和"配成 false"是同一件事,那么:
- 漏配
captcha.login_enabled→ 验证码校验静默消失; - 漏配
job.enabled→ 一个定时任务都不跑,而且没有任何症状(页面能开、接口能通); - 漏配
swagger.enabled→ 文档端点静默 404。
所以配置层给这些键显式设了安全默认值:
| 键 | 默认值 | 漏配的后果(如果不设默认) |
|---|---|---|
captcha.login_enabled |
true |
登录不校验验证码 |
captcha.sms_send_enabled |
true |
发短信不校验验证码 |
auth.revocation_mode |
auto |
token 吊销判定行为不明 |
auth.anomaly.enabled |
true |
异常登录检测静默不跑 |
auth.anomaly.max_concurrent |
3 |
兜底成 1 ⇒ 多人多端登录全被判异常 |
auth.anomaly.active_window |
30m |
兜底成 0 ⇒ 永远不判同时在线 |
job.enabled |
true |
一个定时任务都不跑 |
job.lock_renew |
true |
长任务跑到一半锁过期,副本并发写 |
job.timezone |
Asia/Shanghai |
容器里 TZ 没设 ⇒ 任务在北京时间 11:00 跑 |
swagger.enabled |
true |
/swagger 静默 404 |
swagger.auth.mode |
auto |
空串 = "没配凭据" ⇒ 文档端点裸奔 |
⚠️
swagger.auth同时管着/docs(框架手册) —— 两者共用同一套 BasicAuth 凭据(见 框架手册)。swagger.enabled只管/swagger: 关掉它,手册照旧在/docs上。
反过来,默认值必须是"安全的那一侧":
cache.mode默认auto(有 Redis 用 Redis,没有退纯 L1)—— 缓存失效只会变慢,不会出安全事故,所以漏配无所谓。auth.anomaly.impossible_travel_window默认0s(关闭)—— 没有 IP 地理库,开着必然误报。这是有意关掉的,不是漏配。
配置分块
config.Server 一共 30 个块(见 internal/config/ 下一个文件一个块):
| 块 | 归属模块 | 作用 |
|---|---|---|
system |
— | 端口、模式、时区、超时、请求体上限 |
branding |
swaggerx | 平台名 / 浏览器标题(换名字改这里) |
swagger |
swaggerx | 文档端点开关 + 鉴权方式 |
logger |
logger | 级别、格式、目录、按天/按级别分文件、轮转 |
database / mysql |
— | driver 选择 + 连接池 |
redis |
cachex / kvstore | 连接地址、DB 号、密码 |
jwt |
auth | 签名密钥、access / refresh 有效期、签发方受众 |
auth |
auth / anomalylogin | 吊销存储模式、异常登录检测 |
kv |
kvstore | 限流 / 登录锁定的存储模式(auto/redis/memory) |
cache |
cachex | 两级缓存:L1 容量 / TTL、空值 TTL、抖动 |
job |
cronx / jobs | 调度开关、时区、锁、执行记录保留 |
casbin |
casbinx | 模型文件路径、自动加载策略 |
cors |
— | 允许的 Origin、方法、Header |
captcha |
— | 登录 / 发短信两个独立开关 |
sms |
msn | provider(aliyun/console)、签名、模板 |
email |
emailx | provider、账号、域名 |
push |
pushx | provider、APP 凭证 |
oss |
oss | provider(local/aliyun)、bucket、endpoint |
file |
oss / media | key 根、大小上限、ffmpeg 路径、会话 TTL |
crypto |
crypto | 字段加密开关、算法 |
kms |
kms | provider(local)、轮转周期 |
ratelimit |
ratelimitx | 限流开关与配额 |
audit |
piiaudit | 审计开关与批量大小 |
otel |
otelx | 开关、endpoint、采样率 |
breaker |
— | 熔断阈值与恢复窗口 |
client_ip |
— | 可信反向代理网段(决定 ClientIP 怎么取) |
timeout |
— | 各类请求超时 |
metrics |
metricsx | Prometheus 开关、路径 |
crypto_keys |
crypto | 各业务字段用哪把 key |
每个块的字段级说明见 configs/config.example.yaml(那是唯一逐字段的说明文件,
本手册不重复抄,免得两边漂移)。
⚠️ Windows 上没有官方 Redis ——
redis.addr要指一台真 Redis 时,Windows 上用 Memurai(Redis 协议兼容,装成 Windows 服务, 默认127.0.0.1:6379、无密码)。Developer 版仅供开发/测试,不许上生产。 详见 快速开始。
加一个新配置块的步骤
- 在
internal/config/加一个文件,定义XxxConfigstruct,字段带mapstructuretag; - 在
config.Server里加一个字段,tag 是 yaml 里的块名; - 在
configs/config.example.yaml写默认值 + 注释(注释就是文档); - 如果漏配会有危险,在
config.Load()里v.SetDefault(...)显式钉住; - 消费方只用
config.Get().Xxx,不要自己再读一遍 yaml。