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）

?

?

五、總結：新版部署的核心優化方向

1. 架構升級：從 “本地環境綁定” 到 “容器化微服務”，提升隔離性、可移植性和擴展性，更貼近生產級部署標準。
2. 效率提升：uv?替代 Poetry 加速依賴安裝，預拉取鏡像減少本地構建耗時，適配 CI/CD 流水線和頻繁部署場景。
3. 功能擴展：新增 Smithery、QStash 等配置項，支持工具集成、消息隊列和數據加密，適配復雜業務場景。
4. 易用性優化：全自動化向導 + Docker Compose 腳本封裝，降低操作門檻，無需用戶掌握 Docker 或系統配置細節。
5. API KEY 管理優化：新版對 API KEY 的管理優化，本質是為了適配 “擴展功能增多” 和 “生產級穩定性” 需求，同時也意味著新版對 API KEY 的要求更為嚴格（可能獲取困難或產生費用）。

整體來看，新版部署流程在保留舊版核心功能的基礎上，通過容器化和自動化實現了 “效率、兼容性、擴展性” 的三重升級，同時兼顧本地開發靈活性（仍支持 Poetry 環境）和生產部署規范性。

?

---

六、舊版部署參考資料

?Poetry + GTK + API KEY

【筆記】開源通用人工智能代理 Suna 部署全流程準備清單（Windows 系統）-CSDN博客?

【AI Agent 項目 SUNA 部署】Windows 全版本 GTK 兼容與部署最佳實踐（兼顧 Frontend 前端 和 Backend 后端 順利部署）-CSDN博客?

【筆記】AI Agent 項目 SUNA 部署 之 Docker 構建記錄_suna docker部署-CSDN博客?

……?

更多 SUNA 部署實戰參考資料請參見往期筆記或免費專欄！

Windows 部署 AI Agent - Suna

?