Cloudreve怎么对接S3协议存储源

一、结论

Cloudreve对接S3协议存储源的操作非常简单，不需要修改源码，只需要提前准备好S3服务的Endpoint、AccessKey、SecretKey、Bucket、Region等接入信息，在Cloudreve管理员后台的存储策略板块完成参数填写和连通测试即可启用。整个流程全程可视化操作，普通站长和开发者10分钟内即可完成配置。

二、准备工作

操作前需要提前准备好以下内容，避免配置过程中反复切换页面耽误时间：

• 已完成实名认证的S3协议对象存储服务账号，确保账号状态正常无欠费
• 提前创建完成的存储桶Bucket，存储桶权限需匹配业务需求（公开访问场景需开启公共读权限，私有存储场景保持私有读写即可）
• S3服务官方提供的Endpoint接入地址
• 具备目标存储桶读写权限的AccessKey和SecretKey密钥对
• 目标存储桶对应的Region区域标识
• 已部署完成、可正常登录管理员后台的Cloudreve程序（建议使用v3及以上版本，原生支持S3兼容存储策略）
• 若有存量文件需要迁移，提前将本地存储的文件打包备份好

三、操作步骤

每一步操作均明确操作动作和预期结果，避免走弯路：

1. 登录所用S3对象存储服务的控制台，进入目标存储桶的配置页面，确认存储桶的权限、跨域规则、防盗链等基础配置符合业务需求，预期结果：存储桶状态正常，基础功能测试（手动上传下载文件）可正常使用。

2. 在S3控制台的密钥管理板块，生成或获取对应权限的AccessKey、SecretKey，同时复制存储桶对应的Endpoint、Region、官方Bucket唯一标识，预期结果：所有S3接入必填参数均收集完整，无遗漏。

3. 登录Cloudreve管理员后台，在左侧导航栏找到「存储策略」选项，点击「添加存储策略」按钮，预期结果：进入存储策略类型选择页面。

4. 在存储策略类型列表中选择「S3 兼容存储」，点击下一步进入参数配置表单页，预期结果：打开S3存储专用的参数配置界面。

5. 按照表单提示依次填写提前收集的Endpoint、AccessKey、SecretKey、Bucket名称、Region，非必填项如存储路径、自定义URL前缀、签名版本等可根据业务需要调整，预期结果：所有必填配置项填写完成，无空项。

6. 点击页面底部的「测试连接」按钮，等待Cloudreve后台发起连通性校验，预期结果：系统弹出「连接测试成功」的提示，若提示失败则返回前两步逐一核对参数是否正确。

7. 测试通过后保存存储策略，可根据业务需要将该存储策略设置为默认存储，或在用户组配置中给指定用户分配该存储的使用权限，最后上传一个测试文件，确认可以正常上传、预览、下载，预期结果：S3存储源正式接入Cloudreve，可投入实际业务使用。

四、常见错误

整理了配置过程中最高发的6类错误及对应解决方法：

• Endpoint填写错误：最常见的是漏写http/https前缀，或者误将存储桶的访问域名当成S3接口Endpoint填写，解决建议是直接从S3服务控制台的官方接入指南中复制完整的Endpoint地址，不要手动输入。
• AccessKey或SecretKey填错：复制时多带了前后空格、使用了已过期/被禁用的密钥、密钥没有对应存储桶的读写权限都会导致报错，解决建议是重新生成新的密钥对，复制时确认没有多余字符，同时在S3控制台确认密钥的权限范围包含目标存储桶。
• Bucket名称不匹配：填写时大小写错误、填写了存储桶的自定义备注名而非官方分配的唯一Bucket ID都会导致找不到存储桶，解决建议是从S3控制台的存储桶列表中直接复制准确的Bucket名称。
• Region填写不匹配：不同S3服务商的Region标识有固定格式，填错会导致签名验证失败，解决建议是和Endpoint一起从官方接入文档中复制对应的Region参数，不要自行编造。
• 权限不足导致上传失败：存储桶设置了私有读写但密钥只有读权限、存储桶开启了防盗链但没有添加Cloudreve站点的域名、跨域规则配置错误都会导致上传失败，解决建议是逐一检查存储桶的权限策略、密钥权限、防盗链和CORS配置，确保Cloudreve站点在允许访问的范围内。
• 上传成功但访问链接不可用：通常是URL前缀配置错误、存储桶未开启公网访问权限、CDN域名未完成备案解析导致的，解决建议是先测试直接通过S3服务的默认文件链接能不能访问，如果可以则调整Cloudreve中的URL前缀配置，如果不行则调整存储桶的公网访问权限。

五、示例说明

以下是Cloudreve对接S3存储的通用配置说明，所有参数均需填写对应服务商提供的真实信息，不要自行编造：

• Endpoint：填写所用S3对象存储服务官方提供的接口地址，注意必须带上http/https前缀
• AccessKey：填写在S3控制台生成的、具备目标存储桶读写权限的访问密钥ID
• SecretKey：填写和上述AccessKey配对的私密访问密钥
• Bucket：填写需要对接的存储桶的官方唯一标识，注意不是自己设置的存储桶备注名
• Region：填写对应存储桶所属的区域标识，可从S3服务的接入指南中直接复制
• 存储路径：可自定义文件在存储桶中的存放目录，比如填写cloudreve/file/就会把所有Cloudreve上传的文件存到该目录下，方便和其他业务的文件区分
• URL前缀：如果绑定了自定义CDN域名，可填写已完成解析备案的CDN域名，否则留空会默认使用S3服务提供的默认访问域名
• 签名版本：大部分主流S3服务默认使用V4签名，若所用S3服务仅支持V2签名，可在高级配置中调整签名版本参数

六、更简单的方案

如果不想自己搭建维护MinIO等自建S3存储服务，也不想额外投入服务器资源处理存储扩容、带宽峰值、数据备份等运维问题，可以直接选择成熟的第三方兼容S3协议的云对象存储服务，开箱即可使用，不需要维护底层基础设施。如果你需要一个兼容S3协议、适合网盘系统存储源、图床、文件下载分发的对象存储服务，可以了解七彩云对象存储，它支持标准S3协议，可直接作为Cloudreve的存储源使用，适合需要低门槛接入、不限流量下载分发的站长和开发者。

七、FAQ

Q1：Cloudreve对接S3存储源后，之前存在本地的文件可以迁移到S3里吗？

可以的，你可以先把本地存储的Cloudreve文件批量上传到S3存储桶对应的目录下，然后在Cloudreve后台的存储策略中切换默认存储，同时修改原有文件的存储策略指向即可，也可以使用Cloudreve自带的文件迁移工具完成存量文件的迁移，不需要手动修改数据库。

Q2：对接S3存储源后，下载速度是由Cloudreve的服务器带宽决定的吗？

取决于你配置的访问模式：如果配置的是S3直链模式，文件下载直接走S3服务的带宽，不会占用Cloudreve所在服务器的带宽；如果配置了代理模式，才会经过Cloudreve服务器转发，占用服务器带宽，建议根据自己的业务需求选择对应的模式，流量较大的场景优先选择直链模式。

Q3：为什么我测试连接的时候提示签名验证失败？

签名验证失败绝大多数是因为参数填写错误导致的，优先检查Endpoint、Region、AccessKey、SecretKey这四个核心参数是否和S3服务提供的完全一致，有没有多余空格、大小写错误，同时确认你的S3服务支持V4签名，如果仅支持V2签名需要在Cloudreve的高级配置中调整签名版本参数。

Q4：Cloudreve免费开源版可以对接S3存储源吗？

可以的，Cloudreve的开源免费版已经原生支持S3兼容存储策略的配置，不需要使用付费版本即可完成对接，只有部分高级的存储策略优化、边缘节点调度等功能需要付费版支持，普通站长和个人用户使用免费版的功能即可满足需求。

八、总结

Cloudreve对接S3协议存储源的流程非常清晰，核心只需要完成参数收集、后台配置、连通测试三个环节，不需要复杂的代码修改，零基础的站长也可以快速完成操作。对接S3存储源后，可以有效解决Cloudreve本地存储容量不足、带宽不够、扩容难、数据风险高等问题，适合用于个人网盘、团队共享盘、资源下载站、图床等多种场景，用户可以根据自己的业务规模和运维能力，灵活选择自建S3存储或者使用第三方云对象存储服务。