本项目为开源智能硬件项目 xiaozhi-esp32 提供后端服务。根据 小智通信协议 使用 Python 实现。该项目是开发AI语音助手、AI陪伴、AI玩具的高效捷径！

后端部署

新建和激活一个虚拟环境

conda create -n xiaozhi-esp32-server python=3.10 -y && conda activate xiaozhi-esp32-server

为虚拟环境添加conda国内清华源通道

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

克隆项目GitHub库和安装项目

克隆库文件到服务器

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

安装项目

进入到项目根目录

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

设置pip的国内源

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

安装依赖

pip install -r requirements.txt

下载模型和配置参数

下载语音识别模型

切换到模型目录

cd /home/caovan/xiaozhi-esp32-server/main/xiaozhi-server/models/SenseVoiceSmall

下载模型

wget https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt

修改配置文件

切换到配置文件所在目录

cd /home/caovan/xiaozhi-esp32-server/main/xiaozhi-server

新建一个文件夹data

mkdir data

将config.yaml文件复制到新文件data中，并且更名为“.config.yaml”

cp config.yaml data/.config.yaml

修改配置文件参数

vim data/.config.yaml

主要是设置各种模型的URL和api_key以及模型名称那些，如果要对服务器的IP做域名解析，这里还可以设置一下server的端口，ip一定要是“0.0.0.0”，设置好之后保存退出编辑；

启动后端服务

切换到后端app.py文件所在目录

cd /home/caovan/xiaozhi-esp32-server/main/xiaozhi-server

如果此时不在虚拟环境的激活状态，记得要先激活虚拟环境

conda activate xiaozhi-esp32-server

运行后端文件

python app.py

这里也可以写一个sh脚本，将后端服务在后台运行，避免关掉终端后服务停止。

管理后台前端服务

修改配置文件

进入到前端目录

cd /home/caovan/xiaozhi-esp32-server/main/manager-web

编辑配置文件

vim vue.config.js

下面是我的文件修改之后的内容，供参考：

const {defineConfig} = require('@vue/cli-service');
const dotenv = require('dotenv');

// 确保加载 .env 文件
dotenv.config();

module.exports = defineConfig({
    devServer: {
        host: '0.0.0.0',
        port: 10003,
        allowedHosts: 'all',
        // Bug 修复：将代理配置为环境变量中定义的 API 基础 URL
        proxy: {
            '/xiaozhi-esp32-api': {
                target: process.env.VUE_APP_API_BASE_URL || 'http://localhost:8002', // 后端 API 的基础 URL
                changeOrigin: true, // 允许跨域
                // pathRewrite: {
                //   '^/api': '', // 路径重写
                // },
            },
            '/ws': {
                target: 'ws://127.0.0.1:10002',  // 后端 WebSocket 地址
                ws: true,  // 启用 WebSocket 代理
                changeOrigin: true,
            },
        },
        client: {
            overlay: false,
            webSocketURL: 'wss://xiaozhi.caovan.cn/ws',
        },
    },
});

修改完成之后保存退出编辑！

安装前端依赖与运行前端

运行下面的命令安装前端依赖

npm install

运行前端

npm run serve

运行成功后会显示如下的内容：

DONE Compiled successfully in 5387ms 23:23:55


App running at:
- Local: http://localhost:10003/ 
- Network: http://192.168.1.2:10003/

Note that the development build is not optimized.
To create a production build, run npm run build.

服务器环境配置

修改nginx配置

运行下面的命令编辑NGINX的配置文件

sudo vim /etc/nginx/sites-available/default

添加如下的内容

# 小智AI配置文件
server {
server_name xiaozhi.caovan.cn;

# 代理所有前端请求到开发服务器
location /xiaozhi/v1/ {
proxy_pass http://192.168.1.2:10002;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

# WebSocket 支持
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# 调整超时时间（可选）
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}

# SSL配置（保持不变）
listen 443 ssl;
ssl_certificate /etc/letsencrypt/live/xiaozhi.caovan.cn/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/xiaozhi.caovan.cn/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}

为域名添加SSL证书

在这一步之前，你首先要将域名解析到服务器的IP地址，关于解析域名的方法，这里就不多做介绍，因为我相信看这篇文章看到这里的人应该对解析域名这种事已经了如指掌了！

安装 Certbot 工具

安装 Certbot 和 Nginx 插件

sudo apt update
sudo apt install certbot python3-certbot-nginx -y

验证 Certbot 是否安装成功

certbot --version
# 应输出类似：certbot 2.6.0

获取 SSL 证书

通过 Certbot 自动申请证书
执行以下命令，按提示操作（需输入邮箱并同意协议）：

sudo certbot --nginx -d xiaozhi.caovan.cn

Certbot 会自动检测 Nginx 配置中的 server_name 并完成域名验证。

成功后会提示是否将 HTTP 流量重定向到 HTTPS，建议选择 2（强制重定向）。

验证证书生成
证书文件会保存在以下路径：

/etc/letsencrypt/live/xiaozhi.caovan.cn/fullchain.pem
/etc/letsencrypt/live/xiaozhi.caovan.cn/privkey.pem

检查证书是否生效：

sudo certbot certificates

# 应看到域名 xiaozhi.caovan.cn 的证书信息

Certbot 会自动修改 Nginx 配置文件生成上面你看到的“listen 443 ssl;”以及后面的内容

重启 Nginx 服务

sudo nginx -t # 检查配置语法
sudo systemctl reload nginx

设置证书自动续订

Let’s Encrypt 证书有效期为 90 天，需配置自动续订：

手动测试续订

sudo certbot renew --dry-run
# 若输出 "Congratulations, all renewals succeeded" 表示正常

添加定时任务
Certbot 默认已配置自动续订，可通过以下命令查看：

systemctl list-timers | grep certbot
# 或检查 cron 任务
cat /etc/cron.d/certbot

至此，后端的部署基本上就完成了！我们可以打开网址https://xiaozhi.caovan.cn访问小智的管理后台了！