ONLYOFFICE DocumentServer 与 MinIO S3 存储集成问题解析

问题背景

在 ONLYOFFICE DocumentServer 7.5.1 版本中，用户报告了与 MinIO S3 存储服务集成时出现连接问题。该问题表现为 DocumentServer 无法正确连接到指定的 MinIO 端点，而是错误地尝试连接本地 127.0.0.1:443。

技术分析

配置变更

用户提供的存储配置如下：

{
  "storage": {
    "name": "storage-s3",
    "region": "us-east-1",
    "endpoint": "https://local-S3-url",
    "bucketName": "onlyoffice",
    "storageFolderName": "cache",
    "urlExpires": 604800,
    "credentialId": "AKID",
    "credentialSecret": "SAK",
    "useRequestToGetUrl": true,
    "useSignedUrl": true,
    "sslEnabled": true,
    "s3ForcePathStyle": true,
    "externalHost": ""
  }
}

问题根源

该问题的根本原因在于 ONLYOFFICE DocumentServer 从 7.5.0 版本开始将 AWS SDK 从 V2 升级到了 V3 版本。在 AWS SDK V3 中，一些配置参数名称发生了变化：

1. s3ForcePathStyle 参数被重命名为 forcePathStyle
2. 其他 AWS SDK V3 的兼容性变更

由于参数名称变更未被及时更新，导致 DocumentServer 无法正确解析存储配置，从而出现连接错误。

解决方案

ONLYOFFICE 开发团队已经确认这是一个 bug，并在内部提交了修复代码。该修复已包含在 8.0 版本中发布。

临时解决方案

对于需要使用 7.5.x 版本的用户，可以采取以下临时解决方案：

1. 回退到 7.4.1 版本（但需要注意 7.4.1 版本可能存在其他问题）
2. 等待 8.0 版本发布

验证结果

用户已确认在 8.0 版本中该问题已得到解决，与 MinIO S3 存储的集成恢复正常。

技术建议

1. 当升级到 DocumentServer 7.5.0 及以上版本时，如果使用自定义 S3 存储服务（如 MinIO），需要特别注意 AWS SDK V3 的兼容性问题
2. 建议在升级前测试存储功能
3. 关注官方文档更新，了解配置参数的最新变化

总结

ONLYOFFICE DocumentServer 与 S3 存储的集成是一个重要功能，特别是在使用非 AWS S3 服务（如 MinIO）时。本次问题凸显了在底层 SDK 升级时可能带来的兼容性问题。开发团队已及时响应并修复了该问题，用户升级到 8.0 版本即可解决。