> 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 ≥ 2.25.0 ｜ 后台路径：插件 / 应用市场

插件只负责「Halo ↔ 图床」的对接，图床服务需要单独部署。顺序不要颠倒：**先有图床和 Token，再装插件**。

## 前置条件

| 条件         | 说明                                  |
| ---------- | ----------------------------------- |
| 已部署 oneimg | 参考上游仓库的 Docker Compose 部署方式，确保外网可访问 |
| API Token  | 在 oneimg 后台「系统设置 → API Token」生成并启用  |
| Halo 版本    | ≥ 2.25.0                            |
| 协议         | 建议 HTTPS。HTTP 下 Token 会明文传输         |

## 第一步：部署初春图床

按上游项目文档部署，得到类似 `https://img.example.com` 的访问地址。部署完成后确认：

1. 浏览器能打开图床首页并正常登录
2. 后台存在至少一个存储桶（新建策略时要填桶 ID）
3. 「系统设置 → API Token」可以生成 Token，且 API 功能已启用

## 第二步：安装插件

### 应用市场安装（推荐）

Halo 后台「应用市场」搜索 **初春图床**，安装后启用。

### 手动安装

1. 从 [Releases](https://github.com/AloneNanNan/oneimg-halo-plugin/releases) 下载最新的 `plugin-oneimg-x.y.z.jar`
2. 后台「插件管理 → 上传插件」，选择该 JAR
3. 安装完成后启用

## 第三步：验证

1. 按 [存储策略配置](/oneimg/storage.md) 新建一条策略并设为默认（或指定给某个附件分组）
2. 在「附件」页面上传一张图片
3. 打开图片地址，域名应为你的图床域名；同时到 oneimg 后台确认图片已入库

两步都成功，说明安装完成。

## 升级

- 应用市场内检测到新版本后直接升级，插件设置与存储策略会保留
- 手动升级时上传新 JAR 覆盖安装，同样保留配置
- 升级后若上传异常，先检查 Token 是否仍然有效（图床侧可能轮换过）

## 注意事项

- 插件停用后，已上传图片仍可访问（图床独立存储），但 Halo 侧无法再通过该策略上传
- 同一 Halo 可以配置多条初春图床策略（例如不同存储桶），分别指定给不同附件分组
- 图床地址变更后要同步修改存储策略里的 API 地址，否则上传与同步都会失败