跳至主要內容

Cortex：从 Entity Catalog 到 Scorecard Initiative

高谷深陵大约 7 分钟约 1980 字

Cortex 的价值不在于把各系统页面集中到一个入口，而在于用稳定 Entity Tag、Owner、关系和外部证据形成可执行目录。发现结果、GitOps 描述文件、UI 修改和 API 写入如果没有权威顺序，同一个服务会出现重复身份；Scorecard 变绿也可能只是集成返回了陈旧字段。目录、评估和整改必须分别留下来源与时间证据。

Cortex Entity Catalog、Scorecard、Initiative、GitOps 与退出治理知识海报
Cortex Entity、Scorecard 与 Initiative 闭环高清原图

先用稳定样本校验身份与关系

试点不要导入整个组织。先建立 payment-api、ledger-api 和一个故意缺 Owner 的实体，固定不随仓库改名变化的 Tag，再验证显示名变更、Owner 转移、依赖闭合和归档语义。正向结果是同一 Tag 更新原实体；反向结果是重复 Tag 被拒绝或明确报告冲突，而不是静默生成第二个服务。

component:
  id: payment-api
  owner: payments
  lifecycle: production
  dependsOn: [ledger-api]
  runbook: https://example.com/runbooks/payment-api

部署形态与连接器先进入责任表

Cortex 常见入口是托管工作区，也有由厂商交付的 on-premises 形态。部署地点、升级主体、状态存储、备份恢复、厂商访问和许可必须分列确认。连接 SCM、Kubernetes、IdP、值班和观测系统时，逐条记录网络方向、Token Scope、同步频率、读取字段、限流和撤销动作；只做目录发现的连接不应获得写仓库或改集群能力。

用正反实验验证集成与证据退化

Kubernetes Agent 等路径会把集群对象带入目录与 Scorecard。正向实验只允许读取试点 Namespace，反向实验访问相邻 Namespace 应失败；撤销 Token 后，新同步必须报明确权限错误，旧证据进入 Stale 或 Unknown，而不是继续显示绿色。

Entity Descriptor、Tag 与 Owner 是目录身份

Cortex 的目录核心是 Entity。Entity Descriptor 是兼容 OpenAPI 3 的 YAML，并通过 x-cortex-* 扩展表示类型、唯一 tag、Owner、组、依赖和自定义数据。x-cortex-tag 是稳定标识；x-cortex-type 决定实体类型。目录页面本身更像实体集合过滤器，Catalog 需要在 UI 创建，不能仅靠 GitOps 创建。

启用时先由工作区管理员创建 Cortex 工作区和最小角色，连接一个试点 Git 组织，然后在 Catalogs 中选择发现结果导入。也可以通过 UI 手工创建、API 写入或 GitOps 解析 cortex.yaml。导入向导应显式设置 Entity type、tag、Owner、仓库和 on-call，不要接受所有自动推荐。完成后在 All entities 搜索稳定 tag，查看来源文件、最近 GitOps 日志和 Owner。

openapi: 3.0.0
info:
  title: Payment API
  description: Handles payment authorization.
  x-cortex-tag: payment-api
  x-cortex-type: service
  x-cortex-groups:
    - tag: checkout
  x-cortex-owners:
    - type: group
      provider: CORTEX
      name: payments
  x-cortex-link:
    - name: Runbook
      type: RUNBOOK
      url: https://example.com/runbooks/payment-api

x-cortex-owners 可以引用 Cortex 团队、IdP 或 SCM 组，也可以使用邮箱；团队 Owner 比个人邮箱更能承受人员变化。父域或关系可以设置 Owner 继承，APPEND、FALLBACK、NONE 会分别追加、仅在子实体无 Owner 时回退、完全不继承。配置错误会造成 Owner 过多或无人负责：正向实验让子服务无显式 Owner 并设置 FALLBACK，预期得到域 Owner；反向实验给子服务错误 Owner 再使用 APPEND，若页面同时出现两队，就证明继承不是覆盖，必须明确责任规则。

GitOps 会在默认分支寻找 cortex.yaml/cortex.yml，也支持集中仓库中的 .cortex/catalog、.cortex/teams、.cortex/domains 和 .cortex/scorecards。删除描述文件是否归档实体取决于 auto-archival 配置；移动文件不等同删除。UI editing 与 GitOps importing 的组合尤其容易误解：GitOps 日志可能显示提交但处理了零实体，因为该类型允许 UI 编辑却禁用了 GitOps 导入。排障时先看 GitOps log 的 processed/omitted 数量，再看文件格式和默认分支。

Scorecard 与 Initiative 把失败证据变成行动

Cortex Scorecard 先要求目录中已有 Entity 和所需集成。规则可以用表单或 CQL，采用等级递进或积分；evaluation window 决定重评周期，过短会撞到第三方 API 限流，过长会扩大陈旧窗口。规则应给出失败消息和修复入口。Scorecard 负责持续基准，Initiative 则把已发布 Scorecard 的某个等级或规则变成有目标、期限、适用实体、Owner 通知和行动项的改进计划。草稿 Initiative 不通知，正式启动后实体 Owner 才收到待办。

正向实验创建只适用于试点服务的“生产准备”Scorecard：Owner 存在、runbook 链接存在、值班集成返回有效对象；触发评估后 payment-api 通过，而另一个已有 Owner 但缺 runbook 的试点实体失败。再建立 Initiative，目标是补齐 runbook，预期行动项到达该实体的真实 Owner。ledger-api 缺 Owner 的样本单独验证未分派状态、平台兜底队列或 Initiative Owner 接管，不能期待系统把任务送给不存在的 Owner。反向实验撤销 on-call 集成权限；规则应显示错误或未知证据，不能继续沿用无时间戳的绿色结果。

API 导出不能只复制 GitOps 文件

API 可分页列出 Catalog Entities，返回稳定 tag、类型并按需包含 Owner、metadata 和 links；页大小有上限，大目录导出必须遍历全部页面并记录归档实体。GitOps 适合评审式变更，但官方建议不要用它做高频大批量更新，大规模同步使用 API。退出快照至少包含 Entity descriptor、团队、类型、关系、Scorecard、Initiative 定义、归档状态和外部集成映射；仅复制 cortex.yaml 不能重建 UI 创建的 Catalog 和所有租户设置。

排障从来源、处理日志和证据年龄开始

实体缺失时依次检查连接健康、发现过滤、默认分支、Descriptor 解析和 GitOps processed/omitted 计数。重复实体先比较稳定 Tag、仓库 Canonical URL 与创建来源，再迁移关系和评分后归档副本。Scorecard 大面积同时变化，优先检查集成 Token、第三方限流、Evaluation Window 与 CQL 语义，不假设所有服务同时退化。

$headers = @{ Authorization = "Bearer $env:CORTEX_READ_TOKEN" }
$page = Invoke-RestMethod -Headers $headers -Uri "$env:CORTEX_API/api/v1/catalog?page=0&pageSize=100"
$page.entities | Select-Object tag,type
Remove-Item Env:CORTEX_READ_TOKEN

权限、容量和敏感拓扑共同约束上线

工作区管理员、目录编辑者、Scorecard 管理者、Initiative Owner 与只读用户应分离。导出 Token 只读，写入自动化限制到必要对象，个人 Token 不进入 CI。实体、关系、Owner、值班、漏洞和仓库组合后会暴露组织攻击面，字段可见性与导出保留期必须受控。

容量测试同时计算实体与关系数、集成调用、评估窗口、API 分页和通知量。大规模高频同步走 API，不让 GitOps 扫描持续撞限流。上线门槛包括试点完整同步耗时、第三方 429 退避、陈旧证据比例和一次完整恢复；退出前分页导出 Entity、Team、Type、关系、Scorecard、Initiative 与归档状态，随后撤销 API Key、SCM App、Webhook 和 SSO。

跳到正文