Skip to main content
编排器会监视 outposts API 中等待某个 outpost 的会话，为每个会话预配一个 VM 或容器，并在其中启动工作器。本页介绍这一编排循环：轮询队列、认领会话、运行工作器，以及回收机器。 如果你只是想用现有机器处理会话，请先阅读快速入门——无需编排器。如果你在受支持的平台上运行，集成可能已经为你实现了这一循环。有关完整的 API 和 CLI 说明，请参阅参考。
在 Kubernetes 上运行？devin-outpost-k8s 是一个开源 Operator，可为你实现这一循环：它会监视 队列、认领待处理的会话，并将每个会话作为工作器 pod 运行在任何 认证集群上 (GKE、EKS、…) 。请通过它的 Helm chart 安装， 而不是自行构建编排器。

​
核心流程

​
  1. 注册一个 outpost

outpost 是一个已命名的会话队列，由部署在你的基础架构上的多个工作器提供服务 (例如 rhel、gpu-h200 或 my-outpost) 。使用 devin worker outpost create 创建一个：
注册完成后，启动会话时，outpost 会显示为 Devin Cloud 中的一个机器选项 (与 Ubuntu、Windows 等并列) 。以该 outpost 为目标的会话会在其队列中等待，直到有工作器将其认领。
在 fleet API 中，Outposts 表示为 outposts 资源，其作用域限定在 你的账户下 (由其所有组织共享) 。请参阅 outposts 端点。

​
  1. 监听 fleet API 中等待的会话

你的 编排器 会列出其所服务的 outpost 中待处理的会话：
然后，它通过 Server-Sent Events (SSE) 监听保持视图最新，并从列表的最后一个游标继续：
这是标准的 Kubernetes 风格“先列出后监听”模式：使用响应游标逐页列出结果，然后从列表结束处开始监听，并持久保存每个事件的游标，以便你在重新连接时不会漏掉任何变更。事件投递采用至少一次语义，因此请按 metadata.session_id 执行 upsert，并容忍重复。有关查询参数、响应格式以及完整的分页语义，请参阅 列出排队的会话 和 监听变更。

​
  1. 预配前先认领

在为某个 会话 启动 machine 之前，先以原子操作认领它，避免被其他工作器接走。传入一个 acceptor_id —— 这是工作器自行上报的身份标识：
认领操作是原子的：如果另一个工作器先认领了该会话，就会返回 409。认领意味着会有一个工作器在服务器分配的认领截止时间 (status.claim_deadline) 内就绪；过期的认领会自动返回队列。如果预配失败，请释放认领，以便该会话立即返回队列。

​
  1. 启动一台机器并运行工作器

对于每个已认领的会话，基于你的镜像预配一个 VM 或容器。在其中，从你希望会话工作的目录中运行工作器——其代码仓库位于该目录的 repos 子目录中，即 $(pwd)/repos/<repo-name>：
传入你在 API 认领时使用的同一个 --acceptor-id，并通过 --token 或 DEVIN_OUTPOSTS_TOKEN 提供令牌 (参见完整开关列表) 。工作器会连接到 Devin 的云端，将会话标记为就绪，并开始执行工具调用。

​
  1. 在工作器退出时终止机器

当 devin worker start 退出时，会话即告结束 (或已暂停) 。终止 VM 或容器。如果你的 outpost 支持恢复，请在终止前为机器创建快照，以便在会话恢复时还原。

​
需要持久化的目录

已暂停的会话之后可以恢复，届时它会在原来的位置查找自己的文件。在为恢复的会话启动工作器之前，请先还原以下目录： 为整台机器创建快照即可同时涵盖这两个目录。如果你只持久化部分文件系统 (例如主目录卷) ，请确保这两个目录都在其中，并在恢复时于相同的工作目录中启动工作器。 会话启动时，Devin 会在上述每个目录中为其写入一个小型标记文件：工作目录中的 .devin-outpost-stamps/<session_id>，以及会话状态目录中的 outpost_stamp。如果会话恢复时缺少某个标记文件，则说明对应目录未被持久化，Devin 会在会话中发出警告并指明该目录。在空机器上进行恢复不适用于生产环境：会话将丢失检出的代码、未提交的工作以及已安装的依赖。 你的编排器可以跟踪其已认领的会话及这些会话的状态：
每个条目都包含一个 status.session_status 字段，其值为 pending、running、suspended 或 terminated。

​
去中心化调度

如果你计划运行超过约 16 个协调组件 (即监视并从 outpost 认领任务的工作器或 编排器) ，请先联系你的账户团队——更大的集群会加剧认领竞争并提高队列读取负载，我们希望确保 outpost 已为此做好相应配置。
你不需要中央调度器来运行一个集群。队列 API 的设计使多个彼此独立的工作器无需相互通信，也能共同为同一个 outpost 提供服务：
  • 认领是唯一的协调机制。 每个工作器都会独立监视队列，并竞争认领待处理的会话。认领是在服务器上执行的原子 compare-and-swap 操作：恰好只有一个工作器会成功，其他所有失败者都会收到 409，然后直接继续处理下一个待处理会话。认领竞争失败是正常情况，不是错误。
  • 每个工作器都有自己的身份标识。 acceptor_id 会将工作器的认领、续期和重启恢复限定在该工作器自身范围内。devin worker start 会为每台机器自动生成并持久化一个，因此集群无需额外配置身份标识。切勿在不同机器之间共享 acceptor ID (或复制的工作器数据目录) ——发生冲突的工作器会互相抢走对方的认领。
  • 故障会自行恢复。 如果工作器在认领后终止，其认领会在 claim deadline 到达时过期，该会话会返回队列，由其他工作器接手。无需进行集群级别的健康状态跟踪。
这意味着，横向扩展只需要在更多机器上运行指向同一个 outpost 的工作器：N 台机器可同时处理 N 个并发会话，其余会话则保持待处理状态并继续等待。

​
构建自定义编排器

devin worker start 的所有功能都可以直接通过 fleet API 实现，因此你可以完全替代 CLI：从 Devin 的静态分发源获取 devin-remote 二进制程序，并按照文档中说明的环境自行启动它。请参阅参考文档中的 远程二进制程序分发 和 spawn 约定。