【笔记】Windows 部署 Suna 开源项目完整流程记录
#工作记录
因篇幅有限，所有涉及处理步骤的详细处理办法请参考文末资料。
Microsoft Windows [Version 10.0.27868.1000]
(c) Microsoft Corporation. All rights reserved.(suna-py3.12) F:\PythonProjects\suna>python setup.py '--admin'███████╗██╗ ██╗███╗ ██╗ █████╗ ██╔════╝██║ ██║████╗ ██║██╔══██╗ ███████╗██║ ██║██╔██╗ ██║███████║ ╚════██║██║ ██║██║╚██╗██║██╔══██║ ███████║╚██████╔╝██║ ╚████║██║ ██║ ╚══════╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝ ✅ Frontend dependencies installed successfully
ℹ️ Locking dependencies...
Resolving dependencies... (0.5s)
ℹ️ Installing backend dependencies...
Installing dependencies from lock file No dependencies to install or updateInstalling the current project: suna (1.0)
✅ Backend dependencies installed successfully
ℹ️ Configuring environment files...
✅ Backend .env file created at backend\.env
ℹ️ Redis host is set to: redis
ℹ️ RabbitMQ host is set to: rabbitmq
✅ Frontend .env.local file created at frontend\.env.local
ℹ️ Backend URL is set to: http://localhost:8000/api Step 8/8: Starting Suna
================================================== ℹ️ You can start Suna using either Docker Compose or by manually starting the frontend, backend and worker. How would you like to start Suna?
[1] Docker Compose (recommended, starts all services)
[2] Manual startup (requires Redis, RabbitMQ & separate terminals) Enter your choice (1 or 2): 1
ℹ️ Starting Suna with Docker Compose...
ℹ️ Building images locally...
Compose can now delegate builds to bake for better performance.To do so, set COMPOSE_BAKE=true.
[+] Building 10.5s (34/34) FINISHED docker:desktop-linux=> [worker internal] load build definition from Dockerfile 0.0s=> => transferring dockerfile: 1.63kB 0.0s=> [backend internal] load metadata for docker.io/library/python:3.11-slim 2.5s=> [worker internal] load .dockerignore 0.0s=> => transferring context: 2B 0.0s=> [backend 1/7] FROM docker.io/library/python:3.11-slim@sha256:dbf1de478a55d6763afaa39c2f3d7b54b25230614980276de5cacdde79529d0c 0.1s=> => resolve docker.io/library/python:3.11-slim@sha256:dbf1de478a55d6763afaa39c2f3d7b54b25230614980276de5cacdde79529d0c 0.0s=> [worker internal] load build context 0.0s=> => transferring context: 187.28kB 0.0s=> CACHED [backend 2/7] WORKDIR /app 0.0s=> CACHED [backend 3/7] RUN apt-get update && apt-get install -y --no-install-recommends build-essential curl && rm -rf /var/lib/apt/lists/* 0.0s=> CACHED [backend 4/7] RUN useradd -m -u 1000 appuser && mkdir -p /app/logs && chown -R appuser:appuser /app 0.0s=> CACHED [worker 5/7] COPY --chown=appuser:appuser requirements.txt . 0.0s=> CACHED [worker 6/7] RUN pip install --no-cache-dir -r requirements.txt gunicorn 0.0s=> [worker 7/7] COPY --chown=appuser:appuser . . 0.7s=> [worker] exporting to image 0.5s=> => exporting layers 0.4s=> => exporting manifest sha256:d9b6c17294047f07bb3a7e2b174ba2c2eb174c53cfea4253df6514361a6db334 0.0s=> => exporting config sha256:b254b4129b88069e8201377f394f11f1f13f21b085de694c5a77517910223861 0.0s=> => exporting attestation manifest sha256:3823f42a102cd1bcec424bc9971003a2d80f073059d24b09850dcf72f3d11ed0 0.0s=> => exporting manifest list sha256:9531931264c1c67231df692039fc44c3f37094fec0de1eef368eec051cd32373 0.0s=> => naming to docker.io/library/suna-worker:latest 0.0s=> => unpacking to docker.io/library/suna-worker:latest 0.1s=> [worker] resolving provenance for metadata file 0.0s=> [backend internal] load build definition from Dockerfile 0.0s=> => transferring dockerfile: 1.63kB 0.0s=> [backend internal] load .dockerignore 0.0s=> => transferring context: 2B 0.0s=> [backend internal] load build context 0.0s=> => transferring context: 6.62kB 0.0s=> CACHED [backend 5/7] COPY --chown=appuser:appuser requirements.txt . 0.0s => CACHED [backend 6/7] RUN pip install --no-cache-dir -r requirements.txt gunicorn 0.0s => CACHED [backend 7/7] COPY --chown=appuser:appuser . . 0.0s => [backend] exporting to image 0.1s => => exporting layers 0.0s => => exporting manifest sha256:5fe27f6d1d8c4e63625ebe4b78e988dfd12361b8258b9d8064490f5e3e033d12 0.0s => => exporting config sha256:9ca094178096fcf2f6a187a89eb9d9e6a649fec7ca9e781ed10d749529ca1d7a 0.0s => => exporting attestation manifest sha256:bcac63c630326a71d5547675d0e5ad0dc93f340ad86781584eb880d1daaaf80d 0.0s => => exporting manifest list sha256:58b8227874b53347b04287572bdcbb5de60b178aa5510fedc8884de9d7ccaf31 0.0s => => naming to docker.io/library/suna-backend:latest 0.0s => => unpacking to docker.io/library/suna-backend:latest 0.0s=> [backend] resolving provenance for metadata file 0.0s => [frontend internal] load build definition from Dockerfile 0.0s=> => transferring dockerfile: 704B 0.0s => [frontend internal] load metadata for docker.io/library/node:20-slim 1.7s => [frontend internal] load .dockerignore 0.0s=> => transferring context: 2B 0.0s => [frontend 1/7] FROM docker.io/library/node:20-slim@sha256:cb4abfbba7dfaa78e21ddf2a72a592e5f9ed36ccf98bdc8ad3ff945673d288c2 0.0s => => resolve docker.io/library/node:20-slim@sha256:cb4abfbba7dfaa78e21ddf2a72a592e5f9ed36ccf98bdc8ad3ff945673d288c2 0.0s => [frontend internal] load build context 3.9s => => transferring context: 8.59MB 3.3s=> CACHED [frontend 2/7] WORKDIR /app 0.0s=> CACHED [frontend 3/7] COPY package*.json ./ 0.0s => CACHED [frontend 4/7] RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ build-essential pkg-config libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev && rm -rf /var/lib/apt/lists/* 0.0s => CACHED [frontend 5/7] RUN npm install 0.0s => CACHED [frontend 6/7] COPY . . 0.0s => CACHED [frontend 7/7] RUN npm run build 0.0s => [frontend] exporting to image 0.1s => => exporting layers 0.0s => => exporting manifest sha256:a2a4131242a031513ee69366ae6adc990bcbdf9d21a9671a34a0006ea1c8d200 0.0s => => exporting config sha256:cd7a82e5c0b88d79886c9ae6aad313f07dfeece206cf440b4faf0ccdf613f3f8 0.0s=> => exporting attestation manifest sha256:f27596cd4ba3822772062dda30909cb13f05cc169a17fec132d81f3b0cd71e02 0.0s => => exporting manifest list sha256:2f0d2557c3fd7cfa47f9964f77c5677c414a6efd81834d2af5b9641976819116 0.0s => => naming to docker.io/library/suna-frontend:latest 0.0s => => unpacking to docker.io/library/suna-frontend:latest 0.0s => [frontend] resolving provenance for metadata file 0.0s
[+] Running 8/8✔ backend Built 0.0s ✔ frontend Built 0.0s ✔ worker Built 0.0s ✔ Container suna-redis-1 Healthy 12.3s ✔ Container suna-rabbitmq-1 Healthy 12.3s ✔ Container suna-worker-1 Started 11.8s ✔ Container suna-backend-1 Started 13.1s ✔ Container suna-frontend-1 Started 13.7s
ℹ️ Waiting for services to start...
⚠️ Some services might not be running correctly. Check 'docker compose ps' for details.✨ Suna Setup Complete! ✨ℹ️ Suna is configured to use openrouter/deepseek/deepseek-chat-v3-0324:free as the default LLM model
ℹ️ Your Suna instance is now running!
ℹ️ Access it at: http://localhost:3000
ℹ️ Create an account using Supabase authentication to start using SunaUseful Docker commands:docker compose ps - Check the status of Suna servicesdocker compose logs - View logs from all servicesdocker compose logs -f - Follow logs from all servicesdocker compose down - Stop Suna servicesdocker compose up -d - Start Suna services (after they've been stopped)一、前置工具安装（必须提前完成）
1. 安装 Supabase CLI（核心依赖）
- 作用：用于连接和管理 Supabase 数据库，Suna 必须依赖此工具完成数据库迁移。
- Windows 安装方法：
- 通过 Scoop（推荐）：
scoop install supabase-cli
- 验证安装：
supabase --version # 应输出版本号（如 2.53.0）
2. 安装 Docker Desktop（服务容器化必需）
- 步骤：
- 下载 Docker Desktop for Windows, 启用 WSL 2 后端（需先安装 WSL 2）。
- 启动 Docker，确保状态为
Running。
- 避坑点：
- 若启动失败，检查 Windows 功能中是否启用 Hyper-V 和 Containers。
- 首次启动可能需要几分钟初始化，确保内存分配 ≥4GB。
二、项目克隆与环境准备
1. 克隆 Suna 代码（在虚拟环境前操作）
- 命令：
git clone https://github.com/your-username/suna.git
cd suna
- 避坑点：
- 路径避免中文或特殊符号（如
F:\PythonProjects\suna而非F:\项目\suna）。 - 若克隆速度慢，使用国内镜像：
- 路径避免中文或特殊符号（如
git clone https://gitee.com/mirrors/suna.git # 替换为 Gitee 镜像
2. 创建 Python 虚拟环境（推荐 Poetry）
- 基于 MSYS2 的 Poetry 环境：
# 激活 MSYS2 MinGW64 终端
poetry config virtualenvs.in-project true
poetry new suna-env # 可选，初始化项目
poetry shell # 激活虚拟环境（前缀显示 `(suna-env)`）
- 验证环境：
python --version # 确保为 3.11+（如 3.12.0）
避坑点：若用系统默认 Python，需通过 poetry env use <路径> 指定 MSYS2 的 Python（如 C:/msys64/mingw64/bin/python3.12.exe）。
三、配置与启动 Suna（核心流程）
1. 运行安装向导
-
命令：
python setup.py --admin
-
分步说明：
Step 1: 检查依赖
Step 2: 配置 Supabase
Step 3: 配置 Daytona
Step 4: 配置 LLM 提供商（OpenAI/OpenRouter 等）
Step 5: 配置搜索与爬取工具（Tavily/Firecrawl）
Step 6: 配置 RapidAPI（可选）
Step 7: 链接 Supabase 项目
Step 8: 选择启动方式
- 确保输出中所有工具（
git,docker,poetry等）状态为✅，若某项缺失，按提示安装。 - 常见缺失处理：
node/npm缺失：通过 Node.js 官网 安装 LTS 版本。docker 未运行：启动 Docker Desktop 并等待状态变为Running。
- 获取信息：
- 登录 Supabase 控制台，创建新项目。
- 在 Project Settings > API 中获取：
- Project URL（格式如
https://xxx.supabase.co） - Anon Key 和 Service Role Key（在
Keys部分）。
- Project URL（格式如
- 输入注意事项：
- 确保 URL 无多余空格或符号，Key 直接复制粘贴避免手动输入错误。
- 操作步骤：
- 注册 Daytona 账号，生成 API Key。
- 在 Images 页面创建镜像：
- 名称：
kortix/suna:0.1.2.8 - 入口命令：
/usr/bin/supervisord -n -c /etc/supervisor/conf.d/supervisord.conf
- 名称：
- 避坑点：Daytona API Key 需在 Keys 页面生成，非登录 Token。
- 多提供商选择：
输入1,3表示同时配置 OpenAI 和 OpenRouter，按提示分别输入 API Key。 - 模型选择：
- OpenAI 推荐
gpt-4o（输入1），OpenRouter 可选免费模型（如deepseek-chat-v3-0324:free，输入2）。
- OpenAI 推荐
- 获取 Key：
- Tavily Key：注册 Tavily 账号 后在控制台获取。
- Firecrawl Key：若使用官方服务，注册 Firecrawl 后获取；若自建，输入
y并配置自建 URL。
- 用于 LinkedIn 等第三方 API，若无需求直接按
Enter跳过。 - 登录验证：
输入supabase login后会生成浏览器登录链接，若未自动打开，手动复制链接完成验证。 - 数据库密码：
若无需密码直接按Enter，否则输入数据库密码（通常为空）。 - 暴露 Schema：
按提示在 Supabase 控制台 Project Settings > API 中，将basejump添加到 Exposed Schema。 - 推荐 Docker Compose（选项 1）：
自动构建并启动所有服务，适合新手。 - 手动启动（选项 2）：
需分别启动 Redis、RabbitMQ、Backend、Frontend，适合调试。
- 确保输出中所有工具（
四、启动后验证与常见问题
1. 检查服务状态
- 命令：
docker compose ps # 查看容器状态
- 正常状态：
suna-backend-1、suna-frontend-1、suna-worker-1等容器状态为running。
- 异常处理：
- 若某容器
restarting，查看日志：
- 若某容器
docker compose logs <容器名> # 如 docker compose logs suna-backend-1
2. 访问 Web 界面
- 地址：
http://localhost:3000 - 登录方式：
使用 Supabase 认证（如邮箱注册），首次登录需验证邮箱。
3. 典型错误与解决方案
| 错误场景 | 解决方案 |
|---|---|
Docker build 失败，缺少 gcc | 通过 MSYS2 安装 GCC：pacman -S mingw-w64-x86_64-gcc |
Supabase CLI 登录失败，验证码无效 | 确保浏览器窗口未拦截登录页面，或手动输入链接中的验证码 |
前端页面白屏，控制台报错 404 | 检查 Docker 容器是否全部启动，尝试重启服务：docker compose down && up |
LLM 调用失败，提示 API key 无效 | 重新核对 OpenAI/OpenRouter Key，确保未过期或权限不足 |
五、避坑总结（按阶段分类）
1. 环境准备阶段
- 必装工具优先级：先装 Supabase CLI 和 Docker，再处理 Python 环境，避免路径冲突。
- 虚拟环境路径：项目路径建议英文且层级简洁（如
F:\suna），避免 Poetry 识别失败。
2. 配置阶段
- Key 管理：使用文本编辑器（如 Notepad++）集中保存所有 API Key，避免复制错误。
- Supabase Schema 暴露：此步骤常被忽略，若遗漏会导致后端无法写入数据库，需严格按提示操作。
3. 启动阶段
- Docker 资源分配：在 Docker Desktop 设置中，确保内存 ≥4GB、CPU ≥2 核，避免构建时因资源不足失败。
- 网络代理：若公司网络有代理，需在 Docker 和命令行中配置代理（如
set HTTP_PROXY=http://proxy:8080）。
六、参考资料
Windows 部署 AI Agent - Suna 专栏合集（包含问题处理）
通过以上流程，可系统性完成 Suna 在 Windows 的部署，结合专栏中的具体问题排查案例，能有效避开环境兼容、依赖缺失、配置错误等核心坑点。
