AI语音智能体开发日记（十八）智能体服务器xiaozhi-esp32-server源码部署指南

xiaozhi-esp32-server 全模块源码部署指南

适用系统：Ubuntu 22.04 LTS

硬件建议：4 核 CPU、8G 内存

项目地址：https://github.com/xinnan-tech/xiaozhi-esp32-server

一、架构概览

xiaozhi-esp32-server 采用三层微服务架构，全模块部署需启动以下服务：

|----------------|-----------------------|-------------|----------|
| 服务 | 技术栈 | 默认端口 | 说明 |
| MySQL | MySQL 8.0 | 3306 | 数据库 |
| Redis | Redis 7.0 | 6379 | 缓存 |
| manager-api | Java 21 + Spring Boot | 8002 | 管理后端 API |
| manager-web | Node.js 18 + Vue.js | 8001 | 智控台前端 |
| xiaozhi-server | Python 3.10 + FastAPI | 8000 / 8003 | 核心语音服务 |

二、安装基础工具

2.1 安装 Git

sudo apt update

sudo apt install git -y

2.2 安装 Docker

sudo apt install docker.io -y

sudo systemctl start docker

sudo systemctl enable docker

验证：

docker --version

2.3 安装 Docker Compose

sudo apt install docker-compose -y

验证：

docker-compose --version

如果拉取 Docker 镜像很慢，可配置镜像加速器。编辑 /etc/docker/daemon.json：

{

"registry-mirrors": $"https://docker.m.daocloud.io"$

}

然后重启 Docker：sudo systemctl restart docker

三、安装 JDK 21（manager-api 依赖）

sudo apt install openjdk-21-jdk -y

验证：

java --version

确认输出为 openjdk 21。

同时安装 Maven（构建工具）：

sudo apt install maven -y

四、安装 Node.js 18（manager-web 依赖）

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -

sudo apt install nodejs -y

验证：

node --version

npm --version

五、安装 Miniforge（Python 环境管理）

wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh

bash Miniforge3-Linux-x86_64.sh

安装过程中一路按回车确认，最后选择 yes 初始化 conda。

重启终端使 conda 生效，验证：

conda --version

六、克隆项目源码

mkdir -p ~/server

cd ~/server

git clone https://github.com/xinnan-tech/xiaozhi-esp32-server.git

七、用 Docker 启动 MySQL 和 Redis

7.1 启动 MySQL

docker run -d \

--name xiaozhi-mysql \

-p 3306:3306 \

-e MYSQL_ROOT_PASSWORD=123456 \

-e MYSQL_DATABASE=xiaozhi_esp32_server \

mysql:8.0

7.2 启动 Redis

docker run -d \

--name xiaozhi-redis \

-p 6379:6379 \

redis:7.0

7.3 验证容器状态

docker ps

应能看到 xiaozhi-mysql 和 xiaozhi-redis 两个容器处于运行状态。

八、部署 manager-api（管理后端）

8.1 进入目录

cd ~/server/xiaozhi-esp32-server/main/manager-api

8.2 修改数据库配置

编辑 src/main/resources/application-dev.yml，确认数据库连接信息：

spring**:**

datasource**:**

username**:** root

password**:** 123456

url**:** jdbc:mysql://127.0.0.1:3306/xiaozhi_esp32_server

redis**:**

host**:** 127.0.0.1

port**:** 6379

8.3 编译并启动

mvn clean package -DskipTests

java -jar target/manager-api.jar

启动成功后，manager-api 默认运行在 8002 端口。

使用vscode打开\xiaozhi-esp32-server\main\manager-api\src\main\java\xiaozhi下的AdminApplication.java文件，右键run java或运行快捷键。

前台打开效果

九、部署 manager-web（智控台前端）

9.1 进入目录

cd ~/server/xiaozhi-esp32-server/main/manager-web

9.2 安装依赖并启动

npm install

npm run serve

启动成功后，智控台默认运行在 http://127.0.0.1:8001。

前台效果

9.3 注册超级管理员

用浏览器打开智控台地址，注册第一个用户（即超级管理员）。

十、获取 server.secret 参数

登录智控台（http://127.0.0.1:8001）
在顶部菜单找到 "参数管理"
找到参数编码为 server.secret 的记录
复制其 参数值（随机生成的密钥，每次重新部署会变化）
修改server.websocket

十一、创建 Python 3.10 虚拟环境

conda create -n xiaozhi-esp32-server python=3.10 -y

conda activate xiaozhi-esp32-server

验证：

python --version

确认输出为 Python 3.10.x。

必须使用 Python 3.10，更高版本会导致 PyTorch 等依赖找不到匹配包。

十二、安装 Python 依赖和系统工具

12.1 安装 ffmpeg 和 libopus

conda install ffmpeg libopus -y

验证：

ffmpeg -version

12.2 安装 Python 依赖

cd ~/server/xiaozhi-esp32-server/main/xiaozhi-server

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

pip install -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cpu

十三、配置 xiaozhi-server

13.1 创建 data 目录并复制配置文件

cd ~/server/xiaozhi-esp32-server/main/xiaozhi-server

mkdir -p data

cp config_from_api.yaml data/.config.yaml

13.2 编辑配置文件

nano data/.config.yaml

需要修改的关键项：

secret：填入第十步中从智控台复制的 server.secret 值
url：改为 http://127.0.0.1:8002/xiaozhi（指向 manager-api 的地址）

十四、下载语音识别模型

mkdir -p models/SenseVoiceSmall

从项目文档中提供的百度网盘链接下载 SenseVoiceSmall 模型文件（提取码: qvna），将 model.pt 放入 models/SenseVoiceSmall/ 目录下。

十五、启动 xiaozhi-server

cd ~/server/xiaozhi-esp32-server/main/xiaozhi-server

conda activate xiaozhi-esp32-server

python app.py

启动成功后，日志会输出：

OTA接口是 http://你的IP:8003/xiaozhi/ota/

Websocket地址是 ws://你的IP:8000/xiaozhi/v1/

十六、配置大模型 API Key

回到智控台（http://127.0.0.1:8001）
进入 "模型配置" → "大语言模型"
填入你从大模型服务商获取的 API Key（如智谱AI、DeepSeek、通义千问等）
保存配置

十七、测试验证

登录智控台管理界面

找到参数管理

找到参数代码为 server.websocket 的配置项

将其值改为：ws://192.168.3.132:8000/xiaozhi/v1/

进入xiaozhi-esp32-server/test

python -m http.server 8006

用浏览器打开项目 test 目录下的 test_page.html，填入日志中输出的 WebSocket 地址（ws://你的IP:8000/xiaozhi/v1/）进行测试。

十八、各服务端口汇总

|--------------------------|------|-----------|
| 服务 | 端口 | 说明 |
| MySQL | 3306 | 数据库 |
| Redis | 6379 | 缓存 |
| manager-api | 8002 | 管理后端 API |
| manager-web | 8001 | 智控台前端 |
| xiaozhi-server WebSocket | 8000 | 设备通信 |
| xiaozhi-server HTTP/OTA | 8003 | OTA 和视觉分析 |

十九、常见问题速查

|------------------------------------------|-----------------------------------------------------------------------------------|
| 问题 | 解决方法 |
| Docker 镜像拉取慢 | 配置 registry-mirrors 镜像加速器 |
| 找不到data/.config.yaml | 在 xiaozhi-server 下执行 mkdir -p data && cp config_from_api.yaml data/.config.yaml |
| No such file or directory: 'ffmpeg' | 执行 conda install ffmpeg -y |
| LLM 的 API key 未设置 | 在智控台的"模型配置"中填入真实 API Key |
| No matching distribution found for torch | 确认使用的是 Python 3.10 环境 |
| manager-api 连不上数据库 | 检查 application-dev.yml 中的数据库地址和密码是否正确 |
| TTS 任务出错 | 确认已通过 conda 安装了 libopus 和 ffmpeg |
| 语音识别出现乱码 | 确认 models/SenseVoiceSmall/model.pt 模型文件已正确放置 |

二十、注意事项

所有安装路径严禁包含中文或空格
Python 版本必须为 3.10，不可使用更高版本
每次重新部署后，server.secret 会重新生成，需重新配置
云服务器部署时，安全组需开放 8000-8003 端口
设备与服务端需在同一局域网下，或确保网络可达