Windows 下部署 SUNA 項目：虛擬環境嘗試與最終方案

#工作記錄

#回顧總結

本文記錄了在 Windows 系統上，通過 PyCharm 圖形界面（盡量減少命令行操作）部署 SUNA 項目時，針對不同虛擬環境方案的嘗試過程、遇到的問題以及最終選擇的可行方案，并補充了整體部署思路與推薦。文中步驟以“在 PyCharm 中用界面功能完成環境創建/刪除、依賴安裝”為前提。

一、背景與目標

目標：讓 SUNA 在 Windows 平臺完整部署運行，盡量少用命令行，一切虛擬環境操作（創建/刪除）都通過 PyCharm 的圖形化界面完成。
主要挑戰：
1. 執行 python setup.py --admin 時，會自動在 C 盤創建一個新的 Poetry 虛擬環境，脫離項目目錄，影響依賴管理。
2. 前端需要編譯 canvas（依賴 GTK/cairo），Windows 下缺少相關頭文件和 DLL，往往編譯失敗。
3. 不同 Python 主版本對后端依賴的兼容性差異顯著：過高容易出現包安裝失敗，過低可能缺少新特性。

二、嘗試過的虛擬環境方案

下面按照“Virtualenv（.venv）”和“Poetry”兩大思路，依次列出所做嘗試、遇到問題和結論。

1. Virtualenv（.venv）方案

通過 PyCharm 創建 .venv 虛擬環境，結合 Anaconda 提供的不同 Python 版本，再在該環境中安裝 Poetry 并運行 setup.py --admin。

1.1 基于 Anaconda 的 Python 3.13 + `pip install poetry`

操作：
1. 在 PyCharm 中新建 .venv，選擇 Anaconda Python 3.13。
2. 通過界面或終端執行 pip install poetry。
3. 運行 python setup.py --admin。
問題：
- 腳本會在 C 盤 自動新建一個 Poetry 虛擬環境，與項目目錄無法統一管理。
- Python 3.13 版本過高，部分后端依賴（如一些深度學習或 C/C++ 擴展包）直接安裝失敗，導致部署卡住。
結論：此組合下部署無法繼續。

1.2 基于 Anaconda 的 Python 3.12 + `pip install poetry`

操作：
1. PyCharm 新建 .venv，選擇 Anaconda Python 3.12。
2. 安裝 Poetry：pip install poetry。
3. 運行 python setup.py --admin。
問題：
- 依舊會在 C 盤自動新建 Poetry 環境，脫離項目目錄。
- Python 3.12 版本雖然略低，但仍有部分后端包（依賴新版語法或系統擴展）安裝失敗，導致安裝中斷。
結論：此組合下部署仍不能完成。

1.3 基于 Anaconda 的 Python 3.11 + `pip install poetry`

操作：
1. PyCharm 創建 .venv，指定 Anaconda Python 3.11。
2. 界面或終端執行 pip install poetry。
3. 運行 python setup.py --admin。
問題：
- 同樣會在 C 盤新建 Poetry 環境，項目本地無法集中管理。
- 雖然 Python 3.11 對后端依賴兼容性更好，但前端依賴 canvas 編譯依賴 GTK 庫，在 Windows 下依舊因為找不到 GTK 頭文件/DLL 而報錯，前端構建失敗。
結論：此方案下，后端依賴大部分可裝，但前端依賴無法滿足，部署中斷。

Virtualenv 小結：

共性問題：

setup.py --admin 會在 C 盤新建一個 Poetry 環境，不在我們期望的項目目錄內。

Python 3.12/3.13 對部分后端包兼容性差，安裝失敗。

Windows 下缺少 GTK 導致前端 canvas 無法編譯。

結論：使用 Virtualenv（.venv）拉起來的環境無法同時滿足“Poetry 環境可控”與“前端 GTK 依賴”這兩道關，故不可行。

2. Poetry 原生方案

在項目根目錄利用 Poetry 手動創建虛擬環境，讓 setup.py --admin 不再到 C 盤生成環境，所有東西都留在項目目錄內。

2.1 基于 Anaconda 的 Python 3.12 + Poetry（項目目錄 .venv）

操作：
1. PyCharm → Interpreter → 選擇 Anaconda Python 3.12。
2. 在 PyCharm Terminal 中執行 pip install poetry。
3. 切換到項目根目錄，執行 poetry init --no-interaction，生成 pyproject.toml。
4. 執行 poetry install，讓 Poetry 在項目目錄創建 .venv 并安裝基礎依賴。
5. 運行 python setup.py --admin。
優點：
- setup.py --admin 不會再到 C 盤新建 Poetry 環境，所有虛擬環境都在項目目錄可控范圍。
問題：
- Python 3.12 對部分后端依賴版本兼容性依舊有問題，一些包安裝失敗。
- 前端依賴：canvas 模塊依賴 GTK 庫，而 Windows 下并無 GTK 環境，依舊編譯失敗，前端卡住。
結論：此方案對后端改進有限，前端依賴仍不可行。

2.2 基于 Anaconda 的 Python 3.11 + Poetry（項目目錄 .venv）

操作：
1. PyCharm → Interpreter → 選擇 Anaconda Python 3.11。
2. pip install poetry → poetry init → poetry install。
3. 運行 python setup.py --admin。
優點：
- 后端依賴大部分能正常安裝，Python 3.11 對后端包兼容性顯著改善。
- Poetry 環境都在項目目錄，不會再去 C 盤建。
問題：
- 前端依賴依舊因 GTK 缺失，canvas 無法編譯，前端部署中斷。
結論：此方案只解決了“Poetry 環境可控”，但未解決“GTK 依賴”問題，前端依然掛掉。

2.3 MSYS2 MINGW64 + Python 3.12 + Poetry（項目目錄 .venv）【最終可行方案】

思路：在 MSYS2 MINGW64 環境里用自帶的 Python 3.12 和 Poetry，借助 MSYS2 的 pacman 安裝所有 GTK/cairo 依賴，徹底解決前端編譯問題。
操作步驟（簡要）：
1. 安裝 MSYS2 → 打開 MSYS2 MinGW 64-bit 終端。
2. 更新基礎包：
```
pacman -Syu
```
3. 安裝 Python 3.12、pip、Poetry（如果 MSYS2 鏡像已有，可直接 pacman 安裝，否則用 pip）：
```
pacman -S mingw-w64-x86_64-python3 mingw-w64-x86_64-pip
pacman -S mingw-w64-x86_64-python-poetry
```
4. 在 PyCharm → Project Interpreter → 添加解釋器，選擇 C:\msys64\mingw64\bin\python.exe（MSYS2 Python 3.12）。
5. 在項目目錄（SUNA 根目錄）執行：
```
cd /c/路徑/到/suna
poetry init --no-interaction
poetry install
```
  此時 Poetry 會在項目目錄創建 .venv，并安裝后端依賴（除 C/C++ 擴展外）。
6. 安裝前端所需的 GTK/cairo 相關包、Node.js、make、pkg-config：
```
pacman -S \mingw-w64-x86_64-toolchain \mingw-w64-x86_64-cairo \mingw-w64-x86_64-pango \mingw-w64-x86_64-gdk-pixbuf2 \mingw-w64-x86_64-libpng \mingw-w64-x86_64-freetype \mingw-w64-x86_64-fontconfig \mingw-w64-x86_64-nodejs \make \pkg-config
```
7. 運行 python setup.py --admin：
  - 不會再在 C 盤新建 Poetry 環境，所有后端依賴安裝在項目目錄。
  - 如果后端提示缺少 C/C++ 構建工具，可以通過 pacman -S mingw-w64-x86_64-toolchain make pkg-config 補齊。
8. 構建前端：
```
cd frontend
export PKG_CONFIG_PATH=/mingw64/lib/pkgconfig
export CFLAGS="-I/mingw64/include"
export LDFLAGS="-L/mingw64/lib"
npm install --build-from-source
```
  此時 canvas 模塊可在 MINGW64 下順利編譯，前端構建成功。
9. 構建后端：
```
poetry install
```
優點：
1. Poetry 環境可控：setup.py --admin 不再去 C 盤另外再創建環境，所有環境都在項目目錄。
2. 前端 GTK 依賴一并解決：利用 MSYS2 的 pacman 安裝所需依賴，canvas 能編譯通過。
3. 后端依賴兼容：Python 3.12 對大部分后端包兼容性良好，結合 MSYS2 工具鏈可完成所有 C/C++ 擴展的構建。
問題：
- 初期 MSYS2 中若缺少 mingw-w64-x86_64-toolchain、make、pkg-config，會導致后端原生擴展（如某些 C/C++ 庫）編譯中斷。
- 需要對 MSYS2 包管理（路徑、環境變量）有一定了解，配置過程相對繁瑣。
結論：在 Windows 平臺下，如果要同時滿足“Poetry 環境位置可控”和“前端 GTK/cairo 依賴”兩大要求，MSYS2 MINGW64 + Python 3.12 + Poetry 是目前唯一可行方案，前后端都能順利部署。

Poetry 小結：

方案 2.1/2.2：解決了 Poetry 環境在項目目錄問題，但未解決前端 GTK 依賴，部署中斷。

方案 2.3（MSYS2）：“一勞永逸”地通過 MSYS2 安裝 GTK/cairo、Node.js、make、toolchain，最終前后端均能部署成功。

三、其他補充與部署思考

部署成功后仍有部分報錯需要調試
- 部分錯誤可能源自 SUNA 源碼本身（邏輯或路徑問題），也有很大幾率是 Windows 平臺差異導致。比如：
  - 文件權限、路徑分隔符（\ vs /）引起小模塊加載失敗；
  - C/C++ 擴展在 Windows 下編譯選項需微調；
  - 前端某些資源在 Windows 路徑下找不到，報 EPERM 權限錯誤。
- 因此，即便環境搭建成功，也需要一定量的手動調試和小范圍代碼修改。
最終部署優先級排序
- 首推：Docker 部署
  - 只需安裝 Docker Desktop，并在項目根目錄編寫好 Dockerfile 與 docker-compose.yml，然后一行命令 docker-compose up --build，即可在容器中完成前后端編譯與運行，Windows 主機不必手動配置 GTK、Poetry、工具鏈等。
  - 優勢：隔離性強、環境一致性高、可快速復現。
  - 缺點：需要學習 Dockerfile 寫法、鏡像體積較大、容器與宿主機文件掛載需特別注意權限。
- 次推：WSL（Windows Subsystem for Linux）
  - 在 Windows 設置里開啟 WSL（建議 Ubuntu 20.04/22.04），把所有前端/后端依賴安裝到 Ubuntu 子系統里，部署過程基本與原生 Linux 一致。
  - 優勢：Linux 原生環境，包管理簡單，兼容性好。
  - 缺點：需要提前配置 WSL、網絡與端口映射，文件系統讀寫性能與 Windows 主機有差異，需要適配。
- 最后：MSYS2 MINGW64 + Python 3.12 + Poetry
  - 如果不愿意安裝 Docker/WSL，也能通過 MSYS2 解決 GTK 和 Poetry 環境問題。
  - 優勢：MSYS2 是 Windows 原生的類 Unix 環境，安裝包便捷，但需對路徑與環境變量處理細節有所掌握。
  - 缺點：配置復雜，需要手動補齊多種工具鏈，有一定折騰成本。

綜合評價：

Docker：部署體驗最省心，一行命令搞定環境一致性，開發者只需維護 Docker 鏡像。

WSL：保留 Linux 生態優勢，適合對 Linux 環境熟悉的開發者；缺點在于 Windows ? WSL 文件互通時性能或權限需額外打磨。

MSYS2：適合習慣在 Windows 上使用類 Unix 工具鏈的開發者；但需要對 MSYS2 包管理、路徑映射等有一定了解，偏“折騰派”。

四、文章結構與語言說明

文章結構
- 第一部分：背景與目標
  簡要說明為何要在 Windows 上部署 SUNA、主要挑戰是什么。
- 第二部分：嘗試過的虛擬環境方案
  分為 “Virtualenv（.venv）方案” 和 “Poetry 方案” 兩大類，逐條羅列不同 Python 版本/工具組合下的實際操作、遇到的問題與結論。
- 第三部分：其他補充與部署思考
  包含部署成功后仍需調試之處、不同平臺（Docker/WSL/MSYS2）優劣的策略排序和說明。
- 第四部分：總結與推薦
  最終給出在 Windows 下首推、次推、最后選擇三種方案的簡明對比，幫助讀者快速抉擇。
語言組織
- 保持“輕松嚴謹”風格：
  - 關鍵概念使用短句或分項列表強調，保證信息一目了然。
  - 遇到的問題與解決思路分別列出“操作”“問題”“結論”三要素，讓讀者迅速抓住要點。
  - 結論處對比各方案優缺點，方便讀者根據自身需求快速做選擇。
- 使用“簡潔詞匯 + 適當小結”方式：
  - 每個小節后都做簡短概括，便于從頭瀏覽或查閱。
  - 銜接處使用“然而”、“但是”、“同時”等對比詞，提示不同方案的優劣差異。
- 強調“可復制/可復現”：
  - 在最終總結處給出一行部署思路，供讀者快速復現或保存在 README 里。
  - 對于關鍵命令，直接以三重反引號標注，保證可復制粘貼。

五、總結

Virtualenv（.venv）方案：存在“Poetry 環境脫離項目目錄”與“Windows 下 GTK 依賴缺失”兩大問題，無法完成部署。
Poetry 原生方案：
- Python 3.12/3.11 + Poetry（項目目錄）：只解決了環境位置可控，但依舊因 GTK 缺失或后端包兼容問題導致部署失敗。
- MSYS2 MINGW64 + Python 3.12 + Poetry：利用 MSYS2 的 pacman 安裝 GTK/cairo、Node.js、make、工具鏈，最終前后端部署都成功，是目前唯一可行方案。
部署優先級：
1. Docker 部署（一鍵容器化）——最省心；
```
#項目根目錄下運行
docker compose down && docker compose up --build
```
2. WSL Ubuntu 部署——Linux 生態優勢；
3. MSYS2 MINGW64 + Python 3.12 + Poetry——原生 Windows 方案，需要一定折騰精神。
后續建議：
- 若有機會改進 SUNA 源碼，可嘗試降低前端對 GTK 的依賴，或提供預編譯二進制版本，減輕 Windows 環境編譯負擔。
- 將上述部署步驟整理到項目 README 或內網文檔，減少團隊成員重復踩坑。