编辑 | blame | 历史 | 原始文档

单模块部署固件OTA自动升级配置指南

本教程将指导你如何在**单模块部署**场景下配置固件OTA自动升级功能，实现设备固件的自动更新。

如果你已经使用**全模块部署**，请忽略本教程。

功能介绍

在单模块部署中，xiaozhi-server内置了OTA固件管理功能，可以自动检测设备版本并下发升级固件。系统会根据设备型号和当前版本，自动匹配并推送最新的固件版本。

前提条件

你已经成功进行**单模块部署**并运行xiaozhi-server
设备能够正常连接到服务器

第一步准备固件文件

1. 创建固件存放目录

固件文件需要放在data/bin/目录下。如果该目录不存在，请手动创建：

mkdir -p data/bin

2. 固件文件命名规则

固件文件必须遵循以下命名格式：

{设备型号}_{版本号}.bin

命名规则说明：
- 设备型号：设备的型号名称，例如 lichuang-dev、bread-compact-wifi 等
- 版本号：固件版本号，必须以数字开头，支持数字、字母、点号、下划线和短横线，例如 1.6.6、2.0.0 等
- 文件扩展名必须是 .bin

命名示例：
bread-compact-wifi_1.6.6.bin lichuang-dev_2.0.0.bin

3. 放置固件文件

将准备好的固件文件（.bin文件）复制到data/bin/目录下：

重要的事情说三遍：升级的bin文件是xiaozhi.bin，不是全量固件文件merged-binary.bin!

cp xiaozhi.bin data/bin/设备型号_版本号.bin

例如：
bash cp xiaozhi.bin data/bin/bread-compact-wifi_1.6.6.bin

第二步配置公网访问地址（仅公网部署需要）

注意：此步骤仅适用于单模块公网部署的场景。

如果你的xiaozhi-server是公网部署（使用公网IP或域名），**必须**配置server.vision_explain参数，因为OTA固件下载地址会使用该配置的域名和端口。

如果你是局域网部署，可以跳过此步骤。

为什么要配置这个参数？

在单模块部署中，系统生成固件下载地址时，会使用vision_explain配置的域名和端口作为基础地址。如果不配置或配置错误，设备将无法访问固件下载地址。

配置方法

打开data/.config.yaml文件，找到server配置段，设置vision_explain参数：

server:
  vision_explain: http://你的域名或IP:端口号/mcp/vision/explain

配置示例：

局域网部署（默认）：
yaml server: vision_explain: http://192.168.1.100:8003/mcp/vision/explain

公网域名部署：
yaml server: vision_explain: http://yourdomain.com:8003/mcp/vision/explain

注意事项

域名或IP必须是设备能够访问的地址
如果使用Docker部署，不能使用Docker内部地址（如127.0.0.1或localhost）
如果你使用了nginx反向代理，请填写对外的地址和端口号，不是本项目运行的端口号

常见问题

1. 设备收不到固件更新

可能原因和解决方法：

检查固件文件命名是否符合规则：{型号}_{版本号}.bin
检查固件文件是否正确放置在data/bin/目录
检查设备型号是否与固件文件名中的型号匹配
检查固件版本号是否高于设备当前版本
查看服务器日志，确认OTA请求是否正常处理

2. 设备报告下载地址无法访问