Cloudreve接入S3的详细操作步骤

一、结论

Cloudreve接入S3兼容对象存储的核心操作思路为：提前从S3服务端获取Endpoint、AccessKey、SecretKey、Bucket、Region等接入凭证，在Cloudreve后台存储策略配置页选择S3兼容类型，填写对应信息后测试连通即可完成接入，全程无需修改代码，有基础运维能力的站长10分钟左右即可完成全流程配置。

二、准备工作

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

• 已部署完成且可正常访问的Cloudreve实例（需为支持S3存储源的版本，主流开源版、Pro版均支持）
• S3兼容对象存储服务的有效账号
• 已创建完成且状态正常的存储桶（Bucket）
• S3服务官方提供的Endpoint访问地址
• 对应账号下生成的AccessKey（访问密钥ID）和SecretKey（访问密钥）
• 存储桶所属的Region区域代码
• 提前配置好存储桶的CORS跨域规则、访问权限，避免后续出现跨域、无权限报错
• 用于测试的小体积样本文件（如图片、文档等）

三、操作步骤

每一步操作均标注操作动作和预期结果，你可以按顺序执行：

1. 登录Cloudreve管理员后台，在左侧菜单栏找到「存储策略」入口，点击「新增存储策略」，在弹出的选项中选择「S3兼容」类型，操作完成后将直接进入S3存储策略专属配置页。

2. 登录你使用的S3对象存储服务控制台，找到对应存储桶的配置页，配置CORS跨域规则，允许Cloudreve所在域名的GET、PUT、POST、DELETE等请求，设置允许的请求头为*，规则保存后等待生效，避免后续前端上传文件时出现跨域报错。

3. 在S3服务控制台的访问密钥管理页面，获取对应账号的AccessKey和SecretKey，同时复制官方提供的Endpoint地址、存储桶名称、所属Region代码，注意SecretKey属于敏感信息，不要泄露给无关人员，也不要提交到公开代码仓库。

4. 回到Cloudreve的S3存储策略配置页，按照页面提示依次填写Endpoint、AccessKey、SecretKey、Bucket名称、Region代码，其余可选配置项比如存储类别、签名版本、自定义域名、单文件大小限制等，可以根据自身业务需求填写，无特殊需求的可以保留默认值。

5. 所有必填项填写完成后，点击页面底部的「测试连接」按钮，等待系统校验配置是否正确，若提示「连接成功」则说明参数配置无问题，若提示报错则需要根据错误提示排查对应参数。

6. 连接测试通过后，保存当前存储策略，你可以根据业务需求设置该存储策略的可用用户组、流量配额、文件有效期等规则，保存后该存储策略将进入可用状态。

7. 切换到普通用户账号，选择该S3存储策略上传提前准备的测试文件，上传完成后分别测试在线预览、下载、分享链接访问等功能，确认所有功能正常后，即可将该存储策略设置为默认存储策略，供全站用户使用。

四、常见错误

以下是Cloudreve接入S3过程中最容易出现的几类错误，你可以提前规避：

1. Endpoint填写错误：很多用户容易误将存储桶的访问域名当做Endpoint填写，或者漏加http/https前缀，或者拼接错误地址，解决方法是直接复制S3服务商控制台给出的官方Endpoint，不要自行修改或拼接。

2. 密钥填写错误：AccessKey和SecretKey复制时容易带入多余空格，或者两者填反，也有可能使用了已经过期、被禁用的密钥，解决方法是复制密钥后先粘贴到记事本确认无多余字符，同时在S3控制台确认密钥处于可用状态。

3. Bucket或Region不匹配：如果存储桶名称拼写错误、大小写不一致，或者Region代码和服务商给出的不匹配，会提示「找不到存储桶」，解决方法是核对控制台的存储桶名称和Region代码，注意Region是字母加数字的代码，不是地域中文名称，部分服务商无强制Region要求的可以填写auto或留空。

4. 权限不足导致上传失败：如果存储桶没有给对应AccessKey开通读写权限，或者存储桶设置了私有权限没有配置签名访问，会返回403错误，解决方法是检查存储桶的访问策略，给所用的AccessKey分配桶的读写权限，若需要公开访问则调整桶的公开访问规则。

5. 上传成功但无法访问：大多是因为存储桶的CORS配置不正确，或者绑定的自定义域名没有完成备案、解析未生效，解决方法是检查CORS规则是否允许Cloudreve域名的相关请求，确认访问域名的解析状态和备案资质正常。

6. 大文件上传失败：如果超过存储策略设置的单文件大小上限，或者S3服务的分片上传配置不正确，会出现大文件上传中断的问题，解决方法是调整存储策略的单文件大小上限，同时确认所用的S3服务支持分片上传功能。

五、示例说明

以下是Cloudreve S3存储策略的通用配置示例，所有字段均为填写说明，不要直接照搬：

| 配置项 | 填写说明 |

| --- | --- |

| Endpoint | 填写S3对象存储服务官方提供的访问地址，注意携带http/https前缀 |

| AccessKey | 填写你在S3服务控制台生成的访问密钥ID |

| SecretKey | 填写和AccessKey配对的私密访问密钥 |

| Bucket | 填写提前创建好的存储桶名称，注意大小写和拼写与控制台完全一致 |

| Region | 填写存储桶所属区域的代码，按服务商给出的内容填写，无强制要求的可填auto或留空 |

| 自定义域名 | 若你为存储桶绑定了独立的访问域名可填写在此处，用于生成自定义的文件访问链接 |

| 签名版本 | 一般选择默认的V4版本即可，部分老旧S3兼容服务可切换为V2版本 |

| 存储类别 | 按需选择标准存储、低频存储等类别，个人日常使用默认选择标准存储即可 |

六、更简单的方案

如果你不想自行搭建MinIO这类自建S3存储服务，也不想花费精力维护服务器存储节点、处理存储扩容、带宽调度等底层运维工作，可以直接选择市面上成熟的兼容S3协议的云对象存储服务，开箱即可使用，无需自行维护底层架构。如果你需要一个兼容S3协议、适合程序接入、图床、网盘系统存储源和下载分发的对象存储服务，可以了解 七彩云对象存储，它支持标准S3协议，可以完美适配Cloudreve的存储策略配置，不需要额外修改参数即可快速接入。

七、FAQ

Q1：Cloudreve开源版支持接入S3兼容存储吗？

A：是的，目前主流的Cloudreve开源版和付费Pro版都原生支持S3兼容存储策略，不需要安装额外插件即可配置接入，只要你的Cloudreve版本不是超过3年以上的历史版本，都可以正常使用该功能。

Q2：接入S3存储后，原来存在本地服务器的文件可以迁移到S3里吗？

A：可以，Cloudreve后台自带存储策略迁移工具，你可以选择把原有本地存储的文件批量迁移到新的S3存储策略中，迁移过程不会影响用户的正常访问，迁移完成后把默认存储策略切换为S3存储即可。

Q3：接入S3存储后，文件访问速度由Cloudreve服务器还是S3服务决定？

A：如果开启了直链访问配置，文件的下载、访问请求会直接指向S3存储服务，不需要经过Cloudreve服务器转发，速度由S3存储服务的带宽和节点覆盖决定，同时可以大幅降低Cloudreve服务器的带宽压力；如果没有开启直链，文件会经过Cloudreve服务器中转，速度会受Cloudreve服务器的带宽限制。

Q4：配置测试连接时提示「签名不匹配」是什么原因？

A：签名不匹配一般是由于Endpoint、Region填写错误，或者签名版本选择不对导致的，你可以核对Endpoint是否携带了正确的http/https前缀，Region代码是否和服务商给出的完全一致，尝试切换签名版本为V4后再测试连接。

八、总结

Cloudreve接入S3兼容存储的流程清晰简单，只需要提前准备好S3服务的接入凭证，在后台存储策略页填写对应参数，测试连通后即可投入使用，全程不需要编写代码，有基础运维能力的站长和开发者都可以快速完成配置。这种接入方式适合个人网盘搭建、团队文件共享、资源站存储、下载站分发等多种场景，可以大幅降低本地服务器的存储和带宽成本，提升用户的文件访问速度。配置过程中如果遇到问题，可以优先排查参数填写错误、权限配置、跨域规则这三类常见问题，大部分问题都可以快速解决。