OpenSandbox task-executor任务执行器解析：批任务如何驱动沙箱

OpenSandbox task-executor任务执行器解析：批任务如何驱动沙箱

【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox

OpenSandbox 的 task-executor 是面向 AI Agent 沙箱的批任务任务执行器：它以轻量 Sidecar 形式运行在沙箱 Pod 内，接收来自控制器的任务规格，负责把一个个短生命周期任务（进程或容器）安全地拉起、监控、回收。本文带你快速读懂它的执行原理、任务生命周期与 HTTP 接口，帮你看懂批任务是如何一步步驱动沙箱的。

1. task-executor 是什么：沙箱内的"批任务执行引擎"

在 OpenSandbox 的 Kubernetes 体系中，BatchSandboxController等控制器负责调度决策，而真正"动手干活"的是运行在每个沙箱 Pod 里的task-executor。它有三个关键身份 🧩：

• 本地 Agent：以独立二进制运行，不依赖 etcd，状态全部落在本地文件目录（默认/var/lib/sandbox/tasks）；
• HTTP 服务：默认监听0.0.0.0:5758，对外暴露任务创建、查询、同步、删除等 REST 接口；
• 任务管家：内置一个约 500ms 一轮的协调循环（reconcile loop），持续观察任务进程并把状态变更持久化。

入口逻辑非常直观：加载配置 → 初始化文件存储 → 创建执行器 → 启动任务管理器 → 拉起 HTTP 服务，详见 kubernetes/cmd/task-executor/main.go。

2. 它在架构中的位置：控制器如何把批任务"下发"到节点

BatchSandboxController → TaskScheduler → task-executor (Pod 内 HTTP :5758) → 进程/容器 调度决策 任务分配 本地执行 实际工作负载

控制器并不直接启动进程，而是通过 task-executor 的 HTTP API 下发任务；执行结果再以任务状态的形式被调度器观察，最终反映到BatchSandbox的资源状态中。这种"控制面 / 执行面分离"的设计，让批任务的编排逻辑与节点执行细节彻底解耦。更多架构说明可参考 kubernetes/DEVELOPMENT.md 与 kubernetes/AGENTS.md。

3. 核心三件套：Manager、Runtime、Storage

task-executor 的代码组织在 kubernetes/internal/task-executor/ 下，职责划分清晰：

几个值得注意的设计细节：

• 并发控制：当前单 Pod 内maxConcurrentTasks = 1，保证批任务串行、资源可控（task_manager.go#L34）；
• 优雅删除：删除任务只是打上DeletionTimestamp标记（"软删除"），由协调循环负责发信号、等进程退出、执行 postStop 钩子后再清理；
• 崩溃恢复：重启时从磁盘恢复任务清单，重新Inspect每个任务的实际进程状态，避免"僵尸状态"（recoverTasks）。

4. 任务是怎么"跑起来"的：shim 脚本 + 文件状态锚

process 运行时不用内存跟踪进程，而是用三个小文件作为状态锚点 📁：

1. pid文件：进程启动成功后立即写入 PID；
2. exit文件：进程退出后由 shim 脚本写入退出码（0 = 成功，非 0 = 失败）；
3. stdout.log/stderr.log：任务输出重定向到磁盘，方便事后排查。

所谓 shim 脚本，本质是一个"迷你 init"：它把用户命令放到后台运行、捕获 SIGTERM 并转发给子进程、最终把退出码写进exit文件（见 buildShimScript）。这套机制让 task-executor 即使自身崩溃重启，也能通过文件准确还原每个任务处于 Pending、Running、Succeeded 还是 Failed 状态。

状态推断逻辑同样简单可靠：有exit文件 → 按退出码判定成败；只有pid文件且进程还活着 → Running（并检查是否超过TimeoutSeconds）；PID 对应的进程消失但没有exit文件 → 视为崩溃（Inspect）。

5. Host 与 Sidecar 双模式：任务跑在谁的"世界"里

task-executor 支持两种执行模式，由--enable-sidecar-mode开关控制：

• Host 模式：直接在 task-executor 所在容器内以/bin/sh -c启动任务，简单直接；
• Sidecar 模式：借助nsenter进入主容器（默认名为main）的 mount / pid / net 等命名空间执行任务，使任务与主业务容器"同处一个世界"，可读写主容器内的文件系统、访问其网络环境（useNsenterForProcess）。

Sidecar 模式的定位目标：task-executor 通过扫描/proc找到带有SANDBOX_MAIN_CONTAINER=<容器名>环境变量的进程作为命名空间入口（findPidByEnvVar）。停止任务时也是同样的思路——先 SIGTERM 优雅终止，10 秒未退出再 SIGKILL 整个进程树。

6. 生命周期钩子：preStart 与 postStop

除了主进程，任务规格还支持生命周期钩子，让批任务具备"前置校验 / 后置清理"能力：

• preStart：任务主进程启动前执行，失败则任务直接进入Failed（Reason 为PreStartHookFailed）；
• postStop：任务停止后执行，完成后会在 SubStatus 中追加PostStopHookCompleted标记。

钩子支持独立超时（TimeoutSeconds），输出保留首尾各 8 KiB 用于诊断（execLifecycleHook）。这与 OpenSandbox 沙箱层面的生命周期钩子思路一脉相承，可参考官方文档 docs/guides/lifecycle-hooks.md 中的钩子时序设计。

7. HTTP API 速览：5 个端点管完任务一生

完整接口文档见 kubernetes/examples/task-executor/README.md，常用端点如下：

其中POST /setTasks是声明式同步入口：控制器把"期望状态"整体推过来，不在清单里的任务被标记删除、新任务被创建——这正是批任务与沙箱"驱动"关系的核心：控制器声明意图，执行器负责收敛现实。

8. 动手体验：3 步提交你的第一个沙箱任务

项目自带一个极简客户端示例 kubernetes/examples/task-executor/main.go，演示了完整闭环：

1. 提交任务：client.Set(ctx, task)提交一条echo命令任务；
2. 轮询状态：循环client.Get(ctx)观察 Waiting → Running → Terminated 的状态流转，直到拿到退出码；
3. 清理：传nil调用Set清空任务列表。

本地调试时也可以直接 port-forward 到沙箱 Pod 后curl交互，命令示例见 kubernetes/DEVELOPMENT.md。

9. 小结：task-executor 的设计亮点

🎯 回顾全文，task-executor 用非常少的部件解决了批任务落地的关键问题：

• 文件即状态：pid / exit / 日志三个文件让任务状态可恢复、可审计；
• 声明式同步：setTasks接口让控制器的"期望状态"成为唯一事实来源；
• 优雅生命周期：软删除 + 信号转发 + preStart/postStop 钩子，批任务也能像容器一样被体面地管理；
• Host/Sidecar 双模式：既能独立跑进程，也能借 nsenter 融入主容器环境。

理解了这条"控制器 → HTTP → 文件锚定的进程"链路，你就掌握了 OpenSandbox 批任务驱动沙箱的完整机制。若想深入，可从 kubernetes/internal/task-executor/ 源码与 kubernetes/test/e2e_task/ 端到端测试继续读起。

【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox