# Xiaozhi ESP32 Server Java - 技术文档 ## 项目概述 **Xiaozhi ESP32 Server Java** 是一个基于 Spring Boot 的企业级语音AI助手服务端项目，为 ESP32 硬件设备提供完整的后端支持和管理平台。项目包含前后端完整解决方案，支持多设备接入、语音识别、AI对话、设备管理等功能。 - **项目版本**: 2.8.1 - **开发语言**: Java 21 + JavaScript - **架构模式**: 前后端分离 - **部署方式**: Docker + Docker Compose --- ## 核心技术栈 ### 后端技术栈 #### 核心框架 - **Spring Boot**: 3.3.0 (主框架) - **Spring MVC**: Web层框架 - **Spring WebSocket**: 实时通信 - **Spring Boot Actuator**: 系统监控 - **Spring Cache**: 缓存管理 - **Java**: 21 (LTS版本) #### 数据层 - **MyBatis**: 3.0.3 (持久层框架) - **MySQL**: 数据库 - **PageHelper**: 2.1.0 (分页插件) - **HikariCP**: 数据库连接池 #### AI 和语音技术 - **Spring AI**: 1.0.0 (AI集成框架) - OpenAI 集成 - 智谱AI 集成 - Ollama 本地大模型 - **语音识别 (STT)**: - Vosk: 0.3.45 (本地离线识别) - 阿里云 ASR: 2.2.1 - 腾讯云 STT: 1.0.53 - 讯飞语音: 3.0.2 - **语音合成 (TTS)**: - Edge TTS: 1.2.6 - 阿里云 TTS: 2.2.17 - 火山引擎 TTS - **音频处理**: - JavaCV: 1.5.10 - FFmpeg: 6.1.1 - TarsosDSP: 2.5 - Opus 编码: 1.0.2 #### 智能体平台 - **Coze API**: 最新版本 - **Dify Client**: 1.0.7 (Java客户端) #### 网络和通信 - **WebSocket**: 实时双向通信 - **MQTT**: IoT设备通信 - **OkHttp**: 5.0.0 (HTTP客户端) - **Netty**: 4.1.110 (网络通信框架) #### 工具库 - **Lombok**: 1.18.32 (代码生成) - **Gson**: 2.10.1 (JSON处理) - **Thumbnailator**: 图片处理 - **ONNX Runtime**: 1.20.0 (机器学习推理) #### 云服务 SDK - **腾讯云 COS**: 5.6.155 - **阿里云 Dashscope**: 2.20.2 ### 前端技术栈 #### 核心框架 - **Vue.js**: 2.5.2 (渐进式框架) - **Ant Design Vue**: 1.7.8 (UI组件库) - **Vue Router**: 3.0.1 (路由管理) - **Vuex**: 3.5.1 (状态管理) #### 开发工具 - **Webpack**: 3.12.0 (构建工具) - **Babel**: ES6+转译 - **ESLint**: 代码规范检查 - **Sass**: CSS预处理器 #### 功能库 - **Axios**: 0.19.2 (HTTP客户端) - **ECharts**: 4.9.0 (图表库) - **Chart.js**: 2.9.3 (图表库) - **Moment.js**: 2.27.0 (时间处理) - **Vue-i18n**: 8.18.2 (国际化) - **WaveSurfer.js**: 7.9.1 (音频可视化) ### 容器化技术 #### Docker - **基础镜像**: - 后端: Eclipse Temurin 21-JRE - 前端: Node.js - 数据库: MySQL 8.0 - **编排工具**: Docker Compose - **网络**: Bridge网络模式 - **数据持久化**: Docker Volumes ### 数据库设计 #### MySQL 配置 - **版本**: 8.0+ - **字符集**: UTF-8 - **时区**: Asia/Shanghai - **连接池**: HikariCP - **最大连接数**: 15 - **最小空闲连接**: 5 --- ## 系统架构 ### 整体架构 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ ESP32 设备 │ │ Web 前端 │ │ 移动端 APP │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ WebSocket/MQTT │ HTTP/WebSocket │ HTTP API │ │ │ ▼ ▼ ▼ ┌───────────────────────────────────────────────────────────────┐ │ Spring Boot Server │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│ │ │ Web MVC │ │ WebSocket │ │ MQTT │ │ AI 引擎 ││ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│ │ │ 设备管理 │ │ 语音处理 │ │ 用户管理 │ │ 智能体 ││ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘│ └───────────────────────────────────────────────────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ MySQL │ │ Redis │ │ LLM │ │ (数据存储) │ │ (缓存服务) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ### 核心模块 #### 1. 设备管理模块 - 设备注册与绑定 - 设备状态监控 - 设备配置管理 - 多设备协同控制 #### 2. AI 对话模块 - 多LLM平台集成 - 对话记录管理 - 角色切换系统 - 智能体集成 #### 3. 语音处理模块 - 语音识别 (STT) - 语音合成 (TTS) - 音频格式转换 - 声纹识别 (开发中) #### 4. 用户管理模块 - 用户认证授权 - 权限管理 - 多用户支持 - 个性化配置 #### 5. 实时通信模块 - WebSocket 双向通信 - MQTT 消息推送 - 实时状态同步 - 消息队列处理 --- ## 环境要求 ### 开发环境 - **Java**: 21+ (必须) - **Node.js**: 16+ (前端开发) - **MySQL**: 8.0+ (数据库) - **Maven**: 3.8+ (构建工具) - **Docker**: 20.10+ (容器化，可选) ### 生产环境 - **CPU**: 4核心以上 - **内存**: 8GB以上 - **存储**: 100GB以上 - **网络**: 公网IP或内网穿透 - **操作系统**: Linux (推荐 Ubuntu 20.04+) ### 网络端口 - **后端服务**: 8091 (WebSocket + HTTP API) - **前端服务**: 8084 (生产环境通常使用 Nginx 代理) - **MySQL**: 3306 (内部访问) - **Redis**: 6379 (内部访问，可选) --- ## 核心功能特性 ### 已实现功能 1. **多设备管理**: 支持多个ESP32设备同时接入 2. **AI对话**: 集成多种大语言模型 3. **语音识别**: 支持本地和云端识别 4. **语音合成**: 多种TTS引擎支持 5. **智能体集成**: 支持Coze和Dify平台 6. **实时通信**: WebSocket双向通信 7. **用户管理**: 多用户权限控制 8. **设备监控**: 实时状态监控 9. **音色克隆**: 个性化语音合成 10. **角色切换**: 预设AI角色模式 ### 开发中功能 1. **声纹识别**: 个性化语音识别 2. **多模态交互**: 图像识别集成 3. **Function Call**: 复杂任务处理 4. **Home Assistant**: 智能家居控制 5. **知识库集成**: 外部知识源接入 --- ## 部署方案 ### 1. Docker 部署 (推荐) ```bash # 克隆项目 git clone [项目地址] # 启动服务 docker-compose up -d # 检查状态 docker-compose ps ``` ### 2. 源码部署 ```bash # 后端编译 mvn clean package -Dmaven.test.skip=true # 前端构建 cd web && npm install && npm run build # 启动服务 java -jar target/xiaozhi.server-2.8.1.jar ``` ### 3. 生产环境部署 - 使用 Nginx 作为反向代理 - 配置 SSL 证书 - 设置数据库备份策略 - 配置日志收集和监控 --- ## 配置说明 ### 主要配置文件 - `application.properties`: 基础配置 - `application-dev.properties`: 开发环境配置 - `application-prod.properties`: 生产环境配置 - `docker-compose.yml`: 容器编排配置 ### 关键配置项 ```properties # 服务端口 server.port=8091 # 数据库配置 spring.datasource.url=jdbc:mysql://localhost:3306/xiaozhi spring.datasource.username=xiaozhi spring.datasource.password=123456 # AI 平台配置 spring.ai.openai.api-key=your-api-key spring.ai.zhipuai.api-key=your-api-key # 语音服务配置 xiaozhi.tts.engine=edge xiaozhi.stt.engine=vosk ``` --- ## 技术亮点 ### 1. 企业级架构 - Spring Boot 3.x 最新版本 - 完整的微服务架构设计 - 支持高并发和高可用 ### 2. AI 技术集成 - Spring AI 统一接口 - 多平台AI模型支持 - 智能体平台集成 ### 3. 实时通信 - WebSocket 双向通信 - MQTT 消息推送 - 低延迟语音处理 ### 4. 容器化部署 - Docker 容器化 - 一键部署脚本 - 环境隔离和版本管理 ### 5. 前后端分离 - RESTful API 设计 - Vue.js 现代化前端 - 响应式UI设计 --- ## 后续发展规划 ### 短期目标 (3-6个月) - 完善Function Call功能 - 实现多模态交互 - 优化性能和稳定性 ### 中期目标 (6-12个月) - 集成更多AI平台 - 开发移动端应用 - 支持更多硬件设备 ### 长期目标 (12个月以上) - 构建完整的IoT生态 - 开发商业化版本 - 国际化支持 --- ## 技术支持 ### 文档资源 - [部署文档](./docs/) - [API文档](./docs/api/) - [开发指南](./docs/development/) ### 社区支持 - 微信群: 790820705 - QQ群: 790820705 - GitHub Issues: 技术问题反馈 ### 商业支持 - 定制开发服务 - 技术咨询服务 - 部署和运维支持 --- *文档版本: v2.8.1* *最后更新: 2025年1月*