配置不止一个文件的原因，以及合并规则
一句话总结
Backstage 配置不是一张 app-config.yaml；开发环境地址常为 localhost:3000，实际配置则是多张文件按顺序叠加的结果。mapping 深度合并，list 整体替换，后面的文件获胜。掌握这一规则即可解释大多数“为何修改不生效”。
为什么需要它
同一代码运行于开发者笔记本、CI、staging、production，而 URL、数据库、认证、TechDocs 构建方式都不同。若全部塞进一文件，每次为某环境修改提交都会破坏其他环境，token 和密码也不能放入文件。因此 Backstage 把配置拆分并按顺序叠加读取。
工作原理
多张文件按顺序叠加
| 文件 | 位置 | 内容 |
|---|---|---|
app-config.yaml |
提交到仓库 | 所有环境公共默认值 |
app-config.local.yaml |
个人笔记本，git 忽略 | 个人 override |
app-config.production.yaml |
随容器镜像 | 生产差异 |
启动时按 --config 列出顺序读取，后者覆盖前者。文件名没有特殊魔法，顺序才是一切。
合并规则只有两条
매핑(map) : 키 단위로 깊게 합친다. 뒤에 없는 키는 앞의 값이 그대로 남는다
리스트(list): 합치지 않는다. 뒤에 있으면 통째로 교체된다
list 最容易引发事故。基础文件 catalog.locations 有三项，本地文件只有一项时，结果不是四项而是一项，其余静默消失。mapping 若值类型变化，也没有可深度合并的对象，会直接替换，例如 connection 从 string 变为 mapping 时旧 string 消失。
Secret 来自环境变量而非文件
写 ${GITHUB_TOKEN} 会在启动时用环境变量替换。配置文件会提交到仓库并烘焙进镜像，所以直接写值会永久留在 Git 历史和镜像层。
以 APP_CONFIG_ 开头的环境变量还能覆盖特定配置路径，路径中的点改成下划线：
APP_CONFIG_app_baseUrl=https://portal.example.com → app.baseUrl 을 덮는다
APP_CONFIG_backend_listen_port=7007 → backend.listen.port 를 덮는다
这样修改部署 manifest 即可变更值，无需重建镜像，尤其适合 Kubernetes。
哪些值会进入浏览器
配置值有 visibility。默认仅后端可见，只有 schema 标记为 frontend 的值进入前端 bundle，否则 integrations.github[0].token 等秘密会暴露于浏览器源码。并非配置中的所有值都可由前端读取。
常用区块
| key | 作用 |
|---|---|
app · organization |
浏览器 URL 和名称 |
backend |
listen、port、CORS、database |
integrations |
GitHub、GitLab 等 SCM credential |
proxy |
后端代浏览器调用外部 API |
catalog |
通过 rules 允许 kind、通过 locations 管理手工 location，并通过 providers 进行 discovery |
auth |
登录 provider 与 identity resolver |
techdocs |
谁构建文档、存到哪里 |
proxy 的意义在于前端直接调用外部 API 会受 CORS 限制，也会迫使凭据进入浏览器；应由后端代调，前端只调用自己的后端路径。catalog.providers 的 schedule 也需权衡：太短触发 SCM 限额，太长则信息陈旧、用户失去信任。
现场表现
homelab 曾遇到相似的两类事故。containerd 的 /etc/containerd/conf.d/ 中多个 drop-in 修改同一 plugin 时，并非字段合并，而是按名称最后的文件接管整个 plugin 配置；前面值不保留，缺失项回落默认值。为了“只加一行”新增文件，结果让 runtime 全部回到默认，类似 Backstage list 整体替换。
另一次开启 HTTPS redirect 后证书续期失败，即使更具体地配置 /.well-known/acme-challenge/ 也无效，因为 Cilium 不按路径具体度优先。这说明“写得更具体就会赢”并不成立，真正决定的是顺序。
Ready 也不等于以期望配置运行。门户启动并不证明合并结果正确，必须养成检查最终有效配置的习惯。
下一步
将在 /root/cba-config/ 编写基础、本地 override、production 三张配置，手工预测两张叠加结果并由评分器按相同规则核对。最后把 production 配置作为 ConfigMap 放入集群，并用 APP_CONFIG_ 环境变量覆盖一行。