思源笔记 S3 同步兼容性问题分析与解决方案

问题背景

思源笔记在使用 S3 协议进行数据同步时，部分云服务提供商（如腾讯云 COS、阿里云 OSS、缤纷云等）在 HTTPS 协议下会出现同步失败的问题。这一问题主要源于 AWS SDK 在 v1.33.0 版本中引入的 checksum 模块 v1.5.0 的新特性。

技术分析

问题根源

AWS SDK 在更新后默认启用了严格的校验机制，具体表现为：

1. 在 HTTPS 连接时会使用 aws-chunked 编码方式
2. 增加了对 x-amz-content-sha256 值的校验
3. 部分 S3 兼容服务商尚未完全支持这些新特性

错误表现

用户在使用受影响的服务商时，会遇到如下错误提示：

upload lock sync failed: operation error S3: PutObject, https response error StatusCode: 400, RequestID: 67AAF92CD4BE203039C9E353, HostID: sunhy-host.oss-cn-beijing.aliyuncs.com, api error InvalidArgument: aws-chunked encoding is not supported with the specified x-amz-content-sha256 value.

解决方案

临时解决方案

对于急需使用的用户，可以采取以下临时措施：

1. 将同步协议从 HTTPS 改为 HTTP（不推荐长期使用）
2. 回退到之前的稳定版本

官方修复方案

思源笔记开发团队已针对此问题发布了修复方案，核心修改是禁用 AWS SDK 的严格校验机制：

as3.NewFromConfig(cfg, func(o *as3.Options) {
    o.RequestChecksumCalculation = aws.RequestChecksumCalculationWhenRequired
    o.ResponseChecksumValidation = aws.ResponseChecksumValidationWhenRequired
}

同步过程优化

在修复版本中，同步过程会分两个阶段进行：

1. 上传数据分块（chunk）
2. 上传数据文件（file）

这是正常的设计，用户无需担心看到两次进度条的情况。

最佳实践建议

1. 建议所有设备升级到最新修复版本
2. 如遇到同步问题，可考虑重建云端和本地数据仓库
3. 避免多个设备同时进行同步操作
4. 定期检查同步日志，确保同步过程正常

服务商适配情况

目前已知各云服务商的适配情况如下：

• 七牛云：完全兼容，无同步问题
• 缤纷云：已更新支持 chunked checksum 校验
• 腾讯云 COS：大部分情况下工作正常，偶发 magic number 不匹配提示
• 阿里云 OSS：仍存在兼容性问题

总结

思源笔记团队已针对 S3 同步兼容性问题提供了完善的解决方案。建议用户升级到最新修复版本，并按照最佳实践进行操作。对于仍存在问题的服务商，开发团队将持续跟进并优化兼容性。