亲眼看目录真的拒绝掉什么

本实验使用 Backstage 的真实库运行

VM 中已安装 Backstage 的目录与配置库。 提交 catalog-info.yaml 后，它会被真实验证；错误内容会被拒绝；多个 app-config.yaml 也会被实际合并。

这里不会启动完整的 Backstage 实例——那会占用数百 MB，并需要数分钟 进行构建。我们改为直接运行 Backstage 将实体加入目录时使用的 同一套库。验证、合并和关系解析都是真实行为。

前一模块的目录实验只练习了如何编写 catalog-info.yaml， 却无法确认该 YAML 是否真的能通过验证。

首次启动约需 4 分钟（npm install 需要访问互联网）。

已准备的内容

프로젝트    /opt/cba (Backstage 라이브러리 설치됨)
검증 도구   validate-entity <yaml파일>
라이브러리  /opt/cba/lib.js (catalog-model·config·yaml)

步骤

1. 创建一个实体并使其通过验证，将结果写入 /root/cba/entity.txt。
2. 让错误实体被真正拒绝，将结果写入 /root/cba/reject.txt。
3. 使用实体引用（parseEntityRef）解析关系，将结果写入 /root/cba/refs.txt。
4. 通过所有者和系统连接八类实体，将结果写入 /root/cba/graph.txt。
5. 合并多个 app-config.yaml，将最终胜出的值写入 /root/cba/config.txt。
6. 观察环境变量替换（${...}）的工作方式，将结果写入 /root/cba/env.txt。
7. 扫描整个目录以诊断一致性，将结果写入 /root/cba/audit.txt。
8. 在 /root/cba/report.md 中写入 valid=、rejected=yes、merge_winner= 三行及说明。

提示

• 使用 validate-entity good.yaml 进行验证。通过时输出 OK:，失败时输出 REJECTED:。
• 使用 node script.js 运行脚本，并通过 require('/opt/cba/lib.js') 使用库。
• 常见误区：只要模式验证通过，实体就有效。策略（名称格式、根字段）还会进一步筛选。
• 常见误区：最后一个配置文件会覆盖全部内容。配置实际上会按键进行深度合并。

要加入目录的实体

创建一个实体并使其通过验证，将结果写入 /root/cba/entity.txt。

需要 kind、metadata.name 和 spec。Component 还要求 type、lifecycle 和 owner。

仅有模式验证还不够

让错误实体被真正拒绝，将结果写入 /root/cba/reject.txt。

尝试在名称中加入大写字母和空格，再加入未知的根字段。模式和策略会分别捕获不同问题。

引用建立关系

使用实体引用（parseEntityRef）解析关系，将结果写入 /root/cba/refs.txt。

用 parseEntityRef 解析 user:default/jdoe 和 team-a，观察默认 kind 与 namespace 如何补全。

连接八类实体

通过所有者和系统连接八类实体，将结果写入 /root/cba/graph.txt。

创建 Component、API、Resource、System、Domain、Group、User，并通过 owner、system、providesApis 将它们连接起来。

配置会深度合并

合并多个 app-config.yaml，将最终胜出的值写入 /root/cba/config.txt。

叠加多个 app-config。后一个文件不会覆盖全部内容，而是按键合并。

配置中的环境变量

观察环境变量替换（${...}）的工作方式，将结果写入 /root/cba/env.txt。

${VAR} 会在加载时替换为环境变量值，从而避免把机密写进文件。

目录会随时间腐化

扫描整个目录以诊断一致性，将结果写入 /root/cba/audit.txt。

一次验证多个实体，并统计通过数、拒绝数和无所有者实体数。

总结所学内容

在 /root/cba/report.md 中写入 valid=、rejected=yes、merge_winner= 三行及说明。

写入 valid=、rejected=yes、merge_winner= 三行及说明。