Halo CLI 部署完整教程：AI Agent 环境下的安装与配置（含 Keyring 问题修复）

前言

本文详细介绍如何在 AI Agent 环境中成功部署 Halo CLI，并解决常见的 Keyring 存储问题。

一、环境准备

首先确认 Node.js 和 npm 已安装：

node --version
npm --version

二、安装 Halo CLI

2.1 npm 全局安装

npm install -g @halo-dev/cli

2.2 验证安装

halo --version

成功输出：halo/1.3.0 linux-x64 node-v20.x.x

三、修复 Keyring 问题

3.1 问题原因

在某些环境（如 Docker、AI Agent）中，系统可能没有可用的密钥存储后端，会导致以下错误：

Failed to store credentials for profile "xxx": Platform secure storage failure: Unknown(1)

3.2 修复步骤

第一步：备份原文件

cp /usr/local/lib/node_modules/@halo-dev/cli/dist/cli.mjs \
   /usr/local/lib/node_modules/@halo-dev/cli/dist/cli.mjs.bak

第二步：创建修复脚本

创建文件 patch-halo-cli.js：

const fs = require('fs');

const cliPath = '/usr/local/lib/node_modules/@halo-dev/cli/dist/cli.mjs';
let content = fs.readFileSync(cliPath, 'utf8');

const startMarker = 'var KeyringCredentialStore = class {';
const startIdx = content.indexOf(startMarker);

let braceCount = 0;
let inClass = false;
let endIdx = startIdx;

for (let i = startIdx; i < content.length; i++) {
  if (content[i] === '{') {
    braceCount++;
    inClass = true;
  } else if (content[i] === '}') {
    braceCount--;
    if (inClass && braceCount === 0) {
      endIdx = i + 1;
      break;
    }
  }
}

const newClass = `var KeyringCredentialStore = class {
  constructor() {
    this.credentialsPath = join(homedir(), '.config', 'halo', 'credentials.json');
  }

  async _ensureDir() {
    const dir = dirname(this.credentialsPath);
    await mkdir(dir, { recursive: true });
  }

  async setProfileCredentials(profileName, credentials) {
    try {
      await this._ensureDir();
      let data = {};
      try {
        const raw = await readFile(this.credentialsPath, 'utf8');
        data = JSON.parse(raw);
      } catch (e) {}
      data[profileName] = credentials;
      await writeFile(this.credentialsPath, JSON.stringify(data, null, 2), 'utf8');
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Unknown error.';
      throw new Error(`Failed to store credentials: ${message}`);
    }
  }

  async getProfileCredentials(profileName) {
    try {
      const raw = await readFile(this.credentialsPath, 'utf8');
      const data = JSON.parse(raw);
      return data[profileName];
    } catch (error) {
      if (error.code === 'ENOENT') return undefined;
      throw error;
    }
  }

  async deleteProfileCredentials(profileName) {
    try {
      const raw = await readFile(this.credentialsPath, 'utf8');
      const data = JSON.parse(raw);
      delete data[profileName];
      await writeFile(this.credentialsPath, JSON.stringify(data, null, 2), 'utf8');
    } catch (error) {
      if (error.code === 'ENOENT') return;
      throw error;
    }
  }
}`;

content = content.substring(0, startIdx) + newClass + content.substring(endIdx);
fs.writeFileSync(cliPath, content);
console.log('Patched successfully!');

第三步：执行修复

node patch-halo-cli.js

四、配置站点认证

4.1 获取访问令牌

1. 登录 Halo 管理后台：https://your-domain.com/console
2. 进入 系统 → 附件管理
3. 找到 个人访问令牌 选项
4. 创建新令牌并复制

4.2 登录认证

halo auth login \
  --profile mysite \
  --url https://your-domain.com \
  --auth-type bearer \
  --token 你的访问令牌

4.3 验证认证

# 查看当前配置
halo auth current

# 列出所有配置
halo auth profile list

五、基本使用

5.1 文章管理

列出文章

halo post list --page 1 --size 10

创建文章

halo post create \
  --title "文章标题" \
  --slug "article-slug" \
  --content "文章内容（支持 Markdown）" \
  --raw-type markdown \
  --publish true \
  --tags "标签1,标签2" \
  --categories "分类"

查看文章详情

halo post get 文章名称

导出文章为 Markdown

halo post export-markdown 文章名称 --output ./post.md

导入 Markdown 文件

halo post import-markdown --file ./post.md

5.2 其他命令一览

六、常见问题

Q1: 提示 “No active Halo profile found”

halo auth profile list
halo auth profile use 配置名称

Q2: 认证失败 (401)

可能原因：令牌过期或无效

解决方案：重新生成访问令牌

Q3: 网络连接超时

halo auth profile get 配置名称
curl -I https://your-domain.com

七、总结

通过本文，你应该能够：

1. 成功安装 Halo CLI
2. 解决 Keyring 存储问题
3. 配置 Halo 站点认证
4. 使用命令行管理文章

提示：更多命令帮助请使用 halo --help 或 halo [子命令] --help

相关链接：

• Halo 官网：https://halo.run
• Halo CLI GitHub：https://github.com/halo-dev/cli