README.md

April 21, 2026 · View on GitHub

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 知识库 — 文档上传，智能检索增强生成，长期记忆管理
全链路监控 — Token / 时延 / 设备活跃度等多维度数据可视化
一键部署 — bin 脚本 / Docker Compose，Flyway 自动建表，模型自动下载

技术栈

类别	技术选型
后端	Spring Boot、Spring MVC、MyBatis-Plus、Flyway、WebSocket
前端	Vue.js、Ant Design、响应式布局
数据层	MySQL 8.0、Redis 7
语音识别	Vosk、FunASR、阿里云、腾讯云、讯飞
语音合成	sherpa-onnx（本地）、火山引擎、阿里云、Edge TTS
大语言模型	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 硬件，需要功能完善的管理平台
需要企业级稳定性和扩展性
个人开发者，希望快速搭建使用
需要支持大量设备并发连接的场景

功能对比

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

部署文档

快速开始

git clone https://github.com/joey-zhou/xiaozhi-esp32-server-java
cd xiaozhi-esp32-server-java
./scripts/download_models.sh   # 下载模型和原生库（首次必须）
bin/all.sh start               # 一键编译并启动（server + dialogue）
bin/all.sh status              # 查看状态

models/ 和 lib/ 不在 Git 仓库中，首次部署需通过脚本下载。使用第三方 STT/TTS 可只运行 ./scripts/download_base.sh（仅下载 VAD 模型和原生库）。

部署方式

方式	文档	说明
源码部署（Linux）	CentOS 部署文档	推荐生产环境
源码部署（Windows）	Windows 部署文档	开发和测试
Docker	Docker 部署文档	快速容器化部署
固件编译	固件编译文档	ESP32 固件编译和烧录

成功运行后，xiaozhi-server会输出 OTA 和 xiaozhi-dialogue会输出 WebSocket 连接地址，根据固件编译文档使设备接入服务使用。

性能测试

我们开发了专门的 WebSocket 并发测试工具 Xiaozhi Concurrent，用于评估系统的性能和稳定性。测试工具支持模拟大量设备同时连接，测试完整的 WebSocket 通信流程，并生成详细的性能报告和可视化图表。

📖 测试工具的详细使用说明、安装步骤和参数配置请查看：Xiaozhi Concurrent 仓库

基准测试结果

以下测试数据基于腾讯云服务器（8核8G，100M按量付费带宽） 环境，100个设备、100并发连接、持续5轮 对话测试：

性能指标

测试项目	成功率	平均时延	最小值	最大值	备注
WebSocket连接	100% (500/500)	0.090s	-	-	建立连接耗时
Hello握手	100% (500/500)	0.073s	-	-	握手响应时间
唤醒词响应	100% (500/500)	0.333s	-	-	唤醒词到音频回复
语音识别准确率	100% (500/500)	-	-	-	真实音频识别
语音识别时延	-	0.988s	0.949s	1.255s	ASR识别耗时（包含800ms静音）
服务器处理时延	-	0.849s	0.454s	3.759s	服务端处理耗时（LLM+TTS）
用户感知时延	-	1.837s	1.433s	4.723s	说话结束到收到回复

服务器资源占用

资源类型	空闲时	峰值	说明
CPU使用率	0%	80%	8核CPU占用率
内存占用	1.8G	1.96G	JVM堆内存稳定
网络带宽(上行)	0	2200KB/s	客户端音频上传
网络带宽(下行)	0	3300KB/s	服务端音频下发
WebSocket连接数	0	100	并发活跃连接数