Documenso项目S3存储文件上传CORS问题解决方案

问题背景

在使用Documenso文档签名服务的最新版本时，用户通过Docker Compose部署后发现前端文件上传功能出现异常。具体表现为：当配置使用Hetzner托管的S3存储桶替代默认数据库存储时，前端界面上传文件会失败并显示通用错误信息。

问题分析

经过深入排查，发现问题的根源在于跨域资源共享(CORS)策略配置不当。Documenso采用了一种高效的文件上传机制：服务端生成预签名URL后，前端直接向S3存储桶发起上传请求。这种设计虽然减少了服务器负载，但要求S3存储桶必须正确配置CORS策略以允许来自Documenso前端域的跨域请求。

解决方案

要解决此问题，需要对S3存储桶进行以下配置调整：

1. CORS策略配置：在S3存储桶设置中添加适当的CORS规则，允许Documenso前端域发起跨域请求。典型配置应包括：

   • 允许的来源(AllowedOrigins)：设置为Documenso前端部署的域名
   • 允许的方法(AllowedMethods)：至少包含PUT和POST方法
   • 允许的头部(AllowedHeaders)：应包括Content-Type等必要头部

2. 权限验证：确保预签名URL生成时使用的IAM凭证具有足够的权限执行上传操作，同时存储桶策略也应允许这些操作。

实施建议

对于使用Hetzner S3服务的用户，建议采用以下具体步骤：

1. 登录Hetzner存储控制台
2. 导航至目标存储桶的CORS配置页面
3. 添加新的CORS规则，配置适当的来源、方法和头部
4. 保存配置并等待生效(通常需要几分钟)

技术原理

这种设计模式体现了现代Web应用的最佳实践：

• 减轻服务器负担：通过直接前端到S3的上传，避免了文件数据经过应用服务器
• 提高扩展性：S3服务天然适合处理大文件上传和存储
• 安全性保障：预签名URL提供了临时、有限的访问权限

注意事项

实施解决方案时需注意：

• CORS配置更改可能需要时间生效
• 生产环境应考虑添加更精细的CORS规则限制
• 对于敏感操作，建议在存储桶策略中添加额外的IP限制条件

通过正确配置CORS策略，Documenso与S3存储服务的集成将能够正常工作，为用户提供流畅的文件上传体验。