Xiaozhi Esp32 Server Java

Xiaozhi ESP32 Server Java

基于 Xiaozhi ESP32 项目开发的 Java 版本服务端，包含完整前后端管理平台 为智能硬件设备提供强大的后端支持和直观的管理界面

反馈问题 · 部署文档 · 更新日志

如果这个项目对您有帮助，请考虑给它一个 ⭐ Star！ 您的支持是我们持续改进的动力！

---

项目简介

Xiaozhi ESP32 Server Java 是基于 Xiaozhi ESP32 项目开发的 Java 企业级服务端，采用多模块 + 双进程架构设计，为 ESP32 智能硬件提供完整的后端支撑和可视化管理平台。

核心亮点

• 多模块 + 双进程架构 — 管理后台与对话服务独立运行，互不影响，支持分别扩容
• 多 AI 平台集成 — OpenAI / 智谱 / 讯飞 / Ollama / Dify / Coze，MCP 工具协议扩展
• 语音全链路 — 本地 & 云端 STT/TTS，音色克隆，双向流式交互，实时打断，智能防误打断，极速响应
• 声纹识别 — 识别家庭成员，多成员独立记忆，共用设备互不干扰
• WebSocket + MQTT — 实时双向通信，服务端主动唤醒与消息推送，OTA 分批升级与时间窗控制
• 多设备就近应答 — 同空间多台设备同时唤醒，仅一台应答
• IoT 智能家居 — 语音指令控制设备，多设备协同，Function Call 智能决策
• RAG 知识库 — 多格式文档解析（PDF / Office / 图片），检索增强生成
• 长期记忆与记忆图谱 — 记住用户偏好与关键信息，理解人物关系，跨会话记忆
• 全链路监控 — Token / 时延 / 设备活跃度多维可视化，运维指标对接，设备接入一键自检
• 一键部署 — bin 脚本 / Docker Compose，Flyway 自动建表，模型自动下载

技术栈

类别	技术选型
后端	Spring Boot、Spring MVC、MyBatis-Plus、Flyway、WebSocket
前端	Vue.js、Ant Design、响应式布局
数据层	MySQL 8.0、Redis 7、Qdrant（向量检索）
语音识别	sherpa-onnx SenseVoice（本地）、Vosk（本地）、FunASR、阿里云、阿里云 NLS、腾讯云、讯飞、火山引擎
语音合成	sherpa-onnx（本地）、Edge TTS、阿里云、阿里云 NLS、腾讯云、讯飞、火山引擎、MiniMax
大语言模型	OpenAI、智谱 AI、讯飞星火、火山方舟、星辰、Ollama、Dify、Coze
扩展能力	MCP 工具协议与接入点、Function Call、RAG 知识库、长期记忆与记忆图谱、声纹识别、音色克隆

---

项目架构

📐 架构图源文件：docs/architecture.drawio（可用 draw.io 打开编辑）

双进程架构：两个独立进程共享 MySQL 和 Redis，可分别部署与扩容。

• xiaozhi-server :8091 — 管理后台，提供 REST API、用户/设备/角色管理、OTA 升级
• xiaozhi-dialogue :8092 — 对话服务，处理 WebSocket/MQTT 实时音频流、AI 对话管道

dialogue 支持横向扩展，新实例自动注册至 server，通过设备 OTA 实现负载均衡。

---

适用人群

• 已购买 ESP32 硬件，需要功能完善的管理平台
• 需要企业级稳定性和扩展性
• 个人开发者，希望快速搭建使用
• 需要支持大量设备并发连接的场景

---

功能对比

部分功能未开源，有需求请通过下方联系方式沟通

---

部署

方式	适合	前置条件
Docker（推荐）	直接用起来	只要 Docker
源码	要改代码	JDK 21、Maven、Node 22、MySQL 8、Redis 7

Docker

mkdir xiaozhi && cd xiaozhi
curl -O https://raw.githubusercontent.com/joey-zhou/xiaozhi-esp32-server-java/main/docker-compose.yml
docker compose up -d

等容器都 healthy 后打开 http://localhost:8084，账号 admin / 123456。 详见 Docker 部署。

源码

git clone https://github.com/joey-zhou/xiaozhi-esp32-server-java
cd xiaozhi-esp32-server-java
docker compose -f docker-compose-db.yml up -d   # 起 MySQL + Redis，已有可跳过
./scripts/download_models.sh                    # 下载模型和原生库，首次必须
bin/all.sh start                                # 自检、编译并启动
cd web && npm install && npm run dev            # 前端

Windows 用 bin\all.ps1 start。详见 CentOS 部署 / Windows 部署。

models/ 和 lib/ 不在 Git 仓库中，首次部署需通过脚本下载。 语音识别与合成全用第三方 API 的话，只跑 ./scripts/download_base.sh 即可（仅 VAD 模型和原生库）。

登录之后

要自己配一个大模型的 API Key 才能对话，系统不预置任何密钥。 语音识别用内置本地模型、语音合成用免费 Edge TTS，都可以先不管。 见配置说明。

设备侧填这两个地址（分属两个进程，别写混）：

• OTA：http://<内网IP>:8091/api/device/ota
• WebSocket：ws://<内网IP>:8092/ws/xiaozhi/v1/

改了服务端口时，要同步改 xiaozhi.server.port 与 xiaozhi.dialogue.port， 否则下发给设备的地址还是旧端口。

文档