ChatHexo 是一套给 Hexo 博客增加 AI 问答能力的方案，包含前端插件 hexo-chathexo 和后端服务 chathexo-server 两部分。前端负责在博客页面注入聊天组件，后端负责读取博客文章并基于知识库回答用户问题。

如果你已经有一个 Hexo 博客，那么整个接入流程并不复杂：先安装并启动后端，再给 Hexo 安装插件，最后配置反向代理并重新生成静态页面即可。

ChatHexo 的整体结构

  • chathexo-server 是后端服务，默认运行在本机 4317 端口。
  • hexo-chathexo 是 Hexo 插件，会在执行 hexo generate 时自动注入前端资源。
  • Nginx 负责把博客上的 /api_chat_hexo/ 请求转发到本地后端服务。
  • 后端会读取 source/_posts 目录（也可自定义多个目录）中的文章内容，作为博客问答知识库的基础。

安装后端服务

安装依赖并拉取项目

根据 chathexo-server 的说明，推荐先安装 uv，然后拉取项目并安装依赖：

1
2
3
4
5
6
# 克隆仓库
git clone https://github.com/Telogen/chathexo-server.git
cd chathexo-server

# 安装依赖
uv sync

如果系统中还没有安装 uv，可以先参考其官方安装方式完成准备。

初始化配置文件

1
2
3
4
5
6
# 复制配置模板
cp config/config.example.json config/config.json
cp config/system_prompt.example.txt config/system_prompt.txt

# 编辑配置
vim config/config.json

后端配置里最关键的几个字段如下：

  • blog.posts_dirs 需要填写博客文章目录的绝对路径，例如 /home/yourname/your-blog/source/_posts。
  • providers 需要填写模型服务提供方的 API Key 和 base_url。
  • models.default 用来指定默认使用的模型。

如果你使用的是兼容 OpenAI 接口的模型服务，通常只要把接口地址和密钥配置正确即可。

启动和测试后端服务

启动服务

开发调试时可以前台启动：

1
uv run python -m chathexo.main

如果要在服务器后台长期运行，可以使用：

1
nohup uv run python -m chathexo.main > /tmp/chathexo.log 2>&1 &

服务默认监听地址为：

1
http://127.0.0.1:4317

停止服务

1
ps aux | grep "chathexo.main" | grep -v grep | awk '{print $2}' | xargs kill

本地测试接口

启动成功后，可以先用 curl 做几项简单测试：

1
2
3
4
5
# 健康检查
curl http://127.0.0.1:4317/chathexo-api/health

# 获取可用模型
curl http://127.0.0.1:4317/chathexo-api/models

也可以直接测试聊天接口：

1
2
3
curl -X POST http://127.0.0.1:4317/chathexo-api/chat \
  -H "Content-Type: application/json" \
  -d '{"query":"你好"}'

如果你想测试多轮对话，可以带上 thread_id：

1
2
3
4
5
6
7
curl -X POST http://127.0.0.1:4317/chathexo-api/chat \
  -H "Content-Type: application/json" \
  -d '{"query":"我叫小明","thread_id":"test123"}'

curl -X POST http://127.0.0.1:4317/chathexo-api/chat \
  -H "Content-Type: application/json" \
  -d '{"query":"我叫什么名字？","thread_id":"test123"}'

安装 Hexo 前端插件

在你的 Hexo 博客根目录执行：

1
npm i hexo-chathexo

根据 hexo-chathexo 的说明，插件的兼容性要求如下：

  • Node.js >= 14
  • Hexo 版本需要满足 ^7.0.0

安装完成后，需要在 Hexo 站点的 _config.yml 中加入配置。

配置 Hexo

在博客根目录的 _config.yml 中添加：

1
2
3
4
5
6
7
chathexo:
  enable: true
  api: /api_chat_hexo/chathexo-api/chat
  title: 博客问答
  subtitle: 基于博客知识库的 AI 助手
  assetsPath: chathexo
  indexFile: chathexo/index.json

这些字段的含义可以简单理解为：

  • enable 用于开启插件。
  • api 指向博客前端访问的聊天接口地址。
  • title 和 subtitle 控制聊天窗口的标题文案。
  • assetsPath 和 indexFile 用于指定插件生成的静态资源路径。

执行 hexo generate 时，插件会自动把前端资源注入到生成后的站点中。

配置 Nginx 反向代理

因为后端服务默认运行在本机 4317 端口，而博客页面通常由 Nginx 提供访问，所以还需要加一层反向代理。

可以在站点配置中加入：

1
2
3
4
5
location /api_chat_hexo/ {
    proxy_pass http://127.0.0.1:4317/;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

修改完成后重新加载 Nginx：

1
sudo nginx -t && sudo nginx -s reload

对于我当前这套博客部署方式，Nginx 直接指向 Hexo 的 public 目录，因此只要静态页面生成完成，刷新网页就能看到效果。

重新生成博客并检查效果

在 Hexo 博客根目录执行：

1
hexo clean && hexo generate

如果一切配置正常，访问博客页面后，右下角就会出现聊天按钮。

也可以通过已经配置好的域名代理地址继续测试：

1
2
3
curl -X POST https://your-domain.com/api_chat_hexo/chathexo-api/chat \
  -H "Content-Type: application/json" \
  -d '{"query":"你好"}'

常见问题

端口被占用

如果 4317 端口已经被其他程序占用，可以先查找对应进程：

1
lsof -i :4317

然后停止对应进程：

1
kill <PID>

修改后端端口

如果你不想使用默认端口，可以编辑 config/config.json：

1
2
3
4
5
{
  "server": {
    "port": 4318
  }
}

修改后记得同步更新 Nginx 里的 proxy_pass 端口配置。

自定义系统提示词

如果你想让问答助手更符合自己博客的语气或回答风格，可以编辑：

1
config/system_prompt.txt

修改完成后重启后端服务即可生效。配置提示词时，也要注意把其中的示例域名替换成你自己的真实域名。

适合什么场景

  • 适合文章数量较多、希望读者快速检索内容的个人博客。
  • 适合为技术博客增加一个自然语言检索入口。
  • 适合把已有博客内容包装成一个轻量级知识库问答助手。

如果你的博客本身已经积累了不少教程、踩坑记录或者笔记文章，那么 ChatHexo 确实是一个比较自然的增强方向。

参考资料