> For the complete documentation index, see [llms.txt](https://cube.ewelink.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cube.ewelink.cc/english-pt/primeiros-passos/quickstart/docker.md). # Docker Instale o CUBE OS como um contentor Docker num anfitrião Linux. Este método funciona bem para servidores domésticos, dispositivos NAS e máquinas Linux sempre ligadas. {% hint style="info" %} A implementação Docker é suportada em **Apenas Linux**. Se não tiver um anfitrião Linux, use [Raspberry Pi](/english-pt/primeiros-passos/quickstart/raspberry-pi.md) ou [Máquina Virtual](/english-pt/primeiros-passos/quickstart/maquina-virtual/virtualbox.md). {% endhint %} ### 1. Preparação {% stepper %} {% step %} **Verifique a arquitetura do anfitrião** O CUBE Docker suporta estas arquiteturas Linux: * **amd64** (`x86_64`) — PCs, servidores, Synology NAS e dispositivos semelhantes * **arm64** (`aarch64`) — Raspberry Pi 4/5, Orange Pi e outros anfitriões ARM {% endstep %} {% step %} **Verifique a versão do kernel Linux** Kernel `4.15` ou posterior é necessário. ```bash uname -r ``` {% hint style="warning" %} Alguns dispositivos NAS vêm com kernels mais antigos, como `4.4.x`. Estes anfitriões não são compatíveis com o CUBE Docker. Nesse caso, execute o CUBE OS numa máquina virtual Linux em vez disso. {% endhint %} {% endstep %} {% step %} **Instale o Docker Engine** Instale o Docker Engine no anfitrião antes de continuar. Use o [guia oficial de instalação do Docker](https://docs.docker.com/engine/install/). {% endstep %} {% step %} **Verifique as portas necessárias** Certifique-se de que as portas `80` e `1883` estão livres no anfitrião. ```bash sudo lsof -i :80 sudo lsof -i :1883 ``` * **80** — interface web do CUBE OS * **1883** — broker MQTT Se outro serviço estiver a usar estas portas, pare-o primeiro. {% endstep %} {% step %} **Prepare um dongle Zigbee, se necessário** Se pretende adicionar dispositivos Zigbee, ligue um dongle Zigbee compatível ao anfitrião. Os dongles Zigbee testados incluem: > SONOFF ZBDongle-MAX\ > SONOFF ZBDongle-PMG24\ > SONOFF ZBDongle-LMG21\ > SONOFF ZBDongle-E\ > SONOFF ZBDongle-P\ > [Outros listados](https://darkxst.github.io/silabs-firmware-builder/) pelo desenvolvedor @darkxst {% hint style="info" %} Para obter mais informações sobre configurações e compatibilidade do Zigbee, consulte este [guia](/english-pt/verificacao-de-compatibilidade/zigbee.md). {% endhint %} Para mais informações sobre suporte Zigbee, consulte [este guia](/english-pt/verificacao-de-compatibilidade/zigbee.md). {% endstep %} {% endstepper %} ### 2. Obtenha a imagem {% stepper %} {% step %} **Descarregue a imagem mais recente** ```bash docker pull ghcr.io/ewelinkcube/cube-os:latest ```
{% hint style="info" %} Pode substituir `latest` por uma etiqueta de versão específica, como `2.10.3`. As versões disponíveis estão listadas em [GitHub Releases](https://github.com/eWeLinkCUBE/CUBE-OS/releases/). {% endhint %} {% endstep %} {% endstepper %} ### 3. Inicie o CUBE OS {% stepper %} {% step %} **Crie um diretório de dados** ```bash mkdir -p ~/cubeos-data ``` Este diretório armazena os seus dispositivos, cenários e definições. {% endstep %} {% step %} **Verifique o caminho do dispositivo Zigbee, se usar um (opcional)** Os caminhos de dispositivos comuns são: ```bash ls /dev/ttyUSB* /dev/ttyACM* ``` Use o caminho correto no próximo comando. {% endstep %} {% step %} **Inicie o contentor** Use este comando como base: ```bash 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 ```
{% hint style="info" %} Se não usar Zigbee, remova `--device /dev/ttyUSB0:/dev/ttyUSB0`. Se não usar Matter Hub ou eWeLink Remote, também pode remover a montagem D-Bus. {% endhint %} {% endstep %} {% step %} **Compreenda os principais parâmetros** * `--privileged` — necessário para acesso ao hardware * `--net=host` — necessário para descoberta na LAN e MQTT * `-v ~/cubeos-data:/data` — mantém os seus dados após reinícios do contentor * `--device /dev/ttyUSB0:/dev/ttyUSB0` — faz a passagem de um dongle Zigbee * `-v /run/dbus/system_bus_socket:/host_dbus/system_bus_socket:ro` — permite acesso D-Bus para funcionalidades suportadas {% endstep %} {% endstepper %} ### 4. Aceda ao CUBE OS {% stepper %} {% step %} **Confirme que o contentor está em execução** ```bash docker ps ``` O estado do contentor deve mostrar `Up`. {% endstep %} {% step %} **Abra a interface web** Abra um navegador na mesma rede e visite um destes endereços: * `http:///` * Substitua `` pelo endereço IP do anfitrião Linux. {% endstep %} {% step %} **Use mais tarde o endereço local curto** Após a configuração, pode encontrar o ID curto na página de definições. Pode então usar `cube-{short-id}.local` para identificar esta instância do CUBE OS na sua LAN. {% endstep %} {% endstepper %} ### 5. Atualize o CUBE OS A implementação Docker não suporta atualizações OTA a partir da interface web. Para atualizar manualmente: ```bash docker stop cubeos docker rm cubeos docker pull ghcr.io/ewelinkcube/cube-os:latest 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 ``` Os seus dados permanecem em `~/cubeos-data`, por isso os dispositivos, cenários e definições permanecem após a atualização. ### 6. Limitações Devido ao isolamento do contentor, estas funcionalidades não estão disponíveis em implementações Docker: * **Complementos** — não é possível instalar ou gerir complementos * **Coluna Bluetooth** — a passagem de Bluetooth não é suportada * **Atualização do sistema** — as atualizações OTA na interface web estão desativadas * **Reiniciar / Desligar** — os controlos de energia ao nível do sistema não estão disponíveis ### 7. Nota sobre Raspberry Pi Se executar o Docker num Raspberry Pi, certifique-se de que o tamanho da página é `4096`: ```bash getconf PAGE_SIZE # Se o resultado não for 4096, adicione esta linha e reinicie echo "kernel=kernel8.img" | sudo tee -a /boot/firmware/config.txt sudo reboot ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cube.ewelink.cc/english-pt/primeiros-passos/quickstart/docker.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.