hivemq/hivemq4

快速参考

• 获取帮助： https://www.hivemq.com/contact/

• 提交问题： https://github.com/hivemq/hivemq4-docker-images/issues

• 维护者： https://www.hivemq.com

• Dockerfiles： https://github.com/hivemq/hivemq4-docker-images

HiveMQ 是什么？

HiveMQ 是一个基于 MQTT 的消息平台，专为物联网设备间快速、高效、可靠的数据传输而设计。它使用 MQTT 协议实现设备与企业系统之间的即时双向数据推送。
HiveMQ 旨在解决组织构建新型物联网应用时面临的关键技术挑战，包括：

• 构建可靠且可扩展的业务关键型物联网应用
• 实现快速数据传输，满足终端用户对响应式物联网产品的期望
• 通过高效利用硬件、网络和云资源降低运营成本
• 将物联网数据集成到现有企业系统中

HiveMQ 核心是兼容 MQTT 3.1、MQTT 3.1.1 和 MQTT 5.0 的 MQTT broker，其优势在于为企业用例和专业部署设计的附加功能。

有关更多信息，请参见https://www.hivemq.com/features/%E3%80%82

标签

基本单实例部署

要启动单个 HiveMQ 实例并开放 MQTT 端口及控制中心访问，请https://www.docker.com/get-started 并运行以下命令：

bash
docker run --ulimit nofile=500000:500000 -p 8080:8080 -p 8000:8000 -p 1883:1883 hivemq/hivemq4

您可以通过 MQTT（1883 端口）、WebSocket（8000 端口）连接 broker，或通过 8080 端口访问控制中心。

集群部署

对于 HiveMQ 集群部署，建议使用 DNS 发现镜像。该镜像内置 https://www.hivemq.com/extension/dns-discovery-extension/%EF%BC%8C%E5%8F%AF%E4%B8%8E%E4%BB%BB%E4%BD%95%E6%94%AF%E6%8C%81%E9%80%9A%E8%BF%87%E8%BD%AE%E8%AF%A2 A 记录进行服务发现的容器编排引擎配合使用。也可使用提供 A 记录的自定义解决方案。

以下环境变量可分别用于自定义发现和 broker 配置：

以下是在 Docker Swarm 和 Kubernetes 中使用该镜像的示例，其他支持 DNS 发现的环境也兼容。

Docker Swarm 本地集群

要在本地运行 HiveMQ 集群，可使用 Docker Swarm（注意：不建议在生产环境使用 Docker Swarm）：

• 运行以下命令启动单节点 Swarm 集群：

bash
docker swarm init

• 创建集群节点通信的覆盖网络：

bash
docker network create -d overlay --attachable myNetwork

• 在网络上创建 HiveMQ 服务：

bash
docker service create \
  --replicas 3 --network myNetwork \
  --env HIVEMQ_DNS_DISCOVERY_ADDRESS=tasks.hivemq \
  --publish target=1883,published=1883 \
  --publish target=8080,published=8080 \
  -p 8000:8000/udp \
  --name hivemq \
    hivemq/hivemq4:dns-latest

此命令将部署 3 节点集群，并将 MQTT（1883）和 HiveMQ 控制中心（8080）端口转发到主机网络。MQTT 客户端可通过 1883 端口连接，连接将转发到任意集群节点。

有关集群管理的更多信息，请参见 https://github.com/hivemq/hivemq4-docker-images#managing-the-cluster%E3%80%82

Kubernetes 生产部署

注意：建议使用 https://www.hivemq.com/docs/operator/latest%EF%BC%8C%E5%AE%83%E8%83%BD%E7%AE%80%E5%8C%96 HiveMQ 在 Kubernetes 上的部署。

生产环境中，建议将 DNS 发现镜像与 Kubernetes 结合使用。Kubernetes 中需配置适当的部署以利用 DNS 发现，https://kubernetes.io/docs/concepts/services-networking/service/#headless-services 可提供用于发现的 broker DNS 记录。

以下是使用 DNS 发现的 3 节点 HiveMQ 集群的复制控制器配置示例。需根据 Kubernetes 命名空间和配置的域替换 HIVEMQ_DNS_DISCOVERY_ADDRESS：

yaml
apiVersion: v1
kind: ReplicationController
metadata:
  name: hivemq-replica
spec:
  replicas: 3
  selector:
    app: hivemq-cluster1
  template:
    metadata:
      name: hivemq-cluster1
      labels:
        app: hivemq-cluster1
    spec:
      containers:
      - name: hivemq-pods
        image: hivemq/hivemq4:dns-latest
        ports:
        - containerPort: 8080
          protocol: TCP
          name: hivemq-control-center
        - containerPort: 1883
          protocol: TCP
          name: mqtt
        env:
        - name: HIVEMQ_DNS_DISCOVERY_ADDRESS
          value: "hivemq-discovery.default.svc.cluster.local."
        - name: HIVEMQ_DNS_DISCOVERY_TIMEOUT
          value: "20"
        - name: HIVEMQ_DNS_DISCOVERY_INTERVAL
          value: "21"
        - name: HIVEMQ_CLUSTER_TRANSPORT_TYPE
          value: "TCP"
        readinessProbe:
          tcpSocket:
            port: 1883
          initialDelaySeconds: 30
          periodSeconds: 60
          failureThreshold: 60
        livenessProbe:
          tcpSocket:
            port: 1883
          initialDelaySeconds: 30
          periodSeconds: 60
          failureThreshold: 60
---
kind: Service
apiVersion: v1
metadata:
  name: hivemq-discovery
  annotations:
    service.alpha.kubernetes.io/tolerate-unready-endpoints: "true"
spec:
  selector:
    app: hivemq-cluster1
  ports:
    - protocol: TCP
      port: 1883
      targetPort: 1883
  clusterIP: None

访问 HiveMQ 控制中心

要访问 Kubernetes 集群中的 HiveMQ 控制中心，请执行以下步骤：

• 创建暴露控制中心的服务，使用以下 YAML 定义（保存为 web.yaml）：

yaml
kind: Service
apiVersion: v1
metadata:
  name: hivemq-control-center
spec:
  selector:
    app: hivemq-cluster1
  ports:
    - protocol: TCP
      port: 8080
      targetPort: 8080
  sessionAffinity: ClientIP
  type: LoadBalancer

• 运行 kubectl create -f web.yaml 创建服务。

注意： 根据 Kubernetes 环境提供商，负载均衡器可能不可用或需要额外配置才能访问控制中心。

使用外部客户端访问 MQTT 端口

要允许外部客户端访问 Kubernetes 集群的 MQTT 端口，请执行以下步骤：

• 创建使用负载均衡器暴露 MQTT 端口的服务，使用以下 YAML 定义（保存为 mqtt.yaml）：

yaml
kind: Service
apiVersion: v1
metadata:
  name: hivemq-mqtt
  annotations:
    service.spec.externalTrafficPolicy: Local
spec:
  selector:
    app: hivemq-cluster1
  ports:
    - protocol: TCP
      port: 1883
      targetPort: 1883
  type: LoadBalancer

• 运行 kubectl create -f mqtt.yaml 创建服务。

注意： externalTrafficPolicy 注解用于允许 Kubernetes 服务维持大量并发连接，详见 https://kubernetes.io/docs/tutorials/services/source-ip/#source-ip-for-services-with-type-nodeport%E3%80%82

配置

设置 HiveMQ 控制中心用户名和密码

环境变量 HIVEMQ_CONTROL_CENTER_PASSWORD 允许通过定义自定义密码的 SHA256 哈希来设置控制中心密码。环境变量 HIVEMQ_CONTROL_CENTER_USER 可配置用户名。

有关如何生成密码哈希的更多信息，请参见 https://www.hivemq.com/docs/4/control-center/configuration.html#generate-password%E3%80%82

添加许可证

要在 HiveMQ 容器中使用许可证，需先将许可证文件编码为字符串。运行 cat license.lic | base64（将 license.lic 替换为许可证文件路径），然后将结果字符串设置为容器的 HIVEMQ_LICENSE 环境变量值。

禁用 hivemq-allow-all-extension

默认情况下，HiveMQ 镜像使用内置的 hivemq-allow-all-extension。设置环境变量 HIVEMQ_ALLOW_ALL_CLIENTS 为 false 可在启动时删除该扩展。

禁用权限降级

默认情况下，HiveMQ 镜像在启动时检查 root 权限，若存在则切换到低权限用户以增强容器安全性。设置环境变量 HIVEMQ_NO_ROOT_STEP_DOWN 为 false 可跳过此步骤。

覆盖集群绑定地址

默认情况下，HiveMQ DNS 发现镜像尝试使用容器的 ${HOSTNAME} 设置绑定地址，以确保 HiveMQ 将集群连接绑定到正确接口。设置 HIVEMQ_BIND_ADDRESS 环境变量可覆盖此行为，broker 将使用指定值作为绑定地址。

设置集群传输类型

默认情况下，HiveMQ DNS 发现镜像使用 UDP 作为集群传输协议。设置 HIVEMQ_CLUSTER_TRANSPORT_TYPE 环境变量为 TCP 可改用 TCP。

注意： 建议使用 TCP 作为集群传输协议，可降低高网络负载下网络分区的风险。

构建自定义 Docker 镜像

有关构建自定义 HiveMQ 镜像的更多信息，请参见 https://www.hivemq.com/docs/hivemq/latest/user-guide/docker.html#custom%E3%80%82