CertFlow 安装指南

系统要求

硬件要求

• CPU: 双核 2.0GHz+ (推荐四核)

• 内存: 4GB+ (推荐 8GB)

• 磁盘空间: 1GB+ (含数据和日志)

• 显示器: 1366x768+ (推荐 1920x1080)

软件要求

• 操作系统:

  • Windows 10/11 (64位)

  • Windows Server 2019+

  • Linux (Ubuntu 20.04+, CentOS 7+)

  • macOS 11+ (实验性支持)

• Python: 3.11, 3.12, 3.13

• 包管理器: uv 0.5+

• 数据库: SQLite (内置) 或 MySQL 8.0+ (可选)

网络要求

• 内网部署：无需互联网（首次安装除外）

• 公网部署：需要访问 PyPI 镜像源

安装步骤

1. 克隆项目

# 使用 HTTPS
git clone https://github.com/your-repo/CertFlow-PySide6.git

# 使用 SSH
git clone git@github.com:your-repo/CertFlow-PySide6.git

# 进入项目目录
cd CertFlow-PySide6

2. 安装 uv（如果未安装）

# Windows (PowerShell 管理员)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux/Mac
curl -LsSf https://astral.sh/uv/install.sh | sh

# 验证安装
uv --version

企业内网环境（使用代理）：

# Windows PowerShell
$env:HTTP_PROXY="http://proxy.company.com:8080"
$env:HTTPS_PROXY="http://proxy.company.com:8080"

# Linux/Mac
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

3. 安装依赖（新版 uv 方式）

# 基础安装（仅生产依赖）
uv sync

# 开发环境安装（推荐）
uv sync --group full-dev

# 文档维护者安装
uv sync --group docs-maintainer

# CI/CD 环境安装
uv sync --group ci

# 安装特定依赖组
uv sync --group docs --group lint

# 查看安装详情
uv tree --depth 2

各场景依赖组说明：

场景	命令	包含的依赖组	说明
生产部署	uv sync	无	仅运行时依赖
普通开发	uv sync --group dev	dev	基础开发工具
完整开发	uv sync --group full-dev	dev, docs, lint, typing, test	所有开发工具
文档编写	uv sync --group docs-maintainer	docs, dev	文档专用环境
CI/CD	uv sync --group ci	test, lint, typing	自动化测试环境
代码检查	uv sync --group lint	lint	仅代码格式化

4. 初始化配置

# 创建必要目录（自动）
uv run python scripts/setup_dirs.py

# 或手动创建
mkdir -p config database logs temp output backups

# 复制配置文件模板
cp config/config.yaml.example config/config.yaml

# 编辑配置文件（根据实际环境修改）
# Windows
notepad config/config.yaml

# Linux/Mac
vim config/config.yaml

setup_dirs.py 脚本内容：

#!/usr/bin/env python
import os
from pathlib import Path

def setup_directories():
    """创建项目所需目录"""
    dirs = ['config', 'database', 'logs', 'temp', 'output', 'backups']
    for dir_name in dirs:
        Path(dir_name).mkdir(exist_ok=True)
        print(f"✓ 创建目录: {dir_name}")

    # 设置权限（Linux/Mac）
    if os.name != 'nt':
        os.system('chmod 755 config database logs temp output backups')

    print("✅ 目录初始化完成")

if __name__ == '__main__':
    setup_directories()

5. 配置数据库

# 初始化数据库
uv run python scripts/init_db.py

# 或使用数据库迁移
uv run alembic upgrade head

# 验证数据库连接
uv run python -c "
from certflow.utils.database import DatabaseManager
db = DatabaseManager()
db.init_db()
print('✅ 数据库连接成功')
"

6. 运行程序

# 开发模式（使用 uv）
uv run python src/certflow/main.py

# 或激活虚拟环境后运行
# Windows
.venv\Scripts\activate
python src/certflow/main.py

# Linux/Mac
source .venv/bin/activate
python src/certflow/main.py

# 生产模式（打包后）
# Windows
dist\certflow\certflow.exe

# Linux
./dist/certflow/certflow

# 带参数运行
python src/certflow/main.py --config config/production.yaml --debug

7. 验证安装

# 验证配置文件
uv run python -c "from certflow.config import Config; Config(); print('✅ 配置加载成功')"

# 验证导入模块
uv run python -c "import certflow; print(f'✅ CertFlow v{certflow.__version__}')"

# 测试所有组件
uv run pytest tests/test_imports.py -v

# 查看日志
# Windows
type logs\certflow.log

# Linux/Mac
tail -f logs/certflow.log

环境配置选项

开发环境配置

# 1. 安装 pre-commit 钩子
uv run pre-commit install

# 2. 配置 Git 钩子
uv run pre-commit run --all-files

# 3. 设置环境变量（可选）
# Windows
set CERTFLOW_ENV=development
set CERTFLOW_DEBUG=1

# Linux/Mac
export CERTFLOW_ENV=development
export CERTFLOW_DEBUG=1

生产环境配置

# 1. 设置生产环境变量
export CERTFLOW_ENV=production
export CERTFLOW_LOG_LEVEL=INFO

# 2. 配置 systemd 服务（Linux）
sudo cp scripts/certflow.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable certflow
sudo systemctl start certflow

# 3. 配置 Windows 服务（使用 NSSM）
nssm install CertFlow "C:\CertFlow\certflow.exe"
nssm set CertFlow AppParameters "--config config/production.yaml"
nssm start CertFlow

Windows 服务配置示例

@echo off
REM 安装为 Windows 服务
sc create CertFlow binPath= "C:\CertFlow\certflow.exe" start= auto
sc description CertFlow "CertFlow 合格证打印管理系统"
sc start CertFlow

Docker 部署

使用 Docker Compose（推荐）

创建 docker-compose.yml：

version: '3.8'

services:
  certflow:
    build: .
    container_name: certflow
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
      - ./config:/app/config
      - ./logs:/app/logs
      - ./output:/app/output
      - ./backups:/app/backups
    environment:
      - CERTFLOW_ENV=production
      - TZ=Asia/Shanghai
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import certflow; exit(0)"]
      interval: 30s
      timeout: 10s
      retries: 3

构建镜像

# 标准构建
docker build -t certflow:latest .

# 多架构构建
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t certflow:latest .

# 指定构建参数
docker build \
  --build-arg UV_GROUP=full-dev \
  --build-arg PYTHON_VERSION=3.11 \
  -t certflow:dev .

Dockerfile 示例

# 多阶段构建
FROM ghcr.io/astral-sh/uv:python3.11 AS builder
WORKDIR /app

# 复制依赖文件
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

# 复制源代码
COPY src/ ./src/
COPY config/ ./config/
COPY scripts/ ./scripts/

# 最终镜像
FROM python:3.11-slim
WORKDIR /app

# 安装运行时依赖
RUN apt-get update && apt-get install -y \
    libxcb-xinerama0 \
    libxcb-icccm4 \
    libxcb-image0 \
    libxcb-keysyms1 \
    libxcb-randr0 \
    libxcb-render-util0 \
    libxcb-shape0 \
    libxcb-xfixes0 \
    libxcb-xkb1 \
    libxkbcommon-x11-0 \
    && rm -rf /var/lib/apt/lists/*

# 复制虚拟环境
COPY --from=builder /app/.venv /app/.venv
COPY --from=builder /app/src /app/src
COPY --from=builder /app/config /app/config

ENV PATH="/app/.venv/bin:$PATH"
ENV PYTHONPATH="/app/src"

# 创建数据目录
RUN mkdir -p /app/data /app/logs /app/output /app/backups

# 非 root 用户运行
RUN useradd -m -u 1000 certflow && \
    chown -R certflow:certflow /app
USER certflow

EXPOSE 8080
CMD ["python", "src/certflow/main.py"]

运行容器

# 使用 docker-compose
docker-compose up -d

# 查看日志
docker-compose logs -f certflow

# 停止服务
docker-compose down

# 使用 docker run
docker run -d \
  --name certflow \
  --restart unless-stopped \
  -p 8080:8080 \
  -v ./data:/app/data \
  -v ./config:/app/config \
  -v ./logs:/app/logs \
  -v ./output:/app/output \
  -v ./backups:/app/backups \
  -e TZ=Asia/Shanghai \
  certflow:latest

# 进入容器调试
docker exec -it certflow bash

打包成可执行文件

Windows 打包

# 安装打包依赖
uv sync --group full-dev

# 使用 PyInstaller 打包
uv run pyinstaller certflow.spec

# 或使用自动化脚本
scripts\build.bat

# 输出位置
# dist\certflow\certflow.exe
# dist\installer\CertFlow-Setup.exe (如果配置了 Inno Setup)

certflow.spec 示例：

# -*- mode: python -*-
block_cipher = None

a = Analysis(
    ['src/certflow/main.py'],
    pathex=[],
    binaries=[],
    datas=[
        ('config/*.yaml', 'config'),
        ('src/certflow/views/*.ui', 'certflow/views'),
    ],
    hiddenimports=['PySide6.QtXml'],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    noarchive=False,
)

pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)

exe = EXE(
    pyz,
    a.scripts,
    a.binaries,
    a.datas,
    [],
    name='certflow',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    upx_exclude=[],
    runtime_tmpdir=None,
    console=True,  # GUI应用改为 False
    disable_windowed_traceback=False,
    argv_emulation=False,
    target_arch=None,
    codesign_identity=None,
    entitlements_file=None,
    icon='resources/icon.ico',
)

Linux 打包

# 安装依赖
uv sync --group full-dev

# 打包
uv run pyinstaller certflow-linux.spec

# 创建 .deb 包（Ubuntu/Debian）
scripts/build-deb.sh

# 创建 .rpm 包（CentOS/RHEL）
scripts/build-rpm.sh

依赖管理最佳实践

添加新依赖

# 添加到生产依赖
uv add requests

# 指定版本范围
uv add "pandas>=2.0,<3.0"

# 从 GitHub 安装
uv add "sqlalchemy @ git+https://github.com/sqlalchemy/sqlalchemy.git"

# 添加到开发依赖组
uv add --group dev pytest-xdist

# 添加到文档依赖组
uv add --group docs sphinx-rtd-theme

# 同时添加到多个组
uv add --group dev --group test pytest-mock

更新依赖

# 更新所有依赖
uv sync --upgrade

# 更新特定包
uv add --upgrade sqlalchemy

# 更新依赖组
uv sync --group docs --upgrade

# 检查可更新的包
uv pip list --outdated

移除依赖

# 移除生产依赖
uv remove requests

# 移除开发依赖
uv remove --group dev pytest-xdist

# 清理未使用的依赖
uv remove --unused

配置验证

# 完整配置验证
uv run python scripts/validate_config.py

# 验证配置文件
uv run python -c "from certflow.config import Config; Config(); print('✅ 配置加载成功')"

# 测试数据库连接
uv run python -c "
from certflow.utils.database import DatabaseManager
db = DatabaseManager()
db.init_db()
print('✅ 数据库连接成功')
"

# 验证依赖组
uv run python -c "
import importlib.metadata
packages = ['sphinx', 'pytest', 'ruff', 'mypy']
for pkg in packages:
    try:
        version = importlib.metadata.version(pkg)
        print(f'✅ {pkg}: {version}')
    except:
        print(f'❌ {pkg}: 未安装')
"

# 验证 Qt 环境
uv run python -c "
from PySide6.QtWidgets import QApplication
import sys
app = QApplication(sys.argv)
print('✅ Qt 环境正常')
"

故障排除

常见问题及解决方案

1. 依赖安装失败

# 清理缓存重新安装
uv cache clean
uv sync --reinstall

# 使用不同的镜像源
UV_INDEX_URL=https://pypi.org/simple uv sync

# 跳过损坏的包
uv sync --no-build-isolation

# 查看详细错误
RUST_BACKTRACE=1 uv sync

2. 虚拟环境问题

# 重新创建虚拟环境
rm -rf .venv  # Linux/Mac
rd /s /q .venv  # Windows

uv venv --python 3.11
uv sync --group full-dev

# 查看虚拟环境信息
uv venv --info

# 修复虚拟环境路径
uv venv --relocatable

3. 配置文件格式错误

# 验证 YAML 语法
uv run python -c "import yaml; yaml.safe_load(open('config/config.yaml'))"

# 使用配置验证工具
uv run python scripts/validate_config.py

# 恢复默认配置
cp config/config.yaml.example config/config.yaml

4. 数据库连接失败

# 检查数据库文件权限
ls -la database/  # Linux/Mac
icacls database\  # Windows

# 重建数据库
rm database/certflow.db  # 备份后删除
uv run python scripts/init_db.py

# 检查 SQLite 版本
uv run python -c "import sqlite3; print(sqlite3.sqlite_version)"

5. Qt 相关错误（Windows）

# 重新安装 PySide6
uv remove PySide6
uv add PySide6

# 检查 DLL 依赖
dumpbin /dependents .venv\Lib\site-packages\PySide6\Qt6Core.dll

# 安装 Visual C++ Redistributable
# 下载: https://aka.ms/vs/17/release/vc_redist.x64.exe

6. 内存不足错误

# 限制并行任务数
UV_CONCURRENT_DOWNLOADS=1 uv sync

# 使用交换空间（Linux）
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 增加虚拟内存（Windows）
# 系统属性 → 高级 → 性能设置 → 高级 → 虚拟内存

7. 网络超时问题

# 增加超时时间
UV_HTTP_TIMEOUT=300 uv sync

# 使用镜像源
# 已在 pyproject.toml 中配置腾讯云镜像
# 如需临时使用官方源
uv sync --index-url https://pypi.org/simple

# 企业代理设置
set HTTP_PROXY=http://proxy.company.com:8080
set HTTPS_PROXY=http://proxy.company.com:8080

8. 权限错误

# Linux/Mac - 修复权限
chmod -R 755 .venv
chown -R $USER:$USER .

# Windows - 以管理员运行
# 右键 PowerShell → 以管理员身份运行

# Docker 权限
sudo chown -R $USER:$USER ./data

调试模式

# 启用详细日志
set RUST_LOG=debug  # Windows
export RUST_LOG=debug  # Linux/Mac

# 查看详细安装过程
uv sync --verbose

# 生成依赖图
uv tree --depth 3 > dependencies.txt

# 导出环境信息
uv pip freeze > requirements.txt
uv run python -m certflow.utils.sysinfo

开发工作流

首次设置

# 克隆项目
git clone <repo-url>
cd CertFlow-PySide6

# 安装完整开发环境
uv sync --group full-dev

# 安装 pre-commit 钩子
uv run pre-commit install

# 初始化数据库
uv run python scripts/init_db.py

# 运行测试验证
uv run pytest tests/ -v

# 启动开发服务器
uv run python src/certflow/main.py --debug

日常开发

# 激活环境
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate      # Windows

# 运行应用
python src/certflow/main.py

# 运行测试
pytest tests/ -v
pytest tests/test_certificate.py -v  # 特定测试
pytest -m "not slow"  # 跳过慢速测试

# 代码格式化
ruff format src/
ruff check --fix src/

# 类型检查
mypy src/
pyright

# 生成测试覆盖率
pytest --cov=certflow --cov-report=html
# 打开 htmlcov/index.html

# 查看文档
cd docs && make html
open _build/html/index.html

代码审查前

# 运行所有检查
scripts/pre-commit.sh

# 或单独运行
ruff check src/
black --check src/
mypy src/
pytest tests/

备份与恢复

自动备份

# 创建备份脚本
cat > scripts/backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p $BACKUP_DIR
cp database/certflow.db $BACKUP_DIR/
cp config/config.yaml $BACKUP_DIR/
tar -czf $BACKUP_DIR/logs.tar.gz logs/
echo "备份完成: $BACKUP_DIR"
EOF

chmod +x scripts/backup.sh

# 定期备份（crontab）
0 2 * * * /path/to/CertFlow-PySide6/scripts/backup.sh

恢复数据

# 恢复数据库
cp backups/20240101_020000/certflow.db database/

# 恢复配置
cp backups/20240101_020000/config.yaml config/

# 恢复日志
tar -xzf backups/20240101_020000/logs.tar.gz

性能优化建议

依赖缓存优化

# 使用本地缓存目录
export UV_CACHE_DIR=/path/to/cache

# 离线安装（需要预先缓存）
uv sync --frozen --offline

# 共享缓存（CI/CD）
export UV_CACHE_DIR=/shared/cache/uv

镜像源配置

# pyproject.toml 中已配置腾讯云镜像
# 如需临时使用官方源
uv sync --index-url https://pypi.org/simple

# 多镜像源配置
[[tool.uv.index]]
url = "https://mirrors.cloud.tencent.com/pypi/simple/"
default = true

[[tool.uv.index]]
url = "https://pypi.org/simple"

安全更新

# 检查依赖安全漏洞
uv audit

# 更新有漏洞的依赖
uv add --upgrade <package>

# 生成依赖清单（用于安全审计）
uv pip freeze > requirements.txt

# 使用 safety 检查
uv run safety check -r requirements.txt

迁移指南

从旧版本迁移

# 1. 备份数据
scripts/backup.sh

# 2. 拉取新代码
git pull origin main

# 3. 更新依赖
uv sync --group full-dev --upgrade

# 4. 运行数据库迁移
uv run alembic upgrade head

# 5. 验证配置
uv run python scripts/validate_config.py

# 6. 测试运行
uv run python src/certflow/main.py --test

获取帮助

• 📖 用户指南

• 🔧 开发文档

• 🐛 问题反馈

• 💬 社区讨论

卸载

# 删除虚拟环境
rm -rf .venv

# 删除数据（注意备份）
rm -rf database/ logs/ output/

# 删除配置文件
rm -rf config/

# 删除打包文件
rm -rf dist/ build/

# 卸载服务（Windows）
sc delete CertFlow

---

✅ 安装完成后，请阅读 用户指南 了解如何使用