在 Docker 中运行 ESPHome

ESPHome 发布了一个官方容器镜像，支持 AMD64、ARM 和 ARM64（AARCH64）。使用该镜像无需在主机上安装 Python 或任何构建工具。

docker pull ghcr.io/esphome/esphome

任何命令行子命令都可以通过将其附加到 docker run 调用来使用，同时将配置目录挂载到 /config：

docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome run livingroom.yaml

运行设备构建器

启动时不带任何子命令，镜像会运行 ESPHome 设备构建器仪表盘：

docker run --rm --net=host -v "${PWD}":/config -it ghcr.io/esphome/esphome

然后可以通过 localhost:6052 访问该仪表盘——请参阅ESPHome 入门指南了解其使用介绍。

--net=host 允许仪表盘使用 mDNS，这是它发现设备、解析其 .local 名称以及跟踪设备在线状态的方式。主机网络驱动仅适用于 Linux 主机。在 Docker Desktop 4.34 及更高版本中，该功能可用，但需要先在设置 → 资源 → 网络中启用。

如果不使用主机网络，请改为发布端口：

docker run --rm -p 6052:6052 -v "${PWD}":/config -it ghcr.io/esphome/esphome

设备构建器仍然可以这样运行，并会通过定期的 ICMP ping 扫描来检查设备。但是，没有多播就无法解析 .local 名称，因此扫描只能 ping 那些具有固定地址的设备——可以在设备自身的配置中通过 use_address 或 manual_ip 设置。其他设备将不显示状态。

镜像的默认命令针对 /config 运行 esphome-device-builder。要传递标志（例如 --log-level debug），请将其附加到 docker run 调用中。

通过 USB 烧录

在 Linux 上，将串口设备传递到容器中：

docker run --rm --privileged -v "${PWD}":/config --device=/dev/ttyUSB0 -it ghcr.io/esphome/esphome run livingroom.yaml

WARNING

macOS 上的 Docker 无法透传 USB 设备，因此您无法在容器中通过 USB 烧录设备。其他所有功能均可正常使用，您仍然可以通过仪表盘的 Web 安装程序进行烧录。请参阅物理设备连接了解替代方案。

Docker Compose

services:
  esphome:
    container_name: esphome
    image: ghcr.io/esphome/esphome
    volumes:
      - /path/to/esphome/config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: always
    privileged: true
    network_mode: host
    environment:
      - ESPHOME_USERNAME=admin
      - ESPHOME_PASSWORD=ChangeMe

NOTE

凭据变量是 ESPHOME_USERNAME 和 ESPHOME_PASSWORD，而非旧版仪表盘的裸 USERNAME 和 PASSWORD——后者会与大多数登录 shell 中已设置的 $USERNAME 冲突。建议使用具有受限读取权限的环境文件，而非在命令行上传递密码，因为命令行参数在进程列表中可能被其他用户看到。

镜像标签

该项目发布多个标签；请选择适合您的标签：

latest 和 stable 指向最新的稳定版本。不建议在这些标签上自动更新容器，因为版本之间可能存在破坏性变更。
YEAR.MONTH（例如 2022.8）跟踪该版本内的最新稳定补丁版本。在这些标签内升级容器不应引入破坏性变更。
beta 指向最新的 beta 版本，当没有新的 beta 版本时回退到最新的稳定版本。
dev 是最前沿的版本，每天从 dev 分支构建。

已知问题