Suna 自托管指南（Self-Hosting Guide）

本指南将为你提供详细步骤，帮助你部署和托管自己的 Suna 实例。Suna 是一个开源通用型 AI Agent（智能代理）。

概览

Suna 由以下五个核心组件组成：

1. Backend API - 基于 Python/FastAPI 的服务，负责 REST 接口、线程管理和 LLM 集成
2. Backend Worker - 基于 Python/Dramatiq 的工作服务，处理 Agent 的任务
3. Frontend - 基于 Next.js/React 的应用程序，提供用户界面
4. Agent Docker - 为每个 Agent 提供隔离的执行环境
5. Supabase Database - 用于数据持久化和身份认证

前提条件

在开始安装之前，请确保你具备以下条件：

1. 创建 Supabase 项目

1. 在 Supabase 注册账户
2. 创建一个新项目

3. 记录以下信息（在 Project Settings → API 中可以找到）：

   • 项目 URL（例如：https://abcdefg.supabase.co）
   • API Key（包括 anon key 和 service role key）

2. 获取 API Key

你需要准备以下 API Key：

必需项

• LLM 提供商（以下任意一个）：

  • Anthropic（推荐，性能最佳）
  • OpenAI
  • Groq
  • OpenRouter
  • AWS Bedrock

• 搜索与网页爬取功能：

  • Tavily - 提供增强搜索能力
  • Firecrawl - 提供网页爬虫能力

• Agent 执行环境：

  • Daytona - 提供安全隔离的代理执行

可选项

• RapidAPI - 用于访问其他第三方 API 服务（可选）

3. 安装必要软件

请在本地系统中安装以下工具：

• Git
• Docker
• Python 3.11
• Poetry
• Node.js 和 npm
• Supabase CLI

安装步骤

1. 克隆项目仓库

git clone https://github.com/kortix-ai/suna.git
cd suna

2. 运行安装向导

安装向导将引导你完成安装：

python setup.py

该向导会：

• 检查所有必要工具是否已安装
• 收集你的 API Key 和配置信息
• 初始化 Supabase 数据库
• 配置环境变量文件
• 安装依赖项
• 使用你选择的方式启动 Suna

3. Supabase 配置步骤

在安装过程中，你需要：

1. 登录 Supabase CLI
2. 将本地项目链接到你的 Supabase 项目
3. 推送数据库迁移（Migration）

4. 手动公开名为 basejump 的数据库 Schema：

   • 登录 Supabase 控制台
   • 进入 Project Settings → API
   • 将 basejump 添加到 Exposed Schemas 中

4. Daytona 配置

你还需要：

1. 注册 Daytona 账号
2. 生成一个 API Key

3. 创建一个 Docker 镜像：

   • 镜像名：kortix/suna:0.1.3
   • 启动命令：/usr/bin/supervisord -n -c /etc/supervisor/conf.d/supervisord.conf

手动配置

如果你更喜欢手动配置安装过程，或者需要在安装后进行调整，请参考以下说明：

后端环境配置（backend/.env）

示例配置：

ENV_MODE=local
# 数据库配置
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
# Redis 配置
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_SSL=false
# RabbitMQ 配置
RABBITMQ_HOST=rabbitmq
RABBITMQ_PORT=5672
# LLM 提供商
ANTHROPIC_API_KEY=your-anthropic-key
OPENAI_API_KEY=your-openai-key
MODEL_TO_USE=anthropic/claude-3-7-sonnet-latest
# 搜索 API
TAVILY_API_KEY=your-tavily-key
# 网页爬虫
FIRECRAWL_API_KEY=your-firecrawl-key
FIRECRAWL_URL=https://api.firecrawl.dev
# 安全容器运行平台
DAYTONA_API_KEY=your-daytona-key
DAYTONA_SERVER_URL=https://app.daytona.io/api
DAYTONA_TARGET=us
NEXT_PUBLIC_URL=http://localhost:3000

前端环境配置（frontend/.env.local）

示例配置：

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
NEXT_PUBLIC_BACKEND_URL=http://backend:8000/api
NEXT_PUBLIC_URL=http://localhost:3000

安装完成后的步骤

完成安装后，请执行以下操作：

1. 创建账户：使用 Supabase 认证注册你的第一个用户账号
2. 验证服务是否正常运行：确保所有组件均已启动并运行无误

启动方式

Suna 提供两种启动方式：

1. 使用 Docker Compose（推荐）

该方式会自动启动所有服务：

docker compose up -d # 使用 `docker compose down` 可关闭服务
# 或者
python start.py # 再次运行也可关闭服务

2. 手动启动方式

如果你希望手动启动每个组件：

1. 启动 Redis 和 RabbitMQ：

docker compose up redis rabbitmq -d

1. 启动前端服务（打开一个终端）：

cd frontend
npm run dev

1. 启动后端服务（打开另一个终端）：

cd backend
poetry run python3.11 api.py

1. 启动后台 Worker（再打开一个终端）：

cd backend
poetry run python3.11 -m dramatiq run_agent_background

故障排查（Troubleshooting）

常见问题

1. Docker 服务无法启动

   • 查看日志：docker compose logs
   • 确保 Docker 正常运行
   • 检查端口是否被占用（默认：3000 前端，8000 后端）

2. 数据库连接失败

   • 检查 Supabase 配置是否正确
   • 确保已公开 basejump schema

3. LLM API Key 无效

   • 检查是否正确输入 Key
   • 查看是否达到 API 使用限制或配置有误

4. Daytona 连接失败

   • 检查 Daytona API Key 是否有效
   • 检查容器镜像是否配置正确

查看日志

# 查看 Docker Compose 日志
docker compose logs -f
# 前端日志（手动模式）
cd frontend
npm run dev
# 后端日志（手动模式）
cd backend
poetry run python3.11 api.py
# Worker 日志（手动模式）
cd backend
poetry run python3.11 -m dramatiq run_agent_background

如需更多帮助，请加入 Suna Discord 社区 或访问 GitHub 仓库 查看最新更新与问题反馈。