生产现实（Living Diagram，动态图）

The Reality panel compares production with your model

Reality（现实）让你的 C4 图变成一个反映实际运行情况的动态视图。连接只读的生产环境数据源——Kubernetes、Datadog、New Relic——Archyl 就会发现你真实运行的服务及其依赖关系，再把它们与你精心维护的模型进行对账。你的图不再是一张静态快照，而开始真正反映生产环境。

Reality 是只读且无破坏性的：扫描绝不会更改你的基础设施，也绝不会自行编辑你的 C4 模型。所有被发现的内容都只是一个需要你批准的提议。

工作原理

Reality 始终将三个平面清晰地区分开来：

  • Model（模型）—— 你精心维护的 C4 架构（即意图）。只有你能更改它。
  • Reality（现实）—— 持续刷新的生产环境观测镜像（即事实）。
  • Binding（绑定）—— 二者之间的关联，由你来确认。

扫描器只会写入 Reality 和 Binding 两个平面。把发现的资源提升（promote）进你的模型，始终需要你明确点击操作。

第 1 步 —— 在你的组织中连接数据源

凭据保存在你组织的应用市场中，因此每个数据源只需配置一次，任意项目都可以使用。

前往 Organization → Marketplace（组织 → 应用市场），连接以下任一数据源：

Kubernetes

对集群 API 的只读连接。

  • API Server URL —— 例如 https://10.0.0.1:6443
  • Read-only ServiceAccount Token（只读 ServiceAccount 令牌）—— 创建一个绑定到内置 view ClusterRole 的 ServiceAccount，然后生成令牌
  • Skip TLS Verification（跳过 TLS 校验）—— 仅在自签名的开发集群上才设为 true

Archyl 绝不会写入你的集群——它只调用只读端点（describe/list）。

Datadog

  • API Key 和 Application Key（需具备 APM 读取权限）
  • Site（站点）—— datadoghq.com、datadoghq.eu、us5.datadoghq.com……（必须与你账户所在区域一致）

Datadog 会读取其 APM Service Map（服务地图），包括推断出的外部依赖（数据库、队列、第三方服务）。

New Relic

  • User API Key（NRAK-…）—— 用于读取实体（entity）及其关系
  • Account ID（可选）
  • Region（区域）—— US 或 EU（必须与你的账户一致）

New Relic 会读取 APM 应用和 OpenTelemetry 服务，以及它们之间的 CALLS 关系。

第 2 步 —— 将数据源添加到项目

打开一个项目图，点击工具栏（右上角）中的 Reality。Reality 面板会在右侧打开。

  1. 点击 Add source（添加数据源）。
  2. 选择你已连接的某个集成。
  3. 添加项目作用域（scope）—— Kubernetes 的命名空间（namespace）或 Datadog/New Relic 的环境（environment）（例如 production）。留空则包含全部内容。
  4. 点击 Add & scan（添加并扫描）。

一个项目可以拥有任意数量的数据源——既有 Kubernetes 又有 Datadog、只有一个，或者多个皆可。

第 3 步 —— 扫描

每个数据源都独立扫描。使用数据源上的**刷新（refresh）**图标可重新扫描它。发现过程是幂等的：重新扫描会更新已有内容，而不是重复创建；任何从生产环境中消失的内容都会被标记出来（绝不删除）。

可观测性数据源可能存在延迟：服务通常在几分钟内就会出现，但**关系（relationships）**是通过追踪分析（trace analysis）计算得出的，可能需要 10–30 分钟的持续流量才能填充完整。

第 4 步 —— 对账资源

Resources（资源）选项卡会对发现的内容进行分组：

  • Unmodeled in production（生产环境中未建模）—— 正在生产环境中运行，但尚未出现在你的图上。对于每一项，你可以：
    • Bind（绑定）—— 将其关联到建议的某个已有 C4 元素。
    • Promote（提升）—— 将其转化为一个新的 C4 元素（详见下文）。
    • Ignore（忽略）—— 将其忽略（可恢复）。
  • Drifted（已漂移）—— 已绑定到你的模型，但其生产状态发生了偏离（例如不健康，或已消失）。
  • In your model（在你的模型中）—— 生产环境与 C4 之间已确认匹配的内容。
  • Orphan（孤立项）—— 存在于你的模型中，但在生产环境中没有对应项。

使用**筛选（filter）**字段可按名称、类型（kind）或命名空间进行搜索。

将服务提升到容器层级

提升（Promote）会从一个发现的服务创建一个新的 C4 container（容器）。由于容器位于某个系统内部，因此请先打开你想要的那个系统（下钻到容器层级）。如果没有打开任何系统，Promote 会被禁用并给出提示。新建的容器会落在你当前正在查看的系统中。

第 5 步 —— 对账连接

Connections（连接）选项卡会列出发现的依赖关系（谁调用谁）。当一个连接的两端都已存在于你的模型中（已绑定或已提升）时，该连接才可提升（promotable）。点击 Promote 即可将它作为一条真实关系绘制到你的图上。已提升的连接会自动从提议列表中移除。

图上的 Reality 透镜

当 Reality 面板处于打开状态时，画布会启用一层实时皮肤：那些有已确认生产资源支撑的 C4 元素，会在右上角显示一个小小的健康指示点（health dot）（以及一个实例数量）。这依然是无破坏性的——它只是一层叠加层（overlay），而非编辑。已提升的服务会渲染为干净、普通的节点。

安全与限制

  • 只读 —— Reality 绝不会写入你的生产系统，也绝不会自动编辑你的 C4 模型。每一处更改都由你批准。
  • 数据源隔离 —— 扫描某个数据源绝不会影响另一个数据源的数据。
  • 可逆 —— 绑定可以解除，被忽略的项目可以恢复，已提升的元素就是普通的 C4 元素，你可以随意编辑或删除。
  • 信任级别 —— 关系会按来源标注：observed（观测得到，来自遥测数据，信号最强）与 config-derived（配置推导，来自集群配置）。遥测类数据源（Datadog、New Relic、Kubernetes + 服务网格）能提供最完整的依赖关系图。