huanghai
/
QingLong
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'main'
${ noResults }
QingLong/XiaoZhi/xiaozhi-esp32-server/docs/Deployment_all.md

16 KiB
Raw Permalink Blame History Escape

This file contains ambiguous Unicode characters!

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 目录下。下面两个下载路线任选一个。

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中。

或者直接执行 wget https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/docker-compose_all.yml 下载。

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

1.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、注意，把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 - 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固件了。

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

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密钥中。然后点击保存。

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

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

5.安装Python环境

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

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

conda_prompt

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

conda_env

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模型，进行语音转文字。因为模型较大，需要独立下载，下载后把model.pt 文件放在models/SenseVoiceSmall 目录下。下面两个下载路线任选一个。

8.配置项目文件

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

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

如果你的xiaozhi-server目录没有data，你需要创建data目录。 如果你的data下面没有.config.yaml文件，你可以把xiaozhi-server目录下的config_from_api.yaml文件复制到data，并重命名为.config.yaml

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

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

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

类似这样的效果

manager-api:
  url: http://127.0.0.1:8002/xiaozhi
  secret: 12345678-xxxx-xxxx-xxxx-123456789000

5.运行项目

# 确保在xiaozhi-server目录下执行
conda activate xiaozhi-esp32-server
python app.py

如果你能看到，类似以下日志,则是本项目服务启动成功的标志。

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固件了。

常见问题

以下是一些常见问题，供参考：

1、为什么我说的话，小智识别出来很多韩文、日文、英文

2、为什么会出现“TTS 任务出错 文件不存在”？

3、TTS 经常失败，经常超时

4、使用Wifi能连接自建服务器，但是4G模式却接不上

5、如何提高小智对话响应速度？

6、我说话很慢，停顿时小智老是抢话

7、我想通过小智控制电灯、空调、远程开关机等操作