思源笔记 S3 云同步自签名证书问题深度解析

问题背景

在思源笔记 3.1.26 版本中，用户在使用 S3 云同步功能时遇到一个特定场景下的技术问题：当用户配置使用自签名证书的 S3 服务时，HTTPS 证书校验无法通过，导致云同步功能无法正常启用。值得注意的是，HTTP 协议在此场景下工作正常。

技术分析

问题本质

该问题的核心在于 TLS 证书验证机制。自签名证书由于不是由受信任的证书颁发机构(CA)签发，在默认配置下会被 TLS 客户端拒绝。思源笔记虽然提供了 skipTlsVerify 配置项，但在某些特定环境下仍可能出现验证失败的情况。

配置结构

思源笔记的 S3 配置结构中已包含 SkipTlsVerify 字段(JSON 标签为 skipTlsVerify)，理论上应该能够跳过 TLS 验证。该字段通过 gulu.JSON 进行序列化，在配置保存和读取过程中能够正确保持其值。

底层实现

AWS SDK 默认使用严格的 TLS 验证策略。虽然思源笔记已自定义 HTTP 客户端并设置了 InsecureSkipVerify 参数，但在某些网络环境下(如使用第三方 DNS 加速或反向代理时)，仍可能出现签名校验失败的问题。

典型场景

用户报告中提到了一种典型使用场景：

1. 使用 QNAP 的 QuObjects 作为 S3 服务
2. 通过第三方 DNS 进行加速
3. 在本地服务器上配置反向代理(将 HTTPS 443 端口代理到本机 8010 端口)
4. 使用 ACME 生成的自签名证书

在这种复杂网络环境下，即使设置了 skipTlsVerify，仍可能出现 SignatureDoesNotMatch 错误。

解决方案

对于遇到类似问题的用户，可以考虑以下解决方案：

1. 降级使用 HTTP 协议：在不涉及敏感数据的内部网络环境中，可以暂时使用 HTTP 协议作为临时解决方案。

2. 检查网络配置：

   • 确保反向代理配置正确
   • 检查 SSL/TLS 设置
   • 验证证书链是否完整

3. 调试工具：使用 curl 或 openssl 等工具单独测试 S3 服务的 HTTPS 连接，确认证书问题。

4. 网络拓扑简化：尝试在简单网络环境下测试，逐步添加网络组件，定位问题环节。

最佳实践

对于需要使用自签名证书的场景，建议：

1. 将自签名证书添加到系统的信任存储中
2. 确保证书主题备用名称(SAN)包含所有使用的主机名
3. 避免在证书链中使用过短或弱加密算法
4. 考虑使用私有 CA 而非单机自签名证书

总结

自签名证书在内部系统集成中很常见，但在复杂网络环境下需要特别注意证书验证和网络代理的配置。思源笔记虽然提供了跳过 TLS 验证的选项，但在实际部署时仍需综合考虑整个网络架构的影响因素。