InvoiceNinja 自托管版 PDF 生成问题排查指南

问题背景

在使用 InvoiceNinja 自托管版本（v5.10.10）时，用户遇到了 PDF 生成相关的技术问题。主要表现为两种 PDF 生成引擎（hosted_ninja 和 snappdf）都无法正常工作，系统日志中出现了不同的错误信息。

技术分析

1. 问题现象分类

hosted_ninja 引擎问题表现：

• 虽然 PDF 能够正常渲染显示
• 但系统日志中持续记录错误："The process has been signaled with signal "6""

snappdf 引擎问题表现：

• 完全无法生成 PDF 文件
• 系统日志报错："error while loading shared libraries: libgbm.so.1"

2. 根本原因分析

经过深入排查，发现问题根源在于以下几个方面：

1. 系统依赖库缺失：

   • snappdf 需要 libgbm.so.1 库支持
   • 虽然用户已安装 mesa-libgbm 相关包，但可能存在路径或版本兼容性问题

2. 文件权限配置不当：

   • chrome_crashpad_handler 文件未设置为可执行状态
   • 这是导致 snappdf 无法正常工作的关键因素

3. 临时目录权限问题：

   • /tmp/Crashpad 目录缺失或权限不足
   • 系统临时目录中自动生成的 systemd-private-* 目录被误删

解决方案

1. 针对 snappdf 引擎的完整修复步骤

1. 验证依赖库安装：

   sudo dnf install mesa-libgbm mesa-libgbm-devel
   

2. 设置文件可执行权限：

   chmod +x vendor/beganovich/snappdf/versions/*/chrome-linux/chrome
   chmod +x vendor/beganovich/snappdf/versions/*/chrome-linux/chrome_crashpad_handler
   

3. 创建并配置临时目录：

   sudo mkdir -p /tmp/Crashpad
   sudo chmod 1777 /tmp/Crashpad
   

4. 升级 InvoiceNinja 到最新版本：

   • 确认升级至 v5.10.13 或更高版本

2. 针对 hosted_ninja 引擎的优化建议

虽然 hosted_ninja 引擎能够工作，但信号错误表明存在潜在问题：

1. 检查 PHP 配置中的内存限制
2. 验证服务器时间设置是否正确
3. 确保没有其他进程干扰 PDF 生成

最佳实践建议

1. 定期维护：

   • 不要随意删除 /tmp 目录下的 systemd-private-* 文件夹
   • 定期检查 PDF 生成引擎的日志输出

2. 安全考量：

   • 虽然 /tmp 目录下的临时文件生成是正常行为
   • 但应配置适当的监控策略，避免误报安全警报

3. 性能优化：

   • 对于高负载环境，建议使用 snappdf 引擎
   • 配置适当的缓存策略减少 PDF 生成压力

总结

通过系统性的问题分析和逐步验证，我们确定了 InvoiceNinja PDF 生成问题的根本原因并提供了完整的解决方案。关键点在于确保所有依赖项完整、文件权限正确以及临时目录配置得当。对于自托管用户而言，理解这些底层机制有助于更好地维护系统稳定性和可靠性。

建议用户在实施解决方案后，持续关注系统日志，并在升级新版本时注意检查相关配置是否保持正确。这些措施将确保 InvoiceNinja 的 PDF 生成功能长期稳定运行。