jsntwdj/xiaozhi-esp32-server

By jsntwdj

•Updated 6 months ago

本项目为xiaozhi-esp32提供后端服务，基于官方源码编译的arm64版本。

Image

467

Overview Tags

jsntwdj/xiaozhi-esp32-server repository overview

本项目发行的docker镜像只支持arm64架构。需要amd64（x86）架构版本的请去官方仓库xinnan-tech/xiaozhi-esp32-server⁠按部署教程安装。

⁠一、Docker运行全模块

⁠1. 安装docker

如果您的电脑还没安装docker，可以按照这里的教程安装：docker安装⁠

⁠1.1 手动部署流程

安装Docker

配置镜像源

下载/拉取镜像

下载语音识别模型文件

引导配置服务端

⁠1.2 手动部署

⁠1.2.1 创建目录

安装完后，你需要为这个项目找一个安放配置文件的目录，例如我们可以新建一个文件夹叫xiaozhi-server。

创建好目录后，你需要在xiaozhi-server下面创建data文件夹和models文件夹，models下面还要再创建SenseVoiceSmall文件夹。

最终目录结构如下所示：

xiaozhi-server
  ├─ data
  ├─ models
     ├─ SenseVoiceSmall

⁠1.2.2 下载语音识别模型文件

本项目语音识别模型，默认使用SenseVoiceSmall模型，进行语音转文字。因为模型较大，需要独立下载，下载后把model.pt 文件放在models/SenseVoiceSmall 目录下。下面两个下载路线任选一个。

线路一：阿里魔搭下载SenseVoiceSmall⁠
线路二：百度网盘下载SenseVoiceSmall⁠ 提取码: qvna

⁠1.2.3 下载配置文件

你需要配置两个文件：docker-compose_all.yaml 和 config_from_api.yaml。

⁠1.2.3.1 配置 docker-compose_all.yaml

新建docker-compose_all.yaml，配置如下：

# Docker安装全模块

version: '3'
services:
  # Server模块
  xiaozhi-esp32-server:
    image: jsntwdj/xiaozhi-esp32-server:server_latest
    container_name: xiaozhi-esp32-server
    depends_on:
      - xiaozhi-esp32-server-db
      - xiaozhi-esp32-server-redis
    restart: always
    networks:
      - default
    ports:
      # ws服务端
      - "8000:8000"
      # http服务的端口，用于视觉分析接口
      - "8003:8003"
    security_opt:
      - seccomp:unconfined
    environment:
      - TZ=Asia/Shanghai
    volumes:
      # 配置文件目录
      - ./data:/opt/xiaozhi-esp32-server/data
      # 模型文件挂接，很重要
      - ./models/SenseVoiceSmall/model.pt:/opt/xiaozhi-esp32-server/models/SenseVoiceSmall/model.pt

  # manager-api和manager-web模块
  xiaozhi-esp32-server-web:
    image: jsntwdj/xiaozhi-esp32-server:web_latest
    container_name: xiaozhi-esp32-server-web
    restart: always
    networks:
      - default
    depends_on:
      xiaozhi-esp32-server-db:
        condition: service_healthy
      xiaozhi-esp32-server-redis:
        condition: service_healthy
    ports:
      # 智控台
      - "8002:8002"
    environment:
      - TZ=Asia/Shanghai
      - SPRING_DATASOURCE_DRUID_URL=jdbc:mysql://xiaozhi-esp32-server-db:3306/xiaozhi_esp32_server?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&nullCatalogMeansCurrent=true&connectTimeout=30000&socketTimeout=30000&autoReconnect=true&failOverReadOnly=false&maxReconnects=10
      - SPRING_DATASOURCE_DRUID_USERNAME=root
      - SPRING_DATASOURCE_DRUID_PASSWORD=123456
      - SPRING_DATA_REDIS_HOST=xiaozhi-esp32-server-redis
      - SPRING_DATA_REDIS_PASSWORD=
      - SPRING_DATA_REDIS_PORT=6379
    volumes:
      # 配置文件目录
      - ./uploadfile:/uploadfile
  # 数据库模块
  xiaozhi-esp32-server-db:
    image: mysql:latest
    container_name: xiaozhi-esp32-server-db
    healthcheck:
      test: [ "CMD", "mysqladmin" ,"ping", "-h", "localhost" ]
      timeout: 45s
      interval: 10s
      retries: 10
    restart: always
    networks:
      - default
    expose:
      - 3306
    volumes:
      - ./mysql/data:/var/lib/mysql
    environment:
      - TZ=Asia/Shanghai
      - MYSQL_ROOT_PASSWORD=123456
      - MYSQL_DATABASE=xiaozhi_esp32_server
      - MYSQL_INITDB_ARGS="--character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci"
  # redis模块
  xiaozhi-esp32-server-redis:
    image: redis:8.0
    expose:
      - 6379
    container_name: xiaozhi-esp32-server-redis
    restart: always
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3
    networks:
      - default
networks:
  default:

配置完后，回到本教程继续往下。

⁠1.2.3.2 下载 config_from_api.yaml

用浏览器打开这个链接⁠。

在页面的右侧找到名称为RAW按钮，在RAW按钮的旁边，找到下载的图标，点击下载按钮，下载config_from_api.yaml文件。把文件下载到你的 xiaozhi-server下面的data文件夹中，然后把config_from_api.yaml文件重命名为.config.yaml。

或者直接执行 wget https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/config_from_api.yaml 下载保存。

下载完配置文件后，我们确认一下整个xiaozhi-server里面的文件如下所示：

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

如果你的文件目录结构也是上面的，就继续往下。如果不是，你就再仔细看看是不是漏操作了什么。

⁠2. 备份数据

如果你之前已经成功运行智控台，如果上面保存有你的密钥信息，请先从智控台上拷贝重要数据下来。因为升级过程中，有可能会覆盖原来的数据。

⁠3. 清除历史版本镜像和容器

接下来打开命令行工具，使用终端或命令行工具进入到你的xiaozhi-server，执行以下命令

docker compose -f docker-compose_all.yml down

docker stop xiaozhi-esp32-server
docker rm xiaozhi-esp32-server

docker stop xiaozhi-esp32-server-web
docker rm xiaozhi-esp32-server-web

docker stop xiaozhi-esp32-server-db
docker rm xiaozhi-esp32-server-db

docker stop xiaozhi-esp32-server-redis
docker rm xiaozhi-esp32-server-redis

docker rmi ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:server_latest
docker rmi ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:web_latest

⁠4. 运行程序

执行以下命令启动新版本容器

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

执行完后，再执行以下命令，查看日志信息。

docker logs -f xiaozhi-esp32-server-web

当你看到输出日志时，说明你的智控台启动成功了。

2025-xx-xx 22:11:12.445 [main] INFO  c.a.d.s.b.a.DruidDataSourceAutoConfigure - Init DruidDataSource
2025-xx-xx 21:28:53.873 [main] INFO  xiaozhi.AdminApplication - Started AdminApplication in 16.057 seconds (process running for 17.941)
http://localhost:8002/xiaozhi/doc.html

请注意此刻仅是智控台能运行，如果8000端口xiaozhi-esp32-server报错，先不要理会。

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

接下来要做三件重要的事情：

⁠第一件重要的事情

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

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

复制参数值后，打开xiaozhi-server下的data目录的.config.yaml文件。此刻你的配置文件内容应该是这样的：

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

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

2、因为你是docker部署，把url改成下面的http://xiaozhi-esp32-server-web:8002/xiaozhi

3、因为你是docker部署，把url改成下面的http://xiaozhi-esp32-server-web:8002/xiaozhi

4、因为你是docker部署，把url改成下面的http://xiaozhi-esp32-server-web:8002/xiaozhi

类似这样的效果

manager-api:
  url: http://xiaozhi-esp32-server-web:8002/xiaozhi
  secret: 12345678-xxxx-xxxx-xxxx-123456789000

保存好后，继续往下做第二件重要的事情

⁠第二件重要的事情

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

⁠5.重启xiaozhi-esp32-server

接下来打开命令行工具，使用终端或命令行工具输入

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

如果你能看到，类似以下日志,则是Server启动成功的标志。

25-02-23 12:01:09[core.websocket_server] - INFO - Websocket地址是      ws://xxx.xx.xx.xx:8000/xiaozhi/v1/
25-02-23 12:01:09[core.websocket_server] - INFO - =======上面的地址是websocket协议地址，请勿用浏览器访问=======
25-02-23 12:01:09[core.websocket_server] - INFO - 如想测试websocket请用谷歌浏览器打开test目录下的test_page.html
25-02-23 12:01:09[core.websocket_server] - INFO - =======================================================

由于你是全模块部署，因此你有两个重要的接口需要写入到esp32中。

OTA接口：

http://你宿主机局域网的ip:8002/xiaozhi/ota/

Websocket接口：

ws://你宿主机的ip:8000/xiaozhi/v1/

⁠第三件重要的事情

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

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

接下来，你就可以开始操作你的esp32设备了，你可以自行编译esp32固件也可以配置使用虾哥编译好的1.6.1以上版本的固件。两个任选一个

1、编译自己的esp32固件⁠了。

2、基于虾哥编译好的固件配置自定义服务器⁠了。

其余未尽事宜，详见官网：xinnan-tech/xiaozhi-esp32-server⁠

Tag summary

Recent tags

Content type

Image

Digest

sha256:880f3cfc4…

Size

190 MB

Last updated

6 months ago

docker pull jsntwdj/xiaozhi-esp32-server:web_latest