> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 编排

> 在会话排队时自动预配机器并运行工作器

编排器会监视 outposts API 中等待某个 outpost 的会话，为每个会话预配一个 VM 或容器，并在其中启动工作器。本页介绍这一编排循环：轮询队列、认领会话、运行工作器，以及回收机器。

如果你只是想用现有机器处理会话，请先阅读[快速入门](/zh/cloud/outposts/quickstart)——无需编排器。如果你在受支持的平台上运行，[集成](/zh/cloud/outposts/overview#integrations)可能已经为你实现了这一循环。有关完整的 API 和 CLI 说明，请参阅[参考](/zh/cloud/outposts/reference)。

<Note>
  在 Kubernetes 上运行？[devin-outpost-k8s](https://github.com/CognitionAI/devin-outpost-k8s)
  是一个开源 Operator，可为你实现这一循环：它会监视
  队列、认领待处理的会话，并将每个会话作为工作器 pod 运行在任何
  认证集群上 (GKE、EKS、...) 。请通过它的 Helm chart 安装，
  而不是自行构建编排器。
</Note>

<div id="the-core-flow">
  ## 核心流程
</div>

<div id="1-register-an-outpost">
  ### 1. 注册一个 outpost
</div>

outpost 是一个已命名的会话队列，由部署在你的基础架构上的多个工作器提供服务 (例如 `rhel`、`gpu-h200` 或 `my-outpost`) 。使用 `devin worker outpost create` 创建一个：

```bash theme={null}
devin worker outpost create <name> --platform <platform> --description "..."
```

注册完成后，启动会话时，outpost 会显示为 Devin Cloud 中的一个机器选项 (与 Ubuntu、Windows 等并列) 。以该 outpost 为目标的会话会在其队列中等待，直到有工作器将其认领。

<Note>
  在 fleet API 中，Outposts 表示为 `outposts` 资源，其作用域限定在
  你的账户下 (由其所有组织共享) 。请参阅
  [outposts 端点](/zh/cloud/outposts/reference#outposts)。
</Note>

<div id="2-watch-the-fleet-api-for-waiting-sessions">
  ### 2. 监听 fleet API 中等待的会话
</div>

你的 编排器 会列出其所服务的 outpost 中待处理的会话：

```bash theme={null}
curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?outpost=<outpost_id>&phase=pending"
```

然后，它通过 Server-Sent Events (SSE) 监听保持视图最新，并从列表的最后一个游标继续：

```bash theme={null}
curl -N -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?outpost=<outpost_id>&watch=true&cursor=<cursor>"
```

这是标准的 Kubernetes 风格“先列出后监听”模式：使用响应游标逐页列出结果，然后从列表结束处开始监听，并持久保存每个事件的游标，以便你在重新连接时不会漏掉任何变更。事件投递采用至少一次语义，因此请按 `metadata.session_id` 执行 upsert，并容忍重复。有关查询参数、响应格式以及完整的分页语义，请参阅 [列出排队的会话](/zh/cloud/outposts/reference#list-queued-sessions) 和 [监听变更](/zh/cloud/outposts/reference#watch-for-changes)。

<div id="3-claim-before-provisioning">
  ### 3. 预配前先认领
</div>

在为某个 会话 启动 machine 之前，先以原子操作认领它，避免被其他工作器接走。传入一个 `acceptor_id` —— 这是工作器自行上报的身份标识：

```bash theme={null}
curl -X POST -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"acceptor_id": "worker-1"}' \
  "https://api.devin.ai/opbeta/outposts/devins/{session_id}/claim"
```

认领操作是原子的：如果另一个工作器先认领了该会话，就会返回 `409`。认领意味着会有一个工作器在服务器分配的认领截止时间 (`status.claim_deadline`) 内就绪；过期的认领会自动返回队列。如果预配失败，请[释放认领](/zh/cloud/outposts/reference#release-a-claim)，以便该会话立即返回队列。

<div id="4-spawn-a-machine-and-run-the-worker">
  ### 4. 启动一台机器并运行工作器
</div>

对于每个已领取的会话，基于你的镜像预配一个 VM 或容器。在其中，从已签出该会话代码仓库的目录中运行工作器：

```bash theme={null}
cd /path/to/repos
devin worker start --session=<session_id> --outpost=<outpost_id> --acceptor-id=<worker_id>
```

传入你在 API 认领时使用的同一个 `--acceptor-id`，并通过 `--token` 或 `DEVIN_OUTPOSTS_TOKEN` 提供令牌 (参见[完整开关列表](/zh/cloud/outposts/reference#devin-worker-start)) 。工作器会连接到 Devin 的云端，将会话标记为就绪，并开始执行工具调用。

<div id="5-terminate-the-machine-when-the-worker-exits">
  ### 5. 在工作器退出时终止机器
</div>

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

你的编排器可以跟踪它已认领的会话及其状态：

```bash theme={null}
curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?phase=claimed&acceptor_id=worker-1"
```

每个条目的 `status.session_status` 都会显示为 `pending`、`running`、`suspended` 或 `terminated`。

<div id="centralization-free-scheduling">
  ## 去中心化调度
</div>

<Note>
  如果你计划运行超过约 16 个协调组件 (即监视并从 outpost 认领任务的工作器或 编排器) ，请先联系你的账户团队——更大的集群会加剧认领竞争并提高队列读取负载，我们希望确保 outpost 已为此做好相应配置。
</Note>

你不需要中央调度器来运行一个集群。队列 API 的设计使多个彼此独立的工作器无需相互通信，也能共同为同一个 outpost 提供服务：

* **认领是唯一的协调机制。** 每个工作器都会独立监视队列，并竞争认领待处理的会话。认领是在服务器上执行的原子 compare-and-swap 操作：恰好只有一个工作器会成功，其他所有失败者都会收到 `409`，然后直接继续处理下一个待处理会话。认领竞争失败是正常情况，不是错误。
* **每个工作器都有自己的身份标识。** `acceptor_id` 会将工作器的认领、续期和重启恢复限定在该工作器自身范围内。`devin worker start` 会为每台机器自动生成并持久化一个，因此集群无需额外配置身份标识。切勿在不同机器之间共享 acceptor ID (或复制的工作器数据目录) ——发生冲突的工作器会互相抢走对方的认领。
* **故障会自行恢复。** 如果工作器在认领后终止，其认领会在 claim deadline 到达时过期，该会话会返回队列，由其他工作器接手。无需进行集群级别的健康状态跟踪。

这意味着，横向扩展只需要在更多机器上运行指向同一个 outpost 的工作器：N 台机器可同时处理 N 个并发会话，其余会话则保持待处理状态并继续等待。

<div id="building-a-custom-orchestrator">
  ## 构建自定义编排器
</div>

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