Cloud Native Landscape 数据仓库实战指南：基于 landscape.yml 添加新条目与配置 TAG 的完整规范

• 云原生
• 数据集

CNCF 云原生 Landscape（技术全景图）是云原生领域最具权威的技术地图，用于分类展示数百个云原生项目与产品，并在条目详情中呈现 GitHub Stars、资金、首次/最近提交、贡献者数量、总部位置等动态信息。本文以当前数据仓库为蓝本，系统讲解如何通过修改 landscape.yml 与 hosted_logos 目录向全景图提交新条目，以及如何正确配置 Technical Advisory Groups（TAG）与条目详情摘要字段——读完本文，你将能独立完成一个合规、可合并的 landscape 新条目提交。

仓库定位：全景图的数据源而非生成器

当前仓库并不负责渲染网页，它保存的是生成 CNCF Landscape 所需的数据文件与图片资源：

• landscape.yml：核心数据文件，共 18,291 行，按category → subcategory → item三层结构组织全部条目；
• hosted_logos：本地缓存的 SVG 格式 Logo 目录（当前已收录 1,886 个 SVG 文件，供 2,239 个条目引用）；
• 实际负责渲染的软件位于cncf/landscape2项目（本文不展开其源码细节）。

landscape.yml中的一级分类（Category）如下，新条目必须放进已有的某个分类与子分类，项目方明确表示"我们不太可能为某个产品/项目新建分类"：

以 landscape.yml 开头的真实条目为例，每个条目的基础字段结构如下：

landscape: - category: name: Provisioning subcategories: - subcategory: name: Automation & Configuration items: - item: name: Airship homepage_url: https://www.airshipit.org/ repo_url: https://github.com/airshipit/treasuremap logo: airship.svg twitter: https://twitter.com/airshipproject crunchbase: https://www.crunchbase.com/organization/open-infrastructure-foundation

提交新条目的完整流程

添加新条目需要打开一个 Pull Request，将条目按字母顺序插入 landscape.yml，并将 Logo（SVG 格式）添加到hosted_logos目录，通过logo字段引用。提交前必须逐条核对以下准入规则：

入选门槛与归类原则

1. 云原生属性 + 星标门槛：符合 Cloud Native 定义 的、GitHub Stars 至少 300 的项目，且能清晰归入现有分类的，一般会被收录；项目应放入唯一最合适的那个分类。
2. 一家公司只占一格：一般只列出公司最有代表性/最知名的一款产品，避免同一产品在多处重复出现——若允许重复，全图上千个 Logo 会成倍膨胀。
3. 不新建分类：优先为产品找到现有分类中的最佳位置。
4. 商业版本排除：一般不收录开源软件的商业发行版，唯一例外是所有 Certified Kubernetes 实现。
5. 闭源产品必须有清晰说明：闭源产品需要链接到产品介绍页，不接受"隐身模式"（stealth mode）的公司。
6. Crunchbase 组织归属：crunchbase字段应填写控制该软件的公司或组织（通常是商标持有者，无论商标是否已正式注册）。

Logo 的硬性规范

合并后的可见性

[!NOTE] 目前全景图按天生成，因此 PR 合并后，你的修改应在 24 小时内可见。

配置 TAG（Technical Advisory Groups）

在landscape.yml中，条目可以在extra节点下通过tag字段指定归属的技术咨询组。可选值如下：

• app-delivery
• contributor-strategy
• environmental-sustainability
• network
• observability
• runtime
• security
• storage

仓库中的实际使用示例（landscape.yml 等）表明，tag作为extra的子字段写入，例如：

extra: accepted: '2021-09-14' annual_review_date: '2023-06-13' tag: security

自动检测机制与人工修正

当条目未显式提供tag时，系统会根据 settings 文件中预定义的"分类/子分类 → TAG"映射自动检测归属。由于这种映射并非总能命中真实情况，自动检测结果可能不准确。因此：

• 若发现自动检测的 TAG 不准确，推荐做法是在extra中手动显式提供tag字段；
• 如果你发现某个条目的 TAG 有误，欢迎直接提交 PR 修正。

条目详情摘要：extra节点的信息增强

全景图能够在条目详情视图中展示摘要（summary）区块，前提是在landscape.yml对应条目的extra节点中提供所需字段。需要注意：更新这些信息要求你是项目所有者、维护者，或与项目有紧密关联。完整的字段参考（样例取自 Dragonfly 与仓库中 KubeEdge 等条目的真实写法）如下：

extra: summary_personas: SREs, Cloud Architects, Platform Engineers, DevOps Engineer, DevOps practitioners, DevSecOps practitioners summary_tags: image acceleration, file distribution, images, OCI, container, artefacts, registry, cloud native, p2p, dragonfly, d7y, nydus summary_use_case: >- Provide efficient, stable, securefile distribution and image acceleration based on p2p technology to be the best practice and standard solution in cloud native architectures. It is widely used in the fields of image distribution, file distribution, log distribution, inference model distribution, etc. summary_business_use_case: >- Reduce back-to-source download traffic and back-to-source requests, improve node idle bandwidth utilization. Solve the problem of insufficient bandwidth or overload to download resources when accessing centralized container registry or file service in large-scale Kubernetes cluster. Based on P2P technology, reduce the bandwidth and load of container registry or file service, and accelerate the download speed of images or files. summary_release_rate: Major release every 2 months. summary_integrations: >- Harbor, Docker, Containerd, CRI-O, Podman, ORAS, Nydus, eStargz, HDFS, AWS S3, Google GCS, Azure Blob, Aliyun OSS, HWC OBS, TensorFlow Serving, Triton Server, TorchServe summary_intro_url: https://www.youtube.com/watch?v=TsECBaAvm-g

各字段的撰写要点：

• Target Users（summary_personas）：面向谁？开发者、SRE/DevOps 工程师还是架构师？
• Tags（summary_tags）：描述项目技术属性的标签，聚焦技术特性，目标是让用户在高层面上区分和比较项目。例如 KubeEdge、Akri、OpenYurt、SuperEdge 都会共享Edge标签表明与网络边缘相关；OpenYurt 和 SuperEdge 可能共享IoT标签，而 KubeEdge 与 Akri 则不会；Metal3-io 的标签应突出其是唯一涉及 baremetal 与 provisioning 的项目。
• Use case（summary_use_case）：聚焦项目解决的技术问题与痛点，简明扼要，不超过 500 字符。
• Business use（summary_business_use_case）：阐述项目的业务价值——如何为组织创造价值？降低某类风险（如合规、声誉），还是提升对客户需求的响应速度？是否以降低业务支撑成本的方式增强安全性？同样不超过 500 字符。
• Release cadence（summary_release_rate）：多久发布一个新版本。
• Integrations（summary_integrations）：与哪些系统/组件集成。
• Overview video（summary_intro_url）：可选，5 分钟产品介绍视频链接。

从 landscape.yml 中 KubeEdge 条目的实际写法可以看到，这些字段可以与大段的业务案例描述组合使用，且summary_use_case、summary_business_use_case使用 YAML 折叠块标量（>-）支持多行文本。此外，extra节点还承载其他元数据，如accepted（加入日期）、incubating（孵化日期）、dev_stats_url（devstats 统计链接）、artwork_url、slack_url、clomonitor_name以及audits（安全审计记录）等，这些字段共同构成条目在详情页的丰富信息面板。

勘误与修正（Corrections）

如果在全景图中发现错误，请直接对 landscape.yml 提交带修改建议的 Pull Request。需要特别留意的是：部分展示信息来自 Crunchbase 或 GitHub（如星标数、融资、提交记录、贡献者、总部位置等），这类数据的错误应在其源头修正，而非在 landscape.yml 中修改。

许可证与数据使用边界

• 生成的全景图包含来自 Crunchbase 的数据，该数据不受 Apache License 约束，须遵守 Crunchbase 的 Data Access Terms，且仅允许用于 Linux Foundation landscape 项目；
• 除项目/产品 Logo（版权一般归其创建公司所有，此处仅为可靠性而缓存）外，其余内容遵循 Apache License 2.0；
• 生成的全景图与 landscape.yml 文件可另选用Creative Commons Attribution 4.0许可。

小结：一次合规提交流程的检查清单

1. 确认项目符合 Cloud Native 定义且 GitHub Stars ≥ 300；
2. 在 landscape.yml 中找到唯一最合适的 category/subcategory，按字母序插入条目，补齐homepage_url、repo_url（如适用）、logo、twitter、crunchbase等基础字段；
3. 将符合规范的 SVG Logo 放入 hosted_logos，确保含英文名称、非反色、堆叠版式优先；
4. 如需指定归属，在extra中设置tag字段（app-delivery、security、runtime、network、observability、storage等 8 个取值之一），否则等待系统基于 settings 映射自动检测；
5. 若为项目所有者/维护者，可在extra中补充summary_*摘要字段，让详情页展示目标用户、标签、技术用例、业务价值、发布节奏与集成列表；
6. 提交 PR 并等待合并——由于全景图每日生成，合并后 24 小时内即可生效。

• 云原生
• 数据集