poulti/esphome-avahi

ESPHome with Avahi-Utils 镜像文档

镜像概述和主要用途

本镜像是基于 ESPHome 最新官方镜像构建的自定义 Docker 镜像，通过集成 avahi-utils 工具集，增强了 ESPHome 仪表板的 mDNS（多播 DNS）服务发现能力。主要用途是解决本地网络中 ESP 设备（如 ESP8266/ESP32）通过 .local 域名（如 espdevice.local）访问的问题，实现 ESPHome 仪表板对 ESP 设备的自动发现与域名解析。

核心功能和特性

• 基础镜像：基于 ESPHome 最新官方镜像，继承其全部功能（设备配置、固件编译、OTA 升级等）。
• mDNS 支持：集成 avahi-utils 工具集（包含 avahi-resolve, avahi-browse 等），支持解析本地网络中 ESP 设备的 .local 域名。
• 无缝集成：无需修改 ESPHome 核心配置，仅通过卷挂载即可启用 mDNS 功能，与 ESPHome 仪表板原生流程兼容。

使用场景和适用范围

• 适用环境：运行 ESPHome 仪表板的 Docker 环境（如家庭服务器、NAS、单节点 Docker 主机）。
• 核心场景：
  • 本地网络中需要通过 .local 域名访问 ESP 设备的场景（避免手动配置 IP 地址）。
  • ESPHome 仪表板无法自动发现 ESP 设备（因缺少 mDNS 解析能力）的场景。
  • 需通过命令行工具（如 avahi-browse）手动排查 ESP 设备网络状态的场景。

使用方法和配置说明

前置条件

• 主机需已安装并运行 avahi-daemon 服务（负责本地 mDNS 解析）和 dbus 服务（Avahi 依赖的消息总线）。
• 确保主机路径 /var/run/dbus 和 /var/run/avahi-daemon/socket 存在且可访问（通常由 avahi-daemon 和 dbus 自动创建）。

Docker Run 命令示例

通过以下命令启动容器，需显式挂载主机的 dbus 和 avahi-daemon 套接字：

bash
docker run -d \
  --name esphome-avahi \
  -p 6052:6052 \  # ESPHome 仪表板默认端口
  -v /path/to/your/esphome/config:/config \  # 挂载 ESPHome 配置目录（必填）
  -v /var/run/dbus:/var/run/dbus \  # 挂载 dbus 套接字（mDNS 依赖）
  -v /var/run/avahi-daemon/socket:/var/run/avahi-daemon/socket \  # 挂载 avahi 套接字（mDNS 依赖）
  --restart unless-stopped \
  [镜像名称]  # 替换为实际镜像名称（如自定义构建的镜像标签）

Docker Compose 配置示例

创建 docker-compose.yml 文件，配置如下：

yaml
version: '3'
services:
  esphome:
    image: [镜像名称]  # 替换为实际镜像名称
    container_name: esphome-avahi
    restart: unless-stopped
    ports:
      - "6052:6052"  # ESPHome 仪表板端口
    volumes:
      - /path/to/your/esphome/config:/config  # 本地 ESPHome 配置目录（需替换为实际路径）
      - /var/run/dbus:/var/run/dbus  # 共享主机 dbus 套接字
      - /var/run/avahi-daemon/socket:/var/run/avahi-daemon/socket  # 共享主机 avahi 套接字
    environment:
      - TZ=Asia/Shanghai  # 可选：设置时区（继承自 ESPHome 镜像，支持所有 ESPHome 环境变量）

卷挂载说明

注意事项

1. 主机服务依赖：确保主机已安装 avahi-daemon 和 dbus 并正常运行（可通过 systemctl status avahi-daemon 和 systemctl status dbus 检查）。
2. 权限问题：容器需具有访问主机套接字的权限，建议以非 root 用户运行时，确保用户 ID (UID) 对 /var/run/dbus 和 /var/run/avahi-daemon/socket 有读权限。
3. 兼容性：与 ESPHome 官方镜像完全兼容，支持所有 ESPHome 原生功能和配置参数。