mirror of
https://github.com/xinnan-tech/xiaozhi-esp32-server.git
synced 2026-07-22 23:23:55 +08:00
218 lines
4.9 KiB
Markdown
218 lines
4.9 KiB
Markdown
# 部署指南
|
|
|
|
本项目支持 **x86** 和 **arm64** 架构，可运行于国产操作系统。
|
|
|
|
## 方式一：快速部署（推荐）
|
|
|
|
### 1. 安装 Docker
|
|
|
|
如果未安装 Docker，可参考 [Docker 安装教程](https://www.runoob.com/docker/ubuntu-docker-install.html)。
|
|
|
|
### 2. 创建项目目录
|
|
|
|
选择一个空目录作为 **项目目录**。
|
|
|
|
### 3. 下载配置文件
|
|
|
|
访问 [config.yaml](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/config.yaml)，点击 `RAW` 旁的下载按钮，保存到 **项目目录**。
|
|
|
|
### 4. 运行 Docker
|
|
|
|
打开终端，`cd` 进入 **项目目录**，执行：
|
|
|
|
```sh
|
|
docker run -d --name xiaozhi-esp32-server --restart always --security-opt seccomp:unconfined \
|
|
-p 8000:8000 \
|
|
-v $(pwd)/config.yaml:/opt/xiaozhi-esp32-server/config.yaml \
|
|
ccr.ccs.tencentyun.com/xinnan/xiaozhi-esp32-server:latest
|
|
```
|
|
|
|
### 5. 确认运行状态
|
|
|
|
```sh
|
|
docker ps # 查看容器状态
|
|
docker logs -f xiaozhi-esp32-server # 查看日志
|
|
```
|
|
|
|
## 方式二：使用 Docker Compose 部署
|
|
|
|
### 1. 创建 `docker-compose.yml`
|
|
在 `项目目录` 下创建 `docker-compose.yml` 文件，内容如下：
|
|
|
|
```yaml
|
|
version: '3'
|
|
services:
|
|
xiaozhi-esp32-server:
|
|
image: ccr.ccs.tencentyun.com/xinnan/xiaozhi-esp32-server:latest
|
|
container_name: xiaozhi-esp32-server
|
|
restart: always
|
|
security_opt:
|
|
- seccomp:unconfined
|
|
ports:
|
|
- "8000:8000"
|
|
volumes:
|
|
- ./config.yaml:/opt/xiaozhi-esp32-server/config.yaml
|
|
```
|
|
|
|
### 2. 启动服务
|
|
```sh
|
|
docker-compose up -d
|
|
```
|
|
|
|
### 3. 确认运行状态
|
|
```sh
|
|
docker-compose ps
|
|
docker-compose logs -f
|
|
```
|
|
|
|
### 4. 停止和删除容器
|
|
```sh
|
|
docker-compose down
|
|
```
|
|
|
|
### 5. 版本升级
|
|
|
|
#### 备份配置文件
|
|
```sh
|
|
cp config.yaml config_backup.yaml
|
|
```
|
|
|
|
#### 更新 Docker 镜像
|
|
```sh
|
|
docker-compose pull
|
|
docker-compose down
|
|
docker-compose up -d
|
|
```
|
|
|
|
|
|
## 方式三：源码部署（免环境部署/可修改代码）
|
|
|
|
### 1. 下载源码
|
|
|
|
```sh
|
|
git clone https://github.com/xinnan-tech/xiaozhi-esp32-server.git
|
|
cd xiaozhi-esp32-server
|
|
```
|
|
|
|
或手动下载 [ZIP 包](https://github.com/xinnan-tech/xiaozhi-esp32-server/archive/refs/heads/main.zip)，解压后重命名为 `xiaozhi-esp32-server`。
|
|
|
|
## 2.运行docker
|
|
|
|
修改完配置后，打开命令行工具，`cd`进入到你的项目目录下，执行以下命令
|
|
|
|
```sh
|
|
docker run -it --name xiaozhi-env --restart always --security-opt seccomp:unconfined \
|
|
-p 8000:8000 \
|
|
-p 8002:8002 \
|
|
-v ./:/app \
|
|
ccr.ccs.tencentyun.com/kalicyh/poetry:v3.10_latest
|
|
```
|
|
|
|
然后就和正常开发一样了
|
|
|
|
## 3.安装依赖
|
|
|
|
在刚刚的打开的终端运行
|
|
|
|
```sh
|
|
poetry install --no-root
|
|
```
|
|
|
|
```sh
|
|
apt-get update
|
|
apt-get install -y --no-install-recommends libopus0 ffmpeg
|
|
```
|
|
|
|
速度慢可以尝试使用清华镜像
|
|
|
|
```sh
|
|
echo "deb https://mirrors.tuna.tsinghua.edu.cn/debian/ bookworm main contrib non-free non-free-firmware" > /etc/apt/sources.list
|
|
echo "deb https://mirrors.tuna.tsinghua.edu.cn/debian/ bookworm-updates main contrib non-free non-free-firmware" >> /etc/apt/sources.list
|
|
echo "deb https://mirrors.tuna.tsinghua.edu.cn/debian/ bookworm-backports main contrib non-free non-free-firmware" >> /etc/apt/sources.list
|
|
echo "deb https://mirrors.tuna.tsinghua.edu.cn/debian-security bookworm-security main contrib non-free non-free-firmware" >> /etc/apt/sources.list
|
|
apt-get update
|
|
apt-get install -y --no-install-recommends libopus0 ffmpeg
|
|
```
|
|
|
|
## 4.运行项目
|
|
|
|
```sh
|
|
poetry run python app.py
|
|
```
|
|
|
|
## 方式三：本地运行（适用于开发）
|
|
|
|
### 1. 安装环境
|
|
|
|
```sh
|
|
conda create -n xiaozhi-esp32-server python=3.10 -y
|
|
conda activate xiaozhi-esp32-server
|
|
```
|
|
|
|
#### Mac/Windows:
|
|
|
|
```sh
|
|
conda install conda-forge::libopus conda-forge::ffmpeg
|
|
```
|
|
|
|
#### Ubuntu:
|
|
|
|
```sh
|
|
apt-get install libopus0 ffmpeg
|
|
```
|
|
|
|
### 2. 下载源码 & 安装依赖
|
|
|
|
```sh
|
|
git clone https://github.com/xinnan-tech/xiaozhi-esp32-server.git
|
|
cd xiaozhi-esp32-server
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 3. 运行项目
|
|
|
|
```sh
|
|
python app.py
|
|
```
|
|
|
|
## 版本升级
|
|
|
|
```sh
|
|
docker stop xiaozhi-esp32-server
|
|
docker rm xiaozhi-esp32-server
|
|
docker rmi ccr.ccs.tencentyun.com/xinnan/xiaozhi-esp32-server:latest
|
|
```
|
|
|
|
然后重新按照 **方式一** 或 **方式二** 运行 Docker。
|
|
|
|
## 重要配置
|
|
|
|
修改 `config.yaml` 以适配不同 LLM 和 TTS 组件。
|
|
|
|
示例：
|
|
|
|
```yaml
|
|
selected_module:
|
|
ASR: FunASR
|
|
VAD: SileroVAD
|
|
LLM: ChatGLMLLM
|
|
TTS: EdgeTTS
|
|
```
|
|
|
|
如需使用 `Dify` 或 `DeepSeekLLM`，修改 `LLM` 部分并填写密钥。
|
|
|
|
## 模型文件下载
|
|
|
|
语音转文字默认使用 `SenseVoiceSmall`，需下载 `model.pt` 并存放至 `model/SenseVoiceSmall` 目录。
|
|
|
|
- [阿里魔塔下载](https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt)
|
|
- [百度网盘下载](https://pan.baidu.com/share/init?surl=QlgM58FHhYv1tFnUT_A8Sg&pwd=qvna) 提取码：`qvna`
|
|
|
|
---
|
|
|
|
如遇问题，可参考 `docker logs -f xiaozhi-esp32-server` 进行排查。
|
|
|
|
**至此，部署完成！** 🚀
|
|
|
|
|