7.5 KiB
单模块部署固件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/目录下：
cp your_firmware.bin data/bin/设备型号_版本号.bin
例如：
cp xiaozhi_firmware.bin data/bin/esp32s3_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
配置示例：
局域网部署（默认）：
server:
vision_explain: http://192.168.1.100:8003/mcp/vision/explain
公网域名部署：
server:
vision_explain: http://yourdomain.com:8003/mcp/vision/explain
公网IP部署：
server:
vision_explain: http://111.111.111.111:8003/mcp/vision/explain
使用HTTPS（推荐公网部署使用）：
server:
vision_explain: https://yourdomain.com:8003/mcp/vision/explain
注意事项
- 域名或IP必须是设备能够访问的地址
- 如果使用Docker部署，不能使用Docker内部地址（如127.0.0.1或localhost）
- 端口号默认是8003，如果你修改了
server.http_port配置，需要同步修改这里的端口号
第三步 启动或重启服务
源码运行
python app.py
Docker运行
docker restart xiaozhi-esp32-server
验证服务启动
启动后，查看日志输出，应该能看到类似以下内容：
2025-12-18 **** - OTA接口是 http://192.168.1.100:8003/xiaozhi/ota/
2025-12-18 **** - 视觉分析接口是 http://192.168.1.100:8003/mcp/vision/explain
使用浏览器访问OTA接口地址，如果显示以下内容说明服务正常：
OTA接口运行正常，向设备发送的websocket地址是：ws://xxx.xxx.xxx.xxx:8000/xiaozhi/v1/
第四步 设备自动检测升级
升级原理
当设备连接到服务器时（每次开机或定时检查），会自动发送OTA请求。服务器会：
- 读取设备的型号和当前固件版本
- 扫描
data/bin/目录，查找匹配该型号的所有固件文件 - 比较版本号，如果有更高版本，则返回固件下载地址
- 设备收到下载地址后，会自动下载并安装新固件
版本比较规则
系统使用语义化版本比较方式，按数字段从左到右依次比较：
1.6.6<1.6.71.6.9<1.7.02.0.0>1.9.9
查看升级日志
在xiaozhi-server的日志中，你可以看到OTA相关的日志输出：
[ota_handler] - OTA请求设备ID: AA:BB:CC:DD:EE:FF
[ota_handler] - 查找型号 esp32s3 的固件，找到 3 个候选
[ota_handler] - 为设备 AA:BB:CC:DD:EE:FF 下发固件 1.6.6 [如果地址前缀有误，请检查配置文件中的server.vision_explain]-> http://yourdomain.com:8003/xiaozhi/ota/download/esp32s3_1.6.6.bin
或者如果设备已是最新版本：
[ota_handler] - 设备 AA:BB:CC:DD:EE:FF 固件已是最新: 1.6.6
高级配置
固件缓存时间（可选）
系统会缓存data/bin/目录的扫描结果以提高性能。默认缓存时间为30秒。你可以在配置文件中调整：
firmware_cache_ttl: 60 # 单位：秒，设置为60秒缓存时间
多版本固件管理
你可以同时放置多个版本的固件，系统会自动选择最新版本：
data/bin/
├── esp32s3_1.6.5.bin
├── esp32s3_1.6.6.bin
├── esp32s3_1.7.0-beta.bin
└── xiaozhi-v2_2.0.0.bin
系统会为esp32s3型号的设备推送1.7.0-beta版本（最高版本）。
多型号固件管理
不同型号的设备会自动匹配对应型号的固件：
data/bin/
├── esp32s3_1.6.6.bin # 仅供 esp32s3 型号设备使用
├── xiaozhi-v2_2.0.0.bin # 仅供 xiaozhi-v2 型号设备使用
└── default_1.0.0.bin # 供未识别型号的设备使用
常见问题
1. 设备收不到固件更新
可能原因和解决方法：
- 检查固件文件命名是否符合规则：
{型号}_{版本号}.bin - 检查固件文件是否正确放置在
data/bin/目录 - 检查设备型号是否与固件文件名中的型号匹配
- 检查固件版本号是否高于设备当前版本
- 查看服务器日志，确认OTA请求是否正常处理
2. 设备报告下载地址无法访问
可能原因和解决方法：
- 检查
server.vision_explain配置的域名或IP是否正确 - 确认端口号配置正确（默认8003）
- 如果是公网部署，确保设备能够访问该公网地址
- 如果是Docker部署，确保不是使用了内部地址（127.0.0.1）
- 检查防火墙是否开放了对应端口
3. 如何确认设备当前版本
查看OTA请求日志，日志中会显示设备上报的版本号：
[ota_handler] - 设备 AA:BB:CC:DD:EE:FF 固件已是最新: 1.6.6
4. 固件文件放置后没有生效
系统有30秒的缓存时间（默认），可以：
- 等待30秒后再让设备发起OTA请求
- 重启xiaozhi-server服务
- 调整
firmware_cache_ttl配置为更短的时间
5. 如何回滚到旧版本
系统只会推送更高版本的固件。如果需要回滚：
- 删除或重命名
data/bin/目录中高于目标版本的固件文件 - 等待缓存过期或重启服务
- 设备下次检查时会收到目标版本
安全说明
- 系统会验证固件文件路径，防止目录穿越攻击
- 固件下载接口只允许访问
data/bin/目录下的.bin文件 - 建议在生产环境使用HTTPS协议传输固件
相关教程
如需了解更多，请参考以下教程：