CyberMind-FR
ccfb58124c
Add complete French (fr) and Chinese (zh) translations for all documentation: - Root files: README, CHANGELOG, SECURITY, BETA-RELEASE - docs/: All 16 core documentation files - DOCS/: All 19 deep-dive documents including embedded/ and archive/ - package/secubox/: All 123+ package READMEs - Misc: secubox-tools/, scripts/, EXAMPLES/, config-backups/, streamlit-apps/ Total: 346 translation files created Each file includes language switcher links for easy navigation between English, French, and Chinese versions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
131 lines
4.5 KiB
Markdown
131 lines
4.5 KiB
Markdown
# OpenWrt ARM64 上的 Docker Zigbee2MQTT
|
||
|
||
> **Languages:** [English](../../DOCS/embedded/zigbee2mqtt-docker.md) | [Francais](../../DOCS-fr/embedded/zigbee2mqtt-docker.md) | 中文
|
||
|
||
**版本：** 1.0.0
|
||
**最后更新：** 2025-12-28
|
||
**状态：** 活跃
|
||
|
||
本指南说明如何在 OpenWrt ARM64 目标上部署 SecuBox Zigbee2MQTT "应用"（基于 Docker）。它使用 `secubox-app-zigbee2mqtt` 软件包（安装程序、CLI、procd 服务）以及 LuCI 前端（`luci-app-zigbee2mqtt`）。
|
||
|
||
---
|
||
|
||
## 前提条件
|
||
|
||
1. **OpenWrt 24.10.x ARM64**（ESPRESSObin、MOCHAbin、RPi4 等），具有 >= 256 MB 可用存储空间（Docker 镜像 + 数据目录）。
|
||
2. **内核功能**：cgroups（`/sys/fs/cgroup`）、USB CDC ACM（`kmod-usb-acm`）。
|
||
3. **硬件**：Zigbee 协调器呈现为 `/dev/ttyACM0`（例如 SONOFF ZBDongle-E/MG21）。
|
||
4. **网络**：可访问的 MQTT 代理（本地 Mosquitto 或远程 `mqtt://host:1883`）。
|
||
5. **软件包源**：`docker`、`dockerd`、`containerd` 可用（`opkg update`）。
|
||
|
||
---
|
||
|
||
## 安装步骤
|
||
|
||
```sh
|
||
opkg update
|
||
opkg install secubox-app-zigbee2mqtt luci-app-zigbee2mqtt
|
||
```
|
||
|
||
1. **运行前提条件安装程序**（检查存储、cgroups、USB，安装 Docker，拉取镜像，启用服务）：
|
||
```sh
|
||
zigbee2mqttctl install
|
||
```
|
||
2. **启动服务**：
|
||
```sh
|
||
/etc/init.d/zigbee2mqtt start # 通过安装程序自动启用
|
||
```
|
||
3. **LuCI 配置**（可选的界面流程）：服务 -> SecuBox -> Zigbee2MQTT。调整串口、MQTT 主机/凭据、基础主题等，然后点击"应用"。
|
||
|
||
安装程序将持久化数据写入 `/srv/zigbee2mqtt/data`（配置 + 数据库），并默认在端口 `8080` 上暴露 Zigbee2MQTT Web 界面。
|
||
|
||
---
|
||
|
||
## 命令行参考（`/usr/sbin/zigbee2mqttctl`）
|
||
|
||
| 命令 | 描述 |
|
||
|------|------|
|
||
| `install` | 完整的前提条件设置（Docker 软件包、数据目录、镜像拉取、启用服务）。 |
|
||
| `check` | 重新运行前提条件检查（存储、cgroups、USB 模块、串口设备）。 |
|
||
| `update` | 拉取最新的 Zigbee2MQTT 镜像并重启已启用的服务。 |
|
||
| `status` | 显示 Docker 容器状态（`docker ps` 过滤）。 |
|
||
| `logs [-f]` | 流式输出容器的 Docker 日志。 |
|
||
| `service-run` / `service-stop` | procd init 脚本使用的内部命令；不用于手动调用。 |
|
||
|
||
所有命令必须以 root 身份运行。
|
||
|
||
---
|
||
|
||
## UCI 配置（`/etc/config/zigbee2mqtt`）
|
||
|
||
```uci
|
||
config zigbee2mqtt 'main'
|
||
option enabled '1'
|
||
option serial_port '/dev/ttyACM0'
|
||
option mqtt_host 'mqtt://127.0.0.1:1883'
|
||
option mqtt_username ''
|
||
option mqtt_password ''
|
||
option base_topic 'zigbee2mqtt'
|
||
option frontend_port '8080'
|
||
option channel '11'
|
||
option image 'ghcr.io/koenkk/zigbee2mqtt:latest'
|
||
option data_path '/srv/zigbee2mqtt'
|
||
option timezone 'UTC'
|
||
```
|
||
|
||
通过 `uci` 或 LuCI 表单编辑；提交更改后自动重启：
|
||
```sh
|
||
uci set zigbee2mqtt.main.mqtt_host='mqtt://192.168.1.10:1883'
|
||
uci commit zigbee2mqtt
|
||
/etc/init.d/zigbee2mqtt restart
|
||
```
|
||
|
||
---
|
||
|
||
## 验证和冒烟测试
|
||
|
||
- 快速前提条件检查：
|
||
```sh
|
||
zigbee2mqttctl check
|
||
```
|
||
- 仓库冒烟测试（运行服务启动/停止 + 可选的 MQTT 发布/订阅）：
|
||
```sh
|
||
./scripts/smoke_test.sh
|
||
```
|
||
- 诊断包（通用 SecuBox）：
|
||
```sh
|
||
./scripts/diagnose.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 故障排除
|
||
|
||
| 症状 | 解决方案 |
|
||
|------|----------|
|
||
| `zigbee2mqttctl install` 报告 "/sys/fs/cgroup missing" | 在内核配置中启用 cgroups 或升级到支持 cgroup 的构建版本。 |
|
||
| USB 协调器未检测到 | 确保已安装 `kmod-usb-acm`，`cdc_acm` 模块已加载（`lsmod | grep cdc_acm`），设备出现在 `/dev/ttyACM*` 下。重新插入 dongle。 |
|
||
| Docker 无法启动 | 检查 `/etc/init.d/dockerd status`。如果 `docker info` 失败，检查 `/var/log/messages` 中的存储驱动错误。 |
|
||
| MQTT 认证失败 | 通过 UCI 或 LuCI 设置 `mqtt_username`/`mqtt_password` 并重启服务。 |
|
||
| 端口 8080 已被使用 | 在 UCI 中更改 `frontend_port`，提交，重启服务。相应更新 vhost 映射。 |
|
||
|
||
---
|
||
|
||
## 卸载/清理
|
||
|
||
```sh
|
||
/etc/init.d/zigbee2mqtt stop
|
||
/etc/init.d/zigbee2mqtt disable
|
||
docker rm -f secbx-zigbee2mqtt 2>/dev/null
|
||
opkg remove luci-app-zigbee2mqtt secubox-app-zigbee2mqtt
|
||
rm -rf /srv/zigbee2mqtt
|
||
```
|
||
|
||
---
|
||
|
||
## 后续步骤
|
||
|
||
- 使用 `luci-app-vhost-manager` 在 HTTPS 下发布 Zigbee2MQTT 界面（参见 `luci-app-vhost-manager/README.md`）。
|
||
- 通过添加引用此安装程序的清单条目与即将推出的 SecuBox App Store 集成。
|
||
- 根据项目路线图，在引入这些组件后与配置文件/向导结合使用。
|