Suna 源码解读

a111776

99人浏览 · 2026-07-19 11:35:42

a111776 · 2026-07-19 11:35:42 发布

Suna 源码解读

项目地址：https://github.com/kortix-ai/suna

Suna 是 Kortix AI 开源的"开源版 Manus"——一个端到端的通用型 Agent 平台，能够自主完成数据分析、网页爬取、报告生成、办公自动化等复杂任务。本文从产品形态、源码结构、技术架构、适用场景四个维度做一次完整拆解，重点剖析其 Sandbox 隔离、Redis 流式总线、Supabase 数据中心三大设计。

1. 产品形态及效果

1.1 形态上很像 Manus

Suna 的产品形态可以直接对标 Manus：

对话式任务下发：用户用自然语言描述任务，Suna 自主规划、执行、产出结果

多模态产出：可以输出文本报告、Excel、图表、网页截图，甚至直接操作浏览器

完整的 Agent 工具集：内置浏览器自动化、代码执行、文件系统、API 调用、数据库查询等十余类工具

1.2 实际体验：很慢（外网中间件 + 任务多）

公开 Demo 的体验比单轮 LLM 慢一个数量级，原因有两层：

任务复杂度：一个"调研 + 生成报告"任务往往要 20~80 次 LLM 调用 + 多次工具调用，串行执行天然就慢。

依赖外网中间件：Suna 的 Sandbox 跑在 Daytona 云沙箱上，浏览器自动化用 Browserbase，对象存储用 Supabase Cloud，国内访问这些海外服务有额外延迟。

工程启示：自部署时要把这些海外中间件换成国内/自建服务（如 Daytona → 自建 Docker、Supabase → 自建 Postgres + MinIO），否则生产体验上不去。

2. 源码结构与部署流程

2.1 代码结构
suna/
├── backend/           # 后端服务（Python / FastAPI）
│   ├── agents/        # Agent 主循环、Prompt、工具集
│   │   └── tools/     # 浏览器、代码、文件、API 等工具实现
│   ├── api/           # FastAPI 路由
│   └── ...
├── frontend/          # 前端应用（Next.js / React / TailwindCSS）
├── docs/              # 文档与架构图
├── README.md
└── docker-compose.yml # 一键起 Supabase + Redis + 后端 + 前端
2.2 部署流程（自托管）
git clone https://github.com/kortix-ai/suna
cd suna
cp .env.example .env   # 填 OpenAI / Supabase / Redis / Daytona 密钥
docker compose up -d    # 起所有服务
需要的核心外部依赖：

LLM API：OpenAI / Anthropic（或用 LiteLLM 接国内模型）

Supabase：用作认证、Postgres、对象存储（可自建）

Redis：流式响应缓冲（必须）

Daytona：代码沙箱（可换成自建 Docker）

2.3 源码要点

后端 API：FastAPI 实现，负责业务逻辑、Agent 调度、与 LLM/Supabase/Redis/Daytona 等服务集成。所有 Agent 执行都从这里的 /agent/execute 端点发起。

前端：Next.js 实现，提供聊天界面、仪表盘、文件管理、浏览器远程查看等交互能力，通过 SSE/WS 订阅后端流式推送。

Agent Docker / Daytona：每个智能体都跑在独立的容器中，支持浏览器自动化、代码解释、文件系统访问。这是 Suna 区别于"普通 Agent 框架"的核心。

Supabase：负责用户认证（GoTrue）、数据存储（Postgres）、会话管理、文件存储（S3 兼容）、行为分析（analytics）。

3. 技术架构

3.1 整体架构图
┌────────────┐     ┌─────────────┐     ┌────────────────┐
│  Frontend  │◄───►│  Backend    │◄───►│   LLM API      │
│ (Next.js)  │ SSE │ (FastAPI)   │     │ (OpenAI/Claude)│
└────────────┘     └─────┬───────┘     └────────────────┘
                         │
            ┌────────────┼────────────┬──────────────┐
            │            │            │              │
            ▼            ▼            ▼              ▼
       ┌─────────┐  ┌─────────┐  ┌─────────┐   ┌─────────┐
       │  Redis  │  │Supabase │  │ Daytona │   │ Browser │
       │ (Stream)│  │(Data/Auth)│ (Sandbox)│   │base/CDP │
       └─────────┘  └─────────┘  └─────────┘   └─────────┘
3.2 技术特点

Suna 的设计有几个值得深挖的点：

3.2.1 Sandbox（Daytona 容器隔离）

每个 Agent 任务都会拉起一个独立的 Docker 容器（通过 Daytona SDK 调度），实现：

Agent 之间的隔离：A 任务的代码不会污染 B 任务，文件系统、环境变量完全隔离

效果的稳定：浏览器自动化、依赖安装都在沙箱内，宿主机不被污染

资源限额：单任务 CPU/内存/网络可限制，避免恶意任务拖垮宿主

安全：用户提交的代码、Prompt 注入诱导执行的代码，都跑在沙箱里，攻击面被收窄
# 简化的沙箱启动流程（伪代码）
from daytona_sdk import Daytona

daytona = Daytona()
sandbox = daytona.create()              # 起一个隔离容器
sandbox.exec("pip install pandas")     # 在沙箱里装包
result = sandbox.exec("python analysis.py")  # 在沙箱里执行
daytona.remove(sandbox)                 # 任务结束销毁
生产建议：Daytona 是商业云服务，自部署可以替换成自建 Docker host（docker-in-docker 或 Kubernetes Job），核心是把"Agent 执行环境"和"主服务"做物理隔离。

3.2.2 Redis 作为流式响应缓冲

这是 Suna 最值得借鉴的设计——LLM 流式输出不直接推给前端，而是先写 Redis Stream，前端再从 Redis 读。
# 写入端（推理进程）
for chunk in llm.stream(messages):
    redis.xadd(f"agent_run:{run_id}", {"token": chunk})

# 读取端（推送进程 / SSE 端点）
last_id = request_last_id or "0"
while True:
    entries = redis.xread({f"agent_run:{run_id}": last_id}, block=1000)
    for entry in entries:
        yield entry.token
        last_id = entry.id
3.2.3 Supabase 作为数据中心

Supabase 在 Suna 里"一身多职"，对个人开发者特别友好（一个服务搞定认证 + 数据库 + 存储）：

GoTrue：邮箱/OAuth 登录

Postgres：用户、会话、消息、Agent run、文件元数据

Storage：上传的文档、Agent 产出物（报告、Excel、截图）

Realtime：可选的实时订阅

取舍：Supabase Cloud 免费档对个人项目够用，但企业生产建议自建 Postgres + MinIO，避免 vendor lock-in。

4. Redis 作为流式响应与推送中间件的利弊分析

这一节单独展开，因为这个设计是 Suna 区别于"直接用 OpenAI SDK 流式"的关键，也是企业级 Agent 必然会遇到的架构决策。

4.1 优点

4.1.1 解耦模型推理与前端消费

推理和前端消费完全解耦，支持异步、分布式运行，前端可随时连接 / 断开 / 重连流式接口。

支持多前端 / 多客户端同时订阅同一个 agent_run 的流式输出（手机 + 网页同步看到一份回复）。

4.1.2 容错与重连能力

前端断线、刷新、网络抖动时可重新连接，Redis 保留历史响应，前端不会丢失消息。

支持"断点续传"：前端只需记录上次消费的 index（Stream ID），重连后从该 ID 续读。

4.1.3 多实例 / 分布式支持

多个后端实例可通过 Redis 共享流式数据，天然支持横向扩展和高可用。

推理进程和推送进程可分布在不同机器 / 容器——推理跑在 GPU 机器，推送跑在普通 Web 机器。

4.1.4 统一流式通道

不管底层用什么大模型（OpenAI / Claude / 本地模型），都可统一用 Redis 作为流式"总线"，前端实现不变。

便于后续接入多种模型、工具型响应（如代码执行进度、浏览器操作日志）、混合流式输出等复杂场景。

4.1.5 支持中断、控制信号

通过 Redis 控制通道灵活中断推理、通知前端，增强交互体验。例如用户点"停止"，后端读到一个 cancel 标志就 break 出流式循环。

4.1.6 历史数据可追溯

Redis 保留所有响应，便于后续查询、调试、回放、分析。一个 agent_run 的全流程可以完整重放。

4.2 缺点

4.2.1 增加系统复杂度

需维护 Redis 服务，涉及连接、订阅、消息管理等，开发和运维成本提升。

需处理 Redis 的持久化、容量、过期策略等问题（Stream 默认不裁剪，要配 MAXLEN）。

4.2.2 引入延迟

每条流式响应先写入 Redis，再由 stream 接口读出推送前端，比直接转发多一步，增加微小延迟（通常在毫秒级，可忽略）。

4.2.3 内存消耗

Redis 作为内存数据库，所有流式响应暂存于内存。长文本 / 高并发 / 大批量推理时，内存压力大。

缓解策略：XADD ... MAXLEN ~ 10000 控制单 stream 长度；冷数据落 Postgres。

4.2.4 一致性与幂等性处理

需保证消息不会重复推送、不会丢失，断点续传场景下消息索引和消费状态管理更复杂。

推荐：Stream 自带的消费组（Consumer Group）+ ACK 机制。

4.2.5 对流式模型原生特性利用有限

某些大模型流式接口有特殊"中间 token 事件"、速率控制、心跳等特性，经过 Redis 中转后可能无法 100% 还原原生体验（如 Claude 的 message_delta 中的 stop_reason）。

5. 适用场景（直接使用或二次开发）

5.1 何时选 Suna

适合在以下场景直接使用或基于源码二次开发：

安全要求高：每个智能体之间不会互相干扰（Sandbox 隔离到位）

并发要求高：Redis + 多实例架构很容易做分布式扩展

需要本地优先 + 数据自主：开源，可完全自托管，数据不出企业

5.2 适合的业务场景

5.2.1 智能信息检索与数据分析

市场 / 竞品分析：自动收集、整理和分析行业、竞品信息，生成报告。

舆情监控与分析：抓取论坛、社交媒体、新闻等公开数据，聚类、总结用户反馈和市场动态。

科学文献 / 专利 / 政策检索：自动查找、对比、总结学术论文、专利、政策文件等。

5.2.2 自动化办公与文档处理

报告自动生成：根据输入需求自动生成市场、财务、技术等各类报告。

表格 / 文档自动处理：批量生成、整理、分析 Excel、Word、PDF 等文件。

邮件 / 通知自动撰写与发送：根据业务流程自动生成并发送邮件、通知等。

5.2.3 数据抓取与集成

网站 / 平台数据抓取：自动化爬取公开网站、API 数据，支持多平台集成。

API 聚合与自动化调用：集成第三方 API（如 LinkedIn、Amazon、金融数据等），实现自动化业务流程。

5.2.4 智能助手与对话系统

企业内部智能助手：为员工提供知识问答、流程自动化、数据查询等服务。

客户支持机器人：自动应答客户问题、收集需求、分发工单等。

5.2.5 研发与创新

AI 工具链集成：作为 AI 研发的底座，集成多种 LLM、自动化工具，快速搭建原型。

定制化智能体开发：根据行业需求开发专属智能体，扩展工具集和业务逻辑。

5.3 二次开发建议

5.3.1 模块化扩展

利用 backend/agent/tools/ 目录，可以方便地开发和集成新的工具（如自定义爬虫、API 调用、数据处理等）。

前后端分离，便于替换 UI 或对接自有系统。

5.3.2 安全与合规

生产环境建议加强沙箱隔离、权限控制和日志审计，防止数据泄露和越权操作。

敏感数据存储和传输建议加密，遵循相关法规（如 GDPR、个保法）。

5.3.3 多租户与权限管理

如果面向多企业 / 多团队，建议扩展用户、角色、权限体系，支持多租户隔离。Supabase 的 RLS（Row-Level Security）天然支持多租户。

5.3.4 高可用与扩展性

后端可容器化部署，结合云服务（如 Supabase、Redis 云服务）实现弹性扩展。

前端可独立部署，支持自定义品牌和界面。

5.3.5 LLM / 工具适配

可根据业务需求切换或集成不同的 LLM（如私有大模型、本地模型等）。推荐用 LiteLLM 做模型层抽象。

工具层支持快速适配新业务场景。

5.3.6 自动化与流程编排

可结合工作流引擎（如 Temporal、Prefect）实现更复杂的自动化任务编排和多步操作，补足 Suna 偏"自由 Agent"而弱"强一致工作流"的短板。

6. 一句话总结

Suna 是一个工程完成度很高的开源通用 Agent 平台。它的工程价值在于三个抽象：Sandbox（隔离执行）、Redis Stream（解耦流式）、Supabase（一体化数据）。二次开发时，把这三块换成自建基础设施，就能落地为企业级生产系统。