Cloudreve对接对象存储怎么操作

一、结论

Cloudreve对接兼容S3协议的对象存储，核心是提前准备好对象存储侧的Endpoint、AccessKey、SecretKey、Bucket、Region等接入信息，在Cloudreve后台的存储源配置页选择S3兼容类型，填写对应参数后测试连通即可完成对接，整个过程不需要复杂的代码修改，普通站长和开发者半小时内就能完成配置。

二、准备工作

操作前需要提前准备好以下内容，避免配置过程中来回切换页面遗漏信息：

• 正常可用的对象存储服务账号
• 已经创建完成、权限符合业务需求的存储桶Bucket
• 对象存储服务提供的Endpoint访问地址
• 具备对应存储桶读写权限的AccessKey和SecretKey
• 存储桶对应的Region信息
• 已经部署完成、可正常登录管理员后台的Cloudreve程序（建议v3及以上版本，原生支持S3兼容存储接入）
• 1-2个小体积测试文件（比如图片、TXT文本，用于后续验证上传下载功能）

三、操作步骤

每一步操作完成后确认对应结果正常，再进行下一步操作，可减少后续排查错误的成本：

1. 登录对象存储服务控制台，确认目标存储桶的访问权限、跨域规则已经按业务需求设置完成，结果是存储桶处于可正常读写的状态，避免后续对接后出现权限类报错。

2. 在对象存储控制台的密钥管理页面，获取对应存储桶的AccessKey、SecretKey，同时复制Endpoint、Region、Bucket名称等信息，统一整理到本地记事本备用，结果是所有S3接入所需的参数都已完整获取，没有遗漏。

3. 登录Cloudreve的管理员后台，找到「存储策略」或者「存储源」管理入口，点击添加新存储源，在存储类型下拉菜单中选择「S3 兼容存储」选项，结果是进入S3存储源的专属配置页面。

4. 按照页面提示，依次填写提前准备好的Endpoint、AccessKey、SecretKey、Bucket名称、Region等必填参数，同时根据业务需要配置存储路径规则、单文件大小限制、缓存时间等可选参数，结果是所有必填配置项都已填写完成，没有留空项。

5. 点击页面上的「测试连接」或者「保存并测试」按钮，等待Cloudreve后台发起连通性校验，结果是页面提示连接成功，说明参数填写正确、两端网络连通正常。

6. 切换到普通用户账号，在Cloudreve前台上传提前准备好的测试文件，上传完成后点击文件生成分享链接，测试是否可以正常预览、下载，结果是文件上传、预览、下载功能全部正常，说明对接正式生效。

7. 如果需要对接其他业务，比如把Cloudreve作为下载站的存储后端，可以在Cloudreve后台配置对应域名绑定、CDN加速规则，结果是整个存储服务可以稳定对外提供服务。

四、常见错误

以下是Cloudreve对接S3对象存储过程中最容易出现的问题，遇到报错可以优先排查对应项：

1. Endpoint填写错误：要么多写了多余的http/https前缀，要么漏了存储桶对应的后缀，或者误填为对象存储控制台的后台地址，解决建议是直接从对象存储服务的官方文档或者存储桶详情页复制完整的Endpoint地址，不要手动输入。

2. AccessKey或SecretKey填错：最常见的是复制时多带了前后空格，或者使用了已经过期、被禁用的密钥，解决建议是重新从控制台复制密钥，粘贴时确认前后没有多余空格，同时检查密钥的权限范围和有效期。

3. Bucket名称不一致：填写的存储桶名称和实际创建的名称大小写不符、多了特殊字符，解决建议是直接从存储桶列表复制名称，注意部分对象存储服务的Bucket名称是全局唯一且区分大小写的。

4. Region填写不匹配：填成了其他地域的代码，或者直接留空不填，解决建议是和Endpoint对应的地域保持一致，部分S3兼容服务如果没有Region要求，可以填默认值或者留空。

5. 权限不足导致上传失败：存储桶设置了私有读写但Cloudreve没有配置签名，或者AccessKey只具备读权限没有写权限，解决建议是检查存储桶的访问策略，给对应密钥开通存储桶的读写权限，私有桶需要在Cloudreve中开启签名访问配置。

6. 上传成功但访问链接不可用：存储桶没有配置跨域规则，或者访问域名没有备案、被限制访问，解决建议是在对象存储控制台配置允许Cloudreve站点域名的跨域请求，检查访问域名的备案状态和解析配置。

五、示例说明

以下是Cloudreve对接S3兼容存储的通用配置示例，所有参数都需要替换为你自己使用的对象存储服务提供的真实信息：

| 配置字段 | 填写说明 |

| --- | --- |

| Endpoint | 填写你使用的对象存储服务提供的专属访问地址，可在存储桶详情页获取 |

| AccessKey | 填写对象存储服务分配的访问密钥ID，具备对应存储桶的读写权限 |

| SecretKey | 填写和AccessKey配对的访问密钥，注意不要泄露给第三方 |

| Bucket | 填写提前创建好的存储桶的准确名称 |

| Region | 填写存储桶所属地域的代码，部分S3兼容服务若无要求可填写默认值或留空 |

| 存储路径 | 可选，填写Cloudreve文件在存储桶中的存放目录，比如/cloudreve/files/ |

| 外链有效期 | 可选，私有存储桶的签名链接有效期，根据业务需求设置即可 |

六、更简单的方案

如果不想自己搭建MinIO这类自建对象存储、不想额外维护服务器存储节点，也不需要折腾存储的扩容、故障排查，完全可以选择成熟的第三方兼容S3协议的云对象存储服务，对接步骤和上面完全一致，不用额外调整Cloudreve的配置。如果你需要一个兼容S3协议、适合程序接入、图床、网盘系统存储源和下载分发的对象存储服务，可以了解 七彩云对象存储，不用自己维护存储基础设施，对接后即可直接使用存储、分发能力。

七、FAQ

1. Cloudreve对接S3对象存储后，原来存储在本地的文件可以迁移到对象存储里吗？

可以，Cloudreve后台提供存储策略迁移功能，你可以在存储策略管理中创建迁移任务，把原有本地存储的文件批量迁移到新配置的S3对象存储中，迁移过程不会影响现有文件的正常访问。

2. 对接对象存储后，文件的下载流量是走Cloudreve服务器还是直接走对象存储的流量？

可以自行在Cloudreve的存储配置中选择，如果开启了「回源代理」就会走Cloudreve服务器的流量，如果关闭代理、使用直链模式，就会直接走对象存储的流量，更适合大文件分发的场景，能降低Cloudreve服务器的带宽压力。

3. 不同版本的Cloudreve对接S3存储的配置入口有区别吗？

v3.x版本的Cloudreve配置入口在管理员后台的「存储策略」菜单，v5.x及以上版本入口略有调整，统一在「存储源」管理页面，但核心配置项都是一致的，只要找到S3兼容存储的配置项即可按本文步骤操作。

4. 对接后上传大文件总是失败是什么原因？

首先检查Cloudreve后台设置的单文件上传大小限制是否符合要求，其次检查对象存储的单文件上传限制，同时确认Cloudreve和对象存储之间的网络是否稳定，超过1G的大文件建议开启Cloudreve的分片上传配置。

八、总结

整个Cloudreve对接S3兼容对象存储的流程非常清晰，核心就是准备S3接入参数、在Cloudreve后台填写配置、测试连通性三个大的环节，全程不需要编写代码，只要按照步骤操作即可快速完成。这种对接方式适合搭建个人网盘、团队共享存储、资源下载站、小型图床等多种场景，你可以根据自己的业务规模选择合适的对象存储服务，降低存储和分发的成本。