一、结论
Halo配置远程附件存储的核心思路是使用兼容S3协议的对象存储作为后端，提前准备好Endpoint、AccessKey、SecretKey、Bucket、Region等接入信息，在Halo后台填写对应参数并测试连通后，即可将图片、附件自动同步到远程存储，实现稳定访问。主流版本的Halo均内置S3存储适配能力，整个配置过程不需要修改代码。
二、准备工作
开始配置前，建议先整理好以下内容，避免中途切换页面遗漏信息：
- 可正常登录管理后台的Halo站点，确认版本支持S3兼容存储（主流正式版均已内置，极旧版本可能需安装对应插件）
- 兼容S3协议的对象存储服务，可选择自建MinIO，也可选择公有云对象存储
- 已创建完成的专用存储桶（Bucket），提前规划好访问权限（公共读适合直接对外展示的博客附件，私有存储适合需权限控制的内部文件）
- 对象存储服务商提供的5项核心接入参数：Endpoint（S3 API访问地址）、AccessKey（访问密钥ID）、SecretKey（访问私钥）、Bucket名称、Region（存储桶所属地域标识）
- 用于测试的图片、文档或压缩包等小体积文件
- 可选：已完成备案的自定义域名、HTTPS证书，用于替换附件默认访问域名
三、操作步骤
1. 准备专用存储桶
做什么：登录对象存储管理控制台，新建一个仅用于Halo附件的存储桶，根据博客的访问需求设置访问权限，也可提前规划文件存放的路径前缀，方便后续分类管理。
结果：得到可用的空存储桶，记录下准确的Bucket名称和所属地域信息。
2. 获取S3接入凭证
做什么：在对象存储的密钥管理页面创建专用的AccessKey，复制官方提供的Endpoint、AccessKey、SecretKey、Region信息，建议将密钥保存在安全的本地位置，不要泄露到公开环境。
结果：拿到完整的S3连接参数，确认密钥处于启用状态。
3. 进入Halo存储配置页面
做什么：登录Halo管理后台，在系统设置或附件管理菜单中找到「存储策略」配置入口，选择新建存储策略，类型选择「S3兼容存储」。Halo作为支持S3协议的博客程序，无需额外开发即可对接各类兼容S3的存储服务。
结果：进入S3存储参数的填写表单页面。
4. 填写接入配置
做什么：将提前准备的Endpoint、AccessKey、SecretKey、Bucket、Region依次填入对应字段，可按需设置文件路径前缀、自定义访问域名、缩略图规则等可选配置；Path-Style、签名算法等高级参数无特殊说明保持默认即可，不要随意修改。
结果：所有必填项填写完毕，可选配置符合自身使用需求。
5. 测试连接并保存
做什么：点击页面上的「测试连接」或「保存」按钮，等待Halo向对象存储发起连通性校验。
结果：若提示连接成功，说明网络、参数、权限均正常；若提示报错，可对照后续常见问题逐一排查。
6. 设置默认存储策略
做什么：连接测试通过后，将新建的S3存储策略设置为Halo的默认附件存储，也可根据站点需求配置多存储策略，给不同用户组、不同类型文件分配不同存储位置。
结果：后续在Halo编辑器上传的图片、附件都会自动上传至远程对象存储，不再占用Halo服务器的本地磁盘空间。
7. 上传文件验证全链路
做什么：在Halo文章编辑器中上传测试图片和附件，预览已发布的文章，点击图片查看加载效果、点击附件链接测试下载是否正常，同时可登录对象存储控制台确认文件已成功上传到对应路径。
结果：确认上传、公网访问/下载链路均正常，配置正式生效。
8. 可选：配置自定义域名
做什么：如果需要使用自有域名作为附件访问地址，先在对象存储控制台绑定自定义域名、上传HTTPS证书，完成域名解析后，在Halo的存储配置中将访问域名修改为自有域名。
结果：附件链接使用自有域名，品牌统一性更好，后续迁移存储时也无需批量替换链接。
四、常见错误
1. Endpoint填写错误
这是最常见的报错原因，比如误将对象存储控制台地址当成S3 API地址、自行在Endpoint中拼接Bucket名称、多写或少写协议头/端口。解决方法是直接复制服务商官方文档中提供的S3 Endpoint，不要手动拼接修改，先确认Endpoint可正常访问后再填写。
2. 密钥填写错误或状态异常
复制AccessKey、SecretKey时首尾带了空格，或者使用了已被删除、禁用的密钥，都会导致校验失败。解决方法是重新生成一对专用密钥，粘贴后检查是否有多余空格，尽量不要使用主账号密钥，可创建仅拥有对应存储桶权限的子账号密钥，降低安全风险。
3. Bucket或Region不匹配
比如Bucket名称大小写填写错误、存储桶实际所属地域与填写的Region不一致，或者密钥与存储桶不属于同一个账号。解决方法是进入存储桶概览页，直接复制官方显示的Bucket全称和Region标识，确认账号归属一致。
4. 权限不足导致上传失败
如果AccessKey对应的账号没有目标存储桶的上传、读取权限，或者存储桶未开启对应访问权限，会出现连接成功但上传失败的问题。解决方法是检查存储桶访问策略，给对应密钥授予必要的操作权限，对外公开的附件需确认存储桶的公共读权限已开启。
5. 上传成功但访问链接404
出现这种情况通常是访问域名配置错误、存储桶权限为私有、自定义域名未备案或被拦截、HTTPS证书配置错误导致的。解决方法是先在对象存储控制台用默认域名直接访问测试文件，确认文件本身可访问后，再逐步排查自定义域名、权限、证书的配置问题。
6. 文件路径或命名不规范
如果Object Key（文件路径）开头多了斜杠、文件名包含特殊字符或未正确转义，可能导致链接无法正常访问。解决方法是路径前缀不要以/开头，尽量使用英文、数字、横杠命名文件，Halo默认会自动处理中文文件名转义，非必要不要自定义路径规则。
五、示例说明
以下为通用配置参考，不同版本Halo的字段名称可能略有差异，以实际页面显示为准，请勿直接使用以下内容作为真实配置：
| 配置项 | 填写说明 |
| --- | --- |
| 存储类型 | 选择「S3 兼容存储」 |
| Endpoint | 填写对象存储服务商提供的S3 API访问地址，无需拼接Bucket名称 |
| AccessKey | 填写服务商生成的访问密钥ID，检查首尾无多余空格 |
| SecretKey | 填写与AccessKey配对的私钥，仅创建时可见，注意保密 |
| Bucket | 填写提前创建的存储桶全称，严格区分大小写 |
| Region | 填写存储桶所属的地域标识，以服务商提供的信息为准 |
| 路径前缀（可选） | 可填写如halo/attachments/的路径，用于分类存储文件 |
| 访问域名（可选） | 默认使用存储桶自带域名，绑定自定义域名后可填写自有域名 |
配置时如果服务商有特殊的参数要求，以官方提供的接入文档为准，不要随意开启未知的高级配置项。
六、更简单的方案
如果不想自行搭建MinIO、维护服务器硬件和磁盘扩容，也不想处理本地磁盘损坏、服务器带宽不足导致附件加载慢的问题，可以直接选择兼容S3协议的公有云对象存储服务，开通后即可使用，无需运维底层存储资源。
如果你需要兼容S3协议、适合博客附件存储、图片托管和下载分发的对象存储服务，可以了解 七彩云对象存储，它支持标准S3协议，可直接适配Halo、PicGo、Cloudreve等常用程序，也适合有不限流量下载分发需求的站点。
这类云对象存储一般已经内置了多副本冗余、带宽调度能力，站长只需要专注于博客内容创作，不需要处理硬件故障、扩容、带宽运维等问题，配置流程和上述步骤完全一致，拿到S3接入参数后填写到Halo中即可使用。
七、FAQ
Q：配置S3远程存储后，原有的本地附件会自动迁移到远程吗？
A：不会自动迁移，原有本地上传的附件仍会保存在Halo服务器的本地磁盘中，访问链接也保持原有路径不变。如果需要统一迁移，可以手动将本地附件上传到对象存储的对应路径，再通过Halo自带的工具或数据库批量替换附件链接，操作前建议先备份整站数据和附件文件，避免数据丢失。
Q：必须把S3存储设为默认吗？能不能同时使用本地存储和远程存储？
A：不需要强制设置为默认，Halo支持同时配置多个存储策略。你可以根据自身需求灵活分配，比如将占用空间大的图片、视频存在远程对象存储，小体积的配置文件存在本地，也可以给不同用户组分配不同的存储权限，上传时手动选择存储位置即可。
Q：使用S3对象存储后，附件会占用Halo服务器的空间和流量吗？
A：文件本身存储在对象存储服务商的集群中，不会占用Halo所在服务器的磁盘空间；如果没有配置本地反代，用户访问附件时的流量直接走对象存储的带宽通道，也不会消耗Halo服务器的流量，很适合附件数量多、访问量较大的博客站点。
Q：提示连接成功，但上传文件时报错怎么办？
A：先检查AccessKey对应的账号是否拥有目标存储桶的写入权限，再确认存储桶的容量配额、单文件大小限制、文件格式限制是否符合要求；如果开启了防盗链、跨域校验，需要把Halo的域名加入白名单。可以先上传一个小体积的TXT文件测试，排查是否为文件本身的限制导致的问题。
八、总结
Halo对接远程S3附件存储的整体流程并不复杂，核心可归纳为「准备存储桶和接入参数→Halo后台填写配置→测试连通→验证上传访问」四个环节，全程不需要修改代码，普通站长按照步骤操作即可完成。
这种方案适合个人或团队博客附件数量较多、本地服务器存储空间不足，或者站点访问量较大、服务器带宽不足影响附件加载速度，以及需要多端同步附件、提升数据可靠性的场景。如果不想自行运维存储相关的服务器资源，选择成熟的兼容S3云对象存储服务会更省心。
想进一步了解这个项目？
访问官网查看产品能力、适用场景和最新服务信息。
访问官网