3. 服务目录水位定义
3.1 什么是服务目录水位？
服务目录水位（Service Catalog Water Level）是一个量化指标集合，用于描述某个服务在可靠性、健康度、变更风险三个维度上的当前状态。它类似于一个“仪表盘”，让平台和团队能够快速判断一个服务是否处于“安全可变更”的状态。
在 Backstage 的上下文中，服务目录水位是变更门禁和回滚判断的核心数据源。当水位过高（即风险指标超标）时，系统会自动阻止新的变更进入生产环境，或触发自动回滚流程。
核心定义：服务目录水位 = f(健康分, SLO达成率, 错误预算消耗) —— 一个由多个可靠性指标加权计算得出的综合风险评分。
3.2 水位指标的选取原则
选择哪些指标来构成服务目录水位，直接决定了门禁和回滚判断的准确性。以下是经过生产验证的三大核心指标及其选取原则：
| 指标名称 | 选取原则 | 权重建议 | 数据来源 |
|---|---|---|---|
| 健康分 | 综合反映服务的基础运行状态，包括 CPU/内存使用率、错误率、延迟 P99 等。选取原则：全面性——覆盖基础设施、应用、中间件三个层面。 | 40% | 监控系统 (Prometheus/Datadog) |
| SLO 达成率 | 衡量服务在过去一个时间窗口（如 7 天/30 天）内是否满足用户承诺的可用性目标。选取原则：用户视角——只选取直接影响用户体验的 SLI。 | 35% | SLO 跟踪平台 (Backstage SLO Plugin) |
| 错误预算消耗 | 反映当前错误预算的剩余比例和消耗速度。选取原则：趋势性——不仅看当前值，还要看过去 1 小时的消耗速率。 | 25% | 错误预算计算器 |
最佳实践：不要试图把所有指标都塞进水位的计算中。选取 3-5 个最核心的指标，并定期（如每季度）根据实际效果调整权重。指标过多会导致水位变化过于敏感，反而降低门禁的有效性。
3.3 水位等级与门禁策略
根据上述三个指标的综合计算，服务目录水位被划分为四个等级。每个等级对应不同的变更门禁策略：
| 水位等级 | 综合评分范围 | 变更门禁策略 | 回滚触发条件 |
|---|---|---|---|
| 低水位 | 0 - 30 | 允许所有变更 | 不触发自动回滚 |
| 中水位 | 31 - 60 | 允许变更，但需人工审批 | 仅当水位在变更后 5 分钟内上升超过 20 分时触发 |
| 高水位 | 61 - 85 | 禁止变更，仅允许紧急修复 | 变更后水位上升超过 10 分立即回滚 |
| 严重水位 | 86 - 100 | 完全锁定，禁止任何变更 | 自动回滚最近一次变更 |
3.4 指标计算示例
假设有一个名为 order-service 的服务，其当前水位计算过程如下：
# 健康分计算
健康分 = (CPU使用率得分 * 0.3) + (错误率得分 * 0.4) + (P99延迟得分 * 0.3)
= (80 * 0.3) + (60 * 0.4) + (70 * 0.3)
= 24 + 24 + 21
= 69
# SLO 达成率
SLO 达成率 = 过去 7 天满足 SLO 的时间比例 = 95%
# 错误预算消耗
错误预算消耗 = (已消耗错误预算 / 总错误预算) * 100 = 45%
# 综合水位评分
水位评分 = (健康分 * 0.4) + ((100 - SLO达成率) * 0.35) + (错误预算消耗 * 0.25)
= (69 * 0.4) + (5 * 0.35) + (45 * 0.25)
= 27.6 + 1.75 + 11.25
= 40.6 → 中水位
注意：上述示例中的权重和计算公式仅为演示用途。在实际生产环境中，你需要根据服务的业务重要性和历史故障模式来调整权重。例如，对于核心支付服务，错误预算消耗的权重可能需要提高到 40% 以上。
3.5 水位数据的存储与同步
在 Backstage 中，服务目录水位数据通常存储在自定义实体关系模型中，并通过以下方式保持实时同步：
- 数据源：Prometheus、Datadog、Grafana 等监控系统
- 同步频率：每 1 分钟拉取一次指标数据
- 存储方式：Backstage Catalog 的
metadata.annotations字段 - 更新机制：通过 Backstage 的
EntityProvider接口实现增量更新
# Backstage 实体 YAML 示例（水位数据存储在 annotations 中）
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: order-service
annotations:
reliability.water-level/score: "40.6"
reliability.water-level/level: "medium"
reliability.water-level/health-score: "69"
reliability.water-level/slo-achievement: "95"
reliability.water-level/error-budget-consumed: "45"
reliability.water-level/updated-at: "2025-03-15T10:30:00Z"
spec:
type: service
lifecycle: production
owner: team-payment通过这种方式，Backstage 可以在变更门禁插件中直接读取水位数据，无需额外的 API 调用，从而实现毫秒级的门禁判断。