feat ：init

2025-11-02 19:34:16 +08:00
commit b767041311
617 changed files with 124099 additions and 0 deletions
--- a/技术文档.md
+++ b/技术文档.md
@@ -0,0 +1,357 @@
+# 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月*