Halo CLI 使用教程：在 Docker 部署的 Halo 上管理博客|XiaoLei の小破站

Halo CLI 是 Halo 的命令行管理工具。它不负责运行 Halo，而是通过 Halo 提供的 API，管理文章、页面、附件、主题和插件。

一、先理解 Docker 和 Halo CLI 的关系

如果 Halo 运行在 Docker 中，并不意味着 Halo CLI 也必须安装到容器里。

更推荐把 CLI 安装在服务器宿主机上，通过 Docker 映射出来的端口访问 Halo：

服务器宿主机
└── Halo CLI
        │ HTTP API
        ▼
Docker 容器
└── Halo :8090

只要宿主机可以访问 http://127.0.0.1:8090，CLI 就可以管理容器中的 Halo。这样做的好处是：容器重建时 CLI 不会丢失，文章操作也更方便。

二、安装 Halo CLI

Halo CLI 需要 Node.js 22 或更高版本。

先检查环境：

node --version
npm --version

安装 CLI：

npm install -g @halo-dev/cli

如果安装完成后提示 halo: command not found，通常是 npm 全局命令目录没有加入 PATH：

export PATH="$(npm prefix -g)/bin:$PATH"
hash -r
halo --version

三、创建 Halo 个人令牌

不要把 Halo 管理员密码直接写进脚本。推荐在 Halo 个人中心创建个人令牌：

https://你的域名/uc

进入「个人中心 → 个人令牌 → 创建个人令牌」，根据实际用途选择权限。

如果只是管理文章，选择文章相关权限；如果还要上传图片，再增加附件相关权限。令牌只显示一次，应当像密码一样保存，不要提交到 Git，也不要发到聊天中。

四、登录 Halo CLI

在服务器上执行：

halo auth login \
  --profile blog \
  --url http://127.0.0.1:8090 \
  --auth-type bearer \
  --token '替换为你的Halo个人令牌'

这里的 blog 是本地保存的配置名称，可以换成其他名字。

检查当前登录配置：

halo auth current

如果显示以下信息，就说明连接成功：

name       blog
baseUrl    http://127.0.0.1:8090
auth.type  bearer

五、查看文章

列出文章：

halo post list --profile blog

使用 JSON 输出，方便脚本处理：

halo post list --profile blog --json

查看某篇文章：

halo post get 文章名称 --profile blog

导出 Markdown：

halo post export-markdown 文章名称 \
  --profile blog \
  --output ./article.md

六、创建和发布文章

直接创建一篇 Markdown 文章：

halo post create \
  --profile blog \
  --title "文章标题" \
  --content "# 文章标题\n\n这是文章内容。" \
  --raw-type markdown \
  --publish false

--publish false 表示先保存为草稿。确认内容无误后，再发布会更安全。

也可以直接发布：

halo post create \
  --profile blog \
  --title "文章标题" \
  --content "# 文章标题\n\n这是文章内容。" \
  --raw-type markdown \
  --publish true

七、从 Markdown 文件导入

这是批量写作时更推荐的方式：

halo post import-markdown \
  --profile blog \
  --file ./article.md \
  --json

Markdown 文件可以先在本地编辑、检查，再上传到服务器导入。这样比在命令行中拼接很长的 --content 更不容易出错。

八、更新、删除和备份

更新文章：

halo post update 文章名称 \
  --profile blog \
  --title "新的标题" \
  --tags ERP,数据分析

删除文章前要确认名称，删除命令具有破坏性：

halo post delete 文章名称 \
  --profile blog \
  --force

操作前可以先导出 JSON 备份：

halo post export-json 文章名称 \
  --profile blog \
  --output ./article-backup.json

九、Docker 部署下的常见地址

CLI 在服务器宿主机上运行时，使用：

http://127.0.0.1:8090

如果 CLI 也运行在同一个 Docker 网络中的其他容器里，则可以使用 Halo 的容器名：

http://halo:8090

不要把数据库地址 halodb:3306 填给 Halo CLI。halodb:3306 是 Halo 容器访问 MySQL 的内部地址，不是 CLI 的 API 地址。

十、安全注意事项

不要把个人令牌写入 Git 仓库。
不要把令牌直接写进 Shell 脚本并提交。
令牌暴露后立即在 Halo 个人中心撤销。
文章发布、删除和插件操作前先确认目标。
Docker 容器重启不会影响已经保存在 Halo 数据目录中的文章，但操作前仍建议保留备份。

十一、最常用的命令清单

# 检查 CLI
halo --version

# 检查登录
halo auth current

# 查看文章
halo post list --profile blog

# 导入 Markdown
halo post import-markdown --profile blog --file ./article.md

# 导出文章
halo post export-markdown 文章名称 --profile blog

# 查看帮助
halo post --help