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 或内网文档，减少团队成员重复踩坑。