为自主部署设计无冲突的回滚端点

自主部署代理需要的是安全失败的权限，而不是猜测的权限。危险的回滚很少是因为命令执行失败。更危险的情况是，系统环境已经发生变化，命令却仍然成功，把旧制品恢复到一个并非由该代理创建的发布之上。

安全的回滚操作会明确某次部署尝试，指定某个之前的发布，并在它对当前状态的判断已经过时时拒绝执行。应把回滚视为一种受保护的状态转换，而不是通往“最后一个正常版本”的捷径。这个区别决定了代理是在修复自己的工作，还是抹掉别人的变更。

回滚必须属于某次部署尝试

回滚端点必须把撤销动作绑定到导致疑似故障的那次部署尝试。单靠版本号无法完成这项工作。

团队经常保存 1.8.4、1.8.5 和 1.8.6 这样的序列，然后提供一个“将 1.8.4 部署到生产环境”的操作。代理部署了 1.8.5，收到告警后调用该操作。与此同时，一名工程师已经部署了紧急发布 1.8.6。回滚端点因为 1.8.4 存在而接受请求。此时生产环境运行的是早于这两次变更的制品。API 完全按照请求执行，而问题正在于此。

请分开保存以下身份：

• 发布是一个不可变的代码包，包含配置引用和元数据。为它分配持久 ID 和制品摘要。
• 部署尝试是一次将发布放入指定目标环境的请求。它拥有部署 ID、执行者和生命周期。
• 目标状态是环境当前运行的内容。它包含一个每次接受状态转换都会变化的修订号或代数。
• 回滚意图表示：只有在部署尝试 D 仍然拥有当前状态时，才允许它将目标恢复为发布 R。

人们经常遗漏的是所有权关系。当部署 dep_842 推进发布 rel_105 时，应记录 dep_842 创建了当前目标代数 gen_913。绑定到 dep_842 的回滚只能在 gen_913 仍是当前代数时执行。如果后续部署创建了 gen_914，服务就必须拒绝旧请求。

不要通过比较时间戳来推断所有权。重试、排队的工作进程、人工修复，以及允许用户选择旧发布的系统，都会让时序判断失效。在接受推进操作时，直接保存这种关系。

这也回答了一个棘手的运维问题：代理能否回滚另一个代理的部署？通常不能。独立的授权方可以明确批准这种干预，但普通回滚能力应只覆盖调用者自己发起的操作。广泛的权限看起来很方便，直到两个部署循环同时响应同一事故。

不可变的来源记录让之前的发布可被确定

服务必须在改变目标之前记录回滚来源，因为推进完成后，“之前”这个词就变得含糊。告警发生后再查询发布历史，很容易从列表中选中碰巧相邻的项目。

部署服务接受推进操作时，应创建一条记录，其中包含当时选定的之前稳定发布。这个发布可能不同于紧邻的上一个事件。例如，金丝雀发布可以在 rel_103 仍是稳定基线时推进 rel_105，而 rel_104 只是一次中止的实验。正确的恢复目标可能是 rel_103，而不是 rel_105 之前紧邻的那一行。

最小记录可以如下所示：

{
  "deployment_id": "dep_842",
  "environment": "production",
  "release_id": "rel_105",
  "artifact_digest": "sha256:8b2c...",
  "source_revision": "4f1d9c7",
  "config_digest": "sha256:1a06...",
  "prior_release_id": "rel_103",
  "created_target_generation": "gen_913",
  "migration_set_id": "mig_77",
  "actor_id": "agent-run-27"
}

prior_release_id 是一个决策，不是方便查询的字段。推进控制器应按照运维人员可以检查的规则选择它：例如，选择该目标最近一次经过验证的稳定发布，同时考虑配置和迁移要求是否兼容。回滚操作使用保存下来的决策，不会因为历史表已经变化而重新计算。

制品身份不能只依赖人类可读的发布标签。标签可能被重新指向，构建标签也可能意外复用。回滚应部署原始尝试中记录的内容地址或等效的不可变制品引用。如果制品仓库允许同一标签后来指向不同的字节内容，那么目标发布 ID 必须解析到推进时捕获的摘要。

配置也需要同样严谨。只恢复应用字节，却保留已经变化的功能开关、运行时密钥引用、镜像拉取策略或资源设置，可能会创建一个测试中从未存在过的系统。你不必在部署记录中复制每个值，但应记录不可变的配置版本或摘要，并明确回滚是否会恢复它。

数据库状态是另一个边界。只新增可为空列的发布，通常允许应用回滚。删除列、重写值或改变语义的发布则可能不允许。若发布规划器无法证明兼容性，就不要承诺通用的“完整回滚”。应将部署标记为可回滚应用、可回滚流量，或需要修复。拒绝执行总比让旧代码面对无法理解的架构更好。

端点需要预期的当前发布

回滚请求必须同时携带目标发布，以及它预期要替换的实时状态。没有这个前置条件，端点就无法区分有效恢复和过时指令。

请求契约可以设计成这样：

POST /v1/environments/production/rollbacks
Idempotency-Key: 7e4cd1ee-62cb-4efa-985f-4ee0b77d577b
Content-Type: application/json

{
  "origin_deployment_id": "dep_842",
  "expected_current_release_id": "rel_105",
  "expected_target_generation": "gen_913",
  "restore_release_id": "rel_103",
  "reason": "error rate exceeded release threshold",
  "approval_id": "apr_551"
}

服务应尽可能根据 origin_deployment_id 推导 restore_release_id，然后将请求中的值与保存的 prior_release_id 比较。请求中同时保留这两个字段，有助于审计人员了解代理声称的意图，但最终以服务器记录为准。绝不能让调用者把自己发起的部署变成任意选择历史制品的许可证。

成功时，返回新创建的部署尝试和新的目标代数。如果系统能够同步预留该状态转换，就不要返回含糊的 accepted 响应。

{
  "rollback_deployment_id": "dep_849",
  "reverted_deployment_id": "dep_842",
  "previous_release_id": "rel_105",
  "current_release_id": "rel_103",
  "target_generation": "gen_914",
  "status": "running"
}

如果实时目标已经不匹配，应返回冲突响应。响应正文应包含足够的信息，让代理报告发生了什么，但不能提供足够的权限让它自行设计新动作。

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": "stale_rollback",
  "origin_deployment_id": "dep_842",
  "expected_target_generation": "gen_913",
  "observed_target_generation": "gen_914",
  "observed_release_id": "rel_106"
}

409 是一次成功的安全结果。应让代理知道收到这个结果后必须停止，把响应附加到事故记录中，并请求新的决策。不要给它“去掉预期代数后再试一次”这样的备用指令。这样的备用路径会把你的防护变成表面功夫。

有些团队使用携带 ETag 的 If-Match HTTP 请求头，而不是 JSON 字段。只要 ETag 代表目标状态，并且每次状态转换都会变化，这种方式就可行。具体机制不如这个不变量重要：命令必须明确它可以替换的状态。

序列化可以阻止两个有效请求发生冲突

如果两个工作进程可以在任何一个进程提交之前都通过检查，那么单独的前置条件检查无法保护目标。部署服务必须串行处理同一环境的变更，并在状态存储中使用原子比较并交换。

假设目标当前为 (rel_105, gen_913)。代理提交回滚，操作员提交 rel_106。两个请求都读取到 gen_913。如果服务只在应用内存中检查，之后再无条件写入，那么两个调用都可能声称成功。后写入的值会生效，而审计记录可能报告一个用户从未实际看到过的状态。

应把比较和修改放在同一个事务或条件写入中。关系数据库实现可能使用这样的模式：

UPDATE environment_targets
SET release_id = :restore_release_id,
    generation = generation + 1,
    active_deployment_id = :rollback_deployment_id,
    updated_at = CURRENT_TIMESTAMP
WHERE environment = :environment
  AND generation = :expected_generation
  AND release_id = :expected_release_id;

服务应检查受影响的行数。一行发生变化，表示状态转换已被预留。零行表示冲突。随后应读取当前目标，并在 409 响应中返回实际观测到的值。

队列不能替代这个条件。队列可以降低并发工作的概率，但重复投递、队列之外的人工路径，或工作进程重试，仍可能产生相互竞争的命令。条件写入必须保留在状态实际存储的位置。

幂等性解决的是另一类故障。代理可能在服务接受回滚后丢失响应。如果它使用相同的幂等键重试，服务应返回原来的回滚部署和状态，不得再次预留一个代数或启动第二次执行。

幂等性应限定在调用者和端点范围内，保存请求正文的摘要，并在同一幂等键被不同正文复用时拒绝请求。否则，有缺陷的客户端可能通过复用标识符，把新的意图附加到早先的请求上。

回滚可能保留有问题的依赖状态

应用回滚和环境恢复是两个不同的操作。一个负责部署旧代码的端点，无法自动让所有依赖再次兼容。

我见过一种很典型的故障：发布 rel_105 引入了写入新枚举值的代码。之后的迁移收紧了数据库约束，只允许这些新值。该发布因无关原因失败，操作员恢复了 rel_103。旧代码写入之前的值，数据库拒绝了它，事故因此扩大，因为部署面板看起来显示回滚已经完成。

端点没有造成架构变更，但它的成功响应作出了错误声明。应要求发布元数据以具体方式描述兼容性，避免这种误导。至少要记录恢复发布能否读取当前数据、写入当前数据，以及能否与目标的配置版本一起运行。

流量管理也有自己的陷阱。金丝雀回滚通常只应改变该金丝雀拥有的流量分配。如果另一个发布调整了稳定流量池，或另一个控制器改变了路由规则，那么回滚端点若写入整份路由文档，就可能抹掉这些变更。应使用资源级版本，或者只修改部署预留的分配字段。

基础设施也遵循同一原则。如果某个发布创建了队列、存储桶、角色或防火墙规则，而后续工作已经采用了这些资源，那么在撤销过程中删除它们可能会伤害另一个服务。清理前需要有资源所有权记录，并确认没有后续部署认领该资源。如果无法确认所有权，就保留资源并创建修复任务。

对于不可逆操作，应选择正向修复。代理可以关闭功能开关、转移流量，或部署纠正性发布。操作员不喜欢这个答案，因为“回滚”听起来更快，但一次看似干净、实际破坏了后续数据的撤销，耗时往往超过制定修复计划。

代理需要狭窄的权限和明确的停止点

自主代理应获得完成指定部署所需的最小操作权限。它不需要原始云凭据、拥有生产访问权限的通用 shell，也不需要一个接受任意发布 ID 的端点。

代理开始发布时，为它分配一个部署句柄。该句柄可以授权状态读取、健康检查、部署分配范围内的流量变更，以及一次明确指向原始部署的回滚。当部署进入终止状态，或人工撤销运行时，使句柄失效。部署服务仍必须在服务器端执行所有权检查，因为句柄可能被复制，客户端也可能发生故障。

人工审批应发生在不可逆边界之前，而不是代理已经准备好不可逆命令之后。合理的策略是在代理开始生产部署时请求审批，然后只要所有权前置条件仍然成立，就允许它撤销这次确切的部署。如果代理遇到后续发布，那么它对任何干预都需要新的审批。这是一个适合放慢速度的节点，因为有人已经改变了环境。

Sallyport 可以让 HTTP 和 SSH 凭据留在代理进程之外，同时由人员审批代理运行，或将凭据设置为每次使用都需要审批。这种控制有助于保护操作路径，但回滚服务仍需执行自身的发布和代数检查。凭据由谁保管，不能定义部署所有权。

避免使用 production:rollback:any 这样的能力名称。它会引导调用者在运行时选择范围。更好的做法是使用由服务器签发、绑定到 dep_842、production 环境和具体回滚路由的能力。如果代理请求无关目标，授权层应在部署控制器评估请求之前拒绝它。

记录每次请求对应的代理进程或工作负载身份。人工人员应能回答：谁发起了 dep_842，调用者由什么代码签名或身份验证，哪项审批覆盖了该操作，以及是否有人在执行结束前撤销了访问权限。匿名自动化账户会让每次事故都变成考古工作。

验证必须测试恢复后的发布，而不是测试请求

只有在目标运行预期发布，并且服务验证了触发恢复的条件后，回滚才算完成。HTTP 202、命令成功退出，或控制器发出“已应用”事件，都不能证明旧发布正确地为流量提供服务。

应根据部署实际的故障模式定义验证方式。如果延迟或错误触发了回滚，就在流量切换到恢复服务后，通过同一测量路径观察它。如果工作进程发布消耗了格式错误的任务，就验证工作进程版本和受控工作负载。如果配置错误导致启动失败，就检查已就绪实例以及它们加载的配置版本。

设置有界的观察窗口，并记录结果。端点可以先报告 verifying，之后报告 succeeded、failed 或 needs_operator。不要无限等待可能不可用的指标。达到时间限制后，应生成明确的“无法判断”结果，并交由操作员决定。

审计事件应连接每个阶段：请求撤销的告警或规则、原始部署、预期状态、条件预留、执行事件、健康证据、最终状态以及任何撤销操作。事件需要排序和完整性控制，因为一条看起来友好的部署时间线，在发生争议时远远不够。

Sallyport 会通过加密哈希链审计日志记录代理运行和单独的操作，sp audit verify 无需保险库密钥即可在离线环境中检查这条链。可以使用这类证据证明代理请求过某项操作，同时保留部署服务自身的状态转换和验证记录，作为实际变更内容的权威记录。

熟悉的回滚命令需要更安全的包装层

对于直接操作 Kubernetes Deployment 的人员来说，kubectl rollout undo 很有用，但它不是自主恢复的完整契约。Kubernetes 文档说明，除非调用者提供 --to-revision，否则 kubectl rollout undo 会回滚到之前的部署版本。这种默认行为适合人工排查，却不能证明之前的版本属于发生故障的代理运行。

Kubernetes Deployment 会在 ReplicaSet 中跟踪版本历史，而 revisionHistoryLimit 控制 Kubernetes 保留多少历史。那段历史是控制器的产物，不是你关于发布批准基线、配置兼容性或代理所有权的业务记录。历史被清理后，“撤销”也可能找不到外部部署流程所期待的版本。

不要给代理一份通用的 kubectl 凭据，然后把这个命令称为回滚端点。应在代理和集群之间放置控制器或部署服务。服务应解析原始部署记录，比较目标的实时代数，预留状态变更，并且只有通过这些检查后才调用底层平台。

对于声称“部署版本 X”的云厂商命令，或声称“重新运行之前发布”的 CI 控件，也有同样的问题。它们操作的是平台资源。除非你的控制平面提供上下文，否则它们不知道某个发布是否与代理当前的事故有关。

平台命令本身也应保持狭窄。如果服务只需修改指定工作负载的版本，就不要授予它集群范围的修改权限。在保留广泛凭据的情况下，包装层只是把危险藏到了另一个 API 后面。

在自动化恢复前建立发布台账

无需替换所有部署系统，也可以引入受保护的回滚。先让发布台账成为一个生产目标的权威记录，然后要求人工和代理路径都通过同一个条件转换。

实际的落地步骤可以分为五部分：

1. 为发布和部署尝试分配不可变 ID，并在推进时记录之前批准的发布和目标代数。
2. 增加一个端点，要求提供 origin_deployment_id、预期发布、预期代数和幂等键。
3. 在数据库或控制存储中让目标更新遵循条件，并对每次不匹配都返回 409。
4. 在推进前，分别评估每个发布对应用、配置、数据和流量的可回滚性。
5. 要求控制器在将回滚标记为完成前提供验证证据。

在允许代理执行之前，先以报告模式运行这套契约。让服务计算它会恢复什么，以及它是否会拒绝请求。将这些决策与实际事故处理进行比较。这样可以在不给自动化覆盖生产环境机会的情况下，发现缺失的来源记录和隐藏的人工路径。

然后让拒绝变得平常。过时的回滚应创建一条易于理解的事故事项，其中包含实际观测到的发布和代数，而不是产生一个神秘的失败，诱使人绕过端点。端点只有在始终如一地拒绝不安全请求时才会赢得信任，包括拒绝构建它的人发出的请求。

首先要添加的字段不是 force，而是 expected_target_generation。一旦部署携带这个事实，并保存原始基线，代理就能在清晰的边界内撤销自己的发布。在此之前，自主回滚只是把旧的部署命令指向一个不断变化的目标。