Cloudflare 目标
Cloudflare 目标允许你将 Flue 智能体部署到 Cloudflare Workers。每个智能体成为一个 Durable Object，提供持久对话状态、持久执行和内置的可扩展性。本指南涵盖 Cloudflare 架构、配置、部署、以及高级功能如容器沙盒和 Workers AI。
Cloudflare 架构
在 Cloudflare 上，每个智能体是一个 Durable Object：
- 持久状态。 对话历史和智能体状态存储在 Durable Object 的 SQLite 存储中。
- 持久执行。 智能体在 Durable Object 内部运行，确保工作在中断后继续。
- 可扩展性。 每个对话是一个独立的 Durable Object，水平扩展。
- 全球分布。 Workers 在 Cloudflare 的全球网络上运行，接近你的用户。
Flue 为每个智能体生成一个 Durable Object 类，处理状态管理、工具执行和对话持久性。
配置 Cloudflare 目标
在 flue.config.ts 中配置 Cloudflare 目标：
import { defineConfig } from '@flue/runtime';
export default defineConfig({
target: 'cloudflare',
// Cloudflare 特定选项
cloudflare: {
// 启用容器沙盒
sandbox: true,
// 启用 Workers AI
workersAi: true,
},
});项目结构
Cloudflare 项目有特定的结构：
src/
├── agents/ # 智能体模块
│ └── support.ts
├── cloudflare.ts # Cloudflare 特定代码
├── app.ts # 路由配置
└── index.ts # 入口点
wrangler.jsonc # Cloudflare 配置
flue.config.ts # Flue 配置Durable Objects
每个智能体成为一个 Durable Object 类。Flue 自动生成这些类：
// 生成的代码（你不需要编写）
export class FlueSupportAgent extends DurableObject {
// Durable Object 实现
}在 wrangler.jsonc 中声明 Durable Object 绑定和迁移：
{
"name": "my-flue-worker",
"main": "src/index.ts",
"compatibility_date": "2024-01-01",
"compatibility_flags": ["nodejs_compat"],
"migrations": [
{
"tag": "v1",
"new_sqlite_classes": ["FlueSupportAgent"],
},
],
}部署到 Cloudflare
使用 Flue CLI 部署：
# 构建并部署
flue deploy
# 或者使用 wrangler
pnpm run build
wrangler deployFlue 处理：
- 生成 Durable Object 类
- 生成 Worker 入口点
- 合并配置
- 打包依赖
持久性
Cloudflare 目标提供完整的持久性：
对话历史。 存储在 Durable Object 的 SQLite 存储中。对话在中断和重启后继续。
智能体状态。 usePersistentState() 状态持久化在 SQLite 中。
文件。 沙盒文件可以通过 Cloudflare R2 或容器存储持久化。
本地开发
使用 vite dev 在本地运行 Cloudflare Worker：
vite dev这启动一个开发服务器，使用 workerd（Cloudflare 的运行时）模拟 Cloudflare 环境。
高级功能
容器沙盒
Cloudflare Sandbox 提供容器支持的 Linux 环境：
import { getSandbox } from '@cloudflare/sandbox';
import { env } from 'cloudflare:workers';
import { cloudflareSandbox } from '@flue/runtime/cloudflare';
export function Assistant({ id }: AgentProps) {
useSandbox(cloudflareSandbox(getSandbox(env.Sandbox, id)), { cwd: '/workspace' });
}Workers AI
Workers AI 在 Cloudflare 基础设施上运行 AI 模型：
export function Assistant() {
useModel('cloudflare/@cf/moonshotai/kimi-k2.6');
}无需 API 密钥。授权和计费遵循 Worker 账户。
AI Gateway
Flue 默认为所有 cloudflare/... 模型启用 AI Gateway，提供缓存、请求日志记录和速率限制。
Cloudflare Computer
Cloudflare Computer 提供持久的、基于 SQLite 的工作空间：
import { getComputerSandbox } from '../sandboxes/cloudflare-computer';
export function Assistant({ id }: AgentProps) {
useSandbox(getComputerSandbox(env.Computer, id), { cwd: '/workspace' });
}扩展智能体
使用 extend() 扩展点添加自定义 Cloudflare 功能：
import { extend } from '@flue/runtime/cloudflare';
export const cloudflare = extend({
base: (Base) =>
class extends Base {
async onStart() {
await this.scheduleEvery(60, 'heartbeat');
}
async heartbeat() {
this.setState({ ...this.state, lastHeartbeatAt: Date.now() });
}
},
});可观测性
Flue 提供 Cloudflare 原生的可观测性：
Workers 日志。 查看实时日志和错误。
Workers 跟踪。 跟踪智能体执行、模型调用和工具使用。
自定义跟踪。 使用 createCloudflareTracing() 进行详细的智能体级跟踪。
服务绑定
通过服务绑定从其他 Worker 调用智能体：
import { createFlueClient } from '@flue/sdk';
const client = createFlueClient({
url: 'https://agent.internal/agents/support',
fetch: (input, init) => env.AGENT_APP.fetch(new Request(input, init)),
});限制和注意事项
CPU 限制。 每个调用 30 秒主动 CPU。对于计算密集型智能体，增加 limits.cpu_ms。
内存限制。 Durable Object 内存限制。使用外部存储存储大文件。
冷启动。 Durable Object 在不活动后可能休眠。第一次调用可能较慢。
定价。 Durable Object 请求和存储单独计费。