143 lines
4.4 KiB
Markdown
143 lines
4.4 KiB
Markdown
# 单模块部署固件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/`目录下：
|
||
|
||
重要的事情说三遍：升级的bin文件是`xiaozhi.bin`，不是全量固件文件`merged-binary.bin`!
|
||
|
||
重要的事情说三遍：升级的bin文件是`xiaozhi.bin`，不是全量固件文件`merged-binary.bin`!
|
||
|
||
重要的事情说三遍：升级的bin文件是`xiaozhi.bin`，不是全量固件文件`merged-binary.bin`!
|
||
|
||
```bash
|
||
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`参数：
|
||
|
||
```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必须是设备能够访问的地址
|
||
- 如果使用Docker部署，不能使用Docker内部地址（如127.0.0.1或localhost）
|
||
- 如果你使用了nginx反向代理，请填写对外的地址和端口号，不是本项目运行的端口号
|
||
|
||
|
||
## 常见问题
|
||
|
||
### 1. 设备收不到固件更新
|
||
|
||
**可能原因和解决方法：**
|
||
|
||
- 检查固件文件命名是否符合规则：`{型号}_{版本号}.bin`
|
||
- 检查固件文件是否正确放置在`data/bin/`目录
|
||
- 检查设备型号是否与固件文件名中的型号匹配
|
||
- 检查固件版本号是否高于设备当前版本
|
||
- 查看服务器日志，确认OTA请求是否正常处理
|
||
|
||
### 2. 设备报告下载地址无法访问
|
||
|
||
**可能原因和解决方法：**
|
||
|
||
- 检查`server.vision_explain`配置的域名或IP是否正确
|
||
- 确认端口号配置正确（默认8003）
|
||
- 如果是公网部署，确保设备能够访问该公网地址
|
||
- 如果是Docker部署，确保不是使用了内部地址（127.0.0.1）
|
||
- 检查防火墙是否开放了对应端口
|
||
- 如果你使用了nginx反向代理，请填写对外的地址和端口号，不是本项目运行的端口号
|
||
|
||
### 3. 如何确认设备当前版本
|
||
|
||
查看OTA请求日志，日志中会显示设备上报的版本号：
|
||
|
||
```
|
||
[ota_handler] - 设备 AA:BB:CC:DD:EE:FF 固件已是最新: 1.6.6
|
||
```
|
||
|
||
### 4. 固件文件放置后没有生效
|
||
|
||
系统有30秒的缓存时间（默认），可以：
|
||
- 等待30秒后再让设备发起OTA请求
|
||
- 重启xiaozhi-server服务
|
||
- 调整`firmware_cache_ttl`配置为更短的时间
|