【笔记】开源通用人工智能代理 Suna 部署全流程准备清单（Windows 系统）

#工作记录

一、基础工具与环境

1. 开发工具

   • Git 或 GitHub Desktop（代码管理）
   • Docker Desktop（需启用 WSL2，容器化部署）
   • Python 3.11（推荐版本，需添加到系统环境变量）
   • Node.js LTS（含 npm，前端依赖管理）
   • Poetry（Python 依赖管理，pip install poetry）
   • Visual Studio Build Tools（用于编译 C++ 模块，如canvas）
   • Scoop （用于安装 Supabase CLI ）
   • Supabase CLI  （suna项目重要依赖）

2. 系统依赖

   • GTK + 开发库（Windows 需手动安装，路径C:\GTK\bin需加入系统PATH）
   • libcairo2-dev、libpango1.0-dev等编译依赖（通过 Dockerfile 自动安装）

MSYS2

【笔记】Windows 系统安装 Scoop 包管理工具-CSDN博客 

【笔记】Windows 系统安装 Supabase CLI 完整指南（基于 Scoop）-CSDN博客 

二、账号与密钥（需提前注册）

1. Supabase（数据库与认证）

• 注册账号并创建项目：Supabase Dashboard
• 必选信息：
  • Project URL（如https://gcnijvljsutcxwgcedjz.supabase.co）
  • Anon Key（客户端访问密钥）
  • Service Role Key（服务端管理密钥）
• 可选：数据库密码（若设置需记录）

【笔记】suna部署之获取 Supabase API key 和 project URL -CSDN博客

2. Daytona（代理执行环境）

• 注册账号并生成 API Key：Daytona 密钥管理页面
• 创建镜像配置：
  • 镜像名称：kortix/suna:0.1.2.8
  • 入口点：/usr/bin/supervisord -n -c /etc/supervisor/conf.d/supervisord.conf

【笔记】suna部署之获取 Daytona API key 及 Daytona Sandbox 设置-CSDN博客

【笔记】Suna 部署之 Supabase 数据库 schema 暴露操作-CSDN博客

3. LLM 提供商（至少选一个）

【笔记】Suna 部署之获取 OpenAI API key-CSDN博客

• OpenAI：
  • API Key：OpenAI 密钥管理页面
• OpenRouter（推荐，支持多模型）：
  • API Key：OpenRouter 密钥管理页面
  • 默认模型：openrouter/deepseek/deepseek-chat-v3-0324:free

【笔记】suna部署之获取 OpenRouter API key-CSDN博客

4. 搜索与爬虫服务

【笔记】suna部署之获取 Tavily API key-CSDN博客

• Tavily（网页搜索）：
  • API Key：Tavily 官网
• Firecrawl（网页抓取）：
  • API Key：Firecrawl 官网
  • 自托管选项：若选择n，需使用默认 API 端点https://api.firecrawl.dev

【笔记】suna部署之获取 Firecrawl API key-CSDN博客

5. 可选：第三方 API 服务（如 LinkedIn）

• RapidAPI：
  • 通用 API Key：RapidAPI 官网
  • 用途：激活 LinkedIn 等特定 API 服务

【笔记】Suna 部署之获取 RapidAPI key-CSDN博客

三、配置文件与密钥填充

1. 后端环境文件（backend/.env）

• Supabase 配置：
  • SUPABASE_URL：填入 Supabase 项目 URL
  • SUPABASE_ANON_KEY：填入 Anon Key
  • SUPABASE_SERVICE_ROLE_KEY：填入 Service Role Key
• LLM 配置：
  • OPENAI_API_KEY：OpenAI 密钥（可选）
  • OPENROUTER_API_KEY：OpenRouter 密钥（必填，若启用多模型）
• 第三方服务：
  • RAPID_API_KEY：RapidAPI 密钥（可选）
  • TAVILY_API_KEY：Tavily 密钥（必填）
  • FIRECRAWL_API_KEY：Firecrawl 密钥（必填）
• Daytona 配置：
  • DAYTONA_API_KEY：填入 Daytona API Key
  • DAYTONA_SERVER_URL：默认https://app.daytona.io/api

2. 前端环境文件（frontend/.env.local）

• 公共配置：
  • NEXT_PUBLIC_SUPABASE_URL：同后端SUPABASE_URL
  • NEXT_PUBLIC_SUPABASE_ANON_KEY：同后端SUPABASE_ANON_KEY
  • NEXT_PUBLIC_BACKEND_URL：默认http://localhost:8000/api
  • NEXT_PUBLIC_URL：前端访问地址http://localhost:3000

四、权限与网络准备

1. 文件权限

   确保项目目录（如F:\PythonProjects\suna）对当前用户有完全读写权限，避免EPERM权限错误。

2. 网络优化

   配置国内镜像加速：
   • Docker 镜像加速器（如阿里云）
   • npm 镜像：npm config set registry https://registry.npmmirror.com

3. 端口检查

   确保端口未被占用：
   • Docker 服务：默认端口（如 Redis 6379、RabbitMQ 5672）
   • 后端：8000 端口
   • 前端：3000 端口

五、特殊依赖处理（Windows 专属）

https://gladewin32.sourceforge.net/

1. GTK + 开发库安装

   • 下载地址：GTK for Windows
   • 安装后需将C:\GTK\bin添加到系统环境变量PATH，否则canvas模块编译会报错（缺少.dll文件）。

2. 管理员权限慎用

   • 避免全程使用管理员身份运行终端，仅在必要时（如解决权限错误）以管理员身份执行npm install或scoop命令。

六、验证清单（部署前检查）

项目	状态（是 / 否）	备注
Git 或 GitHub Desktop	✅/❌	代码管理
Docker 运行	✅/❌	任务栏 Docker 图标需显示运行
所有 API 密钥已获取	✅/❌	确保密钥正确，无遗漏（如 Daytona、OpenRouter 等）
.env文件填充完整	✅/❌	检查是否有错别字或格式错误（如密钥前后空格）
GTK 路径加入 PATH	✅/❌	命令行输入echo %PATH%确认包含C:\GTK\bin
系统时区正确	✅/❌	避免因时区问题导致 API 请求过期（如 OpenAI 密钥）

通过以上清单逐项确认，可大幅降低部署过程中因配置缺失或环境问题导致的报错概率。