liqupan/server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
server/技术文档.md
liqupan b767041311 feat ：init
2025-11-02 19:34:16 +08:00

9.8 KiB
Raw Permalink Blame History

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 部署 (推荐)

# 克隆项目
git clone [项目地址]

# 启动服务
docker-compose up -d

# 检查状态
docker-compose ps

2. 源码部署

# 后端编译
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: 容器编排配置

关键配置项

# 服务端口
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生态
  • 开发商业化版本
  • 国际化支持

技术支持

文档资源

社区支持

  • 微信群: 790820705
  • QQ群: 790820705
  • GitHub Issues: 技术问题反馈

商业支持

  • 定制开发服务
  • 技术咨询服务
  • 部署和运维支持

文档版本: v2.8.1 最后更新: 2025年1月

Reference in New Issue View Git Blame Copy Permalink