企业官网建设流程全解析

Flue Cloudflare沙盒实战：零冷启动的Agent云端执行完整指南

【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue

Flue是一个用 TypeScript 构建自主 AI Agent 的沙盒框架，而将它部署到Cloudflare后，Agent 可以在 Workers 边缘网络上获得"零冷启动"级别的执行体验：会话状态由 Durable Object + SQLite 持久化，虚拟沙盒毫秒级启动，甚至可以通过 Workers AI 绑定完全免 API Key 运行。本文将带你完整走一遍 Flue 在 Cloudflare 上的沙盒选型、接入步骤与生产级技巧。

为什么 Flue Agent 适合跑在 Cloudflare 上

大多数团队把 Agent 部署到传统服务器时，会撞上三堵墙：

• 冷启动慢：容器拉起需要数秒，高峰期排队更糟
• 状态易丢：进程崩溃后，Agent 的对话进度和沙盒文件全部蒸发
• 密钥难管：API Token 只能以环境变量注入容器，Agent（以及 LLM 本身）直接可见

Flue 的 Cloudflare 目标是平台原生集成，而非常规 Node 适配器：构建时flue()Vite 插件会扫描你的'use agent'模块，为每个 Agent 生成一个 Durable Object 类，会话流以追加只写方式落盘在 Durable Object SQLite 中。这意味着：

三级沙盒策略：从虚拟到容器

Cloudflare 上 Flue 的沙盒能力分为三层，按需升级即可，起步成本几乎为零：

第一级：虚拟沙盒（默认，最快最省）

只写useModel(...)的 Agent 默认运行在内存虚拟沙盒上（由 just-bash 驱动的 JS Shell）：内置bash、grep、glob、read、write、edit全套工具，毫秒级启动、无容器、无费用。适合高并发的"提示-应答"型 Agent，比如翻译、客服分流。

第二级：Cloudflare Computer 持久工作区

需要"文件要留下来"时用@cloudflare/computer的Workspace：一个 SQLite 支持的持久虚拟文件系统，就住在 Agent 自己的 Durable Object 里，容量约 10 GB，文件状态可跨越 Durable Object 重启存活。Shell 命令通过 Worker Loader 在 Dynamic Worker 中执行，同样无容器、无冷启动等待。

⚠️ 注意：它是 JS 壳环境而非完整 Linux——grep/find可用，但原生二进制和npm不行。需要语言工具链时升级到第三级。

第三级：Cloudflare Sandbox 容器沙盒

当 Agent 需要 git、Node.js、Python、浏览器等完整 Linux 环境，接入@cloudflare/sandbox：每个会话获得独立容器，带持久文件系统与完整 Linux 用户态，镜像由你自己的Dockerfile定义。缓存镜像后启动也只需数秒，是编码类 Agent 的正确选择。

一句话决策法：先虚拟，再持久，最后容器——绝大多数 Agent 停留在前两级就够了。

最快配置方法：三步接入沙盒

以容器沙盒为例，Flue 提供蓝图机制，一条命令生成全部样板代码（完整可运行示例见 examples/cloudflare/）：

1️⃣ 运行蓝图

flue add sandbox cloudflare

2️⃣ 确认 Wrangler 配置（蓝图会自动追加绑定与迁移，你只需检查）：

{ "compatibility_flags": ["nodejs_compat"], "durable_objects": { "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }] }, "migrations": [{ "tag": "v2", "new_sqlite_classes": ["Sandbox"] }], "containers": [{ "class_name": "Sandbox", "image": "./Dockerfile" }] }

3️⃣ 在 Agent 函数中挂载沙盒——整个接线就是一行useSandbox：

'use agent'; import { env } from 'cloudflare:workers'; import { useModel, useSandbox } from '@flue/runtime'; import { cloudflareSandbox } from '@flue/runtime/cloudflare'; import { getSandbox } from '@cloudflare/sandbox'; export function CodingAgent({ id }: AgentProps) { useModel('anthropic/claude-opus-4-7'); useSandbox(cloudflareSandbox(getSandbox(env.Sandbox, id))); return 'You have a full Linux sandbox. Use it to complete the task.'; }

本地vite dev用 workerd 起服务，vite build && wrangler deploy一条链路部署上线。Agent 的完整挂载路由见示例项目的 src/app.ts，持久工作区适配器的完整实现可研读 examples/cloudflare/src/sandboxes/cloudflare-computer.ts。

零冷启动背后的三个关键设计

🚀 执行模型：Flue 在 Cloudflare 上复用了官方 Agents SDK 的 Durable Object 基类，请求直接落在已就绪的 DO 实例上；虚拟沙盒没有"启动容器"这一步，动态 Worker 随取随用。

💾 确定性恢复：部署更新若打断正在执行的 DO，Flue 采用保守重放规则——只在能证明"提供商工作未发生"时才重试，否则在会话历史中记录一条可见的中断提示，绝不盲目重复模型调用。这对生产环境是巨大的安心。

🔐 免 Key 与零信任出口：

• 通过Workers AI 绑定路由模型流量（cloudflare/...模型标识符），全程无需任何提供商 API Key
• 容器需要调用外部 API 时，用outbound Workers出口代理：Token 在代理层注入，容器内永远看不到密钥——零信任模型，且代理与容器同机，延迟可忽略

资源导航：从文档到源码

📚官方文档

• Cloudflare 部署总指南：apps/docs/src/content/docs/ecosystem/deploy/cloudflare.md
• 容器沙盒（@cloudflare/sandbox）：apps/docs/src/content/docs/ecosystem/sandboxes/cloudflare.md
• 持久工作区（@cloudflare/computer）：apps/docs/src/content/docs/ecosystem/sandboxes/cloudflare-computer.md
• 沙盒概念总览：apps/docs/src/content/docs/guide/sandboxes.md

📦核心源码

• Cloudflare 运行时集成（沙盒工厂、Workers AI 提供器、DO 协调器）：packages/runtime/src/cloudflare/
• 端到端示例（Workers AI 绑定、R2 技能、Git 工作区）：examples/cloudflare/src/agents/
• 沙盒蓝图模板（flue add sandbox生成物）：blueprints/sandbox--cloudflare.md、blueprints/sandbox--cloudflare-computer.md

总结

Flue 把"Agent 上云"最棘手的三件事——冷启动、状态持久化、密钥安全——分别交给了 Cloudflare 的 Durable Object、SQLite 存储和出口代理来原生解决。虚拟沙盒起步免费且毫秒级响应，容器沙盒按需升级，配合蓝图一条命令完成接入。如果你的 Agent 正在为冷启动和崩溃恢复头疼，Flue + Cloudflare 值得成为你的第一个验证目标。

【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue