waxgourd-addons/xiaozhi-esp32-server-java/README.md

冬瓜甄选addons：小智ESP32语音助手JAVA版

这是一个基于 ESP32 的语音交互助手系统，支持语音识别和播放功能，适用于智能家居控制。此插件将小智 ESP32 服务器整合为 Home Assistant 加载项，提供更简便的部署和管理方式。

功能特点

• 中文语音识别：基于 VOSK 语音识别引擎，支持准确的中文语音识别
• 与 Home Assistant 集成：完全集成到 Home Assistant 界面中，一键安装和配置
• Web 管理界面：提供直观的 Web 界面管理 ESP32 设备
• 内置中文语音模型：预装中文语音识别模型，开箱即用
• 数据库自动化：自动创建并初始化必要的数据库表结构
• 资源占用优化：可自定义 Java 内存分配，适应不同性能的设备

安装方法

前置要求

• Home Assistant OS 或 Supervised 环境（最低版本 2023.3）
• MariaDB 插件（或外部 MySQL/MariaDB 数据库）
• 网络连接（用于初始化）

安装步骤

1. 在 Home Assistant 中，进入设置 -> 加载项 -> 加载项商店
2. 点击右上角的菜单按钮，选择存储库
3. 添加此仓库地址: ``
4. 点击添加，然后关闭存储库对话框
5. 在加载项商店中找到小智 ESP32 语音助手并安装

配置选项

配置项	默认值	描述
mysql_host	core-mariadb	MySQL 数据库主机地址
mysql_port	3306	MySQL 数据库端口
mysql_database	xiaozhi	数据库名称
mysql_user	xiaozhi	数据库用户名
mysql_password	123456	数据库密码
java_memory	512m	Java 应用内存分配，格式为 XmXg，如 512m、1g 等

使用说明

首次启动

1. 安装并配置 MariaDB 加载项（如果使用外部数据库则跳过此步骤）
2. 在小智 ESP32 语音助手的配置页面，设置数据库连接信息
3. 如需调整 Java 应用内存，可修改 java_memory 参数（默认 512m）
4. 点击保存，然后启动加载项

访问 Web 界面

启动加载项后，有两种方式访问 Web 管理界面：

1. 通过 Home Assistant 边栏中的小智 ESP32图标直接访问
2. 或访问http://你的HomeAssistant地址:8084

设备连接

在 Web 管理界面中，您可以添加和管理 ESP32 设备：

1. 进入设备管理页面
2. 点击添加设备
3. 输入设备名称、IP 地址等信息
4. 在 ESP32 设备上设置 WebSocket 服务器地址为：ws://你的HomeAssistant地址:8091/ws/xiaozhi/v1/

数据库说明

首次启动时，插件会自动：

1. 连接到配置的 MySQL/MariaDB 数据库
2. 如果指定数据库不存在，则创建数据库
3. 执行必要的 SQL 脚本初始化表结构

如果您希望手动初始化数据库，可以：

1. 使用 MySQL 客户端连接到数据库服务器
2. 创建名为"xiaozhi"（或您指定的名称）的数据库
3. 导入/app/db/目录下的 SQL 文件

内存管理

通过配置项 java_memory 控制分配给 Java 应用的堆内存大小，格式示例：

• 512m（512 兆字节，适合大多数使用场景）
• 1g（1 吉字节，适合大量设备和频繁交互场景）
• 1.5g或更高（适合高负载场景）

内存管理建议：

• 默认内存分配（512MB）足够普通使用
• 对于多设备场景，建议分配 1GB 或更多内存
• 如遇内存不足问题，增加分配至 1GB 或更高

故障排查

如果遇到问题，请尝试以下方法：

1. 无法启动：

   • 检查 MariaDB 服务是否正常运行
   • 确认数据库连接信息正确
   • 查看 Home Assistant 日志中是否有错误信息

2. Web 界面无法访问：

   • 确认端口 8084 和 8091 未被占用
   • 检查 Home Assistant 的网络设置，确保这些端口可以访问

3. 语音模型问题：

   • 检查 /config/models/vosk-model 目录是否存在模型文件
   • 如果模型不存在，请手动下载并上传到该目录
   • 确保存储空间足够（至少需要 100MB 空闲空间）

4. 内存不足：

   • 增加 java_memory 参数，分配更多内存（如从 512m 改为 1g）
   • 关闭其他不必要的加载项释放资源
   • 考虑使用性能更强的设备运行 Home Assistant

技术架构

本插件采用以下技术栈：

• 前端：Vue.js + Ant Design
• 后端：Java Spring Boot
• 语音识别：VOSK + ONNX Runtime
• 数据库：MySQL/MariaDB
• 容器化：Docker + S6 Overlay

S6 初始化系统

插件使用 S6 Overlay 作为容器初始化系统，主要初始化流程：

1. 环境变量设置：读取 Home Assistant 配置，设置数据库连接信息等
2. 数据库初始化：等待 MySQL 可用，创建并初始化数据库
3. 模型检查：检查语音模型是否存在并可用
4. Java 应用启动：启动 Spring Boot 应用
5. Nginx 服务：提供静态资源服务，反向代理 API 请求

版权和许可

本项目基于xiaozhi-esp32-server-java开发，采用 MIT 许可证。

参考资源

• 小智 ESP32 服务器 Java 版
• VOSK 语音识别系统
• Home Assistant 开发者文档
• S6 Overlay