357 lines
9.8 KiB
Markdown
357 lines
9.8 KiB
Markdown
# 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月* |