自建实体 YAML 配置说明¶

本文主要说明用户在手动创建自建实体时，应该如何编写 YAML。

这不是某一个实体类型的固定模板，而是一份通用填写规范。文中的 Host 片段只是示例，用来帮助理解“字段应该怎么写”，不代表所有实体都必须包含 Host 相关字段。

配置原则¶

手动编写实体 YAML 时，建议按下面的思路组织：

使用 attributes 作为实体属性主体
先填写通用治理字段，再补充实体专属字段
name 使用稳定标识，不要直接使用会频繁变化的展示名
owner 默认填写责任团队；个人联系人放在 contact 中，避免一个字段同时承担团队和个人两种语义
component_of 和 depends_on 统一使用 entity_type:entity_name 形式引用其他实体。

最小可用示例¶

如果您只想先录入一条最基础的实体信息，建议至少填写以下内容：

attributes:
  name: payment-worker-01
  display_name: 支付工作节点 01
  project: payment
  owner: sre-platform

完整示例¶

下面是一份完整示例。它使用 Host 作为例子，展示通用字段和实体专属字段可以如何组合：

attributes:
  name: prod-host-01
  host: prod-host-01
  project: payment
  display_name: 主机 01
  description: 支付核心服务的生产环境主机，承载结算与对账任务。

  host_ip: 10.20.30.40
  os: linux
  lifecycle: active
  env: prod

  cloud_provider: aliyun
  instance_id: i-bp1example
  region: cn-hangzhou
  zone: cn-hangzhou-h

  owner: sre-platform

  component_of:
    - system:payment-cluster
    - system:payment-platform
  depends_on:
    - service:config-center
    - database:mysql-payment-prod

  custom_tags:
    - category:settlement
    - critical

  contact:
    - type: email
      name: 值班邮箱
      value: sre@example.com
    - type: slack
      name: 告警频道
      value: https://company.slack.com/archives/C12345678
    - type: phone
      name: 值班电话
      value: 123456789

  link:
    - type: view
      name: 主机监控面板
      dashboardUUID: dsbd_a7b598b675e76125614712354feb826e1d
    - type: doc
      name: 故障处理手册
      provider: wiki
      link: https://wiki.example.com/host-runbook
    - type: repo
      name: 仓库
      provider: github
      link: https://github.com/example/payment-host

字段怎么分¶

可以把 YAML 中的字段分成两类理解：

1. 通用字段¶

这类字段用于治理、检索、归属和协作，大多数实体类型都建议支持。

字段	是否建议填写	类型	含义	填写建议
`name`	必填	string	实体唯一标识	使用稳定、不易变化的英文标识。建议只用小写字母、数字和连字符。
`display_name`	建议	string	实体显示名	面向用户展示，可使用中文。
`description`	建议	string	实体说明	简要说明它是什么、做什么、归谁维护。
`project`	建议	string	所属项目	用于归类到项目、业务域或产品线。
`env`	按需	string	环境标识	常见值如 `prod`、`staging`、`test`、`dev`。
`owner`	建议	string	责任团队	默认填写团队名，不建议直接填个人。
`component_of`	按需	string[]	所属上级实体	填写当前实体从属的系统、集群或平台。
`depends_on`	按需	string[]	依赖的下游实体	填写当前实体直接依赖的服务、资源或系统。
`custom_tags`	按需	string[]	自定义标签	用于分类、检索和筛选。
`contact`	建议	object[]	联系方式	用于值班、通知、协作联系。
`link`	建议	object[]	相关链接	用于挂载监控、文档、仓库等链接。

2. 实体专属字段¶

这类字段由具体实体类型决定，不同实体之间会不同。

例如 Host 可能会有：

host
host_ip
os
cloud_provider
instance_id
region
zone
lifecycle

而其他自建实体也可以定义自己的专属字段，例如：

system_type
business_owner
tier
app_id
language

写 YAML 时，不需要把所有实体的字段都写进去，只需要填写：

通用字段中您需要治理和展示的部分
当前实体类型真正用得上的专属字段

通用字段说明¶

`name`¶

name 是实体的稳定标识，建议满足以下原则：

尽量不要使用中文、空格和容易变化的名称
不要直接把展示名当作 name
一旦实体已经被其他对象引用，尽量不要频繁改动。

推荐写法：

name: payment-worker-01

`display_name`¶

display_name 是展示给用户看的名称，可以更自然、更易读。

display_name: 支付工作节点 01

`description`¶

用一句或两句话说明实体的职责、用途或上下文。

description: 承载支付对账任务的生产节点

`project`¶

用于把实体归类到项目、业务域或产品线下。

project: payment

`env`¶

用于标识实体所在环境。建议团队内部统一口径，避免同时出现 prod 和 production 这类同义值。

env: prod

`owner`¶

owner 建议默认填写责任团队，例如：

owner: sre-platform

不建议把 owner 同时当作“团队”和“个人负责人”使用。推荐约定是：

owner 填团队
个人联系人放在 contact 中。

`component_of`¶

表示“当前实体属于谁”，常用于描述归属关系。

统一写法：

component_of:
  - system:payment-platform
  - cluster:payment-cluster

约定格式为：

entity_type:entity_name

例如：

system:payment-platform
service:order-service
database:mysql-payment-prod

`depends_on`¶

表示“当前实体依赖谁”，常用于描述调用、依赖或资源使用关系。

depends_on:
  - service:config-center
  - database:mysql-payment-prod

建议只填写直接依赖，不要把整条依赖链全部展开。

`custom_tags`¶

用于补充分类信息。支持简单标签，也支持带命名空间的标签。

custom_tags:
  - critical
  - category:settlement
  - team:sre

建议：

标签短而稳定
同一类含义尽量只保留一种写法
如果团队已经有标签规范，优先复用现有命名。

`contact`¶

contact 是对象数组，每一项是一条联系方式：

子字段	是否必填	类型	含义	可选值 / 示例
`type`	是	string	联系方式类型	`email` / `phone` / `slack`
`name`	否	string	联系方式名称	`值班邮箱`
`value`	是	string	联系方式内容	`sre@example.com`

示例：

contact:
  - type: email
    name: 值班邮箱
    value: sre@example.com
  - type: phone
    name: 值班电话
    value: 13800000000
  - type: slack
    name: 告警频道
    value: https://company.slack.com/archives/C12345678

`link`¶

link 用于挂载实体相关的链接信息，例如看板、文档、仓库。

常见写法如下：

link:
  - type: view
    name: 主机监控面板
    dashboardUUID: dsbd_a7b598b675e76125614712354feb826e1d
  - type: doc
    name: 故障处理手册
    provider: wiki
    link: https://wiki.example.com/host-runbook
  - type: repo
    name: 仓库
    provider: github
    link: https://github.com/example/payment-host

常见字段含义：

子字段	是否必填	含义	说明
`type`	是	链接类型	值如 `view`、`doc`、`repo`。
`name`	建议	链接显示名	用于前端展示。
`provider`	按需	链接来源	如 `wiki`、`github`。
`link`	按需	外部链接地址	适用于文档、仓库等场景。
`dashboardUUID`	按需	看板 ID	适用于 `view` 类型。

如何补充实体专属字段¶

当您在创建某一种具体实体时，可以在通用字段之外补充该实体自己的属性。

例如创建 Host 时：

attributes:
  name: prod-host-01
  host: prod-host-01
  host_ip: 10.20.30.40
  os: linux
  cloud_provider: aliyun

例如创建一个自定义业务系统时：

attributes:
  name: payment-platform
  display_name: 支付平台
  system_type: business
  tier: core
  owner: payment-tech

判断一个字段是不是“实体专属字段”，可以用这个标准：

如果它主要用于治理、归属、检索、联系，通常属于通用字段
如果它只对某一类实体有业务意义，通常属于实体专属字段

常见错误¶

1. 把 `owner` 填成个人姓名¶

owner 定义的是责任团队。个人联系方式放在 contact 中更稳定。

2. 用展示名充当 `name`¶

display_name 可以灵活变化，但 name 应尽量稳定，否则容易影响引用关系和检索。

3. 把多个联系方式塞进同一个 `value`¶

联系方式建议一条一条拆开写，便于展示、通知和后续处理。

4. 所有字段都照抄模板¶

这份文档的目标是帮助您理解“字段怎么组织”，不是要求您把示例里的字段全部照搬。实际填写时，只保留当前实体真正需要的字段即可。

自建实体 YAML 配置说明¶

配置原则¶

最小可用示例¶

完整示例¶

字段怎么分¶

1. 通用字段¶

2. 实体专属字段¶

通用字段说明¶

name¶

display_name¶

description¶

project¶

env¶

owner¶

component_of¶

depends_on¶

custom_tags¶

contact¶

link¶