> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 存储策略配置

> 适用版本 1.0.4 ｜ 后台路径：附件 → 存储策略 → 新增 → 初春图床

插件通过一条 Halo 存储策略接入图床。策略决定「图片传到哪个图床、哪个桶、带什么标签」。

## 新建策略

1. 后台「附件 → 存储策略 → 新增」
2. 存储策略类型选择 **初春图床**
3. 填写下面四个字段
4. 保存后，在附件设置里把它设为默认策略，或在指定附件分组上使用

## 配置项

| 字段        | 必填 | 说明                                                               |
| --------- | -- | ---------------------------------------------------------------- |
| API 地址    | 是  | 初春图床的部署地址，例如 `https://img.example.com`。务必使用 HTTPS，否则 Token 会明文传输 |
| API Token | 是  | 在初春图床后台「系统设置 → API Token」生成并启用                                   |
| 存储桶 ID    | 是  | 目标存储桶的 ID，默认 `1`                                                 |
| 标签 ID     | 否  | 上传时自动添加的标签，留空则不添加                                                |

## 推荐配法

**单站点单图床**：只建一条策略并设为默认，API 地址填图床主域名，桶 ID 用默认值，标签留空。之后所有上传都走图床。

**按用途分桶**：为「文章配图」「头像」「相册」分别建桶，在 Halo 建多条策略并分配给不同附件分组，便于在图床侧做容量与清理策略。

**带来源标签**：填入标签 ID，所有经 Halo 上传的图片会自动打上该标签，后续在图床后台按标签批量管理。

## 验证配置

1. 保存策略后，到「附件」上传一张图片
2. 打开图片链接，域名应为图床域名
3. 到 oneimg 后台确认图片存在，且桶与标签符合预期

## 常见错误

| 现象       | 原因                    | 处理                       |
| -------- | --------------------- | ------------------------ |
| 上传报 401  | Token 无效、被停用或已轮换      | 回图床后台重新生成 Token 并更新策略    |
| 上传报 403  | API 功能未启用 / Token 无权限 | 确认图床后台已开启 API，Token 状态正常 |
| 上传报桶不存在  | 存储桶 ID 填错             | 在图床后台查看实际桶 ID 后修改        |
| 图片地址 404 | 图床域名、访问路径或防盗链设置       | 在浏览器直接打开图片地址排查           |
| 上传超时     | Halo 到图床网络不通、证书异常     | 在服务器上 `curl` 图床地址确认连通性   |

## 注意事项

- API Token 属于敏感信息，策略页面为密码框；截图分享时注意遮挡
- 修改策略字段只影响后续上传，不会回写已上传图片的地址
- 多条策略可以指向同一个桶，但标签与桶不同会导致图片分散，排查问题时先确认附件用的是哪条策略