JellyfishBot
开发者指南 · 12

Tauri 桌面启动器

12.1 架构

  • Tauri v2（Rust + WebView）封装为原生桌面应用
  • 内嵌 Python 3.12.7 + Node.js 20.18.0 + 后端代码 + 前端构建产物
  • 用户双击 .dmg / .exe 即启动，无需命令行

12.2 文件结构

text
tauri-launcher/
├── package.json                 # @tauri-apps/cli
├── dist/
│   └── index.html               # 自包含启动器 UI（含内联 CSS + JS + base64 logo）
├── bundle-resources/            # 暂存区：app/、config/、frontend dist、launcher.py
├── scripts/
│   ├── build.py                 # 一键打包
│   └── version.py               # 版本管理
└── src-tauri/
    ├── Cargo.toml               # tauri 2 / reqwest / tokio / serde / open / libc
    ├── tauri.conf.json          # 窗口 720×580，NSIS(Windows)，macOS ≥10.15
    ├── build.rs
    └── src/
        ├── main.rs              # entry point
        └── lib.rs               # 14 个 Tauri Command

12.3 14 个 Tauri Commands

核心（9）：

  • detect_environment — Python/Node.js/项目文件检测
  • load_env_config / save_env_config — 读写 .env（保留注释 + 未知键）
  • test_api_key — HTTP 测试 OpenAI/Anthropic/Tavily 连通性
  • start_jellyfish — 调用 launcher.py --skip-check
  • stop_jellyfish — SIGTERM(Unix) / kill(Windows)
  • get_status — 轮询进程 + 端口存活
  • open_in_browser — 浏览器打开前端

注册码 / 用户管理：

  • list_registration_keys / generate_registration_keys(count) / delete_registration_key
  • list_admin_users / reset_admin_password / delete_admin_user / get_admin_stats

关于 / 工具（2026-04-20）：

  • open_project_dir / open_users_dir / open_logs_dir — lazy 创建后打开
  • open_release_page — 浏览器跳转固定 URL
  • get_app_version — 返回 env!("CARGO_PKG_VERSION")

12.4 UI 结构（dist/index.html）

  • 左侧 76px 窄导航栏（Logo + 4 页 Tab）
  • Page 1 控制台：环境检测 3 列 pill + 圆形 START 按钮 + API Keys 配置表单
  • Page 2 注册码管理：表格 + 生成/删除 + 复制按钮
  • Page 3 账户管理：统计摘要 4 卡 + 用户表格 + 重置密码/删除
  • Page 4 关于 / 工具：渐变版本号 + 4 张工具卡（项目目录 / 用户数据 / 日志目录 / Release）

整页是单文件 HTML（含内联 CSS + 内联 JS + base64 logo），无构建步骤。window.__TAURI__ 不存在时走 mockInvoke()，所以拿浏览器直开 file://.../dist/index.html 也能预览样式。

12.5 关键踩坑

12.5.1 Windows \\?\ 扩展长路径前缀（2026-04-20 关键 bug）

  • 症状：Windows .exe 启动后 uvicorn 报 OSError: Cannot load native module 'Crypto.Util._cpuid_c'，但 .pyd 文件物理存在
  • 根因：Tauri 的 app.path().resource_dir() 在 Windows 上返回 \\?\D:\JellyfishBot\ 形式的扩展长路径前缀；该前缀污染 Python 子进程 sys.executable，pycryptodome 的 os.path.isfile() 在 \\?\ 前缀路径下查不到 sibling .pyd
  • 修复：src-tauri/src/lib.rs 的 strip_win_extended_prefix() helper，在 resolve_project_dir / find_bundled_python / find_bundled_node 三处强制剥离前缀；launcher.py 加 _strip_extended_prefix() 双重防御
  • 影响范围：会影响 numpy / scipy / matplotlib 等所有依赖原生扩展的包
  • mac 完全无此问题

12.5.2 其他

  • withGlobalTauri: true — 必须！否则 window.__TAURI__ undefined
  • server.js 使用 ESM — package.json 有 "type": "module"
  • Express 5 通配符 — 用 '/{*path}' 代替 '*'
  • 路径必须绝对 — launcher.py::_resolve_python/node() 必须返回 os.path.abspath()
  • macOS 签名 — 修改 Resources 后需 codesign --force --deep --sign - <app_path>

12.6 Windows 本机 dev 环境

npx tauri dev / build 都需要：

  1. Rust toolchain（cargo 在 C:\Users\{user}\.cargo\bin\ — 默认不在 PATH）
  2. MSVC linker（link.exe） — VS 2022 Build Tools 或 Community
  3. Windows SDK（kernel32.lib / ntdll.lib）— VS 安装时容易漏勾！
  4. 解决：VS Installer → Modify → 勾选「使用 C++ 的桌面开发」

一行式启动 dev：

powershell
$vsBat = "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\VsDevCmd.bat"
& cmd /c "`"$vsBat`" -arch=x64 -no_logo && set" | ForEach-Object {
  if ($_ -match '^([^=]+)=(.*)$') { [Environment]::SetEnvironmentVariable($matches[1], $matches[2], 'Process') }
}
$env:Path = "C:\Users\$env:USERNAME\.cargo\bin;$env:Path"
cd tauri-launcher; npx tauri dev

tauri.conf.json 不要保留 devUrl：纯静态项目没有 Vite/dev server，留着会让 tauri dev 卡在等待中。
冷启动 Rust 全量编译约 4 分钟（457 个 crate），后续增量 ~5-30 秒。

12.7 迭代规则

改动文件处理方式
dist/index.htmldev 模式 Ctrl+R 即时生效；生产模式需 npx tauri build
lib.rs / tauri.conf.json必须 npx tauri build
launcher.py / server.js / app/** / frontend/dist/**Tauri resources，可热修：直接覆盖安装目录对应文件 + 重启 launcher（macOS 还需 codesign）

12.8 构建与发版

bash
cd tauri-launcher
python scripts/version.py bump patch     # 升级版本号
python scripts/build.py                  # 完整打包
python scripts/version.py tag --push     # 推送 tag → CI 自动构建

CI/CD：.github/workflows/release.yml

  • 触发：push tag v* 或手动 workflow_dispatch
  • 三平台矩阵：macOS-arm64 / macOS-x64 / Windows-x64
  • 产物上传 + 自动创建 GitHub Release（draft）

包大小：DMG ~247 MB，解压 ~998 MB。

上一篇←API 参考下一篇跨平台启动器（launcher.py）→