Umami 项目中的 CORS 头部缺失问题分析与解决方案

问题背景

在 Umami 2.16.1 版本中，当用户设置自定义收集端点(COLLECT_API_ENDPOINT)时，出现了跨域资源共享(CORS)头部缺失的问题。这个问题导致网站访问数据无法被正确收集，因为浏览器会阻止跨域请求。

问题原因分析

经过深入调查，发现问题的根源在于 Umami 的 CORS 头部设置机制：

1. 默认配置限制：Umami 默认只在 /api/* 路径下设置 CORS 头部，当用户设置的自定义收集端点不在 /api/ 路径下时，这些必要的头部信息就不会被包含在响应中。

2. Docker 部署的特殊性：在 Docker 环境中，问题表现略有不同。Docker 版本使用了一个中间件(middleware.js)来处理请求，这个中间件使用了 NextResponse.rewrite(url) 方法，但该方法不会自动转发响应头部，导致 CORS 头部丢失。

解决方案

针对这个问题，社区提出了以下解决方案：

1. 代码修复：通过修改代码，使 CORS 头部能够被设置在任何自定义收集端点上，而不仅限于 /api/ 路径。这个修复已经被合并到主分支中。

2. 临时解决方案：

   • 对于非 Docker 部署，可以暂时将收集端点设置为 /api/ 路径下的地址
   • 对于 Docker 部署，可以通过反向代理(如 Nginx)手动添加 CORS 头部
   • 使用 CDN 服务商的转换规则添加必要的 CORS 头部

技术细节

在修复后的版本中，一个正常的 OPTIONS 请求响应应该包含以下头部：

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: GET, DELETE, POST, PUT
Access-Control-Max-Age: 86400

这些头部确保了浏览器能够正确执行跨域请求，允许从任何来源(*)发送请求，支持多种 HTTP 方法，并设置了头部缓存时间。

版本兼容性

这个问题在 2.16.1 版本中被发现，并在后续版本中得到了修复。用户可以通过升级到最新版本来解决这个问题。对于无法立即升级的用户，可以采用上述临时解决方案。

总结

CORS 问题在现代 web 应用中很常见，特别是在涉及跨域数据收集的场景中。Umami 项目通过社区贡献解决了这个特定问题，展示了开源协作的优势。对于使用自定义收集端点的用户，建议升级到包含修复的版本，或者根据部署环境选择合适的临时解决方案。

理解这类问题的本质有助于开发人员更好地调试和解决类似的前后端交互问题，特别是在涉及跨域请求的复杂场景中。