Skip to content

配置总览与优先级 ​

整个平台的配置只有一条装载规则,由 platform-config 的 lib.rs 的单函数 load 统一承载:代码默认值垫底,TOML 文件居中覆盖,环境变量最后覆盖。本篇是配置体系的权威指南入口:这一页讲清优先级与命名规则,装载机制讲合并算法与已知的坑,各服务配置参考给出逐服务、逐字段的键表,示例集给四个真实场景的完整配置。

术语约定 ​

后文的“层”指配置的一个来源(默认值、文件、环境变量);“前缀”指服务在环境变量里的命名空间(如 IAM);“段”指环境变量名里双下划线切出的一段(对应配置树的一层,如 JWT);“键”指最终落到配置结构上的字段名(snake_case,如 seed_file)。四个词的关系用一个环境变量串起来:IAM__JWT__SEED_FILE 里 IAM 是前缀、JWT 是段、SEED_FILE 是键,目标字段是 iam 配置树的 jwt.seed_file。

三层装载与优先级 ​

text
1. T::default()        代码内默认值(各服务 config.rs 的 serde default 函数)
2. TOML 文件(可选)    <PREFIX>_CONFIG 环境变量指向;文件不存在视为该层缺席,不是错误
3. 环境变量             PREFIX__SECTION__KEY 形态,最后合并

没有 CLI 参数层。svc-all-in-one 的 --bootstrap <tenant> <email> <password> 是一次性自举子命令(创建租户与管理员),不属于配置面。单机形态在三层之上再叠加一层装配覆写(all-in-one 按自身布局改写各服务配置),优先级细节见装载机制。

用一个键走一遍三层。网关的每 IP 令牌桶容量 rate.capacity:默认值 100(svc-gateway 的 config.rs 的 d_capacity);TOML 文件里写 [rate] capacity = 50 覆盖为 50;环境变量 GW__RATE__CAPACITY=30 再覆盖为 30。三层同时给值时,环境变量赢。若只给了环境变量 GW__RATE__REFILL_PER_SEC=200,容量仍按低层的 50 生效,合并是逐键的,不是整段替换。

环境变量命名规则 ​

规则只有三条,全部实现于 platform-config 的 env_layer 函数:

  1. 前缀大写,后接双下划线分层:IAM__JWT__SEED_FILE 对应配置树的 jwt.seed_file;
  2. 每段去掉首尾下划线后转小写匹配键名(键名本身全是 snake_case,天然对齐);
  3. 值先按 JSON 解析,能解析成数字或布尔的保持标量形态,其余(含 null、含合法 JSON 字符串、含数组)一律退化为字符串。

一个容易踩的推论:数据库连接段(db)在五个业务服务里经 #[serde(flatten)] 平铺到配置根层,所以库名 URL 的环境变量是 IAM__URL,不是 IAM__DB__URL;后者会被静默忽略。这是实测行为,展开见装载机制的陷阱一节。

bash
# 同一事实的三种给法(优先级从低到高)
# 1. 什么都不给:iam.db.url 用默认 postgres://localhost/postgres
# 2. IAM_CONFIG=/etc/rustsvc/iam.toml 且文件里根层 url = "postgres://..."
# 3. IAM__URL='postgres://postgres:pg@127.0.0.1:5432/iam'

各服务前缀与专用环境变量 ​

服务配置前缀配置文件变量自动迁移变量备注
svc-gatewayGWGW_CONFIG无(网关无库)
svc-iamIAMIAM_CONFIGIAM_AUTO_MIGRATE=1
svc-metadataMETAMETA_CONFIGMETA_AUTO_MIGRATE=1另有 META__PROFILE 启动校验
svc-orchestratorORCHORCH_CONFIGORCH_AUTO_MIGRATE=1另有 ORCH_OWNER 标识执行者
svc-meteringMETMET_CONFIGMET_AUTO_MIGRATE=1
svc-gisGISGIS_CONFIGGIS_AUTO_MIGRATE=1
svc-gis-tantivy-indexerGIS(共用配置结构)GIS_INDEXER_CONFIGGIS_AUTO_MIGRATE=1工作目录走 GIS_INDEXER_WORK_DIR
svc-operatorOP无文件层(仅环境变量)无load_or_default 不传文件
svc-all-in-oneAIOAIO_CONFIG内建(auto_migrate 默认 true)装配覆写见 loading 页

未设 <PREFIX>_CONFIG 时,各服务 main.rs 会探测物料内约定路径(如 svc-iam 自带的 iam.toml),存在才启用;物料实际存在的只有 orchestrator 与 metering 两份开发态 TOML。自动迁移变量(IAM_AUTO_MIGRATE 等,单下划线)与 ORCH_OWNER、GIS_INDEXER_WORK_DIR 一样是 main.rs 直读的进程开关,不在配置树里,别与 PREFIX__ 配置前缀混用。

谁在什么时候读配置 ​

配置只在启动期装载一次,没有热更新线程。各服务 main.rs 的顺序固定:探测 <PREFIX>_CONFIG 或默认路径,装载配置,执行启动校验(metadata 的 profile 与 authz 组合校验是代表),初始化 tracing 与指标,然后进入服务装配。改配置的生效方式就是重启。

两个例外是“配置里声明、运行期经事件变更”的动态面:网关动态路由表经 orch.route.changed.v1 事件热更新(静态表仍来自配置);计量配额经 metering.quota.changed.v1 事件驱动配额快照刷新。它们不是配置层的机制,是业务事件,但排障时要意识到有些“看起来像配置”的行为来自事件流。

两种部署形态的配置来源 ​

形态默认值TOML 层环境变量层
单机 all-in-onecrate 默认AIO_CONFIG 指向的文件AIO__* 之上,各服务自身前缀的环境变量仍然生效(显式值优先于 AIO 派生值)
K8s 分进程crate 默认ConfigMap 挂载 /etc/rustsvc/<svc>.toml,<PREFIX>_CONFIG 指向(chart 的 configmap.yaml 渲染)Secret 以 secretKeyRef 注入 <PREFIX>__URL(数据库凭据);<PREFIX>__MQ__BACKEND 与 <PREFIX>__MQ__NATS_URL 由 deployment.yaml 注入

K8s 形态的完整接线(ConfigMap、Secret、迁移 Job 的关系)见 Kubernetes 部署,单机形态见单机部署。

配置之外的两个独立机制 ​

RUST_LOG 不走 platform-config:它是 platform-obs 里 tracing 初始化的 EnvFilter 通道,直读进程环境,与三层装载并存。ORCH_OWNER 与 GIS_INDEXER_WORK_DIR 同理,是 main.rs 直读的进程标识与路径,不进配置树。排障时先分清值属于哪套机制,再查对应入口。

配置结构定义在哪(改配置前先找对文件) ​

每个服务的配置结构、默认值与校验逻辑都在源码里,键表的权威出处如下:

服务配置结构定义备注
svc-gatewaysvc-gateway 的 config.rs路由表与白名单的默认值也在该文件
svc-iamsvc-iam 的 config.rsJWT 种子解析顺序在 JwtKeyConfig::build_ring
svc-metadatasvc-metadata 的 config.rs审批联动与附件存储的子配置在 src/versioning/config.rs 与 src/attachments/config.rs
svc-orchestratorsvc-orchestrator 的 config.rs
svc-meteringsvc-metering 的 config.rs
svc-gis 与 indexersvc-gis 的 config.rsindexer 复用 GisConfig
svc-operatorsvc-operator 的 config.rs
svc-all-in-onesvc-all-in-one 的 config.rs装配覆写逻辑也在该文件
共用 db 段platform-db 的 pool.rs 的 DbConfig经 serde flatten 平铺进各服务根层
共用 mq 段platform-mq 的 lib.rs 的 MqConfig

每个 config.rs 的测试模块里有 defaults_match_design 一类的断言测试,锁定默认值不被无意改动;本站键表与这些断言同源。

排查一个配置问题的顺序 ​

配置问题的定位按固定顺序走,能避开绝大多数绕路:

  1. 确认键名与层形态:环境变量是否双下划线、数据库键是否在根层(平铺语义)、数组是否误经环境变量给了。
  2. 确认文件层真实存在:<PREFIX>_CONFIG 的值、挂载路径、文件权限;不存在是静默跳过。
  3. 看启动日志的 starting 行:http、grpc、mq 端口与后端是否是期望值。
  4. 检查进程环境里有没有 PG 系变量穿透(连接身份错时尤其)。
  5. 单机形态再查一层:这个键是否属于 AIO 布局(被装配覆写接管),出口是否应为 AIO__*。

各步的展开与原理见装载机制,逐服务的完整键表见各服务配置参考。

三个常见误解 ​

误解一:“单机形态只认 AIO 前缀”。实际上 svc-all-in-one 进程里各服务仍以自身前缀装载(IAM__*、GW__* 等照样生效),AIO 只在其上做布局覆写;显式设置的服务级值优先于派生值。误解二:“环境变量比文件高级,所以文件可以随便写”。合并是逐键的,文件层管住数组与复杂结构(环境变量给不了数组),环境变量管住部署期的少量覆盖,两层是分工不是竞争。误解三:“*_AUTO_MIGRATE 是配置项”。它是 main.rs 直读的进程开关,单下划线,不进配置树,也因此不出现在任何服务的键表里。

一个容易忽略的细节收尾:配置结构的演化遵循 serde 的宽松规则(新字段给默认值、旧字段缺省兼容),因此升级平台版本时旧配置文件通常无需改动;但数组与嵌套结构的形态变化例外,升级说明里会逐条列出需要迁移的键。

相关页面 ​

以仓库代码为事实源构建 · RC Hardening 阶段