Cypress 配置体系深度解析：@packages/config 的配置定义、校验与源码级改写机制
2026/10/11 10:27:17
相关链接：
AI语音智能体开发日记（一）如何为“小智”服务器启用并调试 License 功能-CSDN博客
AI语音智能体开发日记（二）解决 Wi-Fi 配网小程序的兼容性问题-CSDN博客
AI语音智能体开发日记（三）解决小程序配网中的蓝牙命名与MAC地址获取问题-CSDN博客
AI语音智能体开发日记（四）在FreeRTOS中构建线程安全的UART2通信模块-CSDN博客
AI语音智能体开发日记（五）为智能设备注入“灵魂”——详解MCP工具的注册与使用-CSDN博客
AI语音智能体开发日记（六）为智能体注入旋律——七牛云音乐服务的接入与避坑指南-CSDN博客
AI语音智能体开发日记（七）搞定功放控制——详解GX8006平台Mute电平配置-CSDN博客
AI语音智能体开发日记（八）LVGL 8.4.0 移植实战——从零构建嵌入式GUI-CSDN博客
AI语音智能体开发日记（九）LVGL 8.4.0 中文字体配置全攻略-CSDN博客
AI语音智能体开发日记（十）LVGL 图标字体实战——从 FontAwesome 到屏幕显示-CSDN博客
AI语音智能体开发日记（十一）为智能设备“声”临其境——详解音频资源自动化生成流程-CSDN博客
AI语音智能体开发日记（十二）GX8006 固件定制指南——从双唤醒词到 UART 音频传输-CSDN博客
AI语音智能体开发日记（十三）一次由寄存器溢出引发的串口波特率“玄学”问题排查-CSDN博客
推荐链接：
AI语音智能体架构解析（一）系统架构全景图-CSDN博客
AI语音智能体架构解析（二）大模型（AI 的大脑）-CSDN博客
AI语音智能体架构解析（三）智控台（指挥中心）-CSDN博客
AI语音智能体架构解析（四）AI 语音终端（执行器官）-CSDN博客
AI语音智能体架构解析（五）小程序/APP（遥控器）-CSDN博客
推荐链接：
AI 应用 图文 解说 (一) -- 百度智能云 实现 语音 聊天-CSDN博客
AI 应用 图文 解说 (二) -- 百度智能云 ASR LIM TTS 语音AI助手程序 -CSDN博客
xiaozhi-esp32-server全模块源码部署指南
适用系统：Ubuntu 22.04 LTS
硬件建议：4 核 CPU、8G 内存
项目地址：https://github.com/xinnan-tech/xiaozhi-esp32-server
![]()
一、架构概览
xiaozhi-esp32-server 采用三层微服务架构，全模块部署需启动以下服务：
服务 | 技术栈 | 默认端口 | 说明 |
MySQL | MySQL 8.0 | 3306 | 数据库 |
Redis | Redis 7.0 | 6379 | 缓存 |
manager-api | Java 21 + Spring Boot | 8002 | 管理后端 API |
manager-web | Node.js 18 + Vue.js | 8001 | 智控台前端 |
xiaozhi-server | Python 3.10 + FastAPI | 8000 / 8003 | 核心语音服务 |
二、安装基础工具
2.1安装Git
sudo apt update
sudo apt install git -y
2.2安装Docker
sudo apt install docker.io -y
sudo systemctl start docker
sudo systemctl enable docker
验证：
docker --version
2.3安装Docker Compose
sudo apt install docker-compose -y
验证：
docker-compose --version
如果拉取 Docker 镜像很慢，可配置镜像加速器。编辑 /etc/docker/daemon.json：
{
"registry-mirrors": ["https://docker.m.daocloud.io"]
}
然后重启 Docker：sudo systemctl restart docker
三、安装JDK21（manager-api依赖）
sudo apt install openjdk-21-jdk -y
验证：
java --version
确认输出为 openjdk 21。
同时安装 Maven（构建工具）：
sudo apt install maven -y
四、安装Node.js18（manager-web依赖）
curl -fsSL https://deb.nodesource.com/setup_18.x|sudo -E bash -
sudo apt install nodejs -y
验证：
node --version
npm --version
五、安装Miniforge（Python环境管理）
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh
安装过程中一路按回车确认，最后选择 yes 初始化 conda。
重启终端使 conda 生效，验证：
conda --version
六、克隆项目源码
mkdir -p ~/server
cd ~/server
git clone https://github.com/xinnan-tech/xiaozhi-esp32-server.git
七、用Docker启动MySQL和Redis
7.1启动MySQL
docker run -d \
--name xiaozhi-mysql \
-p 3306:3306 \
-e MYSQL_ROOT_PASSWORD=123456 \
-e MYSQL_DATABASE=xiaozhi_esp32_server \
mysql:8.0
7.2启动Redis
docker run -d \
--name xiaozhi-redis \
-p 6379:6379 \
redis:7.0
7.3验证容器状态
docker ps
应能看到 xiaozhi-mysql 和 xiaozhi-redis 两个容器处于运行状态。
八、部署manager-api（管理后端）
8.1进入目录
cd ~/server/xiaozhi-esp32-server/main/manager-api
8.2修改数据库配置
编辑 src/main/resources/application-dev.yml，确认数据库连接信息：
spring:
datasource:
username:root
password:123456
url:jdbc:mysql://127.0.0.1:3306/xiaozhi_esp32_server
redis:
host:127.0.0.1
port:6379
8.3编译并启动
mvn clean package -DskipTests
java -jar target/manager-api.jar
启动成功后，manager-api 默认运行在 8002 端口。
使用vscode打开\xiaozhi-esp32-server\main\manager-api\src\main\java\xiaozhi下的AdminApplication.java文件，右键run java或运行快捷键。
前台打开效果
九、部署manager-web（智控台前端）
9.1进入目录
cd ~/server/xiaozhi-esp32-server/main/manager-web
9.2安装依赖并启动
npm install
npm run serve
启动成功后，智控台默认运行在 http://127.0.0.1:8001。
前台效果
9.3注册超级管理员
用浏览器打开智控台地址，注册第一个用户（即超级管理员）。
十、获取server.secret参数
- 登录智控台（http://127.0.0.1:8001）
- 在顶部菜单找到"参数管理"
- 找到参数编码为 server.secret 的记录
- 复制其参数值（随机生成的密钥，每次重新部署会变化）
- 修改server.websocket
十一、创建Python 3.10虚拟环境
conda create -n xiaozhi-esp32-server python=3.10 -y
conda activate xiaozhi-esp32-server
验证：
python --version
确认输出为 Python 3.10.x。
必须使用 Python 3.10，更高版本会导致 PyTorch 等依赖找不到匹配包。
十二、安装Python依赖和系统工具
12.1安装ffmpeg和libopus
conda install ffmpeg libopus -y
验证：
ffmpeg -version
12.2安装Python依赖
cd ~/server/xiaozhi-esp32-server/main/xiaozhi-server
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip install -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cpu
十三、配置xiaozhi-server
13.1创建data目录并复制配置文件
cd ~/server/xiaozhi-esp32-server/main/xiaozhi-server
mkdir -p data
cp config_from_api.yaml data/.config.yaml
13.2编辑配置文件
nano data/.config.yaml
需要修改的关键项：
- secret：填入第十步中从智控台复制的 server.secret 值
- url：改为 http://127.0.0.1:8002/xiaozhi（指向 manager-api 的地址）
十四、下载语音识别模型
mkdir -p models/SenseVoiceSmall
从项目文档中提供的百度网盘链接下载 SenseVoiceSmall 模型文件（提取码: qvna），将 model.pt 放入 models/SenseVoiceSmall/ 目录下。
十五、启动xiaozhi-server
cd ~/server/xiaozhi-esp32-server/main/xiaozhi-server
conda activate xiaozhi-esp32-server
python app.py
启动成功后，日志会输出：
OTA接口是 http://你的IP:8003/xiaozhi/ota/
Websocket地址是 ws://你的IP:8000/xiaozhi/v1/
十六、配置大模型API Key
- 回到智控台（http://127.0.0.1:8001）
- 进入"模型配置"→"大语言模型"
- 填入你从大模型服务商获取的 API Key（如智谱AI、DeepSeek、通义千问等）
- 保存配置
十七、测试验证
登录智控台管理界面
找到 参数管理
找到参数代码为 server.websocket 的配置项
将其值改为：ws://192.168.3.132:8000/xiaozhi/v1/
进入xiaozhi-esp32-server/test
python -m http.server 8006
用浏览器打开项目 test 目录下的 test_page.html，填入日志中输出的 WebSocket 地址（ws://你的IP:8000/xiaozhi/v1/）进行测试。
十八、各服务端口汇总
服务 | 端口 | 说明 |
MySQL | 3306 | 数据库 |
Redis | 6379 | 缓存 |
manager-api | 8002 | 管理后端 API |
manager-web | 8001 | 智控台前端 |
xiaozhi-server WebSocket | 8000 | 设备通信 |
xiaozhi-server HTTP/OTA | 8003 | OTA 和视觉分析 |
十九、常见问题速查
问题 | 解决方法 |
Docker 镜像拉取慢 | 配置 registry-mirrors 镜像加速器 |
找不到data/.config.yaml | 在 xiaozhi-server 下执行 mkdir -p data && cp config_from_api.yaml data/.config.yaml |
No such file or directory: 'ffmpeg' | 执行 conda install ffmpeg -y |
LLM 的 API key 未设置 | 在智控台的"模型配置"中填入真实 API Key |
No matching distribution found for torch | 确认使用的是 Python 3.10 环境 |
manager-api 连不上数据库 | 检查 application-dev.yml 中的数据库地址和密码是否正确 |
TTS 任务出错 | 确认已通过 conda 安装了 libopus 和 ffmpeg |
语音识别出现乱码 | 确认 models/SenseVoiceSmall/model.pt 模型文件已正确放置 |
二十、注意事项
- 所有安装路径严禁包含中文或空格
- Python 版本必须为 3.10，不可使用更高版本
- 每次重新部署后，server.secret 会重新生成，需重新配置
- 云服务器部署时，安全组需开放 8000-8003 端口
- 设备与服务端需在同一局域网下，或确保网络可达