17 KiB

Raw Blame History Unescape Escape

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

部署架构图

方式一：Docker运行全模块

docker镜像已支持x86架构、arm64架构的CPU，支持在国产操作系统上运行。

1. 安装docker

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

1.1 创建目录

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

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

最终目录结构如下所示：

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

1.2 下载语音识别模型文件

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

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

1.3 下载配置文件

你需要下载两个配置文件：docker-compose_all.yaml 和 config_from_api.yaml。需要从项目仓库下载这两个文件。

1.3.1 下载 docker-compose_all.yaml

用浏览器打开这个链接。

在页面的右侧找到名称为RAW按钮，在RAW按钮的旁边，找到下载的图标，点击下载按钮，下载docker-compose_all.yml文件。把文件下载到你的 xiaozhi-server中。

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

1.3.2 下载 config_from_api.yaml

用浏览器打开这个链接。

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

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

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

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

2. 安装Mysql和Redis

2.1 安装Mysql数据库

如果本机已经安装了MySQL，可以直接在数据库中创建名为xiaozhi_esp32_server的数据库。

CREATE DATABASE xiaozhi_esp32_server CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

如果还没有MySQL，你可以通过docker安装mysql

docker run --name xiaozhi-esp32-server-db -e MYSQL_ROOT_PASSWORD=123456 -p 3306:3306 -e MYSQL_DATABASE=xiaozhi_esp32_server -e MYSQL_INITDB_ARGS="--character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci" -d mysql:latest

2.2 安装Redis

如果还没有Redis，你可以通过docker安装redis

docker run --name xiaozhi-esp32-server-redis -d -p 6379:6379 redis

3. 配置docker-compose_all.yml文件文件

在xiaozhi-server目录，打开docker-compose_all.yml，

1、修改SPRING_DATASOURCE_DRUID_URL里，把192.168.1.25修改成部署mysql的电脑局域网ip，如果是你本地，你要查看一下你本机的局域网ip是什么

2、修改SPRING_DATA_REDIS_HOST里，把192.168.1.25修改成部署redis的电脑局域网ip，如果是你本地，你要查看一下你本机的局域网ip是什么

3、确认一下mysql的用户名SPRING_DATASOURCE_DRUID_USERNAME和密码SPRING_DATASOURCE_DRUID_PASSWORD

4. 运行程序

确认mysql和redis是否运行正常，输入

docker ps

如果你能看到xiaozhi-esp32-server-redis和xiaozhi-esp32-server-db信息，就可以继续往下，如果看不到，说明你的mysql和redis没有安装或没有启动。需要继续回到上面的教程，看看哪一步漏了。

CONTAINER ID             IMAGE   COMMAND   CREATED  TATUS   PORTS               NAMES
xxx       redis          "xx"   xxx   xxx   0.0.0.0:6379->6379/tcp              xiaozhi-esp32-server-redis
xxx       mysql:latest   "xx"   xxx   xxx   0.0.0.0:3306->3306/tcp, 33060/tcp   xiaozhi-esp32-server-db

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

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、把url里的127.0.0.1改成你电脑局域网内的ip

类似这样的效果

manager-api:
  url: http://192.168.1.25: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 - Server is running at 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/

接下来，你就可以开始编译esp32固件了。

6. 版本升级操作

如果后期想升级版本，先备份你的模型密钥。

进入xiaozhi-server目录

5.1、执行以下命令

docker-compose down
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

5.2、删掉docker-compose_all.yaml文件

5.3、重新按1.1开始部署

方式二：本地源码运行全模块

1.安装MySQL数据库

如果本机已经安装了MySQL，可以直接在数据库中创建名为xiaozhi_esp32_server的数据库。

CREATE DATABASE xiaozhi_esp32_server CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

如果还没有MySQL，你可以通过docker安装mysql

docker run --name xiaozhi-esp32-server-db -e MYSQL_ROOT_PASSWORD=123456 -p 3306:3306 -e MYSQL_DATABASE=xiaozhi_esp32_server -e MYSQL_INITDB_ARGS="--character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci" -d mysql:latest

2.安装redis

如果还没有Redis，你可以通过docker安装redis

docker run --name xiaozhi-esp32-server-redis -d -p 6379:6379 redis

3.运行manager-api程序

3.1 安装JDK21，设置JDK环境变量

3.2 安装Maven，设置Maven环境变量

3.3 使用Vscode编程工具，安装好Java环境相关插件

3.4 使用Vscode编程工具加载manager-api模块

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

spring:
  datasource:
    username: root
    password: 123456

在src/main/resources/application-dev.yml中配置Redis连接信息

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

3.5 运行主程序

本项目为SpringBoot项目，启动方式为：打开Application.java运行Main方法启动

路径地址：
src/main/java/xiaozhi/AdminApplication.java

当你看到输出日志时，说明你的manager-api启动成功了。

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

4.运行manager-web程序

4.1 安装nodejs

4.2 使用Vscode编程工具加载manager-web模块

终端命令进入manager-web目录下

npm install

然后启动

npm run serve

请注意，如果你的manager-api的接口不在http://localhost:8002，请在开发时，修改 main/manager-web/.env.development中的路径

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

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

5.安装Python环境

本项目使用conda管理依赖环境。如果不方便安装conda，需要根据实际的操作系统安装好libopus和ffmpeg。如果确定使用conda，则安装好后，开始执行以下命令。

重要提示！windows 用户，可以通过安装Anaconda来管理环境。安装好Anaconda后，在开始那里搜索anaconda相关的关键词，找到Anaconda Prpmpt，使用管理员身份运行它。如下图。

运行之后，如果你能看到命令行窗口前面有一个(base)字样，说明你成功进入了conda环境。那么你就可以执行以下命令了。

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 libopus -y
conda install ffmpeg -y

请注意，以上命令，不是一股脑执行就成功的，你需要一步步执行，每一步执行完后，都检查一下输出的日志，查看是否成功。

6.安装本项目依赖

你先要下载本项目源码，源码可以通过git clone命令下载，如果你不熟悉git clone命令。

你可以用浏览器打开这个地址https://github.com/xinnan-tech/xiaozhi-esp32-server.git

打开完，找到页面中一个绿色的按钮，写着Code的按钮，点开它，然后你就看到Download ZIP的按钮。

点击它，下载本项目源码压缩包。下载到你电脑后，解压它，此时它的名字可能叫xiaozhi-esp32-server-main 你需要把它重命名成xiaozhi-esp32-server，在这个文件里，进入到main文件夹，再进入到xiaozhi-server，好了请记住这个目录xiaozhi-server。

# 继续使用conda环境
conda activate xiaozhi-esp32-server
# 进入到你的项目根目录，再进入main/xiaozhi-server
cd main/xiaozhi-server
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip install -r requirements.txt

7.下载语音识别模型文件

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

8.配置项目文件

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