Halo 2.22 API 完整使用指南总结
本文档基于《Halo 2.22.14 API 完整指南》整理，涵盖了所有核心 API 端点的使用方法和最佳实践。
📚 概述
Halo 2.22.14 提供了完整的 RESTful API，支持文章管理、附件上传、内容查询等核心功能。本指南将帮助你快速掌握 Halo API 的使用。
🔑 核心功能概览
1. 文章管理
| 功能 | 端点 | 状态 |
|---|---|---|
| 获取已发布文章 | /apis/content.halo.run/v1alpha1/posts?phase=PUBLISHED |
✅ 正常 |
| 获取所有文章 | /apis/content.halo.run/v1alpha1/posts |
✅ 正常 |
| 获取文章详情 | /apis/content.halo.run/v1alpha1/posts/{name} |
✅ 正常 |
| 创建文章 | /apis/content.halo.run/v1alpha1/posts |
✅ 正常 |
2. 内容管理
| 功能 | 端点 | 状态 |
|---|---|---|
| 获取快照内容 | /apis/content.halo.run/v1alpha1/snapshots/{name} |
✅ 正常 |
3. 附件管理
| 功能 | 端点 | 状态 |
|---|---|---|
| 上传图片 | /apis/api.console.halo.run/v1alpha1/attachments/upload |
✅ 正常 |
| 获取图片列表 | /apis/api.console.halo.run/v1alpha1/attachments |
✅ 正常 |
⚠️ 重要提示
Halo 2.22 的内容存储机制
Halo 2.22 使用 Snapshot 机制存储文章内容，这与传统 CMS 不同：
- Post 对象：仅存储元数据（标题、slug、分类等）
- Snapshot 对象：存储实际内容（rawPatch 和 contentPatch 字段）
- Base64 编码：内容使用 base64 编码存储
这不是 bug，而是 Halo 2.22 的正常架构设计！
💡 最佳实践
推荐工作流程
graph LR
A[上传图片] --> B[创建文章]
B --> C[获取图片URL]
C --> D[生成Markdown]
D --> E[通过API发布]
关键要点
- 认证方式：使用 Bearer Token
- 内容格式：推荐使用 HTML 格式（兼容 ProseMirror）
- 图片处理：先上传再获取 URL
- 分页查询：使用
page和size参数
📝 示例代码
获取文章列表
import requests
headers = {"Authorization": f"Bearer {token}"}
resp = requests.get(
"https://www.shopqiu.com/apis/content.halo.run/v1alpha1/posts?phase=PUBLISHED&page=0&size=10",
headers=headers
)
data = resp.json()
posts = data.get('items', [])
上传图片
with open('image.png', 'rb') as f:
files = {'file': ('image.png', f.read(), 'image/png')}
data = {'policyName': 'default-policy'}
resp = requests.post(
"https://www.shopqiu.com/apis/api.console.halo.run/v1alpha1/attachments/upload",
headers=headers,
files=files,
data=data
)
创建文章
create_post_data = {
"spec": {
"title": "文章标题",
"slug": "article-slug",
"owner": "admin",
"publish": False,
"visible": "PUBLIC",
"allowComment": True,
"categories": [],
"tags": []
}
}
🎯 总结
Halo 2.22.14 提供了强大而灵活的 API，支持完整的博客管理功能。理解其 Snapshot 机制是高效使用的关键。
核心优势
- ✅ 完整的 RESTful API 设计
- ✅ 灵活的内容管理
- ✅ 高效的附件处理
- ✅ 完善的权限控制
适用场景
- 自动化内容发布
- 批量文章管理
- 第三方系统集成
- 自定义工具开发
文档版本: 1.0
最后更新: 2026-02-28
Halo 版本: 2.22.14
💡 提示: 使用 halo-mcp-server 可以更轻松地管理 Halo 博客，支持自然语言交互和完整的 API 封装。