DX Fabric：Software Catalog、Scorecard 与 Compass 迁移

DX Fabric 的 Software Catalog、Scorecard 和自助工作流建立在 DX 的团队与数据连接之上。自动发现可以快速产生候选 Entity，但名称匹配、Owner 推断和 Alias 自动关联都不是最终权威；Compass 迁移还会改变团队归属、关系和评分对象。采用 DX 的第一步是冻结稳定 Identifier 与字段来源，而不是先追求导入数量。

DX Fabric Catalog、Scorecard 与 Compass 迁移链高清原图

Compass 只作为迁移源，不再成为长期基线

Compass 的核心对象是 Component，包含类型、生命周期、Owner team、链接、依赖、事件、指标和 Scorecard。组件可由连接的 Bitbucket/GitHub 自动创建，也可经 UI、config-as-code 或 GraphQL API 管理。compass.yaml 中的唯一 ID 维持组件与文件的连接，文件在同一仓库内移动不应改变组件身份。对于存量组织，这些能力仍需稳定运行，但所有新自动化都要经过迁移价值审查。

Atlassian 已明确把 Compass 的目录和 Scorecard 转向 DX Fabric，并公布了计划中的支持结束节点。实施时应在 Compass 到 DX 迁移页面 确认合同、支持节点和租户安排，不在内部路线图里假设 Compass 会无限期存在。更重要的是，DX 不是 Compass 数据库原样换壳：组件会重建为 Entity，依赖成为关系，团队映射规则变化，部分双向 Jira/JSM 连接仍存在缺口。

迁移工具执行一次组件目录同步，并可持续把 Atlassian Teams 同步到 DX。需要同时提供 Compass 与 DX API keys。团队模型有实质差异：DX 中用户只属于一个团队，并要求 Team Lead；Compass/Atlassian Teams 中的多团队成员必须选定一个归属，缺少 Team Lead 时迁移过程会推断负责人。这个转换会改变 Owner 语义，不能只比较组件总数。

明确不会自动迁移的对象更关键：Compass Scorecard 必须在 DX 重建；关联的部分 on-call 信息不会直接进入 DX Entity；告警和运维能力需要迁往 Jira Service Management。官方迁移流程会提供一段双系统并行期，但并行不是双向一致性保证。冻结窗口中若继续在两边改 Owner、关系和 Scorecard，最终很难判断哪边权威。

Software Catalog 以 Entity、Type 与 Relation 建模

DX Software Catalog 使用 Entity，可以连接 SCM 自动发现仓库。自动发现的仓库先进入 pending 状态并由用户批准，避免把每个实验仓库直接变成权威服务。Catalog 可以通过 API 从多个系统同步，关系模型能承载分组和纵向依赖。所有 DX 客户都有 Service Catalog 基础入口，但自定义 Entity Type、Property、Relation 和 Team Entity 属于 Fabric 能力，不能拿基础租户的 Service Entity 推断完整目录模型。Owner 与 Team 进入 Scorecard 和 Initiative 的责任链，因此身份源映射应先于质量计划上线。

启用流程从 DX 工作区、SSO/团队和 SCM 连接开始。先审批统一样本的仓库，给 Entity 选择稳定 identifier 和 type，再设置 Owner、关系与 JSM alias。用户、CLI 或代表用户运行的代理使用带过期时间和 scope 的 PAT，权限上限受签发者当前角色约束；后端和机器间流量应使用 organization token。只读验收先调用 Catalog 与 Scorecard API，确认分页、identifier、失败检查和审计归属。Terraform Provider 可管理 Catalog 与 Scorecards 配置，适合把模型、检查和关系配置纳入评审；Provider Registry 才是当前资源和字段的权威，升级前必须看 plan，不能把 Provider 支持推断为“租户所有数据均可导出”。

Scorecard 与 Initiative 不能只比数量

DX 的 Scorecard API 可按 Entity identifier 读取当前报告，并用 only_failing 筛选未通过检查。判据要区分 passed: false、豁免和没有证据。Initiative 把 Scorecard 失败项分配给 Owner 并推动整改。迁移 Compass Scorecard 时先导出旧定义和适用组件快照，再在 DX 建立草稿规则，对同一实体集合比较分布；结果一致后才启用通知。仅凭“Scorecard 数量相同”不能证明迁移完成。

CLI、API 与 Terraform 需要独立身份

DX CLI 可以管理 Catalog、Scorecard 和查询等对象，当前需要受支持的 Node.js 运行时，并通过交互登录或 Token 认证。开发者终端、CI 和代理不能共用个人长期凭据；无头任务通过受保护环境注入 DX_API_TOKEN，完成后清除。每条命令继承 API Scope，CLI 能执行并不代表当前身份应获得写权限。

npm install -g @get-dx/cli
dx --version
dx auth status
dx catalog entities info payment-api
Remove-Item Env:DX_API_TOKEN -ErrorAction SilentlyContinue

用迁移样本验证身份、关系和 Owner

样本包含两个 Service、一个 Team、一个依赖关系、一个 Runbook Alias 和一条故意缺 Owner 的记录。Compass 源快照先保存组件稳定 ID、团队多归属、依赖、Scorecard 和 On-call 映射；导入 DX 后按集合对比 Identifier、Owner、关系闭合与未迁移对象。正向样本保持身份，反向样本进入人工队列，不能为了数量相同而自动选择 Team Lead。

entity:
  type: service
  identifier: payment-api
  owners: [payments]
  relations:
    depends_on: [ledger-api]
  aliases:
    runbook: https://example.com/runbooks/payment-api

排障从候选状态和字段来源开始

目录缺实体时检查连接状态、Entity Discovery 建议、接受或忽略状态、Alias 精确匹配和 API 分页；Owner 不正确时回查部署数据推断、团队同步和人工覆盖。Scorecard 突然变化先读取原始属性、文件匹配规则或 SQL 证据时间，再检查连接器 Token、同步延迟和规则版本。不能用页面仍显示旧值证明后台同步正常。

权限、数据边界和容量决定长期成本

Workspace Admin、Catalog 编辑者、Scorecard 管理者、Connector 管理者和只读用户分开。Repository 集成可能读取文件内容并自动发现文档或属性，因此组织、仓库和字段范围必须最小化。实体、Owner、依赖、部署、事故与生产等级组合后属于敏感组织图谱；API 导出、支持附件和本地迁移文件采用短保留与访问审计。

容量模型覆盖候选扫描、Entity 与 Relation 数、AWS 资源导入、Scorecard 查询、Initiative 通知、部署与事故数据吞吐，以及 Compass 双系统并行期。退出演练分别导出 Catalog、Team、Relation、Scorecard、Initiative、权限和 Connector 清单；Terraform 只证明其已覆盖配置可重建，不能推断租户全部数据可迁移。

退出前先结束 Compass 双写

切换时冻结 Compass 写入，做最终源快照，再让 DX Owner 抽样签认 Identifier、团队、依赖、Alias 和 Scorecard 分布。未自动迁移的 Scorecard、On-call 和 Jira Service Management 分流单独关账。验证 DX 搜索、权限、评分和行动项后，撤销 Compass/DX 迁移 Key、旧 SCM App、Webhook 与 SSO，再按合同删除旧租户数据；保留的审计证据不得包含仍可调用生产系统的 Secret。