运行与部署

本文档介绍如何运行 Mindra 开源版本以及部署相关的事项。

运行应用

前提条件

运行前请确保：

Python 3.8+ 已安装
所需 Python 包已安装 (PySide6, openai, pymysql, PyYAML)
MySQL 数据库已配置（如需用户管理功能）
config.yaml 配置文件已正确配置

启动应用

在项目根目录下运行：

python main.py

首次运行

首次运行时，应用会：

创建 Mindra_data 目录用于数据存储
弹出登录对话框
您需要注册新账户或登录现有账户

注册新用户

在登录对话框点击「注册」按钮
输入用户名、密码和激活码
点击「注册」完成注册
使用新账户登录

注意: 激活码需要预先在数据库中插入。

运行参数

调试模式

如需查看详细日志，可以直接运行，错误信息会输出到控制台。

指定配置文件

如果配置文件不在默认位置，需要修改 user_operations.py 中的配置路径：

# 修改此行
config_path = Path("config.yaml")

# 改为绝对路径
config_path = Path("your/custom/path/config.yaml")

打包分发

使用 PyInstaller 打包

安装 PyInstaller：

pip install pyinstaller

打包应用：

pyinstaller --onefile --windowed --name Mindra --icon=Mindra_logo.ico main.py

参数说明:

参数	说明
`--onefile`	打包为单个可执行文件
`--windowed`	不显示控制台窗口
`--name`	指定输出文件名
`--icon`	设置应用图标
`--add-data`	添加额外文件（如 `config.yaml`）

添加额外文件：

# Windows
pyinstaller --onefile --windowed --name Mindra --add-data "config.yaml;." --add-data "homepage.html;." --icon=Mindra_logo.ico main.py

# macOS/Linux
pyinstaller --onefile --windowed --name Mindra --add-data "config.yaml:." --add-data "homepage.html:." --icon=Mindra_logo.ico main.py

打包后的文件结构

dist/
└── Mindra.exe        # 可执行文件（Windows）
    # 或 Mindra.app（macOS）
    # 或 Mindra（Linux）

创建安装包

Windows - 使用 Inno Setup

下载并安装 Inno Setup
创建安装脚本 setup.iss：

[Setup]
AppName=Mindra
AppVersion=1.0.0
DefaultDirName={pf}\Mindra
DefaultGroupName=Mindra
OutputDir=.
OutputBaseFilename=Mindra_Setup
Compression=lzma
SolidCompression=yes

[Files]
Source: "dist\Mindra.exe"; DestDir: "{app}"; Flags: ignoreversion
Source: "config.yaml"; DestDir: "{app}"; Flags: ignoreversion
Source: "homepage.html"; DestDir: "{app}"; Flags: ignoreversion

[Icons]
Name: "{group}\Mindra"; Filename: "{app}\Mindra.exe"
Name: "{commondesktop}\Mindra"; Filename: "{app}\Mindra.exe"

编译安装包

macOS - 创建 DMG

# 创建 DMG 文件
hdiutil create -volname Mindra -srcfolder dist/Mindra.app -ov -format UDZO Mindra.dmg

部署注意事项

数据库部署

生产环境数据库配置

使用强密码
限制数据库访问 IP
定期备份数据库

-- 备份数据库
mysqldump -u root -p mindra > mindra_backup.sql

-- 恢复数据库
mysql -u root -p mindra < mindra_backup.sql

配置文件管理

生产环境配置

在生产环境中，建议：

使用专用的数据库用户
定期更换 API 密钥
启用数据库 SSL 连接（如支持）

database:
  host: "production-db.example.com"
  database: "mindra"
  user: "mindra_prod_user"
  password: "strong_password_here"

性能优化

数据库优化

-- 为 users 表创建索引
CREATE INDEX idx_username ON users(username);

-- 定期优化表
OPTIMIZE TABLE users;
OPTIMIZE TABLE activation;

应用优化

使用连接池管理数据库连接
启用 PySide6 的硬件加速
减少不必要的日志输出

常见问题

应用无法启动

问题: 双击 exe 文件后无反应

解决方案:

检查是否缺少 config.yaml 文件
在命令行中运行 exe 文件查看错误信息
确保依赖文件在正确位置

登录对话框不显示

问题: 应用启动后没有弹出登录对话框

解决方案: 检查 config.yaml 中的数据库配置是否正确。

打包后无法运行

问题: PyInstaller 打包后程序无法运行

解决方案:

检查是否所有依赖都被正确打包
使用 --hidden-import 添加隐式导入：

pyinstaller --onefile --windowed --hidden-import pymysql --hidden-import openai main.py

中文字体显示问题

问题: 界面中文显示为方块

解决方案: 确保系统安装了中文字体，或在样式中指定中文字体：

# 在 style_settings.py 中指定字体
font-family: "Microsoft YaHei", "SimHei", sans-serif;

更新与维护

版本更新

备份配置文件和数据库
拉取最新代码
安装新增的依赖
运行更新后的应用

日志管理

建议在代码中添加日志记录，便于问题排查：

import logging

logging.basicConfig(
    filename='mindra.log',
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)

logging.info("应用启动")
logging.error("数据库连接失败")