🏠 Hermes + Home Assistant 智能中控部署方案

从零部署 · 7 步完成 · 语音控制 + 微信 AI

最后更新：2026-05-25

1. 全链路架构

1.1 设备分工

1.2 语音对话完整流程

1.3 内存预估

1.4 月度成本估算

语音 LLM 用 v4-flash 几乎零成本。每天的对话量即便翻 10 倍，也才 $0.40/月。

2. 分步部署

下面从零开始，在宿主机上完成全部部署。

Step 1：创建目录和 Docker Compose 重要

# 创建数据目录
mkdir -p ~/ha-stack /opt/data/ha

# 创建 compose 文件（一键复制整段）
cat > ~/ha-stack/docker-compose.yaml << 'EOF'
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - /opt/data/ha:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    privileged: true
    network_mode: host
    environment:
      TZ: Asia/Hong_Kong

  # ═══ 以下是可选的 Piper TTS（仅 HA 语音管道用）═══
  # 如果不用 HA 语音管道（改用 Open-LLM-VTuber 等），
  # 可以整段注释或删除，省 150MB 内存。
  wyoming-piper:
    container_name: wyoming-piper
    image: lscr.io/linuxserver/piper:latest
    restart: unless-stopped
    network_mode: host
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Hong_Kong
      - PIPER_VOICE=en_US-lessac-medium
      - PIPER_LENGTH=1.0
EOF

# 验证 compose 语法
docker compose -f ~/ha-stack/docker-compose.yaml config

Step 2：Nginx 反代 + Cloudflare DNS 跳过会炸

# 创建 Nginx 配置
sudo tee /etc/nginx/sites-available/ha << 'EOF'
server {
    listen 80;
    server_name ha.treetree.tech;
    location / {
        proxy_pass http://127.0.0.1:8123;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
EOF

sudo ln -sf /etc/nginx/sites-available/ha /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

然后去 Cloudflare DNS 添加 A 记录：ha → 168.144.35.51（橙色代理）。

# 在宿主机编辑（用 sudo，文件在 /opt/data/ha/ 挂载目录）
sudo nano /opt/data/ha/configuration.yaml

# 在文件末尾添加以下内容：

# 加到 configuration.yaml 末尾（如果已有 http: 段则合并进去）
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1     # Nginx 在本机，从 127.0.0.1 转发请求

Step 3：启动容器 跳过会炸

cd ~/ha-stack && docker compose up -d

# 等待 2-3 分钟（首次启动 HA 需要初始化数据库），然后检查
docker compose ps
# 应看到 homeassistant 和 wyoming-piper 都是 Up

docker logs homeassistant | tail -20
# 看到 "Home Assistant initialized in X.XXs" 就绪

浏览器打开 https://ha.treetree.tech，按向导创建管理员账号。

Step 4：安装 HACS + 集成 重要

4a. 安装 HACS

# 进入 HA 容器
docker exec -it homeassistant bash

# 在容器内运行安装脚本
wget -O - https://get.hacs.xyz | bash -

# 退出容器，重启 HA
exit
cd ~/ha-stack && docker compose restart homeassistant

HA 重启后，浏览器打开 https://ha.treetree.tech（⚠️ 不要带 :8123，你走的是 Nginx 反代）：

1. 设置 → 设备与服务 → 添加集成 → 搜 HACS → 安装
2. 勾选所有条款 → 提交 → 弹出 GitHub 授权页 → 登录 → 授权
3. 回到 HA → 完成。左侧菜单出现 HACS 入口。

怎么添加自定义仓库：左侧菜单点 HACS → 右上角三个点 ⋮ → 自定义存储库 → 粘贴仓库 URL → 类别选"集成" → 添加。之后就能在 HACS 里搜索该集成的名字并下载。

4b. Extended OpenAI Conversation

安装：

1. HACS → 右上角三点 → 自定义仓库 → 粘贴 https://github.com/jekalmin/extended_openai_conversation → 类别选「集成」→ 添加
2. HACS 搜索 Extended OpenAI Conversation → 下载 → 重启 HA

配置（分两步）：

① 添加集成：HA → 设置 → 设备与服务 → 添加集成 → Extended OpenAI Conversation
　• API Key = 你的 OPENCODE_GO_API_KEY
　• Base URL = https://opencode.ai/zen/go/v1
　（⚠️ 这里没有 Model 字段——在下一步）

② 配置语音助手选项：HA → 设置 → 语音助手 → 编辑助手 → 选项
　• Model = deepseek-v4-flash（默认是 gpt-5-mini，手动改掉）
　• Max Tokens = 500（默认够用）
　• 开启 Advanced Options → Temperature = 0.5

4c. OpenAI Whisper Cloud (Groq STT)

安装：

1. HACS → 自定义仓库 → 添加 https://github.com/fabio-garavini/ha-openai-whisper-stt-api
2. HACS 搜索 OpenAI Whisper Cloud（97⭐）→ 下载 → 重启 HA

配置：

1. 先去 console.groq.com/keys → 用 Google/GitHub 登录 → 创建 API Key → 复制
2. HA → 设备与服务 → 添加集成 → 搜 GroqCloud（不是 OpenAI Whisper Cloud——注意区分）
3. 填 API Key → 模型选 whisper-large-v3-turbo → 提交
4. Temperature 默认 0，Prompt 留空

4d. Model Context Protocol Server

安装：内置集成，不需要 HACS。

1. HA → 设置 → 设备与服务 → 添加集成 → 搜 Model Context Protocol Server
2. 勾选「Control Home Assistant」（允许 MCP 客户端控制设备）→ 提交

4e. Spotify

1. 去 Spotify Developer Dashboard → Create App
2. Redirect URI 填 https://my.home-assistant.io/redirect/oauth（官方推荐，复制粘贴不动）
3. 点开 Settings → View client secret → 拿到 Client ID + Client Secret
4. HA → 设置 → 设备与服务 → 添加集成 → 搜 Spotify → 填凭据 → 授权

4f. Wyoming（见 Step 5a）

Wyoming 协议用于连接 Piper TTS。因为 Piper 需要 HA 启动后才能被发现，具体配置在 Step 5a 中。

Step 5：配好语音管道 跳过会炸

5a. 添加 Wyoming 协议

如果没自动发现，手动添加：

HA → 设置 → 设备与服务 → 添加集成 → 搜 Wyoming → 填：
  Host: 127.0.0.1
  Port: 10200

5b. 配置默认语音助手

HA → 设置 → 语音助手 → 编辑默认的「Home Assistant」助手：

Step 6：Hermes 连接 HA 重要

让 Hermes 在微信里控制 HA 设备（开灯、查状态等），需要两步：

6a. HA 创建长期访问令牌：

6b. Hermes 配置 HA MCP 连接：

① 进入容器编辑 config.yaml：

docker exec -it hermes bash

# 容器内编辑（权限自动正确，不需要 sudo/chown）
nano /opt/data/config.yaml

# 在 mcp_servers 段末尾添加（注意保持 YAML 缩进）：
mcp_servers:
  # ... 已有的其他 MCP 服务器 ...
  home-assistant:
    url: https://ha.treetree.tech/api/mcp
    headers:
      Authorization: "Bearer ${HA_TOKEN}"
    timeout: 120

② 写入 token 到 .env（仍在容器内）：

hermes config set HA_TOKEN "步骤 6a 创建的长期访问令牌"
exit

③ 重启 Gateway：

docker compose restart

④ 验证：docker exec -it hermes hermes mcp list 应列出 home-assistant，状态为 connected。

之后在微信跟 Hermes 说"开灯"，它就会通过 MCP 调 HA。

6c. HA 暴露实体 + 启用控制（必须！）：

1. HA → 设置 → 语音助手 → 暴露实体（直达链接）→ 勾选你想让 Hermes 控制的设备（灯、空调、开关等）
2. HA → 设置 → 设备与服务 → 添加集成 → 搜 Model Context Protocol Server → 提交（无需任何配置，装完即用）

Step 7：Echo Show 越狱 + View Assist

1. Echo Show 5 越狱 → 刷 LineageOS 18.1（教程）
2. 侧载 View Assist Companion App（VACA APK）
3. 在 HA 侧装 View Assist 集成（HACS → 搜索 "View Assist"）
4. VACA 连接 HA 实例：
   • VACA App 中填 HA URL：https://ha.treetree.tech
   • 填 HA 长期访问令牌（新建一个，不要复用 hermes-mcp 的）
   • 选择唤醒词模型：推荐 ok_nabu（开源，识别率高）或 hey_mycroft
5. 在 VACA 中选择 HA 语音助手管道（Step 5 创建的那个）

Step 8：备份与日常维护 建议

# HA 配置备份（宿主机执行）
sudo tar czf ~/ha-backup-$(date +%Y%m%d).tar.gz -C / opt/data/ha/
# 建议加到 cron：每周日凌晨 3 点自动备份

# Hermes 备份（容器内执行）
docker exec -it hermes hermes backup --quick

# 日常健康检查
docker compose -f ~/ha-stack/docker-compose.yaml ps     # 容器状态
curl -s http://localhost:8123/api/                       # HA API 可达
docker exec -it hermes hermes mcp test ha-mcp            # MCP 连接正常

故障排查速查

3. FAQ

4. 参考链接