Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Docker

在 Linux 系统上使用 Docker 安装 CUBE OS 的指南。

在 Linux 主机上将 CUBE OS 作为 Docker 容器安装。此方法非常适合家用服务器、NAS 设备以及一直开机的 Linux 机器。

Docker 部署支持 仅限 Linux.

如果你没有 Linux 主机，请使用 树莓派 或 虚拟机.

1. 准备工作

1

检查主机架构

CUBE Docker 支持以下 Linux 架构：

  • amd64 (x86_64）— PC、服务器、群晖 NAS 及类似设备

  • arm64 (aarch64）— 树莓派 4/5、Orange Pi 和其他 ARM 主机

2

检查 Linux 内核版本

内核 4.15 或更高版本。

uname -r

某些 NAS 设备出厂时使用较旧的内核，例如 4.4.x。这些主机与 CUBE Docker 不兼容。在这种情况下，请改为在 Linux 虚拟机中运行 CUBE OS。

3

安装 Docker Engine

在继续之前，请先在主机上安装 Docker Engine。

请使用 官方 Docker 安装指南.

4

检查所需端口

确保端口 80 和 1883 在主机上未被占用。

sudo lsof -i :80
sudo lsof -i :1883

  • 80 — CUBE OS Web 界面

  • 1883 — MQTT 代理

如果其他服务正在使用这些端口，请先停止它。

5

如有需要，准备一个 Zigbee 适配器

如果你计划添加 Zigbee 设备，请将兼容的 Zigbee 适配器连接到主机。

已测试的 Zigbee 适配器包括：

SONOFF ZBDongle-MAX SONOFF ZBDongle-PMG24 SONOFF ZBDongle-LMG21 SONOFF ZBDongle-E SONOFF ZBDongle-P 列出的其他项 由开发者 @darkxst 提供

有关 Zigbee 配置和兼容性的更多信息，请参阅此 指南.

有关 Zigbee 支持的更多信息，请参阅 本指南.

2. 拉取镜像

1

下载最新镜像

docker pull ghcr.io/ewelinkcube/cube-os:latest

你可以将 latest 替换为某个特定版本标签，例如 2.10.3。可用版本列在 GitHub Releases.

3. 启动 CUBE OS

1

创建数据目录

mkdir -p ~/cubeos-data

该目录用于存储你的设备、场景和设置。

2

如果你使用 Zigbee 设备，请检查其设备路径（可选）

常见的设备路径有：

ls /dev/ttyUSB* /dev/ttyACM*

在下一条命令中使用正确的路径。

3

启动容器

以下命令可作为基础模板：

docker run -d \\
  --name cubeos \\
  --privileged \\
  --net=host \\
  -v ~/cubeos-data:/data \\
  --device /dev/ttyUSB0:/dev/ttyUSB0 \\
  -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro \\
  ghcr.io/ewelinkcube/cube-os:latest

如果你不使用 Zigbee，请删除 --device /dev/ttyUSB0:/dev/ttyUSB0.

如果你不使用 Matter Hub 或 eWeLink Remote，也可以删除 D-Bus 挂载。

4

了解主要参数

  • --privileged — 需要硬件访问权限

  • --net=host — 需要用于局域网发现和 MQTT

  • -v ~/cubeos-data:/data — 在容器重启后保留你的数据

  • --device /dev/ttyUSB0:/dev/ttyUSB0 — 传递 Zigbee 适配器

  • -v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro — 为受支持的功能启用 D-Bus 访问

4. 访问 CUBE OS

1

确认容器正在运行

docker ps

容器状态应显示 运行中.

2

打开 Web 界面

在同一网络中的浏览器中访问以下地址之一：

将 <HOST_IP> 替换为 Linux 主机的 IP 地址。

3

之后可使用简短的本地地址

设置完成后，你可以在设置页面找到简短 ID。

然后你可以使用 cube-{short-id}.local 来在你的局域网中识别这个 CUBE OS 实例。

5. 更新 CUBE OS

Docker 部署不支持通过 Web 界面进行 OTA 更新。

要手动更新：

你的数据保存在 ~/cubeos-data中，因此更新后设备、场景和设置都会保留。

6. 限制

由于容器隔离，以下功能在 Docker 部署中不可用：

  • 附加组件 — 无法安装或管理附加组件

  • 蓝牙扬声器 — 不支持蓝牙透传

  • 系统更新 — 已禁用 Web 界面中的 OTA 更新

  • 重启 / 关机 — 无法使用系统级电源控制

7. 树莓派说明

如果你在树莓派上运行 Docker，请确保页大小为 4096:

上一页UGREEN NAS下一页一键安装

最后更新于