CertFlow 部署文档

本指南涵盖 CertFlow-PySide6 的打包、安装包制作和分发流程。

项目结构

CertFlow-PySide6/
├── config/                    # 配置文件（外置）
│   ├── config.yaml           # 主配置
│   ├── query_fields.yaml     # 查询字段配置
│   ├── ui.yaml               # UI配置
│   ├── userconfig.yaml       # 用户配置（运行时生成）
│   └── schemas/              # JSON Schema（IDE提示用）
├── src/certflow/             # 源代码
├── resources/                # 资源文件
├── data/templates/           # 模板文件
├── scripts/                  # 构建脚本
│   ├── build_exe.py         # 主打包脚本（分支隔离）
│   ├── build.sh             # Linux/Mac 打包入口
│   ├── build.bat            # Windows 打包入口
│   └── clean_package.py     # 清理脚本
└── dist/                     # 输出目录
    └── CertFlow/             # 打包产物
        ├── CertFlow.exe      # 主程序
        ├── start.bat         # Windows启动脚本
        ├── start.sh          # Linux启动脚本
        ├── config/           # 配置文件
        ├── resources/        # 资源文件
        └── data/             # 数据文件

构建要求

软件要求

工具

版本要求

说明

Python

3.10+

运行时环境

uv

0.5+

包管理器

PyInstaller

6.0+

打包工具

Git

2.0+

分支隔离打包（可选）

UPX

最新版

可选，减小体积

依赖安装

# 克隆项目
git clone https://github.com/your-repo/CertFlow-PySide6.git
cd CertFlow-PySide6

# 安装依赖
uv sync

# 安装打包依赖
uv add --dev pyinstaller

打包方式

方式一：使用打包脚本（推荐）

Windows

# 双击运行或在命令行执行
scripts\build\build.bat

# 或使用 Python 脚本
python scripts/build/build_exe.py

Linux / macOS

# 添加执行权限
chmod +x scripts/build/build.sh

# 执行打包
bash scripts/build/build.sh

# 带参数
bash scripts/build/build.sh --no-clean   # 跳过清理
bash scripts/build/build.sh --no-git     # 跳过分支隔离
bash scripts/build/build.sh --console    # 调试模式

方式二：直接使用 PyInstaller

# 单文件模式
pyinstaller --onefile --name CertFlow --console src/certflow/main.py

# 单目录模式（推荐）
pyinstaller --onedir --name CertFlow --windowed src/certflow/main.py

打包选项说明

选项

说明

--clean-only

仅清理构建文件，不打包

--no-clean

跳过清理，直接打包

--no-git

跳过 Git 分支隔离（当前分支直接打包）

--console

控制台模式（调试用）

分支隔离打包

打包脚本会自动创建临时分支进行打包，确保原开发分支不被污染：

# 打包流程
当前分支 (develop)
       │
       ▼
创建临时分支 ──▶ packaging/develop/20240101_120000
       │
       ▼
删除测试/文档等文件
       │
       ▼
执行 PyInstaller 打包
       │
       ▼
切换回原分支 (develop)
       │
       ▼
删除临时分支

输出目录结构

dist/CertFlow/
├── CertFlow.exe              # 主程序
├── start.bat                 # Windows 启动脚本
├── start.sh                  # Linux 启动脚本
├── README.txt                # 使用说明
├── config/                   # 配置文件（可修改）
│   ├── config.yaml
│   ├── query_fields.yaml
│   ├── ui.yaml
│   └── userconfig.yaml       # 运行时生成
├── resources/                # 资源文件
│   └── icons/
└── data/                     # 数据文件
    └── templates/            # Excel 模板

配置文件处理

打包时

  • ✅ 复制 config/*.yaml 到输出目录

  • ❌ 不复制 *.yaml.example 文件

  • ❌ 不复制 schemas/ 目录

运行时

程序会读取 config/ 目录下的配置文件，如果不存在则使用默认值。

启动方式

Windows启动方式

# 方式1：双击启动脚本
start.bat

# 方式2：直接运行
CertFlow.exe

Linux / macOS 启动方式

# 添加执行权限
chmod +x start.sh
chmod +x CertFlow

# 运行
./start.sh
# 或
./CertFlow

安装包制作

Windows (Inno Setup)

创建 installer/setup.iss：

[Setup]
AppName=CertFlow
AppVersion=1.0.0
DefaultDirName={pf}\CertFlow
DefaultGroupName=CertFlow
OutputDir=dist\installer
OutputBaseFilename=CertFlow-Setup
Compression=lzma
SolidCompression=yes

[Files]
Source: "dist\CertFlow\*"; DestDir: "{app}"; Flags: recursesubdirs

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

[Run]
Filename: "{app}\CertFlow.exe"; Description: "启动 CertFlow"; Flags: postinstall nowait

编译安装包：

iscc installer\setup.iss

Linux (.deb)

# 创建 DEB 包结构
mkdir -p debian/usr/local/bin
mkdir -p debian/usr/share/certflow
mkdir -p debian/DEBIAN

# 复制文件
cp dist/CertFlow/CertFlow debian/usr/local/bin/
cp -r dist/CertFlow/config debian/usr/share/certflow/
cp -r dist/CertFlow/resources debian/usr/share/certflow/

# 创建控制文件
cat > debian/DEBIAN/control << EOF
Package: certflow
Version: 1.0.0
Section: utils
Priority: optional
Architecture: amd64
Maintainer: CertFlow Team
Description: Certificate Management System
EOF

# 打包
dpkg-deb --build debian certflow_1.0.0_amd64.deb

Docker 镜像

FROM python:3.11-slim

# 安装依赖
RUN apt-get update && apt-get install -y \
    libxcb-xinerama0 \
    libxcb-icccm4 \
    libxcb-image0 \
    && rm -rf /var/lib/apt/lists/*

# 复制打包产物
COPY dist/CertFlow /app/certflow

WORKDIR /app/certflow

# 运行
CMD ["./CertFlow"]

构建镜像：

docker build -t certflow:latest .
docker run --rm -it certflow:latest

CI/CD 自动化（GitHub Actions）

name: Build and Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3

      - name: Install dependencies
        run: uv sync

      - name: Build
        run: python scripts/build/build_exe.py --no-git

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: certflow-windows
          path: dist/CertFlow/

  build-linux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3

      - name: Install dependencies
        run: uv sync

      - name: Build
        run: python scripts/build/build_exe.py --no-git

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: certflow-linux
          path: dist/CertFlow/

  release:
    needs: [build-windows, build-linux]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4

      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          files: |
            certflow-windows/**/*
            certflow-linux/**/*

常见问题

Q: 打包后运行提示找不到配置文件？

A: 确保 config/ 目录与可执行文件在同一级目录下。

Q: 如何减小打包体积？

A:

  1. 使用 UPX 压缩：upx --best CertFlow.exe

  2. 排除不必要的库：在 spec 文件中配置 excludes

  3. 使用虚拟环境，只安装必需依赖

Q: 打包后程序运行报错？

A:

  1. 使用 --console 模式重新打包查看错误信息

  2. 检查 logs/certflow.log 日志文件

  3. 确认配置文件格式正确

Q: 如何在打包后修改配置？

A: 配置文件外置在 config/ 目录下，直接编辑即可，无需重新打包。

发布检查清单

  • [ ] 运行所有测试：uv run pytest

  • [ ] 检查版本号：config/config.yaml 和 pyproject.toml

  • [ ] 执行打包：scripts\build\build.bat 或 bash scripts/build/build.sh

  • [ ] 测试启动：dist/CertFlow/start.bat 或 ./start.sh

  • [ ] 验证配置文件复制正确

  • [ ] 创建 Git 标签：git tag v1.0.0

  • [ ] 推送标签触发 CI：git push --tags

快速参考

# 安装依赖
uv sync
uv add --dev pyinstaller

# 打包
python scripts/build/build_exe.py          # 分支隔离模式
python scripts/build/build_exe.py --no-git # 当前分支直接打包

# 仅清理
python scripts/build/build_exe.py --clean-only

# 运行打包产物
cd dist/CertFlow
./start.sh      # Linux/Mac
start.bat       # Windows