2. 服务目录平台基础：定义、核心模型与元数据管理
服务目录（Service Catalog）是云原生运维体系中用于描述、注册、发现和管理所有业务服务的“中央注册中心”。在容量水位巡检场景下，服务目录提供了巡检对象的统一视图和元数据来源，是策略引擎（OPA）进行决策的数据基础。
2.1 服务目录的定义与定位
服务目录并非简单的服务列表，而是一个包含服务定义、实例拓扑、集群归属、容量属性、运维策略的结构化元数据仓库。其核心定位包括：
- 统一服务视图：消除多环境、多集群、多团队之间的服务信息孤岛。
- 巡检对象注册：所有需要被容量水位巡检的服务、实例、集群必须先在目录中注册。
- 策略绑定锚点：OPA 策略通过服务目录中的标签、属性、层级关系来匹配目标资源。
- 变更感知基线：服务目录的元数据变更（如实例扩缩、集群迁移）自动触发策略重新评估。
实践要点：服务目录应作为基础设施代码（IaC）的一部分进行管理，通过 Git 仓库维护其 YAML/JSON 定义，确保元数据版本可追溯、变更可审计。
2.2 核心数据模型：服务、实例、集群
服务目录平台围绕三个核心实体构建数据模型，三者形成“服务 → 集群 → 实例”的层级关系。下表总结了各实体的定义、关键属性及在巡检中的用途：
| 实体 | 定义 | 关键属性（示例） | 巡检用途 |
|---|---|---|---|
| 服务（Service） | 业务功能的逻辑抽象，对应一个微服务或应用模块。 | service_id, name, owner, criticality, sla |
确定巡检优先级、告警级别、策略适用范围。 |
| 集群（Cluster） | 一组提供相同服务能力的计算资源集合，如 Kubernetes 集群、虚拟机集群。 | cluster_id, name, region, provider, capacity_total |
定义容量上限、资源池归属、跨集群调度策略。 |
| 实例（Instance） | 服务在集群中的具体运行单元，如 Pod、虚拟机、容器。 | instance_id, ip, cpu_usage, mem_usage, status |
采集实时水位数据，触发单实例或集群级策略评估。 |
2.3 核心模型关系图
下图展示了服务、集群、实例之间的关联关系以及元数据流向：
2.4 元数据管理
元数据是服务目录的“血液”，决定了策略引擎能否准确理解资源上下文。元数据管理涵盖以下维度：
2.4.1 元数据分类
| 分类 | 包含字段 | 示例值 | 策略使用场景 |
|---|---|---|---|
| 标识元数据 | service_id, instance_id, cluster_name |
svc-001, pod-abc-123 |
策略匹配目标资源 |
| 容量元数据 | cpu_limit, mem_limit, disk_limit, max_replicas |
4 core, 8 Gi, 100 Gi |
计算水位百分比、判断是否超限 |
| 运行时元数据 | cpu_usage, mem_usage, request_rate, error_rate |
75.3%, 1200 req/s |
实时水位数据输入 |
| 治理元数据 | owner, criticality, sla, maintenance_window |
team-payment, P0, 99.99% |
告警分级、策略豁免、窗口期抑制 |
2.4.2 元数据生命周期
- 注册：服务上线时通过 API 或 IaC 提交元数据至目录。
- 采集：监控系统（如 Prometheus）定期采集实例运行时数据，回写至目录的运行时元数据字段。
- 变更：扩缩容、集群迁移等操作触发元数据更新，目录发布变更事件。
- 归档：服务下线后，元数据保留一定周期用于审计，之后标记为已归档。
关键设计原则：元数据应保持“不可变基线 + 可变运行时”的分离策略。标识、容量、治理元数据通过 IaC 管理，视为不可变基线；运行时元数据由监控系统实时写入，视为可变状态。OPA 策略同时读取两类元数据进行联合评估。
2.5 元数据在 OPA 策略中的使用示例
以下 Rego 代码展示了如何利用服务目录元数据判断某实例是否超过容量水位阈值：
package catalog.watermark
# 输入：来自服务目录的实例元数据
instance = input.instance
# 从目录元数据中获取容量限制
cpu_limit = instance.capacity.cpu_limit # 单位：core
mem_limit = instance.capacity.mem_limit # 单位：Gi
# 从目录元数据中获取实时使用量
cpu_usage = instance.runtime.cpu_usage # 单位：百分比（0-100）
mem_usage = instance.runtime.mem_usage # 单位：百分比（0-100）
# 策略：CPU 或内存使用率超过 80% 视为水位告警
default allow = true
allow = false {
cpu_usage > 80
}
allow = false {
mem_usage > 80
}
# 输出告警详情
violation[msg] {
allow == false
msg = sprintf("实例 %s 水位超限: CPU=%v%%, MEM=%v%% (限制: CPU=%v core, MEM=%v Gi)", [
instance.id, cpu_usage, mem_usage, cpu_limit, mem_limit
])
}
注意：上述示例假设服务目录已将运行时元数据实时同步至 OPA 的
input 中。在实际生产环境中，通常通过 OPA 的 Bundle 或 Pull 模式定期拉取目录数据，而非每次评估都实时查询数据库，以避免性能瓶颈。
2.6 元数据管理架构图
下图展示了元数据从注册、采集到策略评估的完整流转路径：
2.7 本章小结
- 服务目录是容量水位巡检的“数据底座”，提供统一的服务、集群、实例视图。
- 核心模型采用“服务 → 集群 → 实例”三层结构，每层携带不同粒度的元数据。
- 元数据分为标识、容量、运行时、治理四类，分别服务于策略匹配、阈值计算、实时输入和告警分级。
- OPA 策略通过读取目录元数据（基线 + 运行时）实现精准的容量水位评估。