xiaozhi-esp32-server全模块Docker部署教程

作者

 


Hello 大家好呀！热烈欢迎来到 Turing门徒 的成长世界，一起学习、探索、交流技术 🚀

今天与大家一起学习的是：如何通过Docker全模块部署xiaozhi-esp32-server。

引言

之前我们把米家设备接入了HA，现在来自部署一下小智ESP32语音设备的服务端软件，方面后续通过它来使用HA控制我们的米家设备。

各位看官可以参考官方介绍 https://github.com/xinnan-tech/xiaozhi-esp32-server

不过门徒这里还是重现记录一下，部署完成即可正常使用小智全套语音、OTA等功能。

部署前置准备

设备与系统要求

  • • 服务器系统：Linux系统（一键脚本专属适配Ubuntu，其他系统易出现未知bug）

  • • 权限要求：必须使用 root权限 执行部署命令，避免权限不足导致安装失败

  • • 网络要求：服务器网络通畅，云服务器需提前放行 8000、8001、8002、8003 端口

一键全自动部署

一键脚本为适配全模块的自动化部署工具，可自动完成Docker安装、镜像源配置、模型下载、服务拉取、环境初始化、服务启动全套操作，无需手动敲复杂命令。

部署简便，但暂且只支持Ubuntu服务器一键部署，其他系统未尝试，可能会有一些奇怪的bug。

执行一键部署脚本

使用SSH工具连接到服务器，以root权限执行如下脚本

sudo bash -c "$(wget -qO- https://ghfast.top/https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/main/docker-setup.sh)"

脚本自动执行流程

脚本会自动完成以下操作：

  • • 自动安装依赖工具 whiptail、curl

  • • 检测并安装Docker核心环境

  • • 提供多镜像源选择（轩辕、腾讯云、中科大等，默认推荐轩辕镜像，下载最快）

  • • 自动创建服务端目录、模型存储目录

  • • 下载SenseVoiceSmall语音识别模型

  • • 拉取全套服务Docker镜像，启动全模块服务

  • • 支持一键升级：检测到已安装服务端可自动清理旧容器、旧镜像，备份配置后升级最新版本

部署中途关键操作

脚本运行至镜像源选择界面，新手直接选择1（轩辕镜像），速度最快、成功率最高，无需自定义配置。
若检测到旧版本服务，可选择「升级」，脚本自动备份原有配置，升级不丢失自定义设置。

一键部署完成后配置

跳过手动分步部署，直接查看要做的三件事情。

手动分步部署

门徒采用的是这个方法安装的。

若一键脚本部署失败、网络波动导致模型/配置下载异常，可使用手动部署方案，步骤清晰、每一步可校验，也是主流落地部署方式。

创建项目目录结构

依次执行以下命令，创建服务端根目录、数据目录、语音模型专属目录：

mkdir xiaozhi-server
cd xiaozhi-server/
mkdir -p data models/SenseVoiceSmall
# 安装目录查看工具
sudo apt install tree
# 查看目录结构，确认创建成功
tree

下载核心语音识别模型

进入模型目录，下载必备的SenseVoiceSmall模型文件（服务语音识别核心依赖）：

cd models/SenseVoiceSmall/
wget -c -t 0 https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt
# 返回上级目录
cd ../../

下载核心配置文件

下载Docker编排文件和服务端核心配置文件：

# 下载docker全模块启动配置
wget -c -t 0  https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/docker-compose_all.yml
# 下载服务端默认配置文件
wget -c -t 0  https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/config_from_api.yaml
# 查看文件是否下载成功
ls

迁移配置文件并重命名

将默认配置文件移动到data目录，并重命名为系统识别的隐藏配置文件：

# 移动配置文件至数据目录
mv config_from_api.yaml data/
# 重命名为生效配置文件
mv data/config_from_api.yaml data/.config.yaml
# 校验目录文件完整性
tree -a

xiaozhi-server
  ├─ docker-compose_all.yml
  ├─ data
    ├─ .config.yaml
  ├─ models
     ├─ SenseVoiceSmall
       ├─ model.pt

启动全模块Docker服务

执行Docker命令，后台启动全套服务，首次启动会自动拉取所有镜像：

# 停止旧服务（首次部署可忽略）
docker compose -f docker-compose_all.yml down
# 后台启动全模块服务
docker compose -f docker-compose_all.yml up -d

校验服务启动状态

通过日志查看服务是否正常启动，排查启动异常问题：

# 查看web管理服务日志
docker logs -f xiaozhi-esp32-server-web
# 筛选启动成功日志
docker logs -f xiaozhi-esp32-server-web | grep Start
# 查看服务访问地址日志
docker logs -f xiaozhi-esp32-server-web | grep http
# 查看主服务运行日志
docker logs -f xiaozhi-esp32-server

正常是可以启动成功的，如果端口被占用，则需要更换端口或者找到占用端口的进程关掉它。

部署完成的三件事情

这时，你需要使用浏览器，打开智控台，链接：http://服务器IP:8002 ，注册第一个用户。第一个用户即是超级管理员，以后的用户都是普通用户。普通用户只能绑定设备和配置智能体;超级管理员可以进行模型管理、用户管理、参数配置等功能。

第一件

使用超级管理员账号，登录智控台，在顶部菜单找到参数管理，找到列表中第一条数据，参数编码是server.secret，复制它到参数值。

server.secret需要说明一下，这个参数值很重要，作用是让我们的Server端连接manager-api。server.secret是每次从零部署manager模块时，会自动随机生成的密钥。

复制参数值后，打开xiaozhi-server下的data目录的.config.yaml文件。

  • • 把你刚才从智控台复制过来的server.secret的参数值复制到.config.yaml文件里的secret里。

  • • 因为我们是docker部署，把url改成下面的http://xiaozhi-esp32-server-web:8002/xiaozhi

此刻你的配置文件内容应该是这样的：

server:
  ip: 0.0.0.0
  port: 8000
--
  # 如果使用docker部署，请使用填写成 http://xiaozhi-esp32-server-web:8002/xiaozhi
  url: http://xiaozhi-esp32-server-web:8002/xiaozhi
  # url: http://127.0.0.1:8002/xiaozhi
  # 你的manager-api的token，就是刚才复制出来的server.secret
  # secret: 你的server.secret值
  secret: 你的server.secret值

第二件

使用超级管理员账号，登录智控台，在顶部菜单找到模型配置，然后在左侧栏点击大语言模型，找到第一条数据智谱AI，点击修改按钮， 弹出修改框后，将你注册到的智谱AI的密钥填写到API密钥中（若还没有注册有，则需要去智谱官网进行注册）。然后点击保存。

重启xiaozhi-esp32-server

docker restart xiaozhi-esp32-server
docker logs -f xiaozhi-esp32-server

第三件

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

  • • OTA升级地址：http://服务器IP:8002/xiaozhi/ota/

  • • 设备WebSocket连接地址：ws://服务器IP:8000/xiaozhi/v1/

xiaozhi-esp32固件这边，需要配置CONFIG_OTA_URL
CONFIG_OTA_URL="http://你的IP:8002/xiaozhi/ota/"

  • • 添加智能体，再去设备管理关联设备即可

常见部署问题解决

  • • 模型下载失败：切换服务器网络，或手动复制模型文件至对应目录，跳过下载步骤

  • • Docker镜像拉取超时：重新运行脚本，选择轩辕、腾讯云等国内镜像源

  • • 服务启动超时：检查服务器端口是否放行、内存是否充足，重启Docker后重新启动服务

  • • 密钥配置不生效：重新输入密钥后，手动执行 docker restart xiaozhi-esp32-server 重启主服务

结语

  1. 1. 新手优先一键部署：全程自动化，无需复杂操作，适合快速搭建环境；

  2. 2. 报错首选手动部署：分步操作可精准定位问题，部署稳定性更高；

  3. 3. 部署完成后务必完成密钥配置+端口放行，否则设备无法正常连接、功能无法生效。

非常感谢各位看官，耐心陪着笔者一起学习到这。

 

发表评论