zhaolei
6f402ffcee
- 后端: coworker 智能体框架, WS API, 文件上传, 附件处理 - 前端: Open WebUI, 文件全量走 upload API (含 MD/TXT/JSON 等文本类) - 技能: md-to-office (pandoc + wkhtmltopdf) - 修复: 上传文件路径丢失, Agent 搜索浪费, 输出文件跑到 uploads/ - 打包: PyInstaller one-dir, 预打包 pandoc/wkhtmltopdf/chromium
217 lines
7.2 KiB
Markdown
217 lines
7.2 KiB
Markdown
# OpenMesh 打包流程说明
|
||
|
||
## 概述
|
||
|
||
OpenMesh 是一个基于 Python (FastAPI) + React (Vite) 的 AI 智能助手平台，最终交付形态为 Windows 绿色免安装版。打包产物位于 `dist/openmesh/` 目录，用户双击 `启动 OpenMesh.bat` 即可运行。
|
||
|
||
---
|
||
|
||
## 打包产物目录结构
|
||
|
||
```
|
||
dist/openmesh/
|
||
├── openmesh-server.exe # 后端服务主程序（PyInstaller one-dir 模式）
|
||
├── openmesh-static.exe # 前端静态文件服务器
|
||
├── _internal/ # PyInstaller 运行时依赖（Python 解释器 + 所有库）
|
||
├── frontend/ # 前端构建产物（React + Vite）
|
||
│ ├── index.html
|
||
│ └── assets/
|
||
├── data/ # 用户数据目录（首次启动后生成配置）
|
||
│ ├── config.toml
|
||
│ ├── coworker.db
|
||
│ ├── chat.db
|
||
│ └── skills/ # 已安装的 skills（从 skills/ 初始化复制）
|
||
├── skills/ # 预置内置 skills（首次启动复制到 data/skills）
|
||
├── workspace/ # 默认工作目录
|
||
├── tools/ # 第三方命令行工具（pandoc, tesseract, libreoffice）
|
||
├── .venv/ # Python 虚拟环境（用于 skill 脚本执行）
|
||
├── 启动 OpenMesh.bat # 一键启动脚本
|
||
├── 卸载 OpenMesh.bat # 卸载脚本
|
||
└── 使用说明.txt # 使用说明
|
||
```
|
||
|
||
---
|
||
|
||
## 打包步骤总览
|
||
|
||
完整打包分为 **4 个阶段**，顺序执行：
|
||
|
||
```
|
||
阶段1: 前端构建 → 阶段2: 后端 PyInstaller 打包 → 阶段3: 静态服务器打包 → 阶段4: 组装发布包
|
||
```
|
||
|
||
---
|
||
|
||
## 阶段 1：前端构建
|
||
|
||
### 目的
|
||
将 React + Vite 前端项目编译为静态 HTML/CSS/JS 资源。
|
||
|
||
### 前置条件
|
||
- Node.js >= 16
|
||
- 已执行 `npm install`
|
||
|
||
### 操作命令
|
||
```bash
|
||
cd surfaces/gui
|
||
npm run build
|
||
```
|
||
|
||
### 输入
|
||
- `surfaces/gui/src/` — 前端源码
|
||
- `surfaces/gui/index.html` — HTML 模板
|
||
|
||
### 输出
|
||
- `surfaces/gui/dist/` — 构建产物
|
||
- `index.html`
|
||
- `assets/index-*.js`
|
||
- `assets/index-*.css`
|
||
- 其他静态资源（字体、图片等）
|
||
|
||
### 配置文件
|
||
- `surfaces/gui/vite.config.ts` — Vite 配置
|
||
- `base: "./"` — 相对路径，支持从文件系统直接加载
|
||
- 构建输出到 `dist/`
|
||
|
||
---
|
||
|
||
## 阶段 2：后端服务 PyInstaller 打包
|
||
|
||
### 目的
|
||
将 Python 后端服务（FastAPI + uvicorn）打包为独立的 Windows 可执行程序及运行时目录。
|
||
|
||
### 前置条件
|
||
- Python 3.10+
|
||
- 虚拟环境已安装所有依赖：`pip install -e .`
|
||
- `pyinstaller` 已安装
|
||
|
||
### 操作命令
|
||
```bash
|
||
pyinstaller dist/openworker-server.spec
|
||
```
|
||
|
||
### Spec 文件说明
|
||
路径：`dist/openworker-server.spec`
|
||
|
||
关键配置：
|
||
- **入口**：`packaging/server_entry.py` → 调用 `coworker.server.run:main`
|
||
- **模式**：one-dir（exe + `_internal/` 目录），比 onefile 启动快 6-7 秒
|
||
- **控制台**：`console=True`（uvicorn 需要 stdout，窗口通过 CREATE_NO_WINDOW 隐藏）
|
||
- **收集的包**：coworker, aisuite, mcp, ddgs, uvicorn, certifi, websockets, pypdf, pypdfium2, boto3, botocore 等
|
||
- **排除**：tkinter, matplotlib, PIL, PyQt5 等不需要的库
|
||
|
||
### 输出
|
||
- `dist/openmesh-server/`
|
||
- `openmesh-server.exe` — 主程序
|
||
- `_internal/` — Python 运行时 + 所有依赖库
|
||
|
||
---
|
||
|
||
## 阶段 3：静态文件服务器打包
|
||
|
||
### 目的
|
||
打包一个极简的 HTTP 服务器，用于托管前端静态文件。
|
||
|
||
### Spec 文件
|
||
路径：`openmesh-static.spec` 或 `static-server.spec`
|
||
|
||
入口：`packaging/static_server.py`
|
||
|
||
输出：`dist/openmesh-static.exe` 或 `dist/static-server/static-server.exe`
|
||
|
||
---
|
||
|
||
## 阶段 4：组装发布包
|
||
|
||
### 目的
|
||
将前端、后端、工具、配置等所有组件组装到 `dist/openmesh/` 目录，形成最终可交付的绿色版。
|
||
|
||
### 组装清单
|
||
|
||
| 源位置 | 目标位置 | 说明 |
|
||
|--------|----------|------|
|
||
| `dist/openmesh-server/openmesh-server.exe` | `dist/openmesh/openmesh-server.exe` | 后端服务 |
|
||
| `dist/openmesh-server/_internal/` | `dist/openmesh/_internal/` | Python 运行时 |
|
||
| `surfaces/gui/dist/` | `dist/openmesh/frontend/` | 前端构建产物 |
|
||
| `dist/openmesh-static.exe` | `dist/openmesh/openmesh-static.exe` | 静态文件服务器 |
|
||
| `skills/` (项目内置) | `dist/openmesh/skills/` | 预置 skills |
|
||
| `tools/` (pandoc 等) | `dist/openmesh/tools/` | 第三方工具 |
|
||
| `dist/config.template.toml` | `dist/openmesh/data/config.toml` | 默认配置 |
|
||
| — | `dist/openmesh/workspace/` | 工作目录（空） |
|
||
| — | `dist/openmesh/data/` | 数据目录（空） |
|
||
| `启动 OpenMesh.bat` | `dist/openmesh/启动 OpenMesh.bat` | 启动脚本 |
|
||
| `卸载 OpenMesh.bat` | `dist/openmesh/卸载 OpenMesh.bat` | 卸载脚本 |
|
||
| `使用说明.txt` | `dist/openmesh/使用说明.txt` | 使用说明 |
|
||
|
||
### 启动脚本逻辑
|
||
文件：`dist/openmesh/启动 OpenMesh.bat`
|
||
|
||
关键环境变量：
|
||
```bat
|
||
set DATA_DIR=%SCRIPT_DIR%data :: COWORKER_STATE_DIR 指向 data 目录
|
||
set SKILLS_DIR=%DATA_DIR%\skills :: 实际 skills 目录
|
||
set BUILTIN_SKILLS=%SCRIPT_DIR%skills :: 内置 skills 源
|
||
set COWORKER_DISABLE_AUTH=1 :: 禁用认证（本地使用）
|
||
set COWORKER_STATE_DIR=%DATA_DIR% :: 状态目录
|
||
set COWORKER_SCRATCH_BASE=workspace :: 临时文件基准目录
|
||
```
|
||
|
||
启动顺序：
|
||
1. 创建 data、skills、workspace 目录
|
||
2. 首次启动时，将内置 skills 复制到 data/skills
|
||
3. 启动 `openmesh-server.exe --port 8765 --cwd workspace`（后端，端口 8765）
|
||
4. 启动 `openmesh-static.exe frontend`（前端静态服务器，端口 3000）
|
||
5. 打开浏览器访问 http://localhost:3000
|
||
|
||
---
|
||
|
||
## 重新打包操作清单
|
||
|
||
当代码修改后需要重新打包时，按以下顺序执行：
|
||
|
||
### 仅前端修改
|
||
```
|
||
npm run build → 复制到 dist/openmesh/frontend/
|
||
```
|
||
|
||
### 仅后端修改
|
||
```
|
||
pyinstaller dist/openworker-server.spec → 复制 exe 和 _internal/ 到 dist/openmesh/
|
||
```
|
||
|
||
### 前后端都修改
|
||
```
|
||
1. cd surfaces/gui && npm run build
|
||
2. pyinstaller dist/openworker-server.spec
|
||
3. 组装到 dist/openmesh/
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **data/skills 与 skills/**：内置 skills 仅首次启动时复制。修改内置 skills 后，需删除用户 `data/skills/` 目录才能生效，或手动更新。
|
||
|
||
2. **PyInstaller 增量构建**：build 目录会缓存，重复构建时速度较快。完全干净构建可删除 `build/` 目录。
|
||
|
||
3. **.venv 目录**：发布包中的 `.venv` 用于 skill 脚本执行（如 Python 脚本），与 PyInstaller 打包的运行时是两套独立环境。
|
||
|
||
4. **端口冲突**：默认后端 8765，前端 3000。可在 `data/config.toml` 中修改。
|
||
|
||
5. **UPX 压缩**：server 端默认关闭 UPX（`upx=False`），避免某些库加载失败。static 端开启了 UPX。
|
||
|
||
---
|
||
|
||
## 相关文件索引
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| `pyproject.toml` | Python 项目配置、依赖、入口点 |
|
||
| `dist/openworker-server.spec` | 后端 PyInstaller 配置 |
|
||
| `openmesh-static.spec` | 静态服务器 PyInstaller 配置 |
|
||
| `dist/server_entry.py` | 后端打包入口 |
|
||
| `surfaces/gui/vite.config.ts` | 前端构建配置 |
|
||
| `surfaces/gui/package.json` | 前端依赖和脚本 |
|
||
| `dist/openmesh/启动 OpenMesh.bat` | 启动脚本 |
|
||
| `coworker/server/run.py` | 后端服务主入口 |
|