CertFlow 故障排查指南¶

🚀 启动故障¶

问题：启动时闪退¶

排查步骤：

检查日志文件：logs/certflow.log
检查配置文件是否完整
检查数据库文件是否损坏

解决方案：

# 使用备份数据库
cp database/backups/certflow.db data/db/certflow.db

问题：提示 "No module named 'certflow'"¶

解决方案：

# 重新安装
uv sync
# 或
pip install -e .

🖨️ 打印故障¶

问题：打印输出为空白¶

排查步骤：

检查打印机碳带/墨盒
检查打印机驱动
检查打印模板配置

解决方案：

# 测试打印机
python -m certflow.cli print_cert --ids 1 --printer "测试"

问题：打印位置偏移¶

排查步骤：

检查模板坐标配置
检查纸张大小设置

解决方案：

# config/templates/coordinates.yaml
x_offset: 5   # 水平偏移（毫米）
y_offset: 3   # 垂直偏移（毫米）

问题：打印机无响应¶

排查步骤：

确认打印机已开机并连接
检查打印机名称配置

解决方案：

# 列出可用打印机
python -c "from certflow.services.printer_manager import PrinterManager; print(PrinterManager.get_available_printers())"

💾 数据库故障¶

问题：数据库被锁定¶

排查步骤：

检查是否有其他进程占用
检查是否有未提交的事务

解决方案：

# 在代码中确保事务提交
session.commit()
# 或回滚
session.rollback()

问题：数据导入失败¶

排查步骤：

检查 Excel 格式
检查列映射配置
检查数据唯一键冲突

解决方案：

# 预览模式
python -m certflow.cli import_sales_plan -f file.xlsx --dry-run

📊 Excel导入故障¶

问题：读取Excel失败¶

排查步骤：

检查文件是否被占用
检查文件格式是否正确
检查是否有密码保护

解决方案：

# 转换为CSV再导入
# 使用 pandas 读取
python -c "import pandas as pd; df = pd.read_excel('file.xlsx'); df.to_csv('file.csv')"

问题：列映射错误¶

排查步骤：

检查 Excel 表头
检查 config/columns.yaml 配置

解决方案：

# config/columns.yaml
mappings:
  customer_name: "客户名称"
  product_model: "型号"
  # 添加自定义映射

🐌 性能问题¶

问题：启动慢¶

排查步骤：

检查数据库大小
检查配置文件加载

解决方案：

# 清理日志
rm -rf logs/*.zip
# 压缩数据库
python -m certflow.cli db_sync --vacuum

问题：查询慢¶

排查步骤：

检查查询条件
检查数据库索引

解决方案：

-- 创建索引
CREATE INDEX idx_sale_plans_customer ON sale_plans(customer_name);
CREATE INDEX idx_sale_plans_create_date ON sale_plans(create_date);

📋 日志位置¶

日志类型	路径	说明
应用日志	`logs/certflow.log`	当前日志
旧日志压缩	`logs/certflow.*.log.zip`	历史日志
查询日志	`logs/query_*.sql`	SQL查询记录

🆘 获取更多帮助¶

查看日志文件
```
tail -f logs/certflow.log
```
运行调试模式
```
python run.py --debug
```
提交 Issue https://github.com/your-repo/CertFlow-PySide6/issues

请附上：
- 操作步骤
- 错误日志
- 系统环境信息