Docker Compose 安装 Mosquitto + Home Assistant

一、安装 Mosquitto

使用 Docker Compose 安装 Eclipse Mosquitto 主要分为创建 docker-compose.yml 文件和准备配置文件两步。这里为你提供一个标准、可快速上手的配置方案。

1. 创建 docker-compose.yml 文件

首先，为你的项目创建一个目录（例如 mosquitto），并在其中新建 docker-compose.yml 文件，填入以下内容：

services:
  mosquitto:
    image: eclipse-mosquitto:latest  # 使用官方最新镜像
    container_name: eclipse-mosquitto
    ports:
      - "1883:1883"      # 标准的 MQTT 端口，可设置"10883:1883"
      - "1884:1884"      # 标准的 MQTT 端口，可设置"10884:1884"
      # - "9001:9001"      # WebSocket 端口（可选）
    volumes:
      - ./config:/mosquitto/config  # 配置文件目录
      - ./data:/mosquitto/data      # 持久化数据目录
      - ./log:/mosquitto/log        # 日志目录
    restart: unless-stopped                   # 容器退出时自动重启

说明：volumes 部分将容器内的目录映射到宿主机，这样配置、数据和日志都会保留在本地，便于管理。

可自定义 MQTT 端口

Mosquitto 配置文件（mosquitto.conf）不需要改：

容器内的 listener 1883 0.0.0.0 保持原样即可。Docker 会自动把宿主机收到的 10883 流量转发到容器内的 1883。千万不要把配置文件里的 1883 改成 10883，否则容器内部监听错乱会导致服务无法启动。

关于1883、1884端口

一旦在 mosquitto.conf 中设置了 password_file 并重启了服务，Mosquitto 就会强制要求所有连接（包括 ESP32、电脑客户端、其他服务器）都提供合法的用户名和密码。ESP32 的连接代码必须做相应修改，否则连接会被服务器拒绝，并返回 5（连接被拒）错误。

设置 1883 给 ESP32 等设备专用，不需要密码（内网安全环境下）。

端口 1884 则保留给外部应用管理，需要密码。

2. 准备 Mosquitto 配置文件

对上一步设置的目录，设置 777 权限，避免报错：

$ ls
config  data  docker-compose.yml  log

$ sudo chmod 777 ./*

在上一步 docker-compose.yml 所在的目录下，创建配置文件目录和文件：

mkdir -p ./mosquitto/config

然后，在 ./mosquitto/config/ 目录下创建 mosquitto.conf 文件，写入基础配置：

# 端口1883给ESP32专用，不需要密码（内网安全环境下）
listener 1883 0.0.0.0
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
allow_anonymous true    # 允许匿名访问（测试用），生产环境建议关闭

# 端口1884保留给外部管理，需要密码
listener 1884 0.0.0.0
password_file /mosquitto/config/passwd

3. 启动服务

在 docker-compose.yml 所在目录下，执行以下命令：

# 后台启动服务
docker-compose up -d

# 查看运行状态
docker ps

如果看到容器状态为 Up，则表示 Mosquitto 已成功运行。

4. 生成密码文件

进入容器内部，使用 mosquitto_passwd 命令为 1884 端口创建用户（例如用户名为 admin）：

docker exec -it eclipse-mosquitto sh
mosquitto_passwd -c /mosquitto/config/passwd admin
# 按提示输入两次密码
exit

/mosquitto/config/passwd 为配置文件中指定的密码文件。

重启容器使配置生效。

5. 常见问题排查

  • 端口被占用：检查宿主机 1883 或 9001 端口是否已被其他程序占用，可以修改 docker-compose.yml 中的 ports 映射，例如改为 "1884:1883"。
  • 配置文件未生效：确认 mosquitto.conf 文件已正确放置在 ./config/ 目录下，并且语法无误。
  • 容器无法启动：使用 docker logs eclipse-mosquitto 查看错误日志，根据提示进行修复。

二、安装 Home Assistant

在飞牛 FNOS 系统中，直接在应用中心安装即可，安装过程中可以自选 Web 访问端口。也可以使用 docker-compose.yml 文件创建容器。

1. 创建 docker-compose.yml 文件

services:
  homeassistant:
    container_name: homeassistant
    image: "homeassistant/home-assistant:2026.7.2"
    volumes:
      - "./config:/config"
      - "/etc/localtime:/etc/localtime:ro"
      - "/run/dbus:/run/dbus:ro"  # 支持 Bluetooth 集成（蓝牙适配器）和某些硬件检测，可选
    restart: always
    privileged: true
    network_mode: host
    environment:
      TZ: Asia/Shanghai

2. 启动服务

在 docker-compose.yml 所在目录下，执行以下命令：

# 后台启动服务
docker-compose up -d

# 查看运行状态
docker ps

3. HA 配置 MQTT 集成步骤

  1. 进入集成页面

    打开浏览器访问 http://192.168.1.x:8123/，登录 Home Assistant 并注册账户。

    左侧菜单 → 「设置」（齿轮图标）→ 「设备与服务」。

  2. 添加 MQTT 集成

    点击右下角 「添加集成」 → 搜索框输入 MQTT → 点击搜索结果中的 「MQTT」。

  3. 填入连接参数

    字段 值
    代理（Broker） 192.168.1.x
    端口 10884
    用户名 admin
    密码 <设置的密码>

    其余选项保持默认，点击 「提交」。

  4. 验证连接

    提交后页面显示 「成功！」 即表示 HA 已连上 Mosquitto。

    之后配置 ESP32 等设备、上电连 WiFi 后，MQTT 设备列表会自动出现设备，无需手动添加。

4. 支持 lucky 代理

  1. 修改配置文件

    修改 ./config/configuration.yaml ，新增：

    http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
    - 192.168.1.0/24  # Add the IP address of the proxy server

    文件完整内容：

    # Loads default set of integrations. Do not remove.
default_config:

# Load frontend themes from the themes folder
frontend:
themes: !include_dir_merge_named themes

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml

http:
server_port: 8123
use_x_forwarded_for: true
trusted_proxies:
  - 127.0.0.1
  - 192.168.1.0/24  # Add the IP address of the proxy server

    重启 HA 容器。

  2. 设置对外网址

    左侧菜单 → 「设置」（齿轮图标）→ 「系统」→ 「网络」→ 「Home Assistant 网址」，设置 HTTPS 对外网址。

  3. 使用 lucky 即可代理。

posted @ 2026-07-21 10:38  Yogile  阅读(13)  评论(0)    收藏  举报