Cloudreve怎么对接对象存储实践教程

一、结论

Cloudreve对接对象存储通常基于S3兼容协议实现，无需修改核心代码，提前准备好Endpoint、AccessKey、SecretKey、Bucket、Region等核心参数后，在Cloudreve后台存储策略模块填写配置并测试连通即可完成对接，整体操作门槛较低，普通站长和开发者都可快速上手。

二、准备工作

• 已部署完成且可正常访问的Cloudreve站点，建议使用v3及以上版本，原生支持S3兼容存储策略
• 可用的对象存储服务账号
• 提前创建完成且处于正常状态的存储桶Bucket
• 对象存储服务提供的S3接入Endpoint地址
• 拥有文件读写、列举等必要权限的AccessKey和配对的SecretKey
• 存储桶对应的Region编码
• 用于测试连通性的小体积文件，如图片、TXT文档、压缩包等
• Cloudreve站点管理员账号权限

三、操作步骤

1. 登录Cloudreve管理员后台，进入侧边栏「存储策略」管理页面，点击「新建存储策略」，在类型选择弹窗中选择「S3兼容」类型，确认后进入参数配置界面，无需额外安装插件即可完成后续配置。

2. 登录你的对象存储服务控制台，获取对应存储桶的S3接入参数，包括Endpoint地址、AccessKey、SecretKey、Bucket名称、Region编码，同时确认当前AccessKey已配置足够的操作权限，包含文件上传、下载、列举、删除等你的业务所需的权限，避免后续操作受阻。

3. 回到Cloudreve的S3存储策略配置页，按照页面提示依次对应填写各个参数，注意区分Endpoint的HTTP/HTTPS协议前缀，若你的对象存储服务商要求使用路径样式访问，则需要勾选配置页中的「使用路径样式访问」选项，避免访问异常。

4. 按照业务需求配置存储规则，包括文件上传的路径命名规则、是否开启直链访问、公共文件的缓存过期时间、私有文件的签名有效期等，配置完成后先不要点击保存，先点击页面下方的「测试连接」按钮验证参数有效性。

5. 若系统提示连接测试成功，即可保存该存储策略；若提示连接失败，则根据系统返回的报错信息，逐一核对参数填写是否正确，调整后重新测试即可。

6. 存储策略保存成功后，进入「用户组」或「用户管理」页面，将新建的S3存储策略分配给对应的用户组或单个用户，也可设置为全站默认存储策略，后续对应用户上传的文件将自动存储到对接的对象存储桶中。

7. 切换到普通用户账号，上传提前准备的测试文件，上传完成后复制文件的访问链接，在无痕浏览器中打开测试是否可正常预览或下载，确认无误后即完成全部对接流程。

四、常见错误

1. Endpoint填写错误：常见问题包括多带了存储桶前缀、选错HTTP/HTTPS协议、填写成存储桶的访问域名而非官方S3接入地址，解决方法是核对对象存储服务商官方文档给出的标准Endpoint地址，复制时不要带多余空格或符号。

2. AccessKey或SecretKey填写错误：大多是复制时带入了多余空格、使用了已过期/被禁用的密钥、密钥对不匹配，解决方法是重新生成一对新的AccessKey密钥对，复制时完整选取内容，确认密钥处于启用状态。

3. Bucket名称不一致：填写的存储桶名称和控制台实际创建的名称大小写、字符有出入，或者存储桶尚未创建完成，解决方法是回到对象存储控制台复制存储桶的标准名称，确认存储桶处于正常可用状态。

4. Region填写不匹配：部分S3兼容服务要求填写正确的区域编码，填错会导致签名校验失败，解决方法是核对服务商给出的对应存储桶的Region参数，部分单区域服务商可直接填写官方提供的默认值。

5. 权限不足导致上传失败：AccessKey仅配置了读权限没有写权限，或者存储桶设置了禁止外部写入的规则，解决方法是调整AccessKey的权限策略，添加上传、删除等必要操作权限，同时检查存储桶的访问策略是否放行对应密钥的写入请求。

6. 上传成功但访问链接不可用：多是存储桶未配置公共读权限、跨域CORS规则未配置、CDN缓存规则异常导致，解决方法是根据业务需求调整存储桶访问权限，配置允许Cloudreve站点域名访问的跨域规则，需要直链访问的场景可开启公共读权限或使用签名访问。

五、示例说明

以下是Cloudreve对接S3兼容存储的通用配置示例，无真实参数，可根据实际获取的信息对应填写：

• 存储策略类型：S3兼容
• Endpoint：填写对象存储服务商提供的官方S3接入地址，注意选择对应协议（HTTP/HTTPS）
• AccessKey：填写你在对象存储控制台生成的访问密钥ID
• SecretKey：填写和AccessKey配对的访问密钥Secret
• Bucket：填写你提前创建好的存储桶名称
• Region：填写存储桶所属的区域编码，如无特殊要求可填写服务商提供的默认值
• 路径样式：根据服务商要求勾选「使用路径样式访问」，部分服务商不支持虚拟主机样式需要手动勾选
• 直链配置：根据业务需求开启或关闭直链，私有文件可设置签名有效期为1800秒（可自定义）
• 文件路径规则：可设置为{year}/{month}/{day}/{filename}{.suffix}，避免文件重名覆盖

六、更简单的方案

如果个人站长、小团队不想自己搭建维护MinIO等自建对象存储服务，也不想额外处理服务器存储扩容、数据备份、带宽扩容等运维工作，可以直接选择成熟的兼容S3协议的云对象存储服务，开箱即用无需运维，对接流程和上述通用步骤完全一致。如果你需要一个兼容S3协议、适合Cloudreve等网盘系统作为存储源、支持不限流量下载分发的对象存储服务，可以了解七彩云对象存储。

七、FAQ

Q1：对接对象存储之后，之前已经上传到Cloudreve本地存储的文件可以迁移到对象存储里吗？

可以，Cloudreve后台自带存储迁移工具，你可以在存储策略管理页创建迁移任务，选择将本地存储的文件批量迁移到新的S3存储策略中，迁移完成后文件的原有访问链接不会失效，不需要额外调整前端配置。

Q2：对接对象存储之后，用户下载文件走的是Cloudreve服务器的带宽还是对象存储的带宽？

如果你开启了存储策略的直链功能，用户访问文件时会直接跳转到对象存储的访问地址，不走Cloudreve源服务器的带宽，能大幅降低源服务器的带宽成本；如果没有开启直链，文件会先经过Cloudreve服务器中转，这时候会消耗源服务器的带宽。

Q3：测试连接成功，但是上传大文件的时候失败是什么原因？

大概率是两个原因：一是Cloudreve部署的源服务器的PHP、Nginx配置的上传大小限制低于你上传的文件大小，需要调整源服务器的上传参数，放开大小限制；二是对象存储服务设置了单文件上传大小限制，你可以去对象存储控制台调整存储桶的单文件上限，或者开启分片上传功能，Cloudreve原生支持S3分片上传，大文件会自动拆分上传避免失败。

Q4：对接S3存储的时候需要给存储桶配置跨域规则吗？

如果你的Cloudreve站点域名和对象存储的访问域名不一致，就需要配置跨域CORS规则，允许你的Cloudreve域名的GET、POST、PUT、DELETE等请求，否则会出现前端上传失败、文件预览失败的问题，具体的跨域规则可以参考对象存储服务商的官方文档配置。

八、总结

Cloudreve对接对象存储的整体流程核心为准备S3接入参数、后台填写配置、测试连通、分配存储权限四个环节，全程不需要修改代码，新手按照步骤操作半小时内即可完成对接。这种方案适合个人搭建私有网盘、团队搭建内部文件共享系统、站长搭建资源下载站等场景，能大幅降低本地服务器的存储和带宽成本，同时对象存储的多副本存储机制也能保障文件的安全性，避免本地服务器故障导致文件丢失。