Directus文件上传S3存储配置问题排查指南

问题背景

在使用Directus自托管服务时，用户遇到文件上传失败的问题。具体表现为系统抛出"SERVICE_UNAVAILABLE"错误，并伴随"Resolved credential object is not valid"的提示信息。这种情况通常发生在生产环境，而开发环境通过Docker重启后可以正常工作。

错误现象分析

当用户尝试上传PDF文件时，系统返回以下错误信息：

{
  "errors": [
    {
      "message": "Couldn't save file e1058a1a-4fb0-4472-99e7-ec6925f63158.pdf",
      "extensions": {
        "code": "SERVICE_UNAVAILABLE",
        "service": "files"
      }
    }
  ]
}

同时，控制台日志显示：

WARN: Couldn't save file 86ab5670-2e9f-4f5a-89cb-9184617afc7e.pdf
WARN: Resolved credential object is not valid

初步排查

1. 文件权限检查：确认了/uploads目录的所有权和权限设置为node:node，这是Directus运行时的标准配置。

2. 环境差异：问题仅出现在生产环境，开发环境通过Docker重启后正常，表明问题可能与生产环境的特定配置有关。

深入问题定位

通过进一步分析，发现问题的根源在于AWS S3存储配置。虽然用户已经设置了S3作为存储后端，但缺少了关键的认证信息：

1. 缺失的配置项：

   • STORAGE_S3_KEY
   • STORAGE_S3_SECRET

2. 错误机制：当Directus尝试使用S3存储但缺少必要的认证凭据时，系统会抛出"Resolved credential object is not valid"错误，而不是直接提示缺少认证信息。

解决方案

完整的S3存储配置应包含以下必要参数：

STORAGE_LOCATIONS=s3
STORAGE_S3_DRIVER=s3
STORAGE_S3_BUCKET=your-bucket-name
STORAGE_S3_REGION=your-region
STORAGE_S3_KEY=your-access-key-id
STORAGE_S3_SECRET=your-secret-access-key

配置建议

1. 权限最小化原则：为S3存储配置的IAM角色应仅授予必要的权限，避免使用完全控制权限。

2. 环境隔离：建议在不同环境（开发/测试/生产）使用不同的S3存储桶或前缀，可以通过STORAGE_S3_ROOT参数实现。

3. 安全存储：敏感凭证应通过安全的方式注入环境变量，避免直接写入配置文件。

总结

Directus与S3存储集成时，必须确保所有必要的认证参数都已正确配置。当遇到"Resolved credential object is not valid"错误时，应首先检查存储后端的认证配置是否完整。通过系统化的配置检查和权限验证，可以有效地解决这类文件存储服务不可用的问题。