kortix-ai/suna at v1

一、最新版本号 V1

二、部署截图

本地开发环境仍然依赖于 Poetry 环境：

（Python>=3.11,<3.13）

创建本地 Poetry 虚拟环境

Python 多版本环境治理理念驱动的系统架构设计：三维治理、四级隔离、五项自治原则-CSDN博客

【终极实战】Conda/Poetry/Virtualenv/Pipenv/Hatch 多工具协同 + Anaconda×PyCharm：构建 Python 全版本栈隔离体系与虚拟环境自动化管理指南-CSDN博客

使用命令行创建项目本地的 Poetry 虚拟环境实战演示 —— 基于《Python 多版本与开发环境治理架构设计》的最佳实践-CSDN博客

# 1、交互式生成项目配置文件pyproject.toml
"D:\ProgramData\anaconda3\envs\python311\Scripts\poetry.exe" init# 2、强制使用 Conda Python 版本环境中的Python 3.11创建虚拟环境
poetry env use "D:\ProgramData\anaconda3\envs\python311\python.exe"# 3、激活Windows系统下的本地虚拟环境
.venv\Scripts\activate# 4、在虚拟环境中安装Poetry，实现工具链本地化
pip install poetry# 5、在虚拟环境中验证工具链的本地化
python -V
where python
poetry -V
where poetry

开始部署

python setup.py '--admin'

三、完整日志记录

Docker 构建改用UV 加速：

Microsoft Windows [Version 10.0.27891.1000]
(c) Microsoft Corporation. All rights reserved.(suna-py3.11) F:\PythonProjects\suna>python setup.py '--admin'███████╗██╗   ██╗███╗   ██╗ █████╗ ██╔════╝██║   ██║████╗  ██║██╔══██╗███████╗██║   ██║██╔██╗ ██║███████║╚════██║██║   ██║██║╚██╗██║██╔══██║███████║╚██████╔╝██║ ╚████║██║  ██║╚══════╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝Installation WizardThis wizard will guide you through setting up Suna, an open-source generalist AI agent.ℹ️  Current configuration status:✓ Supabase✓ Daytona✓ LLM (Openrouter)✓ Search APIs✓ RapidAPI (optional)✓ Smithery (optional)✓ QStash & Webhooks✓ MCP encryption keyStep 14/14: Starting Suna
==================================================ℹ️  Starting Suna with Docker Compose...
[+] Running 19/19✔ rabbitmq Pulled                                                                                                                 9.6s ✔ c11385cfddca Pull complete                                                                                                    1.2s ✔ b08e2ff4391e Pull complete                                                                                                    3.1s ✔ df65927f37a8 Pull complete                                                                                                    1.2s ✔ 7a50da602dc1 Pull complete                                                                                                    4.4s ✔ 649069e80308 Pull complete                                                                                                    1.2s ✔ e07387d31093 Pull complete                                                                                                    1.2s ✔ c5443e20a68a Pull complete                                                                                                    4.2s ✔ 10bc06b492f2 Pull complete                                                                                                    4.1s ✔ 0d4a02cfe928 Pull complete                                                                                                    1.1s ✔ redis Pulled                                                                                                                    8.6s ✔ 01864c5b87b0 Pull complete                                                                                                    0.9s ✔ 01e29ec495fd Pull complete                                                                                                    2.8s ✔ f18232174bc9 Pull complete                                                                                                    2.6s ✔ 4f4fb700ef54 Pull complete                                                                                                    0.0s ✔ 38910b7e0e43 Pull complete                                                                                                    1.1s ✔ 8ea5afed640f Pull complete                                                                                                    2.7s ✔ 10753f8102ef Pull complete                                                                                                    1.2s ✔ 0ef5583b6c0f Pull complete                                                                                                    2.1s 
[+] Building 2262.6s (28/28) FINISHED                                                                                                   => [internal] load local bake definitions                                                                                         0.0s=> => reading from stdin 1.09kB                                                                                                   0.0s=> [worker internal] load build definition from Dockerfile                                                                        0.1s=> => transferring dockerfile: 1.12kB                                                                                             0.0s=> [frontend internal] load build definition from Dockerfile                                                                      0.1s=> => transferring dockerfile: 704B                                                                                               0.0s=> [worker internal] load metadata for ghcr.io/astral-sh/uv:python3.11-alpine                                                     3.8s=> [frontend internal] load metadata for docker.io/library/node:20-slim                                                           5.8s=> [backend internal] load .dockerignore                                                                                          0.0s=> => transferring context: 1.48kB                                                                                                0.0s=> [worker stage-0 1/6] FROM ghcr.io/astral-sh/uv:python3.11-alpine@sha256:03f28e0c1ffc6dd8061a4e79c890bfd0441fb9ec1d648ce8ad5  196.5s=> => resolve ghcr.io/astral-sh/uv:python3.11-alpine@sha256:03f28e0c1ffc6dd8061a4e79c890bfd0441fb9ec1d648ce8ad5abfcaaa68789a      0.0s=> => sha256:87ce2dd1364746255f7cd8c3e234b9fc0d3b2f9d43c3598b13f1a961b33771fd 18.86MB / 18.86MB                                 196.2s => => sha256:001a982bd46375c72e605501ad0cc9e18d462f1a1acceab0ffb36efd6ac311b7 249B / 249B                                         1.8s=> => sha256:7f6e5b96bd814093e9e436fd11f5b83f83280688d0290f87954800b3a89196dd 16.23MB / 16.23MB                                  69.3s => => sha256:6760217c9b2110cfef8eec91415fd408ce564ab368e483924d4cb963e37b31cf 460.22kB / 460.22kB                                29.9s => => sha256:fe07684b16b82247c3539ed86a65ff37a76138ec25d380bd80c869a1a4c73236 3.80MB / 3.80MB                                   118.5s=> => extracting sha256:fe07684b16b82247c3539ed86a65ff37a76138ec25d380bd80c869a1a4c73236                                          0.1s => => extracting sha256:6760217c9b2110cfef8eec91415fd408ce564ab368e483924d4cb963e37b31cf                                          0.1s => => extracting sha256:7f6e5b96bd814093e9e436fd11f5b83f83280688d0290f87954800b3a89196dd                                          0.2s=> => extracting sha256:001a982bd46375c72e605501ad0cc9e18d462f1a1acceab0ffb36efd6ac311b7                                          0.0s=> => extracting sha256:87ce2dd1364746255f7cd8c3e234b9fc0d3b2f9d43c3598b13f1a961b33771fd                                          0.1s => [backend internal] load build context                                                                                          0.1s => => transferring context: 2.93MB                                                                                                0.0s=> [frontend internal] load .dockerignore                                                                                         0.0s=> => transferring context: 2B                                                                                                    0.0s=> [frontend 1/7] FROM docker.io/library/node:20-slim@sha256:83a6968f0aff91f162545cd20692787e650918fd761ab5ef4d40b542ec173ca9     6.5s=> => resolve docker.io/library/node:20-slim@sha256:83a6968f0aff91f162545cd20692787e650918fd761ab5ef4d40b542ec173ca9              0.0s=> => sha256:85252198c2faa1d5f1439ad7eae0720f6d9f5e8e6b11e0322d755a67b435d830 447B / 447B                                         0.5s => => sha256:3037dc438bf729105c6e7d59e05191f99b1a32d6ffa572306440f21cb88fcf91 1.71MB / 1.71MB                                     2.1s => => sha256:a3d69bb7d021f8e22f909046fab555624f243288ee8b39cd545639fc9b7d8728 41.20MB / 41.20MB                                   5.8s => => sha256:9cb87e66cf8010a0b027072a0c884f6664180c81e625515e93f5e22cd04fec17 3.31kB / 3.31kB                                     1.0s => => sha256:3da95a905ed546f99c4564407923a681757d89651a388ec3f1f5e9bf5ed0b39d 28.23MB / 28.23MB                                   3.0s => => extracting sha256:3da95a905ed546f99c4564407923a681757d89651a388ec3f1f5e9bf5ed0b39d                                          0.3s => => extracting sha256:9cb87e66cf8010a0b027072a0c884f6664180c81e625515e93f5e22cd04fec17                                          0.0s => => extracting sha256:a3d69bb7d021f8e22f909046fab555624f243288ee8b39cd545639fc9b7d8728                                          0.4s => => extracting sha256:3037dc438bf729105c6e7d59e05191f99b1a32d6ffa572306440f21cb88fcf91                                          0.0s=> => extracting sha256:85252198c2faa1d5f1439ad7eae0720f6d9f5e8e6b11e0322d755a67b435d830                                          0.0s => [frontend internal] load build context                                                                                         0.3s=> => transferring context: 16.19MB                                                                                               0.2s=> [frontend 2/7] WORKDIR /app                                                                                                    0.2s=> [frontend 3/7] COPY package*.json ./                                                                                           0.1s=> [frontend 4/7] RUN apt-get update && apt-get install -y --no-install-recommends     python3     make     g++     build-ess  2076.6s=> [worker stage-0 2/6] WORKDIR /app                                                                                              0.0s=> [backend stage-0 3/6] RUN apk add --no-cache curl                                                                            326.2s=> [worker stage-0 4/6] COPY pyproject.toml uv.lock ./                                                                            0.1s=> [worker stage-0 5/6] RUN --mount=type=cache,target=/root/.cache/uv uv sync --locked --quiet                                 1420.8s=> [backend stage-0 6/6] COPY . .                                                                                                 0.2s=> [backend] exporting to image                                                                                                   8.9s=> => exporting layers                                                                                                            6.5s=> => exporting manifest sha256:66001f690cfcc66059740db76b71eed36166e7869aabcaa9dc4656ddc9079a9c                                  0.7s => => exporting config sha256:b08465c2a23e98966285d8f8ffb7ba6e8804e0103d4eb721f0ee48f713b8e96b                                    0.0s=> => exporting attestation manifest sha256:344b5ebfb0e11e6b06f6307a7b9e68c30ea7747eb844c7abf56bd41b636d14dd                      0.0s => => exporting manifest list sha256:541e1052e04d9d33a8f3257e4676d497aade554fd43585c4b93728bbc4170a66                             0.0s => => naming to ghcr.io/suna-ai/suna-backend:latest                                                                               0.0s => => unpacking to ghcr.io/suna-ai/suna-backend:latest                                                                            1.6s => [worker] exporting to image                                                                                                    8.9s => => exporting layers                                                                                                            6.5s=> => exporting manifest sha256:66001f690cfcc66059740db76b71eed36166e7869aabcaa9dc4656ddc9079a9c                                  0.7s=> => exporting config sha256:b08465c2a23e98966285d8f8ffb7ba6e8804e0103d4eb721f0ee48f713b8e96b                                    0.0s => => exporting attestation manifest sha256:79d4e29650072d5751cfe0565e43488867efb17976e6cb9ea38135a07451caaa                      0.0s=> => exporting manifest list sha256:b31ed693161932d5936e8b4ac30ec944212974f0b37108d687438658c2293dce                             0.0s=> => naming to ghcr.io/suna-ai/suna-backend:latest                                                                               0.0s => => unpacking to ghcr.io/suna-ai/suna-backend:latest                                                                            1.7s=> [backend] resolving provenance for metadata file                                                                               0.0s => [worker] resolving provenance for metadata file                                                                                0.0s => [frontend 5/7] RUN npm install                                                                                                59.2s => [frontend 6/7] COPY . .                                                                                                        0.5s => [frontend 7/7] RUN npm run build                                                                                              78.7s => [frontend] exporting to image                                                                                                 33.9s => => exporting layers                                                                                                           22.9s => => exporting manifest sha256:3c382f95cefe6a787760dfd5280bb1ee3e47f805568a816fefc1f348797f9586                                  0.0s => => exporting config sha256:fffb75079dede2a1892c7b513fb3f69e682e3718c29f6e3c60a7cd868d55ca04                                    0.0s => => exporting attestation manifest sha256:b6c6903ae11636e6fc127751e8a34b5119b53237d5d7498aa753361f396135d2                      0.0s => => exporting manifest list sha256:30f16fde7a1839a6b92741317ad21c603d8fd3a22d9bdc2e1a6fcf8526ab6599                             0.0s => => naming to docker.io/library/suna-frontend:latest                                                                            0.0s => => unpacking to docker.io/library/suna-frontend:latest                                                                        10.9s => [frontend] resolving provenance for metadata file                                                                              0.0s 
[+] Running 11/11                                                                                                                       ✔ worker                       Built                                                                                              0.0s ✔ backend                      Built                                                                                              0.0s ✔ frontend                     Built                                                                                              0.0s ✔ Network suna_default         Created                                                                                            0.4s ✔ Volume "suna_rabbitmq_data"  Created                                                                                            0.0s ✔ Volume "suna_redis_data"     Created                                                                                            0.0s ✔ Container suna-redis-1       Healthy                                                                                           14.3s ✔ Container suna-rabbitmq-1    Healthy                                                                                           14.3s ✔ Container suna-worker-1      Started                                                                                           12.6s ✔ Container suna-backend-1     Started                                                                                           13.9s ✔ Container suna-frontend-1    Started                                                                                           14.7s 
ℹ️  Waiting for services to spin up...
✅  Suna services are starting up!✨ Suna Setup Complete! ✨ℹ️  Suna is configured to use openrouter/google/gemini-flash-1.5 as the default LLM.
ℹ️  Delete the .setup_progress file to reset the setup.
ℹ️  Your Suna instance is ready to use!Useful Docker commands:docker compose ps         - Check service statusdocker compose logs -f    - Follow logsdocker compose down       - Stop Suna servicespython start.py           - To start or stop Suna servicesOnce all services are running, access Suna at: http://localhost:3000(suna-py3.11) F:\PythonProjects\suna>

使用示例

四、新旧版部署区别

新旧版 SUNA 部署流程核心区别对比

（一）部署架构：从 “本地环境依赖” 到 “容器化微服务”

维度	旧版部署流程	新版部署流程
核心架构	依赖 Windows 本地环境，组件（后端、前端、图形库）直接运行在宿主系统，通过本地路径和环境变量关联	基于 Docker 容器化微服务架构，拆分为独立容器：`backend`（后端）、`frontend`（前端）、`worker`（任务处理）及支撑服务（`redis` 缓存、`rabbitmq` 消息队列），通过 Docker 网络通信
环境隔离性	依赖本地环境配置（如 Conda 虚拟环境、MSYS2 路径），组件间依赖易冲突	容器间完全隔离，数据通过 Docker Volume（`rabbitmq_data`、`redis_data`）持久化，避免宿主环境干扰
跨平台兼容性	强依赖 Windows 系统工具（如 MSYS2 GTK、NSSM 服务），移植性差	基于 Docker 镜像，理论上可在支持 Docker 的任何系统（Windows/macOS/Linux）部署，兼容性显著提升

（二）依赖管理工具链：从 Poetry 到 uv 的效率升级

维度	旧版部署流程	新版部署流程
核心工具	依赖 `Poetry` 管理 Python 依赖	改用 `uv`（Rust 编写的快速包管理器）
关键操作日志	`poetry install` `poetry lock`	`uv sync --locked` `uv venv`
核心优势	功能全面（环境隔离 + 依赖锁定 + 打包），适合本地开发中频繁调整依赖	速度更快（依赖解析 / 安装效率提升 3-5 倍），通过 `--locked` 确保依赖一致性，适配容器化构建场景
适用场景	本地开发调试（需手动关联 Conda 环境与 PyCharm）	Docker 镜像构建（自动化依赖同步，无需本地工具链）
兼容性	需手动解决与 GTK 等系统库的路径冲突（如 `LD_LIBRARY_PATH` 配置）	依赖通过 Docker 镜像内置（如 `ghcr.io/astral-sh/uv:python3.11-alpine` 预配置环境），冲突风险低

（三）镜像构建策略：从 “全本地构建” 到 “预拉取 + 部分构建”

维度	旧版部署流程	新版部署流程
基础设施镜像	本地构建 Redis/RabbitMQ 等支撑服务（`Built`）	直接拉取官方预构建镜像（`Pulled`）： `✔ rabbitmq Pulled` `✔ redis Pulled`
核心服务镜像	本地从零构建后端 / 前端镜像（依赖 MSYS2 编译 GTK 等组件）	复用仓库预构建镜像（`ghcr.io/suna-ai/suna-backend:latest`），仅前端需本地构建（`node:20-slim` 基础镜像）
构建耗时	较长（全量本地编译，含系统级依赖，约 20-30 分钟）	较短（预拉取镜像占比高，仅前端 `npm install` 和 `build` 耗时，约 5-10 分钟）
网络依赖	依赖本地工具链（如 MSYS2 pacman 源、PyPI），易受网络波动影响	依赖 Docker 镜像仓库，通过镜像缓存机制减少重复下载

（四）部署步骤与配置项：从 “手动分步” 到 “自动化向导 + 功能扩展”

维度	旧版部署流程	新版部署流程
流程驱动方式	手动分步执行（创建环境→安装依赖→配置 GTK 路径→启动服务），需用户干预路径和环境变量	全自动化安装向导（`python setup.py '--admin'`），自动检测配置状态（如 `✔ Supabase` `✔ LLM`）、构建容器、验证健康状态
总步骤数	8 步（基础环境检测 + 核心依赖安装）	14 步（细分配置环节，覆盖更多扩展功能）
新增配置项	无	新增 3 类可选企业级配置： `✔ Smithery (optional)`（工具集成平台） `✔ QStash & Webhooks`（消息队列 / 定时任务） `✔ MCP encryption key`（数据加密）
用户门槛	需理解环境变量（如 `GTK_PATH`）、依赖冲突解决（如 PyGObject 版本）	零手动配置，仅需等待自动化流程完成，适合非专业运维人员

（五）启动与管理方式：从 “本地进程” 到 “Docker Compose 生命周期管理”

维度	旧版部署流程	新版部署流程
启动方式	本地运行 Python 脚本（如 `python -m suna.gui.main`），或通过 NSSM 注册为 Windows 服务	Docker Compose 统一管理（`docker compose up`），封装为简化脚本 `python start.py`（支持启动 / 停止）
服务状态监控	需通过任务管理器或日志文件查看进程状态，分散且不直观	统一通过 `docker compose ps` 查看容器状态，`docker compose logs -f` 实时跟踪所有服务日志
生命周期管理	服务启停依赖本地进程 ID（PID），易误操作	容器化隔离，支持单服务重启（`docker compose restart backend`）和全量启停（`docker compose down`）

五、总结：新版部署的核心优化方向

架构升级：从 “本地环境绑定” 到 “容器化微服务”，提升隔离性、可移植性和扩展性，更贴近生产级部署标准。
效率提升：uv 替代 Poetry 加速依赖安装，预拉取镜像减少本地构建耗时，适配 CI/CD 流水线和频繁部署场景。
功能扩展：新增 Smithery、QStash 等配置项，支持工具集成、消息队列和数据加密，适配复杂业务场景。
易用性优化：全自动化向导 + Docker Compose 脚本封装，降低操作门槛，无需用户掌握 Docker 或系统配置细节。
API KEY 管理优化：新版对 API KEY 的管理优化，本质是为了适配 “扩展功能增多” 和 “生产级稳定性” 需求，同时也意味着新版对 API KEY 的要求更为严格（可能获取困难或产生费用）。

整体来看，新版部署流程在保留旧版核心功能的基础上，通过容器化和自动化实现了 “效率、兼容性、扩展性” 的三重升级，同时兼顾本地开发灵活性（仍支持 Poetry 环境）和生产部署规范性。