社交媒体

Halo 2.x API 发文完整流程(踩坑总结)

Halo 2.x API 发文完整流程(踩坑总结)

本文总结了通过 Halo 2.x REST API 发布文章的完整流程,包含踩过的坑和解决方案。


前置条件

  • 已部署的 Halo 2.x 博客
  • 在 个人中心 → 个人令牌 中创建 PAT(Personal Access Token)
  • 认证方式:Authorization: Bearer <your_token>

核心端点

基础路径:http://<your-halo-domain>

操作方法端点
获取文章列表GET/apis/api.console.halo.run/v1alpha1/posts
创建草稿POST/apis/api.console.halo.run/v1alpha1/posts
写入内容PUT/apis/api.console.halo.run/v1alpha1/posts/{name}/content
发布文章PUT/apis/api.console.halo.run/v1alpha1/posts/{name}/publish
获取文章内容GET/apis/api.console.halo.run/v1alpha1/posts/{name}/head-content

完整三步流程

第一步:创建草稿

POST /apis/api.console.halo.run/v1alpha1/posts

请求体示例:

{
  "post": {
    "apiVersion": "content.halo.run/v1alpha1",
    "kind": "Post",
    "spec": {
      "title": "文章标题",
      "slug": "article-url-slug",
      "owner": "your-username",
      "cover": "",
      "deleted": false,
      "excerpt": { "autoGenerate": true, "raw": "" },
      "allowComment": true,
      "pinned": false,
      "priority": 0,
      "publish": false,
      "visible": "PUBLIC",
      "categories": [],
      "tags": [],
      "htmlMetas": []
    },
    "metadata": {
      "name": "",
      "generateName": "post-",
      "annotations": {}
    }
  },
  "content": {
    "raw": "placeholder",
    "content": "placeholder",
    "rawType": "markdown"
  }
}

踩坑记录:

  • ❌ 缺少 deleted 字段会报错:Field 'deleted' is required
  • ✅ 必须包含 "deleted": false
  • publish: false 表示创建草稿

第二步:写入内容

PUT /apis/api.console.halo.run/v1alpha1/posts/{name}/content

请求体示例:

{
  "raw": "# 标题\n\nMarkdown 正文内容...",
  "content": "<h1>标题</h1><p>HTML 正文内容...</p>",
  "rawType": "markdown"
}

踩坑记录:

  • ❌ 只提供 raw 不提供 content → 页面空白,只有标题
  • ✅ 必须同时提供 raw(Markdown源码)和 content(HTML渲染结果)
  • 如果用脚本,需要自己将 Markdown 转为 HTML

第三步:发布文章

PUT /apis/api.console.halo.run/v1alpha1/posts/{name}/publish

无需请求体,直接调用即可。

踩坑记录:

  • ❌ 修改内容后不重新发布 → 页面显示旧内容
  • ✅ 每次修改内容后都要重新调用 publish
  • API 返回中 headSnapshot 和 releaseSnapshot 一致才表示内容已同步

PowerShell 快速示例

$token = "your_pat_token"
$headers = @{
    "Authorization" = "Bearer $token"
    "Content-Type"  = "application/json"
}
$baseUrl = "http://your-halo:8090"

# 1. 创建草稿
$createBody = @{ post = @{...}; content = @{...} } | ConvertTo-Json -Depth 10
$post = Invoke-RestMethod -Uri "$baseUrl/apis/api.console.halo.run/v1alpha1/posts" `
    -Method POST -Headers $headers -Body $createBody

# 2. 写入内容
$contentBody = @{
    raw = "# Hello"
    content = "<h1>Hello</h1>"
    rawType = "markdown"
} | ConvertTo-Json
Invoke-RestMethod -Uri "$baseUrl/apis/api.console.halo.run/v1alpha1/posts/$($post.metadata.name)/content" `
    -Method PUT -Headers $headers -Body $contentBody

# 3. 发布
Invoke-RestMethod -Uri "$baseUrl/apis/api.console.halo.run/v1alpha1/posts/$($post.metadata.name)/publish" `
    -Method PUT -Headers $headers

常见问题

问题原因解决
404 Not Found端点路径错误使用 /apis/ 开头,不是 /api/
页面只有标题缺少 HTML content同时提供 raw 和 content
内容没更新未重新发布修改后再次调用 publish
连接被拒绝curl 使用了代理加 --noproxy "*" 参数

总结

记住三步口诀:创建 → 写内容 → 发布

每次改内容都要重新发布!希望这篇踩坑总结能帮到你 🎉