FastGPT Sealos Sandbox Provider 实现指南：基于 sandbox-adapter 的 Sealos Devbox 接入方案-迪斯科星球

FastGPT Sealos Sandbox Provider 实现指南：基于 sandbox-adapter 的 Sealos Devbox 接入方案

【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT

导读

本文围绕 FastGPT 仓库中.agents/issue/implement-sealos-provider.md的实现方案，系统讲解 FastGPT 如何通过统一的@fastgpt-sdk/sandbox-adapter接入两种 Agent Sandbox Provider——自研的 OpenSandbox 与 Sealos Devbox。文章覆盖 Provider 能力对比、统一 Create Spec 设计、Sealos FastGPT Runtime 约定、SandboxEditor文件通道架构以及 FastGPT 侧的环境变量与 API 改造点，并结合仓库内sdk/sandbox-adapter的实际源码（适配器、HTTP 客户端、契约与类型定义）给出可验证的实现细节。读完本文，你将掌握 FastGPT 多 Provider 沙箱的抽象边界、Sealos Devbox 的字段映射规则，以及 Skill 编辑器脱离 iframe 后基于 FastGPT API 的文件操作链路。

1. 设计基线：所有 Sandbox 请求统一走 sandbox-adapter

方案的第一条基线非常明确：FastGPT 不直接请求任何 Provider 的 API，所有沙箱访问都收敛到@fastgpt-sdk/sandbox-adapter这个 SDK 包。

FastGPT -> @fastgpt-sdk/sandbox-adapter -> OpenSandboxAdapter -> OpenSandbox -> fastgpt-agent-sandbox -> SealosDevboxAdapter -> Sealos Devbox -> frameworks/sandbox/fastgpt

设计文档中的几个已确认结论：

OpenSandbox 和 Sealos 都必须走sandbox-adapter，FastGPT 不直接请求 Provider API。
projects/agent-sandbox只用于 OpenSandbox 场景。
Sealos 场景下，Devbox 本身就是 Agent Sandbox 方案。
Sealos 新 runtime 使用labring-actions/devbox-runtime#122新增的frameworks/sandbox/fastgpt，不是 FastGPT 自维护的fastgpt-agent-sandbox镜像。

这一分层在源码中得到完整印证。sdk/sandbox-adapter/src/adapters/index.ts提供了统一的工厂函数createSandbox，根据provider分派到OpenSandboxAdapter或SealosDevboxAdapter，并定义了联合类型SandboxFactoryConfig：

export type SandboxProviderType = 'opensandbox' | 'sealosdevbox'; export function createSandbox(config: SandboxFactoryConfig): ISandbox { switch (config.provider) { case 'opensandbox': return new OpenSandboxAdapter(config.connectionConfig, config.createConfig); case 'sealosdevbox': return new SealosDevboxAdapter(config.connectionConfig, config.createConfig); default: throw new Error('Unknown sandbox provider'); } }

SDK 对外暴露的契约是ISandbox（见sdk/sandbox-adapter/src/contracts/sandbox.ts），它是生命周期（lifecycle）、命令执行（command）、文件系统（filesystem）、健康检查（health）四个契约的交叉类型，并额外要求provider标识、capabilities能力声明和可选的getEndpoint(port)端口访问能力。FastGPT 上层只依赖这个统一接口，从而做到"上层无感、Provider 可插拔"。

2. Provider 能力对比：OpenSandbox 与 Sealos Devbox

2.1 OpenSandbox 能力

OpenSandbox 使用 FastGPT 自己维护的fastgpt-agent-sandbox镜像，当前 FastGPT 依赖的 create 能力包括：

image
entrypoint
env
metadata
volumes
resourceLimits

2.2 Sealos Devbox 能力

Sealos Devbox v2 server 的 create API 支持以下字段：

name
image
upstreamID
env
kubeAccess
pauseAt
archiveAfterPauseTime
labels

Sealos Devbox info API 返回：

state
ssh
gateway.url
gateway.token
gateway.port
gateway.uniqueID

Sealos Devbox server 已原生提供 exec/file 能力：

POST /api/v1/devbox/{name}/exec
POST /api/v1/devbox/{name}/files/upload
GET /api/v1/devbox/{name}/files/download

这些接口内部转发到 Pod 内devbox-sdk-server:9757，FastGPT 不需要自己实现 exec/file 通道。

该结论在sdk/sandbox-adapter/src/adapters/sealos-devbox/client.ts中得到完整验证——DevboxClient实现了与上述 REST 端点一一对应的方法：create、info、pause、resume、delete、exec、uploadFile、downloadFile，并额外提供downloadFileStream，通过原生 HTTP 响应流逐块 yield 数据，避免大文件在 Node 内存中整体缓冲。请求统一携带Authorization: Bearer <token>。

对应地，SealosDevboxAdapter的capabilities（见sdk/sandbox-adapter/src/adapters/sealos-devbox/adapter.ts）声明为：

readonly capabilities: SandboxCapabilities = { command: { streaming: false, background: false, interrupt: false }, filesystem: { streamingRead: true, streamingWrite: true }, metrics: true, expirationRenewal: false };

即 Sealos 场景下命令执行是非流式的（一次性返回 stdout/stderr/exitCode），文件系统支持流式读写，但不支持过期续期——生命周期由 Devbox 的pauseAt/archiveAfterPauseTime策略托管。

由于 Devbox 在Running后其 exec 通道仍可能短暂不可用，适配器内部实现了 Provider 专属的就绪探测waitUntilCommandReady()（超时 300s、间隔 1s），通过反复执行true命令探测 exec 通道；同时getInfoWithProviderRetry会在 gateway 重启期间对 502/503/504 及no healthy upstream做有限重试，但重试仅限初始 info 探测，避免 create/resume/delete 等生命周期变更被重复执行。

2.3 Devbox FastGPT Runtime 约定

frameworks/sandbox/fastgptruntime 的关键约定：

codex-gateway默认监听1317；
Devbox v2 server gateway 固定反代 Pod 内1317；
code-server是 runtime 的可选浏览器编辑服务，当前 FastGPT Skill 编辑页不再依赖它；
如果未来恢复 Provider 页面嵌入，code-server可通过CODE_SERVER_ENABLED=true启动；
默认工作目录是/home/devbox/workspace；
默认 Codex home 是/codex-home。

设计文档建议的 Sealos runtime env：

{ CODEX_GATEWAY_CWD: '/home/devbox/workspace', CODEX_GATEWAY_CODEX_HOME: '/codex-home' }

当前SandboxEditor文件 API 链路不需要启动code-server。如果后续重新接入 Provider 浏览器页面，再额外传入：

{ CODE_SERVER_ENABLED: 'true' }

3. Adapter 方案：统一 Create Spec 与字段映射

3.1 统一 Create Spec 设计

create spec 抽象放在agent-sandbox-adaptor。设计文档建议保留一个统一 schema，不拆 Provider-specific schema，Provider 支持范围用 typed metadata 描述。文档中给出的核心 zod schema 结构：

const SandboxCreateSpecSchema = z.object({ image: z .object({ repository: z.string(), tag: z.string().optional(), digest: z.string().optional() }) .optional(), env: z.record(z.string(), z.string()).optional(), metadata: z.record(z.string(), z.string()).optional(), labels: z.array(z.object({ key: z.string(), value: z.string() })).optional(), lifecycle: z .object({ pauseAt: z.string().optional(), archiveAfterPauseTime: z.string().optional() }) .optional(), kubeAccess: z .object({ enabled: z.boolean().optional(), roleTemplate: z.enum(['view', 'edit', 'admin']).optional() }) .optional(), entrypoint: z.array(z.string()).optional(), workingDir: z.string().optional(), volumes: z.array(z.unknown()).optional(), resourceLimits: z.unknown().optional() });

在仓库当前的 TypeScript 实现中，这一契约以SandboxCreateSpec类型的形式落地于sdk/sandbox-adapter/src/types/sandbox.ts，字段不仅覆盖文档列出的内容，还包含timeoutSeconds、networkPolicy、extensions、upstreamID、skipHealthCheck、readyTimeoutSeconds、healthCheckPollingInterval等扩展项。类型注释明确写道："The surface is intentionally wider than any single provider API: FastGPT builds one runtime profile and maps it to a provider-specific create config before it reaches the adapter factory."（这个表面刻意比任何一个 Provider API 都宽：FastGPT 构建统一的 runtime profile，在到达适配器工厂前映射为 Provider 专属的 create config）。这正是"统一 schema + typed metadata 描述支持范围"设计意图的代码体现。

3.2 OpenSandbox Adapter 映射

OpenSandbox adapter 支持从统一 spec 中映射以下字段：

image
entrypoint
env
metadata
volumes
resourceLimits

3.3 SealosDevbox Adapter 映射

SealosDevbox adapter 的映射规则：

image→ Devboximage，仅使用 Sealos 专用 runtime image；
env→ Devboxenv；
metadata.sessionId或显式字段 → DevboxupstreamID；
workingDir→env.CODEX_GATEWAY_CWD；
labels→ Devboxlabels；
kubeAccess→ DevboxkubeAccess；
lifecycle.pauseAt→ DevboxpauseAt；
lifecycle.archiveAfterPauseTime→ DevboxarchiveAfterPauseTime。

Sealos adapter 不支持：entrypoint、volumes、resourceLimits。

源码SealosDevboxAdapter.buildCreateRequest()完整实现了上述映射：workingDir会被写入env.CODEX_GATEWAY_CWD（若调用方未显式传入该 env），image仅在repository存在时通过formatImageSpec序列化，labels、upstreamID、kubeAccess、pauseAt、archiveAfterPauseTime按名透传。值得注意的是，虽然设计文档称 Sealos 不支持resourceLimits，当前源码的SealosDevboxCreateConfig已通过Pick<SandboxCreateSpec, ...>包含了resourceLimits，并将其映射为 Devbox 的cpu（如"2"）、memory（如"4096Mi"）和storageLimit（如"5G"/"10Gi"，K8s resource quantity 格式），同时对 cpu/memory 做正数校验、对 storage 做非空校验——从源码结构看，这是后续在 Devbox API 支持资源限制后补充的能力。

3.4 Sealos Image 配置策略

默认让 Devbox server 的createDefaults.image配成frameworks/sandbox/fastgpt对应镜像，FastGPT 创建 Devbox 时不传image。

agent-sandbox-adaptor仍保留 Sealosimage映射能力，用于调试、灰度或多 runtime 场景。如果 FastGPT 需要显式控制 runtime 镜像，再新增 Sealos 专用配置：

AGENT_SANDBOX_SEALOS_IMAGE

不要复用：

AGENT_SANDBOX_OPENSANDBOX_IMAGE

这一约定在 FastGPT 侧的环境变量与 runtime profile 中均有体现（详见第 5 节）。

4. 编辑器访问与文件通道

4.1 当前产品形态：不再嵌入 Provider 页面

当前 FastGPT不再使用SandboxIframe嵌入code-server，也不再要求浏览器直接访问 Provider endpoint。Skill 编辑页使用 FastGPT 自己的SandboxEditor文件树和 Monaco 编辑器：

Skill detail page -> SandboxEditor -> /api/core/ai/skill/edit 创建或复用 edit-debug sandbox -> /api/core/ai/sandbox/listRecursive 递归读取 workspace 文件树 -> /api/core/ai/sandbox/read 读取文件 -> /api/core/ai/sandbox/write 写入文件 -> /api/core/ai/sandbox/fileOp mkdir/delete/move/copy/upload -> /api/core/ai/sandbox/download 下载文件或目录 -> /api/core/ai/skill/save-deploy 从 workspace 打包并发布版本

因此首期 Sealos 接入的验收重点是Provider adapter 的生命周期、exec 和文件系统能力，而不是code-serveriframe、WebSocket 或 cookie/session 隔离。

4.2 Backend 文件通道

所有浏览器操作都回到 FastGPT API，由后端鉴权后通过 sandbox adapter 操作远端文件系统：

Browser -> FastGPT API -> authSandboxSession -> getSandboxClient(appId/userId/chatId 或 edit-debug) -> ISandbox.execute / readFiles / writeFiles / listDirectory / getFileInfo / moveFiles -> OpenSandboxAdapter 或 SealosDevboxAdapter

关键边界：

浏览器只知道 FastGPT 的 API，不持有 Provider endpoint、proxy target 或 Provider path；
authSandboxSession统一区分普通 chat sandbox 和 Skilledit-debugsandbox；
getSandboxClient负责确保 sandbox 可用，并刷新本地agent_sandbox_instances记录；
SandboxEditor只处理文件树/文件内容 UI，不承担 Provider endpoint 解析。

4.3 Adapter Endpoint 能力（可选）

ISandbox.getEndpoint(port)可以作为 Provider 暴露端口的可选能力保留，用于未来诊断或额外服务访问。当前 Skill 编辑链路不依赖：

getProxyTarget(service)
sandbox-proxy
/__fastgpt_proxy/code-server/
SandboxIframe.tsx
code-serverHTTP/WS 访问

如果后续重新引入code-server或codex-gateway的浏览器访问，再单独设计 service-level endpoint/proxy target，该设计不应混入当前SandboxEditor文件 API 链路。

源码层面，两个适配器都已实现getEndpoint：OpenSandbox 通过底层 SDK 的sandbox.getEndpointUrl(selector)返回；SealosDevbox 则从 info API 的gateway.url推导 httpgate endpoint——解析出uniqueID（优先取gateway.uniqueID，否则从 gateway pathname 末段提取）和 httpgate 域名（支持httpgateDomain配置覆盖，否则从-gateway.分隔符后的 host 截取），拼装为devbox-<uniqueID>-<port>.<domain>形式的访问地址。这正是设计文档 TODO 第 4 条"支持从gateway.url推导 httpgate endpoint，用于未来端口访问或诊断"的实现。

4.4 Sealos runtime 服务划分

Sealosframeworks/sandbox/fastgptruntime 仍可能包含两个服务：

codex-gateway：1317
code-server：1318

但它们不是当前 FastGPT Skill 编辑 UI 的首期依赖。当前 Sealos Provider 首期需要保证：

Devbox 可创建、恢复、暂停、删除；
execute可运行 shell 命令；
readFiles、writeFiles、listDirectory、getFileInfo、moveFiles等文件能力满足SandboxEditor；
workingDir正确映射到/home/devbox/workspace，并和 Skill 包解压、保存发布使用同一个 workspace。

从SealosDevboxAdapter源码看，rootPath的取值逻辑正是：优先使用createConfig.workingDir（去除末尾斜杠），缺省回退到/home/devbox/workspace，与 runtime 约定完全一致。文件能力中，writeFiles将文件内容通过 Devboxfiles/upload上传（支持流式 body 与duplex: 'half'），readFiles通过files/download拉取；listDirectory、getFileInfo、moveFiles等操作由基类BaseSandboxAdapter通过CommandFilesystemPolyfill（见sdk/sandbox-adapter/src/polyfills/command-filesystem.ts）在 exec 通道之上合成实现。

5. FastGPT 改造点

5.1 Provider 配置

新增或整理 Sealos 专用配置：

AGENT_SANDBOX_PROVIDER=sealosdevbox AGENT_SANDBOX_SEALOS_BASEURL AGENT_SANDBOX_SEALOS_TOKEN AGENT_SANDBOX_SEALOS_IMAGE # 可选

AGENT_SANDBOX_SEALOS_TOKEN是 Devbox server JWT，namespace 来自 token claims。首期 Sealos Provider 使用全局固定 token 和固定 namespace，所有 FastGPT team/user 的 Devbox 都创建在该 namespace 下，通过upstreamID和 labels 标记归属。

这些环境变量在 FastGPT 服务端有完整的 schema 声明与校验（packages/service/env.ts）：

AGENT_SANDBOX_PROVIDER：z.enum(['sealosdevbox', 'opensandbox'])，为空时不启用沙箱；
AGENT_SANDBOX_SEALOS_BASEURL：Sealos Devbox 服务地址（UrlSchema）；
AGENT_SANDBOX_SEALOS_TOKEN：Sealos Devbox 访问 Token；
AGENT_SANDBOX_SEALOS_WORK_DIRECTORY：默认/home/devbox/workspace；
AGENT_SANDBOX_SEALOS_IMAGE：Sealos Devbox 运行态镜像，启用sealosdevbox时必填（与文档"可选"的表述相比，当前实现要求配置该值才能通过校验，说明该镜像现在由 FastGPT 侧显式注入）。

Provider 配置读取集中在packages/service/core/ai/sandbox/infrastructure/provider/config.ts：getConfiguredSandboxProvider()在AGENT_SANDBOX_PROVIDER缺失时直接抛错；sealosdevbox分支读取AGENT_SANDBOX_SEALOS_BASEURL与AGENT_SANDBOX_SEALOS_TOKEN并执行validateSandboxConfig校验，与 OpenSandbox 分支的AGENT_SANDBOX_OPENSANDBOX_*系列配置完全隔离，印证了"不要复用 OpenSandbox image env"的设计要求。

5.2 Sandbox 创建

FastGPT 上层继续传递统一 create spec：

OpenSandbox 使用现有镜像与 entrypoint 逻辑；
Sealos 只传支持字段：

{ image: sealosImageIfConfigured, env: { CODEX_GATEWAY_CWD: '/home/devbox/workspace', CODEX_GATEWAY_CODEX_HOME: '/codex-home' }, metadata: { sessionId } }

Provider 与 runtime profile 的映射由packages/service/core/ai/sandbox/infrastructure/provider/runtimeProfile统一负责（.agents/design/core/ai/sandbox/index.md明确要求：业务层不能根据 Provider 名称自行拼默认镜像、工作目录、HOME 和环境变量）。其中sealosdevbox.ts的buildSealosRuntimeProfile()以AGENT_SANDBOX_SEALOS_WORK_DIRECTORY || '/home/devbox/workspace'为工作目录、以AGENT_SANDBOX_SEALOS_IMAGE为默认镜像。

5.3 SandboxEditor 文件 API

Skill 编辑页不再嵌入 Provider 页面，前端固定使用SandboxEditor，所有文件操作走 FastGPT API。首期需要保证以下接口在 Sealos Provider 下行为一致：

/api/core/ai/skill/edit：创建或复用 edit-debug sandbox，并把当前版本包解压到 workspace；
/api/core/ai/sandbox/listRecursive：展示 Skill 文件树；
/api/core/ai/sandbox/read//api/core/ai/sandbox/write：读写编辑器内容；
/api/core/ai/sandbox/fileOp：目录和文件的创建、删除、移动、复制、上传；
/api/core/ai/sandbox/download：下载 workspace 文件或目录；
/api/core/ai/skill/save-deploy：从 sandbox workspace 打包 ZIP，上传对象存储并切换当前版本。

在仓库中可确认这些 API 的真实落点：projects/app/src/pages/api/core/ai/skill/save-deploy.ts（Skill 保存发布）、projects/app/src/pages/api/core/ai/sandbox/download.ts（文件/目录下载）、upload.ts（上传）以及checkExist.ts、keepalive.ts、getTicket.ts、verifyTicket.ts、getHtmlPreviewLink.ts等配套接口；Skill 侧还有debugChat.ts、runtime/init.ts、runtime/getStatus.ts、runtime/upgrade.ts、version/*等编辑调试与版本管理接口。整体目录结构符合设计文档中"API 边界负责 parseApiInput 校验、sourceType/sourceId 转换、权限校验与 ticket 签发/验证"的描述。

后续如果要接入code-server或codex-gateway浏览器页面，再新增对应 endpoint/proxy 设计。

6. 集成测试待办与验收闭环

设计文档末尾给出了完整的实施清单，其中已完成项覆盖：

agent-sandbox-adaptor：定义统一SandboxCreateSpecSchema；
agent-sandbox-adaptor：SealosDevbox adapter 支持env/upstreamID/kubeAccess/pauseAt/archiveAfterPauseTime/labels/image；
agent-sandbox-adaptor：保留getEndpoint(port)作为可选端口访问能力；
agent-sandbox-adaptor：SealosDevbox adapter 支持从gateway.url推导 httpgate endpoint；
agent-sandbox-adaptor：OpenSandbox adapter 内收 direct endpoint 解析逻辑；
FastGPT：Skill 编辑页改为SandboxEditor文件 API 链路，不再依赖SandboxIframe；
FastGPT：新增 Sealos runtime 配置，避免复用 OpenSandbox image env；
FastGPT：Sealos provider 不再拒绝所有 create spec，而是只传支持字段；
FastGPT：新增 provider-aware sandbox 文件 API，覆盖文件树、读写、文件操作和下载；
删除旧sandbox-proxy/SandboxIframe依赖路径。

尚未完成的是最后一项（11）：

增加集成测试：创建 Devbox、exec、upload/download、listDirectory、getFileInfo、moveFiles，并通过SandboxEditor相关 API 验证编辑/发布闭环。

从源码结构看，上述 1～10 条已在sdk/sandbox-adapter与 FastGPT 服务端落地（适配器、DevboxClient、runtime profile、SandboxEditor相关 API 均已存在），集成测试是后续补充的验收环节。感兴趣的同学可以在此基础上编写针对 Sealos Devbox 的端到端用例，覆盖"创建 → 就绪探测 → exec → 文件读写 → 打包发布"的完整生命周期。

7. 总结：两条关键边界

回顾整份方案，可以提炼出两条贯穿始终的设计边界：

Provider 抽象边界：FastGPT 只面向ISandbox统一契约编程，OpenSandbox 与 SealosDevbox 的差异（能力声明、字段映射、生命周期语义、就绪探测）全部封装在sdk/sandbox-adapter的适配器内，业务层甚至不接触 Provider 的 API 地址。
编辑器访问边界：浏览器永远只访问 FastGPT 自己的 API，由后端鉴权后通过 adapter 操作远端沙箱文件系统；code-server/codex-gateway的浏览器访问属于可选的未来能力，与当前SandboxEditor文件 API 链路严格隔离。

对 Sealos 场景而言，接入的本质是：把 FastGPT 的 Skill 编辑工作区映射到 Devbox 的/home/devbox/workspace，用upstreamID和 labels 做业务归属，通过pauseAt/archiveAfterPauseTime托管生命周期——其余的 exec、文件、端口访问细节，都由SealosDevboxAdapter与DevboxClient代为处理。

深入阅读：sdk/sandbox-adapter/src/adapters/sealos-devbox/adapter.ts、sdk/sandbox-adapter/src/adapters/sealos-devbox/client.ts、sdk/sandbox-adapter/src/adapters/index.ts、sdk/sandbox-adapter/src/types/sandbox.ts、sdk/sandbox-adapter/src/contracts/sandbox.ts、packages/service/core/ai/sandbox/infrastructure/provider/config.ts、packages/service/core/ai/sandbox/infrastructure/provider/runtimeProfile/sealosdevbox.ts、packages/service/env.ts、.agents/design/core/ai/sandbox/index.md，以及projects/app/src/pages/api/core/ai/skill/save-deploy.ts与projects/app/src/pages/api/core/ai/sandbox/目录下的文件 API。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析