Stirling-PDF文件转换服务故障排查与解决方案

问题背景

在Stirling-PDF项目0.43.1版本中，用户反馈使用"任意文件转PDF"功能时出现系统错误。该功能依赖LibreOffice的UNO接口进行文档转换，但在RHEL 9服务器环境下执行失败，错误信息显示UNO服务连接被拒绝。

技术分析

架构变更影响

自0.42.0版本起，项目进行了重大架构调整：

1. 弃用老旧的unoconv工具
2. 采用新的unoserver+unoconvert组合方案
3. 服务通信端口默认变更为2003

错误根源

日志显示的核心错误是ConnectionRefusedError，表明：

• Python的xmlrpc客户端无法连接到UNO服务
• 服务可能未启动或监听配置不正确
• 防火墙可能阻止了端口通信

解决方案

服务部署方案

推荐采用systemd管理unoserver服务，以下是标准配置：

[Unit]
Description=UNO Document Conversion Service
After=network.target

[Service]
Type=simple
User=pdfservice
ExecStart=/usr/local/bin/unoserver --port 2003 --interface 0.0.0.0
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

关键配置说明

1. 用户权限：建议使用非root专用用户运行
2. 网络绑定：必须指定0.0.0.0以允许本地连接
3. 端口设置：需与Stirling-PDF的settings.yml配置一致
4. 自动恢复：配置故障后5秒自动重启

版本兼容建议

对于生产环境用户：

• 需要长期稳定的用户可停留在0.41.0版本
• 升级到新版必须同步部署unoserver服务
• 建议先在测试环境验证服务连通性

最佳实践

1. 服务验证命令：

netstat -tulnp | grep 2003
curl http://localhost:2003

2. 日志监控要点：

• 检查unoserver启动日志
• 监控Stirling-PDF的连接错误
• 记录文档转换耗时

3. 性能优化建议：

• 调整UNO服务线程数
• 配置文档转换超时时间
• 建立服务健康检查机制

总结

通过将unoserver转为系统服务管理，不仅解决了当前连接问题，还为后续维护提供了标准化方案。建议所有升级到0.42.0+版本的用户都采用这种服务化部署方式，确保文档转换功能的稳定运行。