Xiaozhi-ESP32-Server 全模块部署指南

Xiaozhi-ESP32-Server 全模块部署指南

xiaozhi-esp32-server 本项目为xiaozhi-esp32提供后端服务，帮助您快速搭建ESP32设备控制服务器。Backend service for xiaozhi-esp32, helps you quickly build an ESP32 device control server. 项目地址: https://gitcode.com/gh_mirrors/xia/xiaozhi-esp32-server

项目概述

Xiaozhi-ESP32-Server 是一个基于ESP32芯片的智能语音交互系统，包含语音识别、自然语言处理、语音合成等功能模块。本文将详细介绍如何部署该项目的全模块环境，包括服务端、管理后台和数据库等组件。

部署架构

系统采用微服务架构，主要包含以下组件：

• 核心服务（xiaozhi-esp32-server）：处理语音交互逻辑
• 管理后台（manager-web）：提供可视化配置界面
• 管理API（manager-api）：提供RESTful接口
• MySQL数据库：存储系统配置和用户数据
• Redis：缓存服务

部署方式一：Docker容器化部署

1. 环境准备

首先确保系统已安装Docker引擎，建议使用最新稳定版本。Docker提供了跨平台的容器化解决方案，能够简化依赖管理和部署流程。

2. 目录结构准备

创建项目目录并建立如下结构：

xiaozhi-server
  ├─ data          # 配置文件目录
  ├─ models        # 模型文件目录
     ├─ SenseVoiceSmall  # 语音识别模型

3. 模型文件准备

语音识别模型使用SenseVoiceSmall，需手动下载：

1. 从阿里魔塔或百度网盘获取model.pt文件
2. 放置到models/SenseVoiceSmall目录下

4. 配置文件准备

下载两个关键配置文件：

• docker-compose_all.yml：定义所有服务的容器编排
• config_from_api.yaml：服务端核心配置文件

将config_from_api.yaml重命名为.config.yaml并放入data目录。

5. 启动服务

执行以下命令启动所有服务：

docker compose -f docker-compose_all.yml up -d

6. 初始化配置

1. 访问管理后台（http://127.0.0.1:8002）注册管理员账号
2. 配置server.secret密钥
3. 配置大语言模型API密钥（如智谱AI）
4. 设置WebSocket和OTA服务地址

部署方式二：本地源码部署

1. 数据库准备

创建MySQL数据库：

CREATE DATABASE xiaozhi_esp32_server 
CHARACTER SET utf8mb4 
COLLATE utf8mb4_unicode_ci;

2. 运行管理API

1. 安装JDK21和Maven
2. 配置application-dev.yml中的数据库连接
3. 运行AdminApplication主类

3. 运行管理后台

1. 安装Node.js
2. 执行npm install安装依赖
3. 运行npm run serve启动开发服务器

4. Python环境准备

使用conda创建隔离环境：

conda create -n xiaozhi-esp32-server python=3.10
conda install libopus ffmpeg
pip install -r requirements.txt

5. 启动核心服务

配置.config.yaml文件后，执行：

python app.py

关键配置说明

1. server.secret：服务间通信密钥，需与管理后台保持一致
2. 大语言模型API：系统对话能力的核心，需配置有效的API密钥
3. WebSocket地址：设备连接的服务端点
4. OTA地址：设备固件升级服务端点

常见问题解决方案

1. 语音识别异常：检查模型文件是否正确放置，确认音频采样率设置
2. TTS服务失败：检查网络连接，确认语音合成服务配置
3. 4G连接问题：确保服务有公网可达地址，检查防火墙设置
4. 响应速度优化：调整语音端点检测参数，优化网络延迟

后续步骤

完成服务部署后，您可以选择：

1. 自行编译ESP32固件
2. 使用预编译固件进行配置

建议首次使用的用户从预编译固件开始，熟悉系统后再考虑自定义开发。

性能优化建议

1. 对于生产环境，建议使用GPU加速语音识别模型
2. 高并发场景下，考虑使用Redis集群
3. 定期备份数据库重要配置
4. 监控服务资源使用情况，及时扩容

通过本文档的指导，您应该能够成功部署Xiaozhi-ESP32-Server全模块环境。如在部署过程中遇到问题，可参考项目文档中的FAQ部分或寻求社区支持。

xiaozhi-esp32-server 本项目为xiaozhi-esp32提供后端服务，帮助您快速搭建ESP32设备控制服务器。Backend service for xiaozhi-esp32, helps you quickly build an ESP32 device control server. 项目地址: https://gitcode.com/gh_mirrors/xia/xiaozhi-esp32-server