package/README.md

AI 学术写作助手 - 可执行文件打包

本目录包含将前后端项目打包为单个可执行文件 (exe) 的代码和配置。

目录结构

package/
├── backend/           # 后端代码（修改版，支持 exe 模式）
├── frontend/          # 前端代码（修改版，生产环境配置）
├── main.py            # 统一入口文件
├── app.spec           # PyInstaller 打包配置
├── requirements.txt   # Python 依赖
├── build.sh           # Linux/macOS 构建脚本
├── build.ps1          # Windows 构建脚本
└── README.md          # 本文件

本地构建

前置条件

• Python 3.9+
• Node.js 18+
• pip 和 npm

构建步骤

Linux/macOS:

cd package
chmod +x build.sh
./build.sh

Windows:

cd package
.\build.ps1

构建完成后，可执行文件位于 dist/ 目录。

GitHub Actions 自动构建

项目配置了 GitHub Actions 工作流，可以自动构建 Windows、Linux 和 macOS 版本的可执行文件。

触发方式

1. 打标签触发: 推送以 v 开头的标签时自动触发构建并创建 Release

   git tag v1.0.0
   git push origin v1.0.0
   

2. 手动触发: 在 GitHub Actions 页面手动运行工作流

构建产物

• AI学术写作助手-Windows-{version}.zip - Windows 可执行文件
• AI学术写作助手-Linux-{version}.tar.gz - Linux 可执行文件
• AI学术写作助手-macOS-{version}.tar.gz - macOS 可执行文件

运行说明

1. 下载对应平台的可执行文件
2. 解压到任意目录
3. 首次运行会自动创建 .env 配置文件模板
4. 编辑 .env 文件，填入必要的配置：
   • API Key（OPENAI_API_KEY、POLISH_API_KEY 等）
   • 管理员密码（ADMIN_PASSWORD）
   • JWT 密钥（SECRET_KEY）
5. 再次运行程序
6. 程序会自动打开浏览器访问 http://localhost:8000

配置文件说明

.env 文件和数据库文件 (ai_polish.db) 都会保存在可执行文件同目录下，方便备份和迁移。

访问地址

• 用户界面: http://localhost:8000
• 管理后台: http://localhost:8000/admin
• API 文档: http://localhost:8000/docs

与原项目的区别

1. 运行方式：原项目需要分别启动前端和后端服务，exe 版本一键启动
2. 配置位置：exe 版本的 .env 和数据库文件在 exe 同目录
3. 前端访问：exe 版本前后端在同一端口，无需代理

技术细节

前端修改

• 修改 vite.config.js 添加生产环境构建配置
• 修改 API 配置，生产环境直接使用根路径

后端修改

• 修改 config.py，支持动态获取 exe 目录下的配置文件
• 数据库路径默认指向 exe 同目录

统一入口

• main.py 创建 FastAPI 应用
• 挂载静态文件服务前端页面
• 处理 SPA 路由（admin、workspace 等）
• 自动打开浏览器

PyInstaller 配置

• 包含所有必要的隐式导入
• 包含前端静态文件
• 包含后端应用代码
• 排除不必要的大型库