企业官网建设流程全解析

• 后端
• DevOps
• 云原生
• 微服务

Deployment Monitor（部署监控器）是 Spinnaker Orca 中「受监控部署（Monitored Deploy）」策略的核心外部组件：它由第三方服务实现，在部署进行的关键节点接收 Orca 发来的 HTTP 回调，并依据对新实例健康状态的分析结果来决定部署是继续、暂停等待、直接完成还是中止回滚。本文以 orca-deploymentmonitor/readme.md 为骨架，结合模块源码，完整说明部署监控器的三端点接口、请求/响应数据结构、orca.yml注册配置，以及 Orca 内部的调用链路，读者读完后可以独立实现一个符合规范的 Deployment Monitor 并接入 Orca。

一、背景：Monitored Deploy 策略与 Deployment Monitor 的定位

在 Spinnaker 的部署流程中，monitored是一种特殊的高阶部署策略：部署不是按固定的容量百分比盲推进，而是每完成一个部署步骤后暂停，交由外部的健康评估服务判断新实例是否健康、能否继续。这一策略由 MonitoredDeployStrategy.groovy 实现（类上标注了@ConditionalOnProperty(value = "monitored-deploy.enabled")，即只有启用该配置时策略才生效），其中：

• 部署前会将容量（capacity）置为min: 0, max: 0, desired: 0，先创建空的新服务器组；
• 随后按照deploySteps（如 10%、20%、……、100%）逐步扩容，每一步之间都插入健康评估环节；
• 部署过程中会动态编排NotifyDeployStartingStage、EvaluateDeploymentHealthStage、NotifyDeployCompletedStage等合成阶段，分别对应下文介绍的三个回调端点。

Deployment Monitor 的职责：它由第三方（如日志监控、金丝雀分析、自定义健康评分服务）实现，为受监控部署提供「新实例健康/状态」这一输入。Orca 本身不评判健康，只负责在正确的时机把部署上下文发给监控器，并根据监控器的指令决定下一步动作。

二、Deployment Monitor 接口：三个必须暴露的 HTTP 端点

监控器必须以POST方式暴露三个端点。Orca 侧的接口定义见 DeploymentMonitorService.java，这是用 Retrofit 声明的客户端契约：

public interface DeploymentMonitorService { @POST("deployment/starting") Call<EvaluateHealthResponse> notifyStarting(@Body RequestBase request); @POST("deployment/completed") Call<ResponseBody> notifyCompleted(@Body DeploymentCompletedRequest request); @POST("deployment/evaluateHealth") Call<EvaluateHealthResponse> evaluateHealth(@Body EvaluateHealthRequest request); }

三个端点相对于baseUrl拼接，具体语义如下：

1.POST /deployment/starting—— 部署启动通知

Orca 在受监控部署开始时调用此端点。此时监控器可以中止整个部署——例如，当它发现自身并没有被配置为监控当前应用时，可以返回abort让部署立即终止，避免出现「无人监控却继续灰度」的危险局面。

2.POST /deployment/completed—— 部署完成通知

Orca 在部署流程结束（无论成功或失败）时调用此端点。它纯粹是信息性通知：监控器的响应会被忽略，不会影响流程。请求中携带部署结果状态，见下文数据结构。

3.POST /deployment/evaluateHealth—— 部署步骤健康评估

Orca 每完成一个部署步骤（例如扩到 10%）后调用此端点。这是受监控部署中最关键的决策点，监控器可以在此时返回四种指令之一（对应 EvaluateHealthResponse.java 中的NextStepDirective枚举）：

注：UNSPECIFIED是内部占位值，监控器不应返回；如果未指定，Orca 会走常规异常处理路径。

每次evaluateHealth调用还携带currentProgress（当前已部署百分比），监控器可以据此判断当前处于哪个部署步骤。

三、请求与响应的数据结构

3.1 通用请求字段（RequestBase）

所有三个端点的请求都包含部署上下文，字段定义见 RequestBase.java：

一个POST /deployment/starting的请求体示例（JSON 序列化后）：

{ "application": "myapp", "executionId": "exec-12345", "stageId": "stage-67890", "deploymentId": "deploy-24680", "oldServerGroup": "myapp-v001", "newServerGroup": "myapp-v002", "account": "prod", "region": "us-west-2", "cloudProvider": "aws", "parameters": { "allowedErrorRate": "0.5", "warmupMinutes": "10" } }

3.2evaluateHealth的专属字段（EvaluateHealthRequest）

在RequestBase基础上增加两个字段，见 EvaluateHealthRequest.java：

• newInstances：新实例 ID 列表（源码中标注了TODO(mvulfson)，说明当前实现尚未填充该字段）；
• currentProgress：当前已部署百分比（取自内部阶段数据currentProgress）。

3.3completed的专属字段（DeploymentCompletedRequest）

见 DeploymentCompletedRequest.java，在RequestBase基础上增加：

• status：部署状态，取值为success/failure/not_performed（枚举DeploymentStatus）；
• rollback：回滚操作的状态，取值同上（若用户未请求回滚则为not_performed）。

示例：

{ "application": "myapp", "executionId": "exec-12345", "stageId": "stage-67890", "deploymentId": "deploy-24680", "oldServerGroup": "myapp-v001", "newServerGroup": "myapp-v002", "account": "prod", "region": "us-west-2", "cloudProvider": "aws", "parameters": {}, "status": "success", "rollback": "not_performed" }

3.4evaluateHealth的响应结构（EvaluateHealthResponse）

监控器对/deployment/starting与/deployment/evaluateHealth均返回EvaluateHealthResponse，包含两个字段（见 EvaluateHealthResponse.java）：

• nextStep：类型为DeploymentStep（见 DeploymentStep.java），包含percent（希望下一步部署到的百分比）、instanceCount（实例数）、directive（abort/complete/continue/wait）；
• statusReason：类型为StatusReason，用于说明决策原因（见下文）。

响应示例（健康未就绪，请求稍后重试）：

{ "nextStep": { "percent": 10, "instanceCount": 3, "directive": "wait" }, "statusReason": { "message": "New instances are still warming up, re-evaluating in ~30s", "logSummary": [ "3/3 instances in service", "error rate within threshold" ], "additionalData": [ { "key": "dashboard", "text": "View deployment dashboard", "link": "http://logmonitor.example.com/dashboards/myapp-v002" } ] } }

3.5 决策原因说明（StatusReason）

监控器应当（尤其是在失败场景下）在响应中携带决策原因，见 StatusReason.java：

• message：人类可读的原因描述；
• logSummary：日志摘要列表，帮助用户理解评估依据；
• additionalData：附加数据列表，每项包含key、text、link（见 StatusAdditionalData.java），可携带指向监控面板的超链接。

这些信息会展示在 Deck（Spinnaker UI）中，让用户清楚理解部署为何按当前方式推进——例如「因错误率超标而中止」而非看起来毫无理由的失败。

四、监控器注册：orca.yml中的白名单机制

部署监控器必须先注册到orca.yml中才会被使用。这是一种安全机制：Orca 不希望部署过程中随意请求未知 URL。配置绑定类为 MonitoredDeployConfigurationProperties.java，前缀为monitored-deploy（Spring Boot 松绑定下，文档中的monitoredDeploy写法同样可解析）。

完整的注册示例（继承自原文档）：

monitoredDeploy: enabled: true deploymentMonitors: - id: id1 name: LiveLogMonitor baseUrl: http://logmonitor.aws.com/spinnaker failOnError: false maxAnalysisMinutes: 40 - id: id2 name: LocalTestMonitore baseUrl: http://localhost:8080/v1 failOnError: true maxAnalysisMinutes: 10

参数说明（结合 DeploymentMonitorDefinition.java 补充源码确认的默认值与额外字段）：

除上述字段外，DeploymentMonitorDefinition.java 还定义了源码级的两个可选字段：

• supportContact：支持/联系信息链接（展示在 UI 中，便于用户在部署失败时快速找到监控器负责人）；
• stable：标记监控器是否稳定；stable = false的监控器不会出现在 Deck UI 的下拉列表中，但仍可在阶段 JSON 中直接引用（相当于灰度准入机制）。

五、Orca 内部调用链路与验证

5.1 客户端工厂：DeploymentMonitorServiceProvider

DeploymentMonitorServiceProvider.java 负责按注册表创建并缓存监控器客户端：

• 启动时打印所有已注册监控器的名称日志；
• getDefinitionById(id)按 ID 查找定义，找不到时抛出用户异常，防止阶段引用未注册监控器；
• getServiceByDefinition通过ServiceClientProvider基于baseUrl创建 Retrofit 服务实例，并以id为键缓存（serviceCache），同一监控器复用同一客户端连接。

在 MonitoredDeployStrategy.groovy 的composeBeforeStages中可以看到：部署真正开始前，Orca 会先调用deploymentMonitorServiceProvider.getDefinitionById(stageData.deploymentMonitor.id)校验阶段引用的监控器是否已注册——校验失败则提前中止，这正是注册白名单机制的落地实现。

5.2 阶段级参数与覆盖

监控器不仅可以在全局orca.yml注册，还可以在单个部署阶段的 JSON 中携带实例级配置，见 DeploymentMonitorStageConfig.java：

• id：引用已注册监控器的 ID；
• parameters：不透明参数 Map，随每个请求透传给监控器（见RequestBase.parameters）；
• maxAnalysisMinutesOverride：针对本次部署覆盖全局maxAnalysisMinutes；
• failOnErrorOverride：针对本次部署覆盖全局failOnError。

这为不同应用/不同流水线使用不同评估策略提供了灵活性。

5.3 超时与重试行为

从代码注释可以确认完整的等待语义：

• 监控器返回wait后，Orca 大约等待30 秒（~30s）后重新调用evaluateHealth；
• 重试不能无限进行：对于每个监控器，健康评估的总时长上限是maxAnalysisMinutes（未配置时默认30 分钟）；
• 若监控器在时限内持续以 HTTP 错误响应或干脆不响应，且failOnError = true，部署将被判定失败并终止。

这意味着监控器实现应把「评估中」的状态尽快以wait返回，而不是长时间阻塞 HTTP 请求，从而把超时控制权留给 Orca 侧。

5.4 测试佐证

模块内包含单元测试 DeploymentMonitorCapabilitiesSpec.groovy，用于验证监控器定义/能力解析等逻辑，可作为实现同类功能时的参考。

六、最小可运行实现要点（实战清单）

基于以上契约，实现一个 Deployment Monitor 的最小清单如下：

1. 实现三个POST端点：/deployment/starting、/deployment/evaluateHealth、/deployment/completed，路径拼在注册时的baseUrl之后；
2. 正确解析请求 JSON：三个端点共享RequestBase中的部署上下文字段；evaluateHealth额外有currentProgress与newInstances（当前为空列表）；completed额外有status与rollback；
3. 在evaluateHealth中返回四选一指令：wait（评估中）、continue（健康，继续）、complete（直接 100%）、abort（不健康，终止）；
4. 总是携带statusReason：给出message与可选的logSummary/additionalData，让 Deck UI 能向用户解释部署决策；
5. 评估耗时不要超过maxAnalysisMinutes：评估过程通过wait+ 快速重试表达，超时由 Orca 兜底判定失败；
6. 在orca.yml中注册并启用：配置monitoredDeploy.enabled: true，为每个监控器分配唯一id、baseUrl，按需设置failOnError（建议true）与maxAnalysisMinutes；
7. 在部署阶段 JSON 中按id引用监控器：可通过阶段级parameters、maxAnalysisMinutesOverride、failOnErrorOverride做单次部署的定制。

七、总结

Deployment Monitor 是 Spinnaker Orca 受监控部署策略与外部健康评估能力之间的标准接口：Orca 负责节奏控制与超时兜底，第三方监控器负责真正的健康判断，二者通过三个明确的 HTTP 端点和一套完整的 JSON 数据结构解耦协作。接入方只需实现端点、返回合规指令，并在orca.yml完成注册，即可让 Spinnaker 的部署流程具备「按真实健康状态驱动灰度推进、必要时自动中止或直达 100%」的能力。更多细节可继续阅读 orca-deploymentmonitor/readme.md 及其同目录下的源码与测试。

• 后端
• DevOps
• 云原生
• 微服务