如何解决Weights & Biases媒体文件上传失败？S3/GCS云存储配置详解

Weights and Biases（简称WandB）在训练过程中会生成大量图表、样本图片、视频和音频文件。这些媒体数据如果无法正常上传，实验记录页面就会出现空白或报错，而问题根源通常不在训练代码，而在服务器端的媒体文件存储配置。默认情况下，自托管WandB服务把媒体文件写到本地磁盘，当实例重启、容器重新调度或使用多个副本时，本地路径会失效或数据丢失，上传请求就会失败。要彻底解决，需要把媒体存储切换到Amazon S3或Google Cloud Storage这样的对象存储服务。本文会先拆解上传失败的常见原因，然后分别给出S3和GCS的完整配置步骤，最后介绍如何验证和排查权限问题。

一、媒体文件上传失败的常见原因

WandB自托管版本的媒体文件存储独立于数据库和指标存储。如果没有显式配置云存储，服务会使用容器内部的本地目录，比如 /vol/wandb/media。当Kubernetes的Pod被重新调度，或者Docker容器被重建后，这个目录中的数据可能已经不存在，但元数据仍然指向旧的媒体路径，导致前端请求媒体文件时返回404或权限错误。

另一个常见原因是桶权限不足。如果WandB服务使用的云凭据只具备读取权限，或者没有对目标桶执行 PutObject 的权限，上传阶段就会在对象存储侧返回 Access Denied。此外，私有S3兼容服务（如MinIO、Ceph RGW）需要显式指定endpoint和path-style参数，否则客户端会尝试访问AWS公共地址，导致超时。网络策略、安全组或VPC端点配置错误也会让上传请求在建立连接阶段失败。

还有一种容易忽略的情况是配置没有真正生效。WandB的媒体存储配置通常写在环境变量或 settings.yaml 文件中，如果错改了数据库配置段或者使用了旧版变量名，服务仍然会回退到本地存储，上传请求表面成功但文件没有进入云桶。因此，排查时需要结合服务启动日志，确认初始化阶段打印的存储后端类型。

二、配置Amazon S3作为媒体文件存储

使用S3之前需要准备一个专用桶，并为WandB服务创建独立的IAM用户或角色。桶的权限建议限制在最小范围，例如只允许该用户对桶执行 s3:PutObject、s3:GetObject、s3:DeleteObject 和 s3:ListBucket。如果桶开启了版本控制或加密，不会影响上传，但跨区域访问时要注意region参数必须与桶所在地一致。

WandB支持通过环境变量注入S3配置。以下示例展示了接入AWS S3需要设置的关键变量：

export WANDB_MEDIA_FILE_STORAGE_PROVIDER=s3
export WANDB_MEDIA_FILE_STORAGE_BUCKET=your-media-bucket
export WANDB_MEDIA_FILE_STORAGE_REGION=us-east-1
export WANDB_MEDIA_FILE_STORAGE_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
export WANDB_MEDIA_FILE_STORAGE_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

如果使用的是MinIO或其他S3兼容对象存储，必须额外指定endpoint地址和path-style模式，否则客户端会尝试把请求发到AWS公共区域。对应配置可以写成：

export WANDB_MEDIA_FILE_STORAGE_PROVIDER=s3
export WANDB_MEDIA_FILE_STORAGE_BUCKET=wandb-media
export WANDB_MEDIA_FILE_STORAGE_ENDPOINT_URL=https://s3.internal.ipipp.com
export WANDB_MEDIA_FILE_STORAGE_REGION=us-east-1
export WANDB_MEDIA_FILE_STORAGE_PATH_STYLE=true
export WANDB_MEDIA_FILE_STORAGE_ACCESS_KEY=minioadmin
export WANDB_MEDIA_FILE_STORAGE_SECRET_KEY=minioadmin

注意这里的endpoint示例域名为演示用途，实际应替换为自己的对象存储网关地址。配置完成后需要重启WandB服务，并观察日志中的存储初始化信息。如果使用Helm部署，也可以把这些变量写入values.yaml的 env 段落，而不是直接修改容器环境。

对于需要更细粒度控制的场景，可以创建如下IAM策略附加给WandB使用的用户或角色：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::your-media-bucket/*"
    },
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::your-media-bucket"
    }
  ]
}

这个策略把权限限制在目标桶范围内，避免误操作其他资源。如果WandB服务运行在AWS EC2或EKS上，建议使用IAM Role而不是长期Access Key，这样可以避免密钥泄露和轮换问题。

三、配置Google Cloud Storage作为媒体文件存储

GCS的配置思路与S3类似，但使用服务账号进行身份认证。首先在Google Cloud Console中创建一个专用服务账号，并授予 roles/storage.objectAdmin 角色，或者更细粒度的 storage.objects.create、storage.objects.get、storage.objects.delete 权限。下载服务账号JSON密钥后，需要把该文件挂载到WandB服务容器中，并设置环境变量指向它。

以下是GCS媒体存储的环境变量配置示例：

export WANDB_MEDIA_FILE_STORAGE_PROVIDER=gcs
export WANDB_MEDIA_FILE_STORAGE_BUCKET=your-gcs-media-bucket
export GOOGLE_APPLICATION_CREDENTIALS=/etc/wandb/gcs-service-account.json

关键点在于 GOOGLE_APPLICATION_CREDENTIALS 必须指向容器内部可读的JSON文件路径。如果使用Kubernetes Secret挂载，需要确保挂载后的路径与变量一致。部分环境会使用Workload Identity将GKE服务账号与GCS权限绑定，此时可以不提供静态密钥，但WandB仍需要能通过元数据服务器获取令牌。

如果要使用 settings.yaml 而不是环境变量，可以在WandB服务配置中加入类似下面的内容：

wandb:
  media_file_storage:
    provider: gcs
    bucket: your-gcs-media-bucket
    credentials: /etc/wandb/gcs-service-account.json

上面的YAML配置适合使用配置文件管理的部署方式，效果与环境变量等同。需要注意的是，配置文件中的密钥路径必须是WandB进程可访问的绝对路径，同时不要把这个配置文件提交到公共仓库。

GCS桶还可以设置生命周期规则自动清理过期媒体文件，但这不是上传失败的主要原因。如果上传时遇到 403 Forbidden，第一步应检查服务账号是否有该桶的写入权限，可以用 gsutil acl get gs://your-gcs-media-bucket 或 gcloud storage buckets describe 来确认。

四、验证配置与排查权限问题

完成云存储配置并重启服务后，不要急着跑完整训练。先在WandB界面中手动创建一个实验，上传一张测试图片或一段短视频，然后观察前端网络请求的响应。如果媒体上传成功，实验日志中通常会出现类似 media file upload complete 的信息，并且在对应云存储桶中能看到以实验ID为前缀的新文件。

命令行验证可以帮助区分是WandB配置问题还是云平台权限问题。对于S3，可以使用AWS CLI执行 aws s3 ls s3://your-media-bucket/ 来确认凭据和桶名是否正确。对于GCS，可以执行 gsutil ls gs://your-gcs-media-bucket/。如果这些命令也失败，说明云凭据本身有问题，需要回到IAM或服务账号设置中检查。

如果命令行可以访问桶但WandB上传仍然失败，需要查看WandB服务日志。常见错误包括存储后端初始化失败、endpoint解析错误、超时等。将日志中的错误信息与云存储服务商的错误码对照，能快速缩小范围。另外，如果前端使用预签名URL直传，还需要检查桶的CORS策略是否允许来自WandB域名的跨域请求，否则浏览器侧的上传会被拦截。

对于大规模部署，建议把媒体文件存储切换为云存储后，定期检查桶中是否存在孤儿文件，并配置合适的生命周期策略。S3和GCS都支持按对象年龄自动删除或转移存储类别，这有助于控制成本。同时，确保WandB服务的多个副本共用同一云存储桶，避免不同副本各自写本地磁盘造成数据不一致。

WandB媒体文件上传S3云存储配置GCS云存储配置修改时间：2026-08-30 00:40:04