add:添加单模块部署时，使用ota接口自动升级固件的教程

2026-07-21 10:55:38 +00:00 · 2025-12-18 17:38:58 +08:00
parent 6e7c86e159
commit f3f0d62f12
2 changed files with 265 additions and 0 deletions
@@ -69,6 +69,7 @@ VAD:
 ### 9、编译固件相关教程
 1、[如何自己编译小智固件](./firmware-build.md)<br/>
 2、[如何基于虾哥编译好的固件修改OTA地址](./firmware-setting.md)<br/>
+3、[单模块部署如何配置固件OTA自动升级](./ota-upgrade-guide.md)<br/>

 ### 10、拓展相关教程
 1、[如何开启手机号码注册智控台](./ali-sms-integration.md)<br/>
@@ -0,0 +1,264 @@
+# 单模块部署固件OTA自动升级配置指南
+
+本教程将指导你如何在**单模块部署**场景下配置固件OTA自动升级功能，实现设备固件的自动更新。
+
+## 功能介绍
+
+在单模块部署中，xiaozhi-server内置了OTA固件管理功能，可以自动检测设备版本并下发升级固件。系统会根据设备型号和当前版本，自动匹配并推送最新的固件版本。
+
+## 前提条件
+
+- 你已经成功进行**单模块部署**并运行xiaozhi-server
+- 设备能够正常连接到服务器
+
+## 第一步 准备固件文件
+
+### 1. 创建固件存放目录
+
+固件文件需要放在`data/bin/`目录下。如果该目录不存在，请手动创建：
+
+```bash
+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/`目录下：
+
+```bash
+cp your_firmware.bin data/bin/设备型号_版本号.bin
+```
+
+例如：
+```bash
+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`参数：
+
+```yaml
+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部署：
+```yaml
+server:
+  vision_explain: http://111.111.111.111:8003/mcp/vision/explain
+```
+
+使用HTTPS（推荐公网部署使用）：
+```yaml
+server:
+  vision_explain: https://yourdomain.com:8003/mcp/vision/explain
+```
+
+### 注意事项
+
+- 域名或IP必须是设备能够访问的地址
+- 如果使用Docker部署，不能使用Docker内部地址（如127.0.0.1或localhost）
+- 端口号默认是8003，如果你修改了`server.http_port`配置，需要同步修改这里的端口号
+
+## 第三步 启动或重启服务
+
+### 源码运行
+
+```bash
+python app.py
+```
+
+### Docker运行
+
+```bash
+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请求。服务器会：
+
+1. 读取设备的型号和当前固件版本
+2. 扫描`data/bin/`目录，查找匹配该型号的所有固件文件
+3. 比较版本号，如果有更高版本，则返回固件下载地址
+4. 设备收到下载地址后，会自动下载并安装新固件
+
+### 版本比较规则
+
+系统使用语义化版本比较方式，按数字段从左到右依次比较：
+
+- `1.6.6` < `1.6.7`
+- `1.6.9` < `1.7.0`
+- `2.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秒。你可以在配置文件中调整：
+
+```yaml
+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. 如何回滚到旧版本
+
+系统只会推送更高版本的固件。如果需要回滚：
+1. 删除或重命名`data/bin/`目录中高于目标版本的固件文件
+2. 等待缓存过期或重启服务
+3. 设备下次检查时会收到目标版本
+
+## 安全说明
+
+- 系统会验证固件文件路径，防止目录穿越攻击
+- 固件下载接口只允许访问`data/bin/`目录下的`.bin`文件
+- 建议在生产环境使用HTTPS协议传输固件
+
+## 相关教程
+
+如需了解更多，请参考以下教程：
+
+1. [如何自己编译小智固件](./firmware-build.md)
+2. [如何基于虾哥编译好的固件修改OTA地址](./firmware-setting.md)
+3. [如何进行全模块部署](./Deployment_all.md)