近期 (3.1.1X) 版本起出现的 S3 同步失败常见问题排查

在最近的某个版本（大约在 3.1.17 上下），思源更新了 S3 的支持库，带来了更加严格的设置校验。如果以前在某些地方填写的配置不规范，就算之前能够同步成功，现在也会卡在检查配置的环节。

配置界面介绍

配置界面的截图如上。具体的在若干教程中都有相应介绍。

这里有近期新加的配置项 Concurrent Reqs，这个是同步时的线程数，如果每次同步都需要花费几十秒甚至更长的时间可以适当调大。这里的默认值在 S3 为 8，Webdav 为 1，可以手动调整线程数。比如部分 Webdav 不支持并发可以设置为 1，如果同步时间过长可以适当调高，最大值为 16。具体设置的时候需要注意服务提供商对于调用的限制或者并发的限制，不要超过限制了。链接可见：WebDAV/S3 data sync and backup support configurable concurrent requests · 议题 #12798 · siyuan-note/siyuan

这里的截图用的是腾讯云的 COS（对象存储），不过各家的云服务基本都有通用的标准，可以自行参考对应平台的配置文件进行设置。下面对常见问题进行讲解，文末配上了我找到的云服务提供商的文档链接，可以拖到文章最后查看。

常见问题及解决方案

Endpoint

这个地方常见的问题是 http 协议，也就是开头的 http:// 或 https://。

常见错误有：

http://http(s)://
http(s)://

这个是需要改成 http:// 或者 https://，具体要改成哪个看你服务提供商的配置（是否支持加密访问），国内的几家通常都支持 https 协议甚至要求使用 https 协议。这个请看你服务提供商对应说明或者你看的配置教程的说明。

思源后面会兼容这种情况，不过我个人认为这种写法还是一种错误，请注意不要在其他应用中配置错误。

简单介绍一下：在网络访问中，http:// 和 https:// 用于标识目前使用什么协议上网，前一个是普通版本，后一个是带有 SSL 证书验证的加密版本，即 https 是建立在 http 基础上的升级版本，可以提供更安全的服务。而能够生效的只有这两个形式，而不是两者混合的形式（见上文）。同理，可用的协议还有 ftp://、ws:// 和 wss:// 等，它们分别是 FTP 协议、WebSocket 协议和带 SSL 的 WebSocket 协议。网络协议是一个固定的部分，对于这里的场景只允许使用 http:// 或 https://，如果使用别的前缀则出错。具体可以在浏览器地址栏里面试试，比如 http://www.baidu.com、https://www.baidu.com 和 http://https://www.baidu.com，前两者会跳转到 https，而后者可能被浏览器裁剪成 https，也可能显示一个错误界面。

Bucket

存储桶名称就是检查你这里是不是填写了你创建存储桶的时候的名称，一般不会出问题。多半是英文的，同时可能含有数字部分。如果填写错误你在之前的版本也同步不了，所以多半可以略过检查。

Region ID

地域 id 用于指明你要访问的 S3 的地域。这个地方只能看你服务提供商的文档要求填写什么，比如腾讯云要求使用 ap-guangzhou、ap-beijing 格式。如果你看的配置教程填的是中文，还请查看你所用的服务提供商的文档改成正确的格式。

这里附上我刚在社区看到的可能和 Region ID 有关的报错：

operation error S3: ListBuckets, resolve auth scheme: resolve endpoint: endpoint rule error, Invalid region: region was not a valid DNS name. (Provider: S3)

这里就是要改成服务提供商在文档里写的格式，比如 ap-beijing（腾讯云）、cn-beijing（阿里云）这样的。原帖是自建 MinIO，可能是别的问题。

使用 MinIO 并且没有改过 Server Location 的话，思源中 Region ID 需要配置为 us-east-1。

Addressing

这个是地址格式。如何选择取决于服务提供商如何访问储存桶，一般在服务提供商的文档中有相关说明。现在一般建议使用 Virtual-host-style，如果出现问题才回退到 Path-style。前者是目前推荐的使用方法，后者正在退出技术舞台。

贴上一段解析：

在 Path-style 中，bucket 的名字紧跟在 domain 之后，成为 URL path 的一部分。在 Virtual-hosted-style 中，bucket 的名称成了 subdomain。分别为：

(path style)            https://domain.com/siyuan-bucket
(virtual host style)    https://siyuan-bucket.domain.com

因此，在 Virtual-host-style 中，储存桶名称必须 DNS 友好，即只能包含 [a-zA-Z0-9\-]，而不能有其他字符。

TLS Verify

这个是一个安全认证的选项，用于检验和服务器的连接是否安全。默认验证应该没有问题，如果自建服务不支持可以关掉试试。

在 Alist 的 S3 配置教程中明确写明需要关闭，如果使用 Alist 自建 S3 服务请注意检查。

网络连接错误

其实网络连接错误也是常见问题，具体表现为公司电脑连不上外网、有白名单、你所在区域网络突然出现问题等等。又或者你家宽带在全速跑别的任务，一时没分给你足够的带宽等等都有可能。一般是自己的网络问题，只有很少时候是服务提供商真的宕机了，而如果有这种情况很快你就能在网上看到铺天盖地的文章和视频。

我不会配置怎么办

在社区里搜一下你平台的配置教程，带上链接，去找你服务提供商的用户支持，让他教你配置。只要有良好的态度、详尽的文档、清晰的语言、充足的耐心，客服工程师会给你搞定的。并且这样设置下来多半不会出现参数配置错误，而且响应速度（工作时间内）多半比社区发帖等回帖快。

参考链接

更新到 3.1.17 后 S3 同步一直失败 - 链滴，这篇文章有一些解答，可以看看。

对象存储 在兼容 S3 的第三方应用中使用 COS 的通用配置-实践教程-文档中心-腾讯云

对象存储 地域和访问域名-产品简介-文档中心-腾讯云

OSS 地域和访问域名_对象存储(OSS)-阿里云帮助中心

OSS 产品中涉及的基本概念_对象存储(OSS)-阿里云帮助中心

华为云我没找到，不过可以看看这个：基本概念_对象存储服务 OBS_华为云

MinIO 我没找，应该有，不过都是自建的有点难排查，可以先看看这个更新到 3.1.17 后 S3 同步一直失败 - 回帖

v3.1.17 或更高版本通过 CloudFlare Tunnel 访问 MinIO S3 提示 SignatureMismatch 问题的一些研究 - 链滴

七牛云没找到，可以看看这个：AWS S3 兼容_使用指南_对象存储 - 七牛开发者中心

附加信息

在储存桶的详情页一般会有一个概述页这样的地方，可以看到存储桶的名字和地域之类的，比如腾讯云就可以看到名字、地域（要英文部分）、访问域名（需要适当调整），这里可以复制名字和地域填写到配置中，之后将访问域名删掉储存桶名字部分填入 endpoint。这个配置方法不一定可靠，但是可作参考，建议配合配置文档检查问题。

先写到这里，我后续看看有没有其他人反馈的未列出情况我试着理解一下，看看能不能找出其他的或未列出的处理方案。如有错漏也欢迎指正，我会尽快修正。