4. 服务目录元数据管理：元数据模型设计、版本控制、标签与分类体系
服务目录的核心价值在于将分散的微服务信息统一为可信、可检索、可审计的元数据资产。本章围绕元数据模型的三层结构、版本控制策略、标签与分类体系展开，为后续的准入控制与策略执行奠定数据基础。
4.1 元数据模型设计：三层抽象结构
服务目录的元数据模型采用服务基础信息、运行时属性、治理与合规属性三层抽象，确保模型既能满足开发者的快速查询需求，又能支撑平台级的策略评估。
| 层级 | 核心字段 | 数据来源 | 更新频率 |
|---|---|---|---|
| L1 基础信息 | serviceName, owner, team, repoURL, description, createdTime | 开发者注册 / GitOps 仓库 | 低频（创建/变更时） |
| L2 运行时属性 | cluster, namespace, endpoints, ports, protocol, version, healthStatus | Kubernetes API / 服务网格 | 高频（实时同步） |
| L3 治理与合规 | complianceLevel, dataClassification, allowedEgress, auditPolicy, slaTier | 平台管理员 / 安全策略引擎 | 中频（策略变更时） |
serviceName + version 组合键关联，避免数据冗余。
4.2 元数据版本控制：基于语义化版本的演进策略
服务目录的元数据版本控制遵循 SemVer 2.0 规范，格式为 MAJOR.MINOR.PATCH，每个版本对应一个不可变的元数据快照。版本控制的核心目标是支持准入控制器的策略回溯与灰度发布。
- MAJOR：元数据模型结构变更（如新增必填字段、删除字段）
- MINOR：元数据属性扩展（如新增可选标签、新增合规属性）
- PATCH：元数据值修正（如修复 owner 信息、更新描述）
# 元数据版本示例：v2.3.1
metadata:
version: "2.3.1"
serviceName: "payment-gateway"
owner: "team-payment"
complianceLevel: "PCI-DSS"
dataClassification: "sensitive"
changelog: "修复 owner 邮箱格式，新增 dataClassification 字段"--metadata-version=v2.3.0 来引用历史版本，实现策略的向后兼容。
4.3 标签与分类体系：多维度的服务发现与策略绑定
标签（Label）与分类（Category）是服务目录的两大检索维度。标签用于细粒度属性标记，分类用于粗粒度的业务域划分。两者共同构成服务目录的语义网络。
4.3.1 标签体系：键值对与保留标签
标签采用 key=value 格式，支持自定义标签与平台保留标签。保留标签由平台统一管理，用于准入控制器的策略匹配。
| 保留标签 Key | Value 示例 | 用途 |
|---|---|---|
tier |
critical / standard / dev | 服务等级划分，影响 SLA 与监控告警阈值 |
data-sensitivity |
high / medium / low | 数据敏感度，控制 Cilium NetworkPolicy 的加密与审计级别 |
compliance-scope |
pci-dss / hipaa / soc2 | 合规范围，触发对应的准入控制规则集 |
owner-team |
team-payment / team-user | 团队归属，用于 RBAC 与通知路由 |
4.3.2 分类体系：树形结构与继承规则
分类采用树形结构，支持多级分类。子分类自动继承父分类的标签与策略，同时可覆盖或扩展。分类体系由平台管理员维护，开发者只能选择已有分类。
# 分类树示例
├── 核心业务 (core)
│ ├── 支付 (payment) → 继承 core 标签: tier=critical
│ │ ├── 网关 (gateway) → 额外标签: data-sensitivity=high
│ │ └── 结算 (settlement) → 额外标签: data-sensitivity=medium
│ └── 用户 (user)
│ ├── 认证 (auth) → 继承 core 标签: tier=critical
│ └── 资料 (profile) → 继承 core 标签: tier=standard
└── 基础设施 (infra)
├── 日志 (logging) → 标签: tier=standard
└── 监控 (monitoring) → 标签: tier=critical4.4 元数据生命周期与准入控制集成
服务目录的元数据管理不是静态的，而是与 Cilium 准入控制器形成闭环。下图展示了元数据从注册、版本化到策略评估的完整流程。
4.5 元数据一致性校验：准入控制器的前置检查
在 Cilium 准入控制器执行网络策略之前，服务目录会先对元数据本身进行一致性校验，确保策略评估的输入是可信的。校验规则包括：
- 必填字段完整性：L1 层的 serviceName、owner、team 不可为空；L3 层的 complianceLevel 不可为空。
- 标签值合法性：保留标签的值必须在预定义枚举范围内（如
tier只能为 critical/standard/dev）。 - 版本连续性：新版本的 MAJOR 变更必须附带 changelog 说明，且不允许跳版本（如从 v1.0.0 直接到 v3.0.0）。
- 分类路径有效性：所选分类必须在分类树中存在，且叶子节点不允许有子分类。
# 元数据校验失败示例（准入控制器拒绝）
{
"serviceName": "payment-gateway",
"version": "2.0.0",
"errors": [
{"field": "tier", "message": "值 'gold' 不在枚举范围 [critical, standard, dev] 内"},
{"field": "complianceLevel", "message": "必填字段缺失"}
]
}4.6 元数据查询与检索：标签索引与分类聚合
服务目录提供两类查询接口：标签索引查询（精确匹配、模糊匹配）和分类聚合查询（树形路径匹配、子分类递归）。查询结果用于 Cilium NetworkPolicy 的 EndpointSelector 生成。
| 查询类型 | API 示例 | 返回结果 | 典型场景 |
|---|---|---|---|
| 标签精确匹配 | GET /metadata?label=tier:critical |
所有 tier=critical 的服务列表 | 生成高优先级服务的隔离策略 |
| 标签模糊匹配 | GET /metadata?label=data-sensitivity:high* |
所有 data-sensitivity 以 high 开头的服务 | 批量加密策略的 Endpoint 选择 |
| 分类路径查询 | GET /metadata?category=core/payment/* |
core/payment 下所有子分类的服务 | 按业务域统一配置审计策略 |
| 版本快照查询 | GET /metadata/v2.3.0?serviceName=payment-gateway |
指定版本的完整元数据快照 | 准入控制器的策略回溯审计 |
通过上述元数据管理机制，服务目录为 Cilium 准入控制器提供了结构化的、版本化的、可追溯的策略输入，确保每一次网络策略的评估都基于一致且可信的服务信息。