首次推出xiaozhi-esp32-server-java;

升级了dozzle、dpanel、drawio、emby、portainer、redis-server、xiaozhi-esp32-server-mini、xiaozhi-esp32-server、xiaozhi-esp32-webui;
2025-12-06 12:28:28 +08:00 · 2025-04-27 19:49:13 +08:00
parent 065e754376
commit 062165aa78
30 changed files with 532 additions and 164 deletions
--- a/xiaozhi-esp32-server-java/CHANGELOG.md
+++ b/xiaozhi-esp32-server-java/CHANGELOG.md
@@ -0,0 +1,4 @@
+### 2.7.22 （2025-04-27）
+- 版本升级
+### 1.0.0-32 (2025-04-25)
+- 首次推出
--- a/xiaozhi-esp32-server-java/DOCS.md
+++ b/xiaozhi-esp32-server-java/DOCS.md
@@ -0,0 +1,182 @@
+# 小智 ESP32 语音助手
+
+这是一个基于 ESP32 的语音交互助手系统，支持中文语音识别和播放功能，适用于智能家居控制。作为 Home Assistant 的加载项，提供便捷的安装和管理体验。
+
+## 使用指南
+
+### 安装前准备
+
+1. Home Assistant OS、Supervised 或 Container 安装方式
+2. MariaDB 加载项已安装（或外部 MySQL/MariaDB 数据库）
+3. 具有较好网络连接的环境
+4. 足够的存储空间（至少 500MB）
+
+### 配置选项说明
+
+| 选项             | 描述                                                   |
+| ---------------- | ------------------------------------------------------ |
+| `mysql_host`     | 数据库主机地址，默认使用 MariaDB 插件为 `core-mariadb` |
+| `mysql_port`     | 数据库端口，默认为 `3306`                              |
+| `mysql_database` | 数据库名称，默认为 `xiaozhi`                           |
+| `mysql_user`     | 数据库用户名，默认为 `xiaozhi`                         |
+| `mysql_password` | 数据库密码，默认为 `123456`                            |
+| `java_memory`    | Java 应用内存分配，如 `512m`、`1g`、`1.5g`             |
+
+### 数据库设置
+
+**自动配置方式**：
+插件会尝试自动创建数据库和所需表结构，您只需在配置中提供有效的数据库连接信息。
+
+**手动配置方式**：
+如果您希望手动设置数据库，可以执行以下步骤：
+
+```sql
+CREATE DATABASE xiaozhi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'xiaozhi'@'%' IDENTIFIED BY '你的安全密码';
+GRANT ALL PRIVILEGES ON xiaozhi.* TO 'xiaozhi'@'%';
+FLUSH PRIVILEGES;
+```
+
+### 内存管理
+
+可以通过配置项 `java_memory` 控制分配给 Java 应用的堆内存大小，格式示例：
+
+- `512m`（512 兆字节，适合大多数使用场景）
+- `1g`（1 吉字节，适合大量设备和频繁交互场景）
+- `1.5g`或更高（适合高负载场景）
+
+**内存管理建议**：
+
+- 默认内存分配（512MB）足够普通使用
+- 对于多设备场景，建议分配 1GB 或更多内存
+- 如遇内存不足问题，增加分配至 1GB 或更高
+
+**优化资源使用**：
+
+- **关闭其他不必要的加载项释放资源**：Home Assistant 上可能同时运行多个加载项，每个加载项都会消耗系统资源。建议临时停用不常用的加载项，特别是资源密集型的加载项（如 Node-RED、VS Code 等），以释放更多内存给语音识别服务。
+
+- **监控资源使用**：通过 Home Assistant 的系统监控加载项，定期检查系统资源使用情况，确保有足够的可用内存。
+
+- **优化运行时参数**：对于性能有限的设备（如某些 Raspberry Pi 型号），确保系统有足够的交换空间(swap)。
+
+- **定期重启**：如果发现内存使用率持续升高，建议定期重启加载项，以释放累积的内存占用。可以在 Home Assistant 中设置自动化，定期重启此加载项。
+
+### 端口说明
+
+本加载项使用以下端口：
+
+- **8091**：API 服务端口（ESP32 设备通过 WebSocket 连接此端口）
+- **8084**：Web 管理界面端口（可通过 Home Assistant 边栏访问）
+
+## Web 界面功能
+
+通过 Home Assistant 的边栏图标或直接访问`http://你的HA地址:8084`进入 Web 管理界面。
+默认账号：admin
+默认密码：123456
+
+### 设备管理
+
+可以添加、编辑和删除 ESP32 设备，主要功能：
+
+- 设备列表查看
+- 设备状态监控（在线/离线）
+- 设备信息编辑
+
+### 音色配置
+
+支持为 ESP32 设备配置不同的语音合成音色：
+
+- 预设多种中文音色
+- 音色预览功能
+- 为不同设备分配不同音色
+
+### 角色设置
+
+可以选择不同的 AI 助手角色：
+
+- AI 助手
+- 智能家居助手
+- 其他预设角色
+
+### 对话管理
+
+查看与 ESP32 设备的历史对话：
+
+- 按时间查看历史消息
+- 按关键词搜索对话内容
+- 消息管理功能
+
+## ESP32 设备配置
+
+1. 获取并烧录 ESP32 固件（从[原始项目](https://github.com/78/xiaozhi-esp32)获取）
+2. 将 ESP32 设备连接到与 Home Assistant 相同的网络
+3. 在 ESP32 固件配置中设置服务器地址：
+   ```
+   ws://你的HA地址:8091/ws/xiaozhi/v1/
+   ```
+4. 在 Web 管理界面中添加对应的设备信息
+
+## 高级功能
+
+### 持久化对话
+
+系统支持持久化对话记录，可以记住与用户的对话上下文：
+
+- 自动保存对话历史
+- 根据历史对话进行上下文理解
+- 提供更自然的对话体验
+
+### 自定义唤醒词（需 ESP32 固件支持）
+
+如果 ESP32 固件支持，可以通过接口设置自定义唤醒词。
+
+## 故障排查
+
+### 加载项无法启动
+
+- 检查 MariaDB 服务是否正常运行
+- 验证数据库连接信息（主机、端口、用户名、密码）
+- 查看 Home Assistant 日志是否有错误信息
+- 确保分配了足够的内存给加载项
+
+### 语音模型问题
+
+- 检查 `/config/models/vosk-model` 目录是否存在模型文件
+- 如果模型不存在，请手动下载并解压到该目录
+- 确保存储空间足够（至少需要 100MB 空闲空间）
+- 确保下载的是中文语音模型
+
+### ESP32 设备无法连接
+
+- 验证 ESP32 和 Home Assistant 在同一网络环境
+- 检查 WebSocket 地址格式是否正确（ws://ip:8091/ws/xiaozhi/v1/）
+- 确认 ESP32 固件是否正确配置
+- 检查防火墙是否阻止了 WebSocket 连接
+
+### 内存不足错误
+
+- **增加`java_memory`配置**：根据设备性能适当增加，如从 512m 改为 1g
+- **关闭其他不必要的加载项释放资源**：
+  - 在 Home Assistant 的加载项页面，暂时停用不常用的资源密集型加载项
+  - 特别关注数据库、多媒体相关加载项，它们通常消耗较多资源
+  - 考虑使用 Home Assistant 的"系统诊断"功能，检查哪些加载项占用较多资源
+  - 如果使用的是低配置设备（如 Raspberry Pi 3 或更低），可能需要限制同时运行的加载项数量
+- **优化系统配置**：
+  - 增加系统交换空间（在树莓派等设备上尤为重要）
+  - 考虑使用性能更强的设备运行 Home Assistant
+  - 确保设备有足够的散热，避免因过热导致的性能降低
+
+## 技术架构
+
+本加载项基于以下技术构建：
+
+- **容器技术**：Docker + S6 Overlay（进程管理）
+- **前端**：Vue.js + Ant Design（Web 管理界面）
+- **后端**：Java Spring Boot（RESTful API 和 WebSocket 服务）
+- **语音处理**：VOSK（语音识别）+ ONNX Runtime（模型推理）
+- **数据存储**：MySQL/MariaDB（对话历史和配置）
+
+## 支持与贡献
+
+如有问题或建议，请访问[项目 GitHub 页面](https://github.com/joey-zhou/xiaozhi-esp32-server-java)。
+欢迎提交问题报告、功能请求或代码贡献。
--- a/xiaozhi-esp32-server-java/README.md
+++ b/xiaozhi-esp32-server-java/README.md
@@ -0,0 +1,149 @@
+# 冬瓜甄选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](https://github.com/joey-zhou/xiaozhi-esp32-server-java)开发，采用 MIT 许可证。
+
+## 参考资源
+
+- [小智 ESP32 服务器 Java 版](https://github.com/joey-zhou/xiaozhi-esp32-server-java)
+- [VOSK 语音识别系统](https://alphacephei.com/vosk/)
+- [Home Assistant 开发者文档](https://developers.home-assistant.io/)
+- [S6 Overlay](https://github.com/just-containers/s6-overlay)
--- a/xiaozhi-esp32-server-java/config.yaml
+++ b/xiaozhi-esp32-server-java/config.yaml
@@ -0,0 +1,38 @@
+name: "小智ESP32语音助手JAVA版"
+version: "2.7.22"
+slug: "xiaozhi_esp32_server_java"
+description: "基于ESP32的语音交互助手，支持语音识别和播放功能"
+url: "https://gitcode.com/waxgourd/addons"
+arch:
+  - aarch64
+  - amd64
+startup: application
+boot: manual
+init: false
+host_network: false
+map:
+  - config:rw
+services:
+  - mysql:need
+options:
+  mysql_host: "core-mariadb"
+  mysql_port: 3306
+  mysql_database: "xiaozhi"
+  mysql_user: "homeassistant"
+  mysql_password: "homeassistant"
+  java_memory: "512m"
+schema:
+  mysql_host: str
+  mysql_port: port
+  mysql_database: str
+  mysql_user: str
+  mysql_password: password
+  java_memory: str
+ports:
+  8091/tcp: 8091
+  8084/tcp: 8084
+ports_description:
+  8091/tcp: "API/WS服务端口"
+  8084/tcp: "Web管理界面"
+webui: "http://[HOST]:[PORT:8084]"
+image: r.hassbus.com/wghaos/xiaozhi-esp32-server-java-{arch}
--- a/xiaozhi-esp32-server-java/translations/en.yaml
+++ b/xiaozhi-esp32-server-java/translations/en.yaml
@@ -0,0 +1,30 @@
+configuration:
+  mysql_host:
+    name: MySQL Host
+    description: MySQL database host address
+  mysql_port:
+    name: MySQL Port
+    description: MySQL database port
+  mysql_database:
+    name: Database Name
+    description: Database name, default is xiaozhi
+  mysql_user:
+    name: Database Username
+    description: Username for database connection
+  mysql_password:
+    name: Database Password
+    description: Password for database connection
+  java_memory:
+    name: Java Memory Size
+    description: Memory allocation for Java application in format like XmXg, e.g. 512m, 1g
+
+addon:
+  start: Starting Xiaozhi ESP32 Voice Assistant...
+  stop: Stopping Xiaozhi ESP32 Voice Assistant...
+  configure: After configuration, click Save and restart the add-on to apply changes
+  logs:
+    starting: Starting service...
+    started: Service started
+    stopping: Stopping service...
+    stopped: Service stopped
+    error: Service failed to start, please check logs
--- a/xiaozhi-esp32-server-java/translations/zh-Hans.yaml
+++ b/xiaozhi-esp32-server-java/translations/zh-Hans.yaml
@@ -0,0 +1,30 @@
+configuration:
+  mysql_host:
+    name: MySQL主机
+    description: MySQL数据库主机地址
+  mysql_port:
+    name: MySQL端口
+    description: MySQL数据库端口
+  mysql_database:
+    name: 数据库名称
+    description: 数据库名称，默认为xiaozhi
+  mysql_user:
+    name: 数据库用户名
+    description: 用于连接数据库的用户名
+  mysql_password:
+    name: 数据库密码
+    description: 用于连接数据库的密码
+  java_memory:
+    name: Java内存大小
+    description: 分配给Java应用的内存大小，格式为 XmXg 等，例如：512m, 1g
+
+addon:
+  start: 正在启动小智ESP32语音助手...
+  stop: 正在停止小智ESP32语音助手...
+  configure: 完成配置后，点击保存并重启加载项使配置生效
+  logs:
+    starting: 正在启动服务...
+    started: 服务已启动
+    stopping: 正在停止服务...
+    stopped: 服务已停止
+    error: 服务启动失败，请检查日志