📚 课程目录第4章服务目录（Service Catalog）概念

平台工程落地：分布式追踪值班台服务目录 - 第4节

4.1 服务目录的定义与核心价值

服务目录（Service Catalog）是平台工程中所有可观测服务、微服务、数据管道及基础设施组件的权威注册中心。它不仅是“服务清单”，更是分布式追踪值班台的可观测性数据索引与运维行动入口。

维度	说明
定义	一个集中式、可查询、版本化的服务元数据仓库，记录每个服务的标识、所有者、依赖、运行状态及可观测性接入点。
核心价值	消除服务信息孤岛，加速故障定位，支撑值班台“一键跳转”到对应服务的追踪、日志、指标视图。
在值班台中的角色	作为分布式追踪的“服务地图”，将 Trace ID 与 Service Name 关联，实现从调用链到服务元数据的双向导航。

平台工程视角： 服务目录是平台与开发者之间的“契约”。开发者注册服务时声明元数据，平台据此自动配置可观测性采集、告警路由和值班轮转。

4.2 元数据管理

元数据是服务目录的“血液”。每项服务必须包含以下核心元数据字段，才能支撑分布式追踪值班台的自动化运维场景。

4.2.1 元数据分类与字段清单

分类	字段示例	说明
标识元数据	`service_name`, `service_id`, `version`	全局唯一标识，用于关联 Trace 中的 `service.name`。
所有权元数据	`team`, `slack_channel`, `oncall_rotation`	值班台告警通知与升级策略的依据。
依赖元数据	`upstream_services`, `downstream_services`, `data_stores`	构建服务依赖图，用于根因分析与故障影响范围评估。
可观测性元数据	`trace_sample_rate`, `log_index`, `dashboard_url`	平台自动生成可观测性配置的输入参数。
运行时元数据	`deployment_env`, `region`, `language_runtime`	用于环境过滤与性能基线对比。

4.2.2 元数据生命周期管理

注册阶段： 开发者通过平台 API 或 GitOps 提交服务描述文件（如 catalog.yaml），平台自动校验必填字段并生成唯一 ID。
变更阶段： 任何元数据更新（如依赖变更、团队交接）必须经过审批流，并记录变更历史。
退役阶段： 服务下线时，平台自动清理可观测性采集配置，并更新依赖图，避免“僵尸服务”污染追踪数据。

# catalog.yaml 示例
apiVersion: catalog.platform.io/v1
kind: Service
metadata:
  name: payment-service
  version: "2.1.0"
spec:
  team: "payment-platform"
  oncall:
    slack: "#payment-oncall"
    rotation: "primary"
  dependencies:
    upstream:
      - "order-service"
      - "user-service"
    downstream:
      - "ledger-service"
    dataStores:
      - "postgresql://payment-db"
  observability:
    traceSampleRate: 0.1
    logIndex: "payment-prod"
    dashboardUrl: "https://grafana.platform.io/d/payment"

4.3 服务依赖关系

服务依赖关系是分布式追踪值班台进行根因分析（RCA）和故障影响评估的核心数据模型。服务目录必须维护一个实时、准确的依赖图。

  依赖关系在值班台中的实战价值： 当分布式追踪检测到 payment-service 的 P99 延迟飙升时，值班台自动查询服务目录，发现其下游依赖 ledger-service 近期有版本变更，立即将该变更事件关联到告警上下文，缩短 MTTR。

4.4 服务所有权模型

清晰的所有权模型是值班台告警分派、升级和问责的基础。服务目录必须定义多级所有权结构，避免“无主服务”或“责任模糊”。

4.4.1 所有权层级

层级	角色	职责
L1：值班工程师	On-Call Engineer	处理值班台告警，执行应急响应，进行初步根因分析。
L2：服务负责人	Service Owner	负责服务架构决策、性能优化、变更审批，作为 L1 的升级联系人。
L3：团队负责人	Team Lead	跨服务协调、资源分配、SLO 违约复盘。

4.4.2 所有权模型设计原则

单一责任原则： 每个服务必须有且仅有一个 L2 负责人，避免多人同时负责导致推诿。
可升级路径： 服务目录必须记录 L1 → L2 → L3 的升级链，值班台在告警超时未确认时自动升级。
自动化同步： 所有权信息应从人力资源系统（如 LDAP、HR SaaS）自动同步，减少手动维护成本。

常见陷阱： 不要将服务目录的所有权字段设计为“可选”。一旦允许服务注册时留空，平台将产生大量“孤儿服务”，导致值班台告警无法分派，最终所有告警都落入默认兜底队列，失去值班台的意义。

4.5 服务目录与分布式追踪的集成

在值班台场景中，服务目录不是孤立的数据存储，而是与分布式追踪系统深度绑定的“服务大脑”。每次追踪 Span 携带的 service.name 都会实时查询服务目录，获取该服务的元数据上下文。

追踪数据	服务目录查询结果	值班台展示效果
`service.name: payment-service`	团队: payment-platform, Slack: #payment-oncall	告警卡片直接显示值班联系人，支持一键 @Slack 或拨号。
`trace_id: abc123` 中检测到错误 Span	该 Span 所属服务的依赖图	自动高亮可能的下游故障节点，辅助根因定位。
服务版本从 v2.0 变更为 v2.1	服务目录记录变更历史	值班台在告警上下文面板展示“该服务 10 分钟前发布新版本”。

通过服务目录，分布式追踪值班台从“只看链路”升级为“看懂链路”——每一条追踪数据背后都承载着完整的服务上下文、所有权归属和依赖关系，让值班工程师在告警风暴中始终拥有清晰的行动地图。