Penpot项目导出功能故障排查与解决方案

问题现象

在使用Penpot自托管部署时，用户遇到了导出功能异常的问题。具体表现为：在Web界面点击"文件->导出"后，界面显示"导出中...0/1"并卡住，浏览器未弹出预期的PNG文件下载对话框。

环境配置

该问题出现在基于Red Hat Enterprise Linux 9.5的自托管环境中，使用Podman 5.2.2和systemd Quadlets部署。涉及的容器包括：

• Penpot后端服务
• Penpot前端服务
• Penpot导出服务
• PostgreSQL数据库
• Redis缓存服务

问题分析

通过检查日志发现，虽然导出服务实际完成了文件生成工作（可通过直接访问生成的URL下载文件），但前端界面未能正确接收和处理导出完成的通知。这表明系统各组件间的通信存在异常。

深入分析日志后，发现关键线索：

1. 前端服务成功发送了导出请求到后端
2. 导出服务正常处理了请求并生成了文件
3. 前端未能接收到导出完成的通知

根本原因

问题根源在于多租户配置不一致。用户在后端服务中设置了PENPOT_TENANT=pro，但在导出服务中未做相应配置，导致两个服务使用不同的租户设置。这种不一致性使得Redis消息队列无法正确传递导出状态通知。

解决方案

解决此问题的方法很简单：

1. 确保后端和导出服务使用相同的租户配置
2. 推荐在两个服务中都设置PENPOT_TENANT=default

具体配置示例：

# 后端服务配置
PENPOT_TENANT=default

# 导出服务配置
PENPOT_TENANT=default

最佳实践建议

为避免类似问题，在部署Penpot时应注意：

1. 所有相关服务(前端、后端、导出)的租户配置必须一致
2. Redis配置需要在所有服务中保持一致
3. 确保PENPOT_PUBLIC_URI在所有服务中正确设置
4. 为安全考虑，应设置PENPOT_SECRET_KEY

总结

Penpot的导出功能依赖于多个服务间的协调工作，任何配置不一致都可能导致功能异常。通过确保各服务的租户配置一致，可以有效解决导出功能卡住的问题。这提醒我们在部署复杂系统时，需要特别注意各组件间配置的协调性和一致性。