4. 蓝绿发布 API 核心功能：切换流量、回滚、健康检查、状态查询

蓝绿发布的核心价值在于通过两套独立环境（蓝环境与绿环境）实现零停机切换与快速回滚。本章聚焦于自助服务 API 必须暴露的四个核心功能：流量切换、回滚、健康检查与状态查询。这四个 API 端点构成了自动化发布流程的“操作手柄”，也是 DevOps 团队与平台交互的主要入口。

设计原则：每个 API 端点应遵循幂等性与最终一致性原则。流量切换与回滚操作建议采用异步任务模式，避免长时间阻塞调用方。

4.1 核心功能总览

下表对比了四个核心 API 的用途、触发方式与关键响应字段，帮助快速建立全局认知。

API 功能 HTTP 方法 典型路径 触发方式 关键响应字段
切换流量 POST /api/v1/deploy/switch 手动 / 自动流水线 task_id, status, target_env
回滚 POST /api/v1/deploy/rollback 手动 / 告警触发 rollback_id, previous_env, reason
健康检查 GET /api/v1/health 定时轮询 / 事件驱动 overall_status, checks[]
状态查询 GET /api/v1/deploy/status 轮询 / Webhook 回调 current_env, history[]

4.2 切换流量 API

流量切换是蓝绿发布的核心操作，负责将用户流量从当前活跃环境（如蓝环境）瞬间切换到新版本环境（如绿环境）。API 设计需支持全量切换与灰度切换两种模式。

4.2.1 请求与响应结构

POST /api/v1/deploy/switch
Content-Type: application/json

{
  "target_env": "green",
  "strategy": "full",           // "full" | "canary"
  "canary_percent": 0,          // 灰度比例，仅 strategy=canary 时有效
  "reason": "v2.3.1 版本发布",
  "timeout_seconds": 120
}
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "task_id": "switch-20250321-a1b2c3",
  "status": "in_progress",
  "target_env": "green",
  "estimated_completion_seconds": 45,
  "poll_url": "/api/v1/deploy/status/switch-20250321-a1b2c3"
}
关键设计点：
  • 返回 202 Accepted 而非 200 OK，表明操作已接受但尚未完成。
  • 提供 poll_url 供调用方轮询任务状态，避免长连接。
  • 灰度切换时，canary_percent 建议以 5% 为步进单位，最小不低于 1%。

4.2.2 流量切换流程

下图展示了从发起切换请求到流量完全迁移的完整流程，包含前置检查、路由更新与后置验证三个阶段。

流量切换 API 执行流程 发起切换请求 前置健康检查 更新路由规则 后置验证 切换完成 说明 前置检查失败 → 自动拒绝切换 后置验证失败 → 自动触发回滚 超时未完成 → 标记为失败

4.3 回滚 API

回滚是蓝绿发布的安。当新版本出现严重故障时，API 应支持一键回滚到上一个已知健康的环境。回滚操作必须记录原因并保留审计轨迹。

4.3.1 请求与响应结构

POST /api/v1/deploy/rollback
Content-Type: application/json

{
  "target_env": "blue",
  "reason": "v2.3.1 出现 500 错误率超过 5%",
  "skip_health_check": false,
  "rollback_timeout": 180
}
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "rollback_id": "rb-20250321-x9y8z7",
  "status": "rolling_back",
  "from_env": "green",
  "to_env": "blue",
  "reason": "v2.3.1 出现 500 错误率超过 5%",
  "poll_url": "/api/v1/deploy/status/rb-20250321-x9y8z7"
}
回滚安全策略：
  • 默认启用前置健康检查，确保目标环境（如蓝环境）仍处于健康状态。
  • 设置 skip_health_check: true 仅限紧急场景，需额外权限校验。
  • 回滚完成后自动触发一次全量健康检查，结果写入审计日志。

4.4 健康检查 API

健康检查是蓝绿发布的“眼睛”，为流量切换与回滚提供决策依据。API 设计需支持多层级检查：应用层、中间件层与基础设施层。

4.4.1 健康检查层级

层级 检查项 预期响应 超时设置
L7 应用层 HTTP 200 / 业务探针 {"status":"ok"} 5s
L4 中间件层 数据库连接 / 缓存可达 TCP 连通 + 响应时间 < 200ms 10s
L3 基础设施层 Pod 状态 / 节点资源 Running & CPU < 80% 15s

4.4.2 健康检查响应示例

GET /api/v1/health?env=green

HTTP/1.1 200 OK
Content-Type: application/json

{
  "overall_status": "healthy",
  "checks": [
    {
      "level": "L7",
      "name": "application-probe",
      "status": "pass",
      "response_time_ms": 42
    },
    {
      "level": "L4",
      "name": "postgres-connection",
      "status": "pass",
      "response_time_ms": 87
    },
    {
      "level": "L3",
      "name": "node-cpu",
      "status": "warn",
      "message": "CPU 使用率 72%，接近阈值 80%"
    }
  ],
  "timestamp": "2025-03-21T10:30:00Z"
}
健康检查最佳实践：
  • L7 探针应模拟真实用户请求，避免仅检查静态页面。
  • L4 检查应包含连接池状态，而非仅 TCP 握手。
  • L3 检查应关注资源余量，而非仅存活状态。
  • 整体状态 overall_status 采用“木桶原理”：任一 L7 失败即判定为 unhealthy。

4.5 状态查询 API

状态查询 API 提供当前发布环境的全局视图，包括活跃环境、历史操作记录与各环境健康状态。该 API 是运维仪表盘与自动化流水线的主要数据源。

4.5.1 状态查询响应结构

GET /api/v1/deploy/status

HTTP/1.1 200 OK
Content-Type: application/json

{
  "current_active_env": "green",
  "standby_env": "blue",
  "environments": {
    "blue": {
      "version": "v2.3.0",
      "health": "healthy",
      "traffic_percent": 0
    },
    "green": {
      "version": "v2.3.1",
      "health": "healthy",
      "traffic_percent": 100
    }
  },
  "history": [
    {
      "action": "switch",
      "from_env": "blue",
      "to_env": "green",
      "timestamp": "2025-03-21T10:15:00Z",
      "status": "completed"
    },
    {
      "action": "rollback",
      "from_env": "green",
      "to_env": "blue",
      "timestamp": "2025-03-20T22:30:00Z",
      "status": "completed",
      "reason": "错误率过高"
    }
  ],
  "last_updated": "2025-03-21T10:30:00Z"
}

4.5.2 状态查询与健康检查的关系

下图展示了状态查询 API 如何聚合健康检查数据，形成完整的发布视图。

状态查询 API 数据聚合架构 L7 应用探针 L4 中间件探针 L3 基础设施探针 健康检查聚合器 木桶原理判定 状态查询 API 返回完整视图 数据流说明 探针数据 → 聚合器 聚合器 → 状态查询缓存 缓存 TTL: 30s

4.6 API 调用优化建议

性能优化清单：
  • 批量查询：状态查询 API 支持 ?envs=blue,green 参数，一次请求获取多环境状态。
  • 条件轮询：健康检查 API 支持 ?since= 参数，仅返回变更后的检查结果。
  • 异步回调：切换与回滚 API 支持 X-Callback-URL 请求头，任务完成时主动推送结果。
  • 缓存策略：状态查询结果缓存 30 秒，健康检查结果缓存 10 秒，减少后端压力。
  • 限流保护：每个 API 端点按客户端 ID 限流，切换/回滚 API 每分钟最多 10 次。

4.7 错误处理与幂等性

场景 HTTP 状态码 错误码 处理策略
目标环境不健康 409 Conflict ENV_UNHEALTHY 拒绝切换，返回详细检查结果
回滚目标不存在 404 Not Found ROLLBACK_TARGET_MISSING 提示用户手动指定目标环境
重复提交相同请求 200 OK IDEMPOTENT_REPLAY 返回已有任务状态，不重复执行
操作超时 408 Request Timeout OPERATION_TIMEOUT 自动触发回滚（切换场景）或标记失败
幂等性实现要点：
  • 每个切换/回滚请求必须携带 idempotency_key（UUID），服务端缓存 24 小时。
  • 相同 idempotency_key 的重复请求直接返回首次执行结果，不重复操作。
  • 健康检查与状态查询天然幂等，无需额外处理。
← 上一章 📖 返回目录 下一章 →