💴【付费】小智AI × Halo 博客：用语音管理你的博客（MCP 完全指南 + 全程踩坑实录）
小智AI × Halo 博客：用语音管理你的博客（MCP 完全指南 + 全程踩坑实录）
最终效果：对着小智语音设备说"帮我看看博客最近的文章"，它通过 MCP 协议实时调用你 Halo 博客的 45 个工具（搜索/创建/修改文章、页面、分类、标签、评论、附件、主题设置、瞬间……），并语音回答你。
环境：极空间 NAS（192.168.5.178，Docker）· Halo 2.26+（NAS 内 Docker，内网 8081，公网域名 blog.seguzhixue.top）· 小智AI（xiaozhi.me，设备 xingzhi-abs-2.0 固件 2.2.3）· Windows 电脑
桥接器：xiaozhi-mcphub（Docker 常驻 7×24）
整理日期：2026-10-03 ｜ 全程配图已上传至本站媒体库
目录
踩坑实录（六连坑，全程图文） ★重头戏
一、架构与原理
1.1 为什么需要桥接器
小智和 Halo 两头协议对不上，无法直连：
桥接器 xiaozhi-mcphub 做两件事：
主动连小智：用 WebSocket 常驻连接小智接入点，把手里的工具"上报"给小智；
主动连 Halo：作为 MCP 客户端连接 Halo 的
/mcp端点，拉取博客的全部工具。
1.2 完整链路
你说话 → 小智语音终端（手机/音箱/设备 xingzhi-abs-2.0）
│ 语音（WiFi）
▼
小智云端 api.xiaozhi.me
│ WebSocket 长连接（wss://api.xiaozhi.me/mcp/?token=...）
▼
┌──────────────────────────────────────────────┐
│ 极空间 NAS 192.168.5.178（Docker） │
│ │
│ ┌────────────────────────┐ │
│ │ mcphub 桥接器 │ Web管理 :8090 │
│ └───────────┬────────────┘ │
│ │ HTTP + Bearer Token │
│ ▼ │
│ Halo 博客 blog.seguzhixue.top/mcp │
│ （NAS 内网端口 :8081，Nginx/网关转回） │
│ │
│ ┌────────────────────────┐ │
│ │ PostgreSQL（mcphub-db） │ :5432 内部 │
│ └────────────────────────┘ │
└──────────────────────────────────────────────┘
│ 查询结果原路返回
▼
小智语音播报结果
1.3 工具命名规则
小智端看到的工具名格式为：服务器名-工具名，例如 halo-seguzhixue-halo_search_content（服务器叫 halo-seguzhixue，工具是 halo_search_content）。所以服务器命名时用有辨识度的名字。
1.4 mcphub 的依赖
mcphub 用 PostgreSQL + pgvector 存配置（服务器、端点、用户、日志），所以 NAS 上要跑两个容器：mcphub（本体）+ db（数据库）。
二、准备工作（三样凭证）
密钥权限最小化：首次只勾"搜索/查看"类只读工具，确认稳定后再逐步放开"创建草稿"等安全操作；发布/删除权限谨慎开放。
三、Halo 侧：开启 MCP 服务与访问密钥
Halo 版本要求 ≥ 2.26.0；
Halo 后台 → MCP 服务（管理入口仅超级管理员可见）→ 确认 MCP 端点已启用；
新建访问密钥：勾选允许调用的工具 → 保存 → 立即复制 token（
hmcp_开头，只显示一次）；记下 MCP 端点地址：
http://<你的Halo地址>/mcp。
建议：给小智单独建一个密钥，与其他客户端（如 WorkBuddy）隔离，方便日后单独禁用/轮换。
四、极空间 NAS：Docker 镜像加速
mcphub 的镜像托管在 Docker Hub，国内直连大概率超时。
方式 A：极空间图形界面（优先试）
Docker 应用 → 设置 → 镜像仓库，添加加速源。
方式 B：SSH 改配置
极空间系统设置开启 SSH 后登录执行：
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json > /dev/null <<'EOF'
{
"registry-mirrors": [
"https://docker.1ms.run",
"https://docker.xuanyuan.me",
"https://docker.m.daocloud.io"
]
}
EOF
改完在图形界面重启 Docker 服务（或重启 NAS）。
实测可用的加速源（失效就换下一个）：
docker.1ms.run
docker.xuanyuan.me
docker.m.daocloud.io
docker.1panel.live
docker.kejilion.pro
五、部署 mcphub 桥接器（Docker Compose）
极空间 Docker 应用 → Compose（容器编排） → 新建编排 → 粘贴以下内容 → 启动：
services:
db:
image: pgvector/pgvector:pg16
container_name: mcphub-db
restart: unless-stopped
environment:
POSTGRES_USER: xiaozhi
POSTGRES_PASSWORD: 改成你的数据库密码
POSTGRES_DB: xiaozhi_mcphub
volumes:
- mcphub-db-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U xiaozhi -d xiaozhi_mcphub"]
interval: 10s
timeout: 5s
retries: 5
mcphub:
image: huangjunsen/xiaozhi-mcphub:latest
container_name: xiaozhi-mcphub
restart: unless-stopped
ports:
- "3000:3000"
environment:
DB_URL: postgres://xiaozhi:改成你的数据库密码@db:5432/xiaozhi_mcphub
SMART_ROUTING_ENABLED: "false"
volumes:
- mcphub-data:/app/data
depends_on:
db:
condition: service_healthy
volumes:
mcphub-db-data:
mcphub-data:
字段说明：
启动后两个容器均"运行中"，浏览器打开 Web 管理台（本例 http://192.168.5.178:8090）。
⚠️ 排错伏笔：部署完成后记清楚两个端口——mcphub Web 管理的端口 和 Halo 博客的端口是两回事，后面坑 2 就栽在这里。
六、mcphub 初始化与账号体系
默认管理员：
admin/改成你的密码，首次登录后立即在「用户」页改密码；mcphub 支持多用户注册，普通用户和管理员的权限差别很大（直接决定了后面能不能连内网，见坑 3）：
本文的坑 3 和坑 6 都是这一条引发的。结论先行：需要连内网服务的服务器，一律用 admin 创建。
全站资源 + 付费文档密码
微信扫码 · 付 ¥9.90
发送付款截图
此处内容已隐藏，「密码可见」