从零本地跑通 Suna：一套可复刻的调试实践

1 源码下载

首先在Suna的Github仓库上下载源码：

bash 复制代码

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

由于Suna是前后端完全开源的，因此根目录下包含前端工程和后端工程，以及方便小白用户快速启动的脚本文件（该脚本主要是使用docker快速启动容器）等。

由于本文是介绍如何在本地调试Suna项目，因此会详细介绍如何启动前后端工程，忽略一键启动脚本。项目中比较重要的文件目录：

backend：后端工程目录，基于FastAPI构建
frontend：前端工程目录，基于Nextjs构建
docker-compose.yaml：容器文件，我们可以稍微修改该文件，然后以容器的方式启动Suna依赖的redis和rabbitmq，这两个中间件和调试关系不大，通过容器方式启动会更加便捷。

2 redis和rabbitmq容器启动

我们先构建基础环境，Suna依赖redis作为信号通信和中间数据存储媒介；依赖rabbitmq解耦后端接口和agent执行逻辑。因此我们需要先启动这两个容器才能顺利启动后端工程。

启动容器的前提是在本地安装好Docker Desktop，可以参考该文档进行安装。

随后参考如下步骤：

1、打开根目录下的docker-compose.yaml文件，注释backend、worker 、frontend三个服务，这三个服务后续都会在本地启动，因此无需通过docker安装。

yaml 复制代码

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
      - ./backend/services/docker/redis.conf:/usr/local/etc/redis/redis.conf:ro
    command: redis-server /usr/local/etc/redis/redis.conf --save 60 1 --loglevel warning
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

  rabbitmq:
    image: rabbitmq
    ports:
      - "5672:5672"
      - "15672:15672"
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

  # backend:
  #   build:
  #     context: ./backend
  #     dockerfile: Dockerfile
  #   ports:
  #     - "8000:8000"
  #   volumes:
  #     - ./backend/.env:/app/.env:ro
  #   env_file:
  #     - ./backend/.env
  #   environment:
  #     - REDIS_HOST=redis
  #     - REDIS_PORT=6379
  #     - REDIS_PASSWORD=
  #     - REDIS_SSL=False
  #     - RABBITMQ_HOST=rabbitmq
  #     - RABBITMQ_PORT=5672
  #   depends_on:
  #     redis:
  #       condition: service_healthy
  #     rabbitmq:
  #       condition: service_healthy
  #     worker:
  #       condition: service_started

  # worker:
  #   build:
  #     context: ./backend
  #     dockerfile: Dockerfile
  #   command: python -m dramatiq run_agent_background
  #   volumes:
  #     - ./backend/.env:/app/.env:ro
  #   env_file:
  #     - ./backend/.env
  #   environment:
  #     - REDIS_HOST=redis
  #     - REDIS_PORT=6379
  #     - REDIS_PASSWORD=
  #     - REDIS_SSL=False
  #     - RABBITMQ_HOST=rabbitmq
  #     - RABBITMQ_PORT=5672
  #   depends_on:
  #     redis:
  #       condition: service_healthy
  #     rabbitmq:
  #       condition: service_healthy

  # frontend:
  #   init: true
  #   build:
  #     context: ./frontend
  #     dockerfile: Dockerfile
  #   ports:
  #     - "3000:3000"
  #   volumes:
  #     - ./frontend/.env.local:/app/.env.local:ro
  #   environment:
  #     - NODE_ENV=production
  #   command: ["npm", "run", "start"]
  #   depends_on:
  #     - backend

volumes:
  redis_data:
  rabbitmq_data:

2、在terminal中执行如下脚本，拉取并启动镜像。

bash 复制代码

docker compose -f docker-compose.yaml up -d

可以看到，docker正在拉取两个镜像。

随后观察下Docker Desktop，可以看到容器已经成功启动，并且也将对应端口暴露出来。

3 backend启动

3.1 创建python环境

我们首先为Suna创建一个独立环境，这里我使用conda创建。

由于Suna官方文档上写了，支持的python版本≥3.11，因此，我们创建环境的python版本就为3.11。

bash 复制代码

conda create -n suna python=3.11

随后激活该环境。

bash 复制代码

conda activate suna

3.2 安装依赖

进入backend文件夹下，安装对应依赖。

bash 复制代码

pip install -r requirements.txt

3.3 配置环境变量

我们复制一份.env.example，命名为.env。

3.3.1 中间件配置

我们首先将redis和rabbitmq两个配置修正过来。

由于本地启动，我们直接将redis和rabbitmq的host修改为127.0.0.1即可。

ini 复制代码

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_SSL=false

RABBITMQ_HOST=127.0.0.1
RABBITMQ_PORT=5672

3.3.2 大模型配置

由于你懂得原因，这里暂时使用openrouter的api key配置claude模型，保证最终的输出效果。

好在Suna天然支持openrouter，我们的适配工作就大大减少了。

ini 复制代码

OPENROUTER_API_KEY=your api key

3.3.3 联网搜索能力配置

然后我们配置下联网搜索、爬取相关的两个配置，TAVILY和FIRECRAWL的api key，这两个key的申请非常简单，分别在对应官网上注册账号即可每月拥有一定免费额度，用于测试完全没有问题。

tavily：www.tavily.com/
firecrawl：www.firecrawl.dev/

ini 复制代码

TAVILY_API_KEY=your tavily api key

FIRECRAWL_API_KEY=your firecrawl api key
FIRECRAWL_URL=https://api.firecrawl.dev

3.3.4 数据库supabase配置与迁移

然后配置supabase，这里算是里面比较复杂的了，其复杂点不仅在于几个配置，并且后续的数据库迁移还稍微有些麻烦，咱们一步步来。

首先，我们去supabase官网注册一个账号，并跟随教程创建一个项目。

supabase官网：supabase.com/
supabase教程：supabase.com/docs/

随后，我们能在Project Settings→Data API处，找到Project URL，这个就是我们需要的SUPABASE_URL配置。

然后，在Project Settings→API Keys处，我们可以找到anon和service_role对应的api key，也就是我们需要的SUPABASE_ANON_KEY和SUPABASE_SERVICE_ROLE_KEY

至此，我们找到了所有需要的supabase配置。

ini 复制代码

SUPABASE_URL=your supabase url
SUPABASE_ANON_KEY=your anon key
SUPABASE_SERVICE_ROLE_KEY=your service role key

之后，我们需要进行数据库的迁移。

执行下面的命令安装supabase cli。

bash 复制代码

brew install supabase/tap/supabase

登录supabase账号，执行下面命令后，跟随指导，按下enter键跳转chrome获取授权码，在终端中输入授权码即可正常登录。

bash 复制代码

supabase login

执行如下命令链接你的远程项目，也就是你在supabase saas服务上的项目，跟随指引选择你需要的项目即可。初始化项目应该只有一个。

选择项目后会让你输入密码，

bash 复制代码

supabase link

最后执行如下命令进行数据库迁移，Suna已经为我们准备好了所有迁移文件，我们进需要简单执行下面的命令即可。然后输入Y确定迁移。

bash 复制代码

supabase db push

至此，你的数据库也配置并迁移完成。

3.3.5 Daytona配置

我们在Daytona官网上创建一个账号即可获取对应的api key，免费账号足够我们测试使用了。

DAYTONA_SERVER_URL和DAYTONA_TARGET直接使用Daytona文档上提供的case即可。

ini 复制代码

DAYTONA_API_KEY=your api key
DAYTONA_SERVER_URL=https://app.daytona.io/api
DAYTONA_TARGET=us

然后我们需要在Daytona的image页面上配置Suna所需的镜像，我们依次点击Images→Create Image，然后分别输入name和entrypoint。

name：kortix/suna:0.1.2.8

entrypoint：/usr/bin/supervisord -n -c /etc/supervisor/conf.d/supervisord.conf

注意，不同版本代码的name一般来说不同，我们可以在创建镜像的时候查看代码中主要使用的是哪个name，代码文件一般在config.py文件下。

3.4 修改启动host

在api.py文件中，我们修改下后端服务的启动host，便于在本地调试。将0.0.0.0修改为127.0.0.1即可。

python 复制代码

if __name__ == "__main__":
    import uvicorn
    
    if sys.platform == "win32":
        asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
    
    workers = 1
    
    logger.info(f"Starting server on 0.0.0.0:8000 with {workers} workers")
    uvicorn.run(
        "api:app", 
        host="127.0.0.1", # 0.0.0.0 -> 127.0.0.1
        port=8000,
        workers=workers,
        loop="asyncio"
    )

3.5 小结

完成以上步骤后，理论上就可以启动后端服务了。

在浏览器中输入127.0.0.1:8000/api/health，如果能够正常返回说明服务启动正常。

4 worker启动

只要backend能够顺利启动，worker的启动非常容易，因为需要的配置已经准备齐全了。

worker的启动方式，我们可以参考backend目录下的docker-compose.yml文件，启动命令藏在了docker运行脚本中。

因此，我们执行下面的命令就可以顺利启动worker了。

bash 复制代码

python -m dramatiq --processes 4 --threads 4 run_agent_background

我们能够在控制台中看到如下的命令，就可以证明worker服务正常启动。

5 frontend启动

首先，我们从根目录进入到frontend目录，安装前端工程所需要的依赖。

执行以下命令：

bash 复制代码

pnpm install

复制.env.example文件为.env文件，在其中，我们填入必要的配置。

我们这里不做Google OAuth登录，因此，NEXT_PUBLIC_GOOGLE_CLIENT_ID设置为空即可。

ini 复制代码

NEXT_PUBLIC_ENV_MODE="LOCAL" #production, or staging
NEXT_PUBLIC_SUPABASE_URL=your supabase url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your supabase anon key
NEXT_PUBLIC_BACKEND_URL="http://127.0.0.1:8000/api"
NEXT_PUBLIC_URL="http://127.0.0.1:3000"
NEXT_PUBLIC_GOOGLE_CLIENT_ID=""
OPENAI_API_KEY=""

环境变量设置完毕后，执行以下命令启动前端。

bash 复制代码

pnpm dev

6 登录注册

以上工程全部启动后，我们登录http://127.0.0.1:3000，可以看到如下页面。

说明全部工程正常启动了。

我们依次点击Signup→Create new account按钮注册账号。

注册账号后，会发送一个邮件到你的邮箱，你把邮箱中的激活链接复制到浏览器访问，然后就可以快乐使用Suna啦！

7 总结

上面带领大家部署了容器和前后端工程，其实整个过程也没那么复杂，只是Suna将这些步骤全部封装在了docker文件中。

后面想要本地调试开源项目也是这样，如果仅仅是测试效果，那么通过docker快速部署是非常方便的方式，能够让我们快速体验项目。但是，想要进一步深入了解项目，那必然需要本地调试，此时我们首先应该研究开源项目的docker文档，看看启动步骤是如何执行的，一步步拆解后就可以得到完整的部署路径了。

通过以上的步骤，Suna的启动基本就没什么问题了，如果还有问题，请联系我，我来手把手带你部署完成。