Suna是一个功能强大的开源AI助手，能够帮助你完成各种实际任务。本文将详细介绍Suna的完整安装过程，包括环境准备、配置依赖服务、故障排除等内容，确保你能顺利运行这个强大的AI工具。
1. 前期准备
在开始安装前，需要确保系统已安装以下必要工具：
必备工具
- Git：用于克隆代码仓库
- Docker & Docker Compose：用于容器化运行各种服务
- Python 3.11+：运行设置脚本
- Poetry：Python依赖管理工具
- Node.js & npm：前端依赖
检查工具是否已安装
# 检查Git版本
git --version
# 检查Docker版本
docker --version
docker compose version
# 检查Python版本
python3 --version
# 检查Poetry版本
poetry --version
# 检查Node.js和npm版本
node --version
npm --version
确保Docker服务正在运行：
# 检查Docker是否运行
docker info
2. 获取Suna代码
首先，从GitHub克隆Suna的代码仓库：
# 克隆仓库
git clone https://github.com/kortix-ai/suna.git
# 进入项目目录
cd suna
3. 运行安装向导
Suna提供了一个设置向导，可以引导你完成整个安装过程：
# 运行设置向导
python3 setup.py
这个向导会检查系统要求，收集必要的API密钥，并设置所有需要的服务。
4. 设置向导详解
4.1 检查系统要求
向导首先会检查所有必要的工具是否已安装，确保Docker正在运行，并验证是否在Suna仓库根目录下。
4.2 设置Supabase
Supabase是Suna使用的数据库和认证服务。设置步骤：
- 访问Supabase Dashboard创建一个新项目
- 获取以下信息：
- Supabase项目URL（格式如：
https://abcdefg.supabase.co） - Supabase匿名密钥（anon key）
- Supabase服务角色密钥（service role key）
- Supabase项目URL（格式如：
这些信息可以在Supabase项目设置的"API"部分找到。
在向导中输入这些信息后，会自动设置数据库连接。
4.3 设置Daytona（用于安全的代码执行环境）
Daytona提供安全的代码执行环境：
- 创建Daytona账户
- 在"Keys"菜单生成API密钥
- 在"Images"菜单创建镜像：
- 镜像名：
kortix/suna:0.1.2.8 - 入口点：
/usr/bin/supervisord -n -c /etc/supervisor/conf.d/supervisord.conf
- 镜像名：
在向导中输入Daytona API密钥。
4.4 设置LLM API密钥
Suna支持多种LLM提供商。选择并配置至少一个：
可以根据需要配置多个提供商，并设置默认使用的模型。
4.5 设置搜索和网络抓取功能
配置搜索和网络抓取工具：
4.6 配置RapidAPI（可选）
如需使用LinkedIn等API服务，可以配置RapidAPI密钥。
4.7 设置Supabase架构
向导会自动连接到Supabase并设置必要的数据库架构。这个过程包括：
- 使用Supabase CLI登录
- 将项目链接到Supabase
- 推送数据库迁移
注意：需要在Supabase控制台手动添加"basejump"模式到暴露的架构列表中。
5. 启动Suna
安装完成后，可以选择如何启动Suna：
# 使用Docker Compose启动（推荐）
docker compose up -d
# 或者使用start.py脚本
python start.py
启动后，可以通过访问http://localhost:3000使用Suna。
6. Docker容器和服务解析
Suna使用多个Docker容器协同工作：
6.1 核心服务
- frontend：Next.js前端界面，端口3000
- backend：FastAPI后端服务，端口8000
- worker：后台任务处理器，使用Dramatiq
- redis：用于缓存和消息传递，端口6379
- rabbitmq：消息队列，端口5672
6.2 Firecrawl服务
Firecrawl是一个网页抓取工具，由以下容器组成：
- firecrawl-api：API服务，端口3002
- firecrawl-worker：处理抓取任务的worker
- firecrawl-redis：Redis实例用于Firecrawl
- firecrawl-playwright-service：浏览器自动化服务
6.3 Docker命令参考
# 查看所有容器状态
docker compose ps
# 查看容器日志
docker compose logs
docker compose logs backend
docker compose logs worker
# 停止所有服务
docker compose down
# 单独停止特定容器
docker stop firecrawl-api-1 firecrawl-worker-1
# 重新启动单个服务
docker compose restart backend
# 查看资源使用情况
docker stats
7. 环境配置文件解析
Suna使用多个环境配置文件存储设置：
7.1 后端配置 (backend/.env)
关键配置项包括：
- Supabase连接信息
- Redis和RabbitMQ设置
- LLM API密钥和模型选择
- 搜索和网络抓取API密钥
- Daytona配置
7.2 前端配置 (frontend/.env.local)
关键配置项包括：
- Supabase连接信息
- 后端API URL
- 环境模式设置
8. 故障排除
8.1 常见问题与解决方案
Supabase连接问题
错误信息：The schema must be one of the following: public, graphql_public
解决方案：在Supabase控制台的Project Settings → API → Exposed Schema中添加"basejump"模式。
Daytona积分问题
错误信息：Failed to create sandbox: Organization is suspended: Depleted credits
解决方案：在Daytona控制台中确认账户状态，确保有足够的积分。
LLM API连接问题
错误信息：httpx.ConnectError或Connection closed by server
解决方案：
-
检查API密钥是否正确
-
在中国使用时，可能需要配置代理：
# 在backend/.env中添加 HTTP_PROXY=http://你的代理地址:端口 HTTPS_PROXY=http://你的代理地址:端口 -
尝试切换不同的LLM提供商
Docker服务启动问题
如果某些容器无法启动：
# 检查容器日志
docker compose logs [服务名]
# 重建容器
docker compose down
docker compose up --build -d
9. 使用Firecrawl
Firecrawl是一个强大的网页抓取工具，可以单独使用：
# 使用curl发送抓取请求
curl -X POST http://localhost:3002/api/crawl \
-H "Content-Type: application/json" \
-H "x-api-key: 你的Firecrawl密钥" \
-d '{"url": "https://example.com", "selector": "body"}'
# Python示例
import requests
api_key = "你的Firecrawl密钥"
base_url = "http://localhost:3002"
response = requests.post(
f"{base_url}/api/crawl",
headers={"Content-Type": "application/json", "x-api-key": api_key},
json={"url": "https://example.com"}
)
print(response.json())
10. 关闭和清理
正确关闭Suna和相关服务：
# 停止Suna服务
docker compose down
# 停止Firecrawl服务
docker stop firecrawl-api-1 firecrawl-worker-1 firecrawl-redis-1 firecrawl-playwright-service-1
# 移除所有停止的容器
docker container prune
避免直接关闭Docker程序，这可能导致数据不一致或损坏。
总结
安装Suna需要一系列步骤，但setup.py向导大大简化了这个过程。按照本指南操作，你应该能够成功安装和运行Suna，享受这个强大AI助手的所有功能。
记住，当遇到问题时，检查日志是解决问题的最佳起点。此外，确保所有必需的API密钥都是有效的，特别是在中国使用时，可能需要额外的网络配置。