bug: media upload in dataset items failed for azure storage account

快速结论：当 Langfuse 自托管实例使用 Azure Blob Storage 作为存储后端时，前端在数据集（dataset）中上传媒体文件时未设置 Azure 要求的 x-ms-blob-type 请求头，导致上传失败。优先排查上传请求的请求头是否包含 x-ms-blob-type: BlockBlob。

问题场景

在自托管的 Langfuse 实例中（版本 v3.197.1），后台存储后端配置为 Azure Blob Storage，用户通过前端 UI 向数据集（dataset items）上传媒体文件时触发报错。

报错原文

<Error><Code>MissingRequiredHeader</Code><Message>An HTTP header that's mandatory for this request is not specified.
RequestId:ac0c2acb-901e-005d-62c8-04717d000000
Time:2026-06-25T17:34:48.3352843Z</Message><HeaderName>x-ms-blob-type</HeaderName></Error>

原因分析

Langfuse 前端 useDatasetItemMediaUpload hook 中的上传代码（PR #14257 引入）硬编码了 S3 风格的请求头：

headers: {
    "Content-Type": file.type,
    "x-amz-checksum-sha256": sha256Hash,
}

该方式适用于 S3/MinIO 存储，但 Azure Blob Storage 在使用 SAS token 进行 PUT 上传时，强制要求设置 x-ms-blob-type 请求头（值为 BlockBlob），并且可选设置 x-ms-version。当前实现缺少这些 Azure 必需的请求头，因此 Azure 服务端返回 MissingRequiredHeader 错误。

环境排查

确认 Langfuse 部署版本是否为 v3.197.1（Issue 中复现的版本）。
确认存储后端配置为 Azure Blob Storage。
检查是否使用 SAS token 方式访问 Azure Blob Storage。

解决步骤

后端修改（推荐方案）：
将 Azure getSignedUploadUrl 方法（位于 StorageService.ts 中）改为返回额外的上传请求头信息，例如 x-ms-blob-type: BlockBlob。后端返回结构类似：
```
{
  uploadUrl: "...", 
  mediaId: "...", 
  uploadHeaders: { "x-ms-blob-type": "BlockBlob", ... }
}
```
前端修改（配合后端修改）：
修改 useDatasetItemMediaUpload hook 中的上传逻辑，不再硬编码 S3 专属请求头，而是使用后端返回的 uploadHeaders 动态设置请求头：
```
const response = await fetch(uploadUrl, {
  method: "PUT",
  body: file,
  headers: { "Content-Type": file.type, ...uploadHeaders },
});
```

以上方案可使客户端保持存储无关性，适配不同的存储后端。

验证方法

在配置了 Azure Blob Storage 的自托管 Langfuse 实例中，尝试通过 UI 向数据集上传媒体文件。若上传成功且不再返回 MissingRequiredHeader 错误，则问题解决。

注意事项

此修复方案在 Issue 中被提出并得到确认，但截至 2026-06-26 该 Issue 仍为 💉❔ unconfirmed bug 状态，尚未合并官方修复。若用户急切需要修复，可优先尝试自行打补丁或等待官方更新。

参考来源

langfuse/langfuse #14569

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

bug: media upload in dataset items failed for azure storage account