zikun
zikun
发布于 2026-10-21 / 43 阅读
0

用 API 给 Halo 发文章:三个坑和一条流水线

博客跑在 Halo 上,一直有个偷懒的想法:写完 Markdown 直接推上去,不用再打开后台编辑器粘贴一遍。这周把这个念头落地了,中间撞了三个坑,每个坑都不复杂,但都能让人对着 500 发呆半小时。记一下。

一、Halo 的两套 API

Halo 2.x 的 API 分成几组,接入前先分清:

  • content.halo.run/v1alpha1 —— 资源本身,Post / Category / Tag 的标准 CRUD,返回裸对象。
  • api.console.halo.run/v1alpha1 —— 控制台的行为,建草稿、发布、撤回,返回的是包装对象。
  • 认证用「个人中心 → 个人令牌」创建的 PAT,请求头 Authorization: Bearer pat_xxx。2.26 的令牌是一串 pat_ 开头的 JWT,将近一千个字符,别被长度吓到。

这里先埋一个坑:两套 API 返回的结构不一样。比如列文章:

{
  "page": 1, "size": 20, "total": 1,
  "items": [
    { "post": { … }, "stats": { … }, "owner": { … }, "categories": [], "tags": [] }
  ]
}

文章本体在 items[].post 里,不在 items[] 上。第一版脚本就是在这里报的 Cannot read properties of undefined。

二、坑一:建草稿不能直接发 Post

直觉是 POST 一个 Post 对象过去。照着 v1alpha1 的 schema 拼:

{
  "apiVersion": "content.halo.run/v1alpha1",
  "kind": "Post",
  "spec": { "title": "测试", "slug": "test" }
}

返回 500,日志里是:

java.lang.NullPointerException: Cannot invoke "run.halo.app.core.extension.content.Post.getSpec()" because "post" is null

一个经典的 Java NPE,看得人一头雾水:我明明传了 post 啊。

翻 issue 才发现这是个老问题(2.24 就有人问过),回答是 body 结构不对,要按 DraftPost 的 schema 来。真正的结构是外面再包一层:

{
  "post": {
    "apiVersion": "content.halo.run/v1alpha1",
    "kind": "Post",
    "metadata": { "generateName": "post-" },
    "spec": { "title": "…", "slug": "…" }
  },
  "content": {
    "raw": "# 标题\n\n正文",
    "content": "<h1>标题</h1>\n<p>正文</p>",
    "rawType": "markdown"
  }
}

一个 PostRequest,包着「文章元数据」和「正文」两样东西。 post 为 null 时 NPE 就是这么来的——服务端在解包。

三、坑二:Markdown 得自己渲染

content 里有 raw 和 content 两个字段,看名字像是「原文 + 渲染结果」。我以为只给 raw 就行,服务端会补渲染。

实测拿 head-content 回来对比:raw 是我传的 Markdown,content 是我随手写的 HTML,一个字节都没动。

Halo 是 headless 架构,渲染在编辑器侧完成。所以想让页面正常显示,必须自己把 Markdown 转成 HTML——本地用 marked 就够了:

const html = marked.parse(markdown, { gfm: true });

这一步偷懒的后果很隐蔽:后台编辑器里看文章是好的(它拿 raw 重新渲染),但发布出去的页面是空白的。

四、坑三:环境变量在,但读不到

PAT 放在 Windows 用户环境变量 HALO_TOKEN 里。脚本里 process.env.HALO_TOKEN 一读,空的——因为 agent 进程启动早于设置变量。

退一步,让 node 自己调 PowerShell 去取:

execFileSync('powershell.exe', [
  '-Command',
  '[Environment]::GetEnvironmentVariable("HALO_TOKEN","User")'
]);

直接 EPERM。沙箱不允许 node 起子进程(管道被拦),但同样的命令在 bash 里是通的。

最后的解法是加一层 shell 包装:由 bash 读环境变量、注入进程环境,再 exec node。多一个 halo.sh,问题消失。令牌从头到尾只活在内存和注册表里,没落过盘。

五、流水线

工具跑起来是这样:

./halo.sh post article.md \
  --categories "技术" \
  --tags "Halo,API" \
  --publish

内部五步:读 Markdown → 渲染 HTML → 解析分类和标签(不存在的自动建)→ POST 建草稿 → 可选发布。

发布接口要带快照名:

PUT /apis/api.console.halo.run/v1alpha1/posts/{name}/publish
{ "headSnapshotName": "4bc2e2d3-…" }

这个名字在草稿返回体的 spec.headSnapshot 里,别自己编。

另外删除走的是 DELETE /apis/content.halo.run/v1alpha1/posts/{name}。console 组同名端点返回 404,我第一次删测试文章删了个寂寞。

六、验证

一次端到端:建草稿 → 发布 → curl 前台页面 grep 到正文 → 撤回 → 删除。五步全 200,页面里能搜到刚写的那句话,才算真通了。

顺手把测试过程留下的分类、标签、文章都清干净,站点回到原样。

尾声

现在写文章的流程变成了:丢一个主题过去,十分钟后草稿躺在后台,预览链接直接可点,确认没问题再点发布。

顺便说一句,这篇也是这么发出来的。

参考