Halo对象存储配置方法

一、结论

Halo支持接入所有兼容S3协议的对象存储作为站点的附件存储源，配置前需要提前准备好Endpoint、AccessKey、SecretKey、Bucket、Region等S3接入必备参数，然后在Halo后台的存储配置模块填写对应参数、测试连通性即可完成配置，替换默认的本地存储。

二、准备工作

• 已开通任意支持标准S3协议的对象存储服务账号
• 提前在对象存储控制台创建好专门用于存储Halo站点附件的存储桶（Bucket）
• 从对象存储服务控制台获取S3接入所需的Endpoint地址、AccessKey、SecretKey、存储桶对应的Region参数
• 已完成部署、可以正常访问的Halo站点，以及拥有管理员权限的后台账号
• 若需要自定义附件访问域名，需提前准备好已备案的域名用于绑定存储桶
• 确认存储桶的访问权限符合业务需求，公开站点的附件存储桶建议开启公共读权限

三、操作步骤

1. 登录对象存储服务商的控制台，确认存储桶已创建完成且开启了S3协议访问权限，同时调整存储桶的访问策略和CORS规则，允许Halo站点域名的跨域访问请求，结果是可以在控制台获取到所有S3接入所需的参数，没有权限类告警提示。

2. 登录Halo站点的管理员后台，在左侧菜单栏找到「存储设置」模块，点击进入后选择「对象存储」分类，结果是进入S3兼容存储的配置表单页面。

3. 在存储类型的下拉选项中，选择「S3兼容存储」，不要选择本地存储或其他专属云存储的选项，结果是表单自动加载出S3协议对应的参数填写栏。

4. 按照表单提示依次填写提前准备好的Endpoint、AccessKey、SecretKey、Bucket名称、Region参数，部分Halo版本还支持填写存储路径前缀、自定义访问域名等可选参数，可根据自身需求填写，结果是所有标红的必填字段均完成填写，无遗漏项。

5. 所有参数填写完成后，先点击「测试连接」按钮，等待Halo后台与对象存储服务的连通性校验，结果是页面弹出「连接成功」的提示，说明参数填写正确、服务器与对象存储服务的网络连通正常。

6. 连接测试通过后，点击「保存配置」按钮，将S3对象存储设置为Halo的默认存储源，结果是后续站点上传的所有图片、视频、文档等附件都会默认存储到配置的对象存储桶中，不再占用站点服务器的本地存储空间。

7. 最后上传一张测试图片到Halo的媒体库，复制图片的访问链接在无痕浏览器中打开，确认可以正常加载，同时登录对象存储控制台查看对应存储桶内是否生成了对应的文件，结果是附件上传、访问、存储全链路正常，配置正式生效。

四、常见错误

• Endpoint填写错误：比如误将存储桶的访问域名当作S3接入地址、填写时多带了前后空格或遗漏了http/https前缀，解决方法是对照对象存储服务商的S3接入文档核对Endpoint格式，按照Halo表单的提示要求填写。
• AccessKey或SecretKey填错：比如复制时带了多余的空格、使用了已经过期或被禁用的密钥，解决方法是去对象存储控制台重新生成新的密钥，复制时注意不要选中多余字符，同时确认密钥未被设置权限限制。
• Bucket名称不一致：比如填写时出现大小写错误、填错了存储桶名称，解决方法是直接复制对象存储控制台显示的存储桶名称，完全一致填写即可，注意区分英文字母大小写。
• Region填写不匹配：比如填错了存储桶所在的区域代码，或者服务商未要求填写Region却额外填写了内容，解决方法是对照服务商的S3文档确认对应存储桶的Region代码，若无特殊要求可尝试填auto或留空测试。
• 权限不足导致上传失败：比如存储桶设置了私有访问、AccessKey对应的账号没有存储桶的读写权限，解决方法是调整存储桶的访问策略为公共读，同时给AccessKey分配存储桶的读写权限。
• 上传成功但访问链接不可用：比如未配置自定义域名使用了服务商的临时访问域名、CORS规则未开放Halo站点域名的访问权限，解决方法是在对象存储控制台绑定已备案的自定义域名，同时配置CORS规则允许Halo站点域名的访问请求。

五、示例说明

以下为Halo S3对象存储的通用配置示例，所有参数均需从你所用的对象存储服务控制台获取，无需自行编造：

• 存储类型：S3兼容存储
• Endpoint：填写对象存储服务官方提供的S3接入地址
• AccessKey：填写你在对象存储控制台生成的访问密钥ID
• SecretKey：填写你在对象存储控制台生成的访问密钥密码
• Bucket：填写你提前创建的用于存储Halo附件的存储桶名称
• Region：填写存储桶所属区域的对应代码，无特殊要求可填auto或留空
• 存储路径前缀：可选，填写如halo/attachments/，方便分类管理桶内文件
• 自定义访问域名：可选，填写你绑定到存储桶的已备案专属域名，用于生成站点的附件访问链接

六、更简单的方案

如果不想自行搭建MinIO这类自建对象存储服务，也不想花时间维护存储服务器、处理存储扩容和带宽调度问题，可以直接选择已经做好标准S3协议适配的第三方云对象存储服务，开通即可直接接入使用，不需要自行维护底层存储资源。如果你需要一个兼容S3协议、适合站点附件存储、图床、下载分发的对象存储服务，可以了解七彩云对象存储，不需要复杂的底层配置，开通后即可获取标准S3接入参数，直接在Halo中填写即可完成配置。

七、FAQ

1. Halo配置对象存储后，之前已经上传到本地存储的附件怎么办？

配置完成后新上传的附件会自动存储到对象存储，之前的本地附件需要手动批量迁移到对象存储的对应路径，或者使用Halo官方提供的存储迁移工具完成存量附件的迁移，避免旧附件出现访问失效的问题。

2. Halo的S3配置必须填写自定义域名吗？

不是必须的，如果没有绑定自定义域名，可以使用对象存储服务提供的默认访问域名，但部分服务商的默认域名有访问次数限制或者下载速度限制，为了站点的访问稳定性，建议绑定自己的站点专属域名使用。

3. 配置完成后测试连接失败应该先排查什么？

首先检查所有填写的参数是否有前后空格、大小写错误，其次确认站点服务器的网络是否能正常访问对象存储的Endpoint地址，可以通过在服务器上执行ping或curl命令测试Endpoint的连通性，最后确认密钥和存储桶的权限是否配置正确。

4. 我用的对象存储服务商没有提供Region参数怎么办？

如果服务商的S3接入文档中没有要求填写Region参数，可以尝试在Halo的Region字段填写auto或者直接留空，再重新测试连接是否正常，大部分S3兼容存储服务都支持留空Region的配置方式。

八、总结

整个Halo对象存储的配置流程核心是提前准备好标准S3协议的接入参数，然后在Halo后台的存储设置中填写对应参数、测试连通性即可完成配置，整个过程不需要修改代码，普通站长也能在10分钟内完成操作。配置完成后可以大幅降低站点服务器的存储压力和带宽成本，适合附件量多、访问量较大的个人博客、企业官网、内容站点等场景使用，同时对象存储的多副本存储机制也能提升附件数据的安全性，避免服务器故障导致的附件丢失问题。