laumy的学习笔记
首页
联系我

ubuntu系统xiaozhi server本地部署

🕒 2025-10-30 📁 Ai应用 👤 laumy 🔥 20 热度

简介

本文主要是记录在ubuntu系统从零源码的方式本地部署小智Ai服务端的过程，项目的地址为：xiaozhi-server。在部署之前简单了解一下其项目框架，这里总结可以分为3部分：manager-web、manager-api、xiaozhi-server，这3部分的运行是互相独立的，相互之间通过http rest api的方式进行访问，如下图:

  • manager-web: 前端控制台（Vue）。管理员用浏览器操作；调用后端接口，不直接连设备。
  • manager-api: 后端管理服务（Java Spring Boot）。负责用户/设备/模型/参数/OTA/激活等业务，对外提供 REST API；对数据库(MySQL)与缓存(Redis)读写。
  • xiaozhi-server: 实时语音与智能体服务（Python）。负责 WebSocket 连接、ASR/LLM/TTS、工具/视觉接口；启动时向 manager-api 拉取配置、运行时上报对话。

3个组件分别使用了不用的语言环境，其中manager-web使用的是Vue.js，而manager-api使用的是java spring boot，xiaozhi-server使用的是python。因此需要装3个不同的语言环境。同时对于后端manager-api需要对数据进行存储，因此还需要安装mysql、redis。下面就围绕这3部分进行展开。

先在本地拉取一份代码：

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

值得注意的时，xiaozhi server最简化版本安装，只需要安装xiaozhi-server即可，简化版部署见后续章节。

manager-api安装

数据库安装

由于后端的数据管理需要用到数据库，因此需要安装mysql、redis。

（1）mysql安装

# 安装MySQL
sudo apt update
sudo apt install -y mysql-server

# 启动MySQL服务
sudo systemctl start mysql
sudo systemctl enable mysql

# 创建数据库
sudo mysql -e "CREATE DATABASE xiaozhi_esp32_server CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 创建用户并指定认证方式（关键改动）
sudo mysql -e "CREATE USER 'xiaozhi'@'localhost' IDENTIFIED WITH mysql_native_password BY 'xiaozhi123';"

# 授权
sudo mysql -e "GRANT ALL PRIVILEGES ON xiaozhi_esp32_server.* TO 'xiaozhi'@'localhost';"
sudo mysql -e "FLUSH PRIVILEGES;"

mysql数据库安装后，同时也创建了用户和密码，分别是xiaozhi和xiaozhi123，这个后续需要填充到manaer-api的配置文件中，以便manager-api可以访问。

（2）安装Redis

# 安装Redis
sudo apt install -y redis-server

# 启动Redis服务
sudo systemctl start redis-server
sudo systemctl enable redis-server

# 检查Redis状态
redis-cli ping

Spring boot环境安装

因为后端程序manager-api使用的是java spring boot，因此需要安装java的运行环境。官方提示安装JDK21和Maven，前者是java的运行环境，后者是java项目管理工具。

# 安装JDK 21
sudo apt install -y openjdk-21-jdk

# 设置JAVA_HOME环境变量
echo 'export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64' >> ~/.bashrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 验证Java安装
java -version

# 安装Maven
sudo apt install -y maven

# 验证Maven安装
mvn -version

配置数据库

数据库和java环境安装好后，就可以配置java spring boot与数据库的连接了。

在xiaozhi-esp32-server/main/manager-api/src/main/resources/application-dev.yml中配置数据库连接信息

@@ -13,8 +13,8 @@ spring:
       #MySQL
       driver-class-name: com.mysql.cj.jdbc.Driver
       url: jdbc:mysql://127.0.0.1:3306/xiaozhi_esp32_server?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&nullCatalogMeansCurrent=true
-      username: root
-      password: 123456
+      username: xiaozhi
+      password: xiaozhi123
       initial-size: 10
       max-active: 100
       min-idle: 10

在xiaozhi-esp32-server/main/src/main/resources/application-dev.yml中配置Redis连接信息（redis默认配置好了，不用改）

spring:
    data:
      redis:
        host: localhost
        port: 6379
        password:
        database: 0

编译运行

配置好对数据库的连接后，就可以进行编译了。

# 进入manager-api目录
cd xiaozhi-esp32-server/main/manager-api


# 编译项目
mvn clean package -DskipTests

# 编译完成后的jar包位置
ls -lh target/*.jar

编译完成之后，就可以运行项目了。

java -jar target/xiaozhi-esp32-api.jar --spring.profiles.active=dev

运行如果没有什么报错就说明启动成功了。

manager-web安装

安装node.js

由于前端使用的的是vue.js，所以需要安装node.js环境。

# 安装Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 验证Node.js安装
node -v
npm -v

安装依赖

node.js环境安装好后，就可以安装manager-web的依赖了。

# 进入manager-web目录
cd xiaozhi-esp32-server/main/manager-web

# 安装依赖
npm install

启动

切换到manager-web路径下，就可以运行服务程序了。

cd xiaozhi-esp32-server/main/manager-web
npm run serve

启动成功之后，就可以访问后台了。登陆地址：http://127.0.0.1:8001，登陆后进行注册一个用户就可以进入到后台进行配置了。

配置模型api key

要让设备能够访问，需要配置模型的api key，登陆到智普的后台，注册获取一个api key。

这里使用的是智谱ai，注册一个账户，然后申请一个api key

然后登陆智控台配置密钥。

xiaozhi-server安装

conda python环境

# 下载并安装miniconda
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3

# 初始化conda
$HOME/miniconda3/bin/conda init bash
source ~/.bashrc

# 创建Python环境
conda remove -n xiaozhi-esp32-server --all -y
conda create -n xiaozhi-esp32-server python=3.10 -y

# 激活环境
conda activate xiaozhi-esp32-server

# 添加清华源
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge

# 安装必要的系统库
conda install -y libopus ffmpeg libiconv

python依赖包

# 进入xiaozhi-server目录
cd xiaozhi-esp32-server/main/xiaozhi-server

# 设置pip镜像源
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

# 安装Python依赖
pip install -r requirements.txt

下载语音模型

# 进入models目录
cd xiaozhi-esp32-server/main/xiaozhi-server/models

# 下载模型文件（推荐阿里云镜像）
cd SenseVoiceSmall
wget https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt

# 验证文件
ls -lh model.pt

配置密钥

配置密钥主要是xiaozhi-server与manager-api交互时需要进行认证，因此需要先获取密钥。

（1）先在本地创建配置文件

# 创建data目录
cd xiaozhi-esp32-server/main/xiaozhi-server
mkdir -p data

# 复制配置文件
cp config_from_api.yaml data/.config.yaml

# 编辑配置文件
vim data/.config.yaml

配置.config.yaml:

manager-api:
  url: http://127.0.0.1:8002/xiaozhi
  secret: 待会从智控台获取

server:
  websocket: ws://你的IP:8000/xiaozhi/v1/

（2）然后登陆智控台获取密钥

  1. 访问智控台：http://127.0.0.1:8001
  2. 注册账号（第一个为超级管理员）
  3. 登录 → 参数管理 → 找到 server.secret 并复制
  4. 回到xiaozhi-server配置：

vim xiaozhi-esp32-server/main/xiaozhi-server/data/.config.yaml

设置为

manager-api:
  url: http://127.0.0.1:8002/xiaozhi
  secret: 你刚才复制的server.secret值

启动服务

cd xiaozhi-esp32-server/main/xiaozhi-server
conda activate xiaozhi-esp32-server
python app.py

执行成功的话应该是下面这样

(xiaozhi-esp32-server) liumingyuan@HP-ProBook:~/xiaozhi-esp32-server/main/xiaozhi-server$ python app.py 
从API读取配置
251029 20:47:34[0.8.5-00000000000000][core.providers.vad.silero]-INFO-SileroVAD
251029 20:47:34[0.8.5-00000000000000][core.utils.modules_initialize]-INFO-初始化组件: vad成功 VAD_SileroVAD
251029 20:47:38[0.8.5-00000000000000][core.providers.asr.fun_local]-INFO-funasr version: 1.2.3.
251029 20:47:38[0.8.5-00000000000000][core.utils.modules_initialize]-INFO-ASR模块初始化完成
251029 20:47:38[0.8.5-00000000000000][core.utils.modules_initialize]-INFO-初始化组件: asr成功 ASR_FunASR
251029 20:47:38[0.8.5-00000000000000][__main__]-INFO-视觉分析接口是    http://10.0.90.104:8003/mcp/vision/explain
251029 20:47:38[0.8.5-00000000000000][__main__]-INFO-Websocket地址是   ws://10.0.90.104:8000/xiaozhi/v1/
251029 20:47:38[0.8.5-00000000000000][__main__]-INFO-=======上面的地址是websocket协议地址，请勿用浏览器访问=======
251029 20:47:38[0.8.5-00000000000000][__main__]-INFO-如想测试websocket请用谷歌浏览器打开test目录下的test_page.html
251029 20:47:38[0.8.5-00000000000000][__main__]-INFO-=============================================================

服务访问地址：

  • 智控台：http://127.0.0.1:8001
  • API文档：http://127.0.0.1:8002/xiaozhi/doc.html
  • WebSocket：ws://127.0.0.1:8000/xiaozhi/v1/
  • OTA接口：http://127.0.0.1:8002/xiaozhi/ota/

配置websocket和OTA

由于是全模块部署，所以需要登陆智能控台，设置ota和websocket的接口，需要注意的是weboscket的启动必须是要等xiaozhi-server app启动才能设置。

OTA接口：http://你电脑局域网的ip:8002/xiaozhi/ota/
Websocket接口：ws://你电脑局域网的ip:8000/xiaozhi/v1/
请你务必把以上两个接口地址写入到智控台中：他们将会影响websocket地址发放和自动升级功能。

1、使用超级管理员账号，登录智控台，在顶部菜单找到参数管理，找到参数编码是server.websocket，输入你的Websocket接口。

2、使用超级管理员账号，登录智控台，在顶部菜单找到参数管理，找到数编码是server.ota，输入你的OTA接口。

简化部署

所谓简化部署就是只跑xiaozhi-server，前后端都不跑。简化部署先参考”xiaozhi-server安装”章节，然后再次基础上进行配置文件即可。与完整部署xiaozhi-server部分唯一的区别就是配置文件不一样。如果要对接前后端使用的默认文件是config_from_api.yaml而如果是简化部署使用的默认文件是config.yaml。

下面是配置步骤。

cd xiaozhi-esp32-server/main/xiaozhi-server/data

cp .config.yaml .config.yaml_back     #对云端的配置作个备份
cp ../config.yaml .config.yaml            #拷贝默认的配置

设置API key

测试

本地服务搭建好好后可以进行测试验证，可以使用xiaozhi-server自带的test程序，也可以使用开源的客户端py-xiaozhi，或者直接搭建esp32的设备接入。这里先用前面两者方式。

xiaozhi-server test

cd xiaozhi-esp32-server/main/xiaozhi-server/test
python -m http.server 8006

然后网页登陆：http://localhost:8006/test_page.html

py-xiaozhi

git clone https://github.com/huangjunsen0406/py-xiaozhi.git

sudo apt-get update && sudo apt-get install -y portaudio19-dev libportaudio2

conda create -n py-xiaozhi-client python=3.10
conda activate py-xiaozhi-client

配置完成之后就可以执行应用获取到设备验证码之后，登陆绑定即可进行对话。

python main.py --protocol websocket

发表你的看法

\t↑