Cloudreve对接S3存储源详细配置教程

一、结论

Cloudreve对接S3兼容存储源的核心操作逻辑非常清晰，仅需提前准备好S3服务的Endpoint、AccessKey、SecretKey、Bucket、Region等核心接入信息，在Cloudreve后台的存储策略模块选择S3兼容存储类型，填写对应参数并测试连通性后即可正式投入使用，全程无需修改代码，仅通过可视化配置即可完成。

二、准备工作

操作前需要提前准备好以下内容，避免配置过程中出现中断：

• 已搭建完成且可正常访问的Cloudreve站点（开源版、Pro版均支持）
• S3兼容对象存储服务的有效账号
• 已在对象存储服务中创建完成、状态正常的存储桶Bucket
• 存储桶对应的官方Endpoint访问地址
• 具备存储桶读写权限的AccessKey和对应SecretKey
• 存储桶所属的Region编码（部分服务商无强制要求可提前确认）
• 若需使用自定义域名分发文件，需提前完成域名解析配置
• 若站点有跨域访问需求，需提前准备好Cloudreve站点域名用于配置S3服务的CORS规则

三、操作步骤

1. 登录Cloudreve管理员后台，进入左侧菜单栏的「存储策略」管理页面。结果是可看到当前站点已配置的所有存储策略列表，以及「新增存储策略」的操作入口。

2. 点击「新增存储策略」按钮，在弹出的存储类型选择列表中选中「S3 兼容存储」选项。结果是页面自动跳转到S3存储的专属配置表单，展示所有需要填写的必填和可选参数项。

3. 按照表单提示依次填写提前准备好的Endpoint、AccessKey、SecretKey、Bucket名称、Region编码，根据业务需要勾选是否开启HTTPS、是否使用自定义域名、是否开启断点续传、是否开启直链下载等可选配置。结果是所有带*号的必填参数全部填写完成，无空缺项。

4. 继续向下填写Cloudreve侧的存储策略规则，包括存储路径规则、单文件大小限制、允许的文件类型、存储配额等，比如可设置{year}/{month}/{day}/{name}{ext}的路径规则实现文件按上传日期分目录存储，方便后续管理。结果是Cloudreve侧的策略规则配置完成，符合站点的实际运营需求。

5. 所有参数填写完成后，点击页面底部的「测试连接」按钮，系统会自动向配置的S3存储源发起连接测试请求。结果是页面弹出「连接成功」的提示，说明参数填写无误、密钥权限配置正常、网络连通性符合要求。

6. 测试连接通过后，点击「保存」按钮完成存储策略创建，随后进入用户组或用户管理页面，将该S3存储策略关联到对应用户组或指定用户的存储权限中。结果是目标用户在上传文件时可选择该S3存储源，或系统默认将该类用户的上传文件自动存储到该S3存储中。

7. 切换到普通用户账号，上传一个测试文件，依次测试文件上传、在线预览、下载、分享链接访问等功能是否正常。结果是所有功能均正常运行，说明Cloudreve与S3存储源的对接配置完全生效。

四、常见错误

配置过程中大概率会遇到以下几类问题，可对照排查解决：

• Endpoint填写错误：常见错误包括自行拼接存储桶前缀、遗漏http/https前缀、误填存储桶访问域名而非服务Endpoint，解决建议是直接从S3服务控制台复制官方提供的Endpoint地址，不要自行修改或拼接。
• AccessKey或SecretKey填错：多为复制时带了多余空格、使用了已过期或被删除的密钥、密钥未绑定对应存储桶的权限，解决建议是重新生成新的具备读写权限的密钥，复制时注意剔除前后空格。
• Bucket名称不匹配：常见于填写时大小写错误、存储桶还未创建就填写、填成了其他账号下的存储桶名称，解决建议是到S3服务控制台确认存储桶的准确名称，确认存储桶处于正常运行状态。
• Region填写不匹配：多为填错了存储桶所属的区域编码、部分无需Region的服务误填了错误值，解决建议是查看S3服务的官方文档获取对应存储桶的Region编码，若服务无强制要求可填auto或留空。
• 权限不足导致上传失败：常见于AccessKey对应的账号只有读权限没有写权限、存储桶设置了禁止公写的访问规则，解决建议是检查密钥的权限策略，确认包含s3:PutObject、s3:GetObject等必要操作权限，调整存储桶的访问策略适配站点需求。
• 上传成功但无法访问文件：多为存储桶未配置公网访问权限、自定义域名未解析到正确地址、CORS规则未配置导致跨域拦截，解决建议是检查存储桶的访问权限配置，确认域名解析正常，根据Cloudreve的站点域名配置S3存储桶的CORS规则，允许站点域名的跨域请求。

五、示例说明

以下为通用配置示例，所有参数均需替换为自己的实际信息即可：

• 存储策略名称：自定义填写，比如「S3对象存储-通用用户组」
• Endpoint：填写S3存储服务官方提供的Endpoint地址，不要自行拼接存储桶前缀
• AccessKey：填写S3服务控制台生成的具备读写权限的AccessKey
• SecretKey：填写与上述AccessKey对应的SecretKey
• Bucket：填写已经创建完成的存储桶的准确名称
• Region：填写S3服务提供的对应存储桶的区域编码，无特殊要求可填auto
• 域名设置：如果使用自定义分发域名，填写提前解析完成的域名，否则可以使用S3服务提供的默认存储桶访问域名
• 路径规则：可填写{year}/{month}/{day}/{name}{ext}实现按日期分目录存储文件
• 大小限制：根据业务需求设置单文件最大上传大小，支持大文件场景可设置为100GB

六、更简单的方案

很多站长和开发者初期会选择自建MinIO作为S3存储源，但需要自己维护服务器、处理磁盘扩容、网络带宽调度、故障排查等问题，运维成本较高，且如果服务器带宽不足还会影响用户的下载体验。如果不想自己维护私有存储集群，也可以直接选择成熟的兼容S3协议的云对象存储服务，无需自行运维，开箱即可使用。如果你需要一个兼容S3协议、适合网盘系统存储源、文件下载分发、图床存储的对象存储服务，可以了解 七彩云对象存储，适合需要低门槛S3接入、不限流量下载分发的项目使用。

七、FAQ

1. Cloudreve开源版支持对接S3兼容存储源吗？

支持，不管是开源版还是Pro版的Cloudreve都内置了S3兼容存储的对接模块，无需额外安装插件即可直接配置使用，功能差异仅在于Pro版支持更多高级的权限控制和缓存配置。

2. 对接S3存储源后，之前已经上传到Cloudreve本地存储的文件可以迁移到S3存储吗？

可以，Cloudreve后台提供了存储策略迁移工具，可以选择将指定用户或指定路径的文件从旧的存储策略批量迁移到新的S3存储策略中，迁移过程中系统会自动更新文件的存储路径映射，不会影响文件的正常访问。

3. 对接S3存储源后，用户下载文件是走S3的带宽还是Cloudreve服务器的带宽？

可以自行配置，如果你开启了直链下载模式，用户下载会直接走S3存储的分发链路，不占用Cloudreve服务器的带宽；如果使用代理模式，则会经过Cloudreve服务器中转，占用服务器的带宽资源，大流量场景建议开启直链模式降低服务器压力。

4. 配置时提示连接失败但参数看起来都没问题怎么办？

可以先检查Cloudreve服务器的网络是否能正常访问S3服务的Endpoint，部分云服务器会对外部端口做访问限制，可登录Cloudreve服务器使用curl命令测试Endpoint的连通性，也可以查看Cloudreve的运行日志获取具体的错误代码，再对照S3服务的错误文档排查具体原因。

八、总结

整个Cloudreve对接S3存储源的操作流程非常简单，全程都是可视化后台配置，无需修改任何代码，普通站长也能在10分钟内完成全部配置。这种对接方式适合需要扩大存储容量、降低服务器存储成本、提升文件下载分发速度的网盘站点、资源站、内部文件管理系统等场景使用，搭配成熟的云对象存储服务可以大幅降低运维成本，提升站点的用户体验，也不用再担心本地存储的磁盘扩容、数据备份等问题。