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

# 编排

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

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

如果你只想用一台已有的机器来处理会话，请先阅读[快速入门](/zh/onboard-devin/outposts/quickstart)——无需编排器。如果你在受支持的平台上运行，[集成](/zh/onboard-devin/outposts#integrations)可能已经为你实现了这一循环。有关完整的 API 和 CLI 说明，请参阅[参考文档](/zh/onboard-devin/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 等并列) 。以其为目标的会话会在其队列中等待，直到被某个工作器认领。

<Note>
  在 fleet API 中，Outposts 表示为作用域限定在你的账户下的 `outposts` 资源
  (在该账户的所有组织之间共享) 。请参阅
  [outposts 端点](/zh/onboard-devin/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/onboard-devin/outposts/reference#list-queued-sessions)和[监听变更](/zh/onboard-devin/outposts/reference#watch-for-changes)。

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

在为会话启动机器之前，先以原子方式认领它，避免被其他工作器领取。传入一个 `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/onboard-devin/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/onboard-devin/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：

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

这意味着，横向扩展只需在更多指向同一个 outpost 的 machine 上运行工作器即可：N 台 machine 可同时处理 N 个 session，其余的则以待处理状态继续等待。

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

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