aerialtech/vernemq

docker-vernemq

VerneMQ是什么？

VerneMQ是一款高性能的分布式MQTT消息broker。它可在普通硬件上进行水平和垂直扩展，以支持大量并发发布者和消费者，同时保持低延迟和容错能力。VerneMQ是IoT平台或智能产品的可靠消息枢纽。

VerneMQ是采用Erlang开发的Apache2许可分布式MQTT broker。

如何使用该镜像

1. 使用Helm在Kubernetes上部署

首先根据文档安装并配置Helm。然后添加VerneMQ Helm图表仓库：

bash
helm repo add vernemq https://vernemq.github.io/docker-vernemq

现在可以在Kubernetes集群上部署VerneMQ：

bash
helm install vernemq/vernemq

更多信息请查看Helm图表的README。

2. 使用纯Docker命令

bash
docker run --name vernemq1 -d erlio/docker-vernemq

有时需要配置端口转发（例如在Mac上）：

bash
docker run -p 1883:1883 --name vernemq1 -d erlio/docker-vernemq

这会启动一个新节点，监听1883端口（MQTT连接）和8080端口（MQTT over WebSocket连接）。但此时broker无法认证连接的客户端。要允许***客户端，使用DOCKER_VERNEMQ_ALLOW_ANONYMOUS=on环境变量：

bash
docker run -e "DOCKER_VERNEMQ_ALLOW_ANONYMOUS=on" --name vernemq1 -d erlio/docker-vernemq

自动加入VerneMQ集群

这允许新启动的容器自动加入VerneMQ集群。假设你已像上面的示例启动了第一个节点，可以按以下方式自动加入集群（当前集群仅包含单个容器'vernemq1'）：

bash
docker run -e "DOCKER_VERNEMQ_DISCOVERY_NODE=<VERNEMQ1的IP>" --name vernemq2 -d erlio/docker-vernemq

（注意：可以使用docker inspect <容器名/ID> | grep \"IPAddress\"查找Docker容器的IP。）

3. 在Kubernetes上不使用Helm的自动集群

在Kubernetes中运行VerneMQ时，可以让匹配特定标签的pod自动组成集群。此功能使用Kubernetes API发现其他节点，依赖默认pod服务账户（需启用）。

只需在pod的环境中设置DOCKER_VERNEMQ_DISCOVERY_KUBERNETES=1，并通过MY_POD_NAME暴露自己的pod名称。默认情况下，此设置会让同一命名空间中带有app=vernemq标签的所有pod加入同一集群。集群名称（默认cluster.local）、命名空间和标签设置可分别通过DOCKER_VERNEMQ_KUBERNETES_CLUSTER_NAME、DOCKER_VERNEMQ_KUBERNETES_NAMESPACE和DOCKER_VERNEMQ_KUBERNETES_LABEL_SELECTOR覆盖。

pod环境的示例配置如下：

yaml
env:
  - name: DOCKER_VERNEMQ_DISCOVERY_KUBERNETES
    value: "1"
  - name: MY_POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
  - name: DOCKER_VERNEMQ_KUBERNETES_LABEL_SELECTOR
    value: "app=vernemq,release=myinstance"

启用Kubernetes自动集群时，不要设置DOCKER_VERNEMQ_DISCOVERY_NODE。

若遇到如下"SSL证书错误（主题名称与主机名不匹配）"，可尝试设置DOCKER_VERNEMQ_KUBERNETES_INSECURE为"1"：

text
kubectl logs vernemq-0
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0curl: (51) SSL: certificate subject name 'client' does not match target host name 'kubernetes.default.svc.cluster.local'
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0curl: (51) SSL: certificate subject name 'client' does not match target host name 'kubernetes.default.svc.cluster.local'
vernemq failed to start within 15 seconds,
see the output of 'vernemq console' for more information.
If you want to wait longer, set the environment variable
WAIT_FOR_ERLANG to the number of seconds to wait.
...

如果使用vernemq.conf.local文件，可在配置中插入占位符###IPADDRESS###，在POD创建时会替换为VerneMQ运行的POD实际IP地址，使VMQ集群成为可能。

4. 使用Docker Swarm

请遵循官方Docker指南正确设置包含一个或多个节点的Swarm集群。

Swarm设置完成后，可部署VerneMQ栈。以下代码片段使用docker-compose.yml文件描述栈：

yaml
version: "3.7"
services:
  vmq0:
    image: erlio/docker-vernemq
    environment:
      DOCKER_VERNEMQ_SWARM: 1
  vmq:
    image: erlio/docker-vernemq
    depends_on:
      - vmq0
    environment:
      DOCKER_VERNEMQ_SWARM: 1
      DOCKER_VERNEMQ_DISCOVERY_NODE: vmq0
    deploy:
      replicas: 2

运行docker stack deploy -c docker-compose.yml my-vernemq-stack部署3节点VerneMQ集群。

注意：Docker Swarm目前缺乏类似Kubernetes中statefulset的功能。因此VerneMQ必须依赖特定的发现服务（如上的vmq0服务），该服务需在其他副本之前启动。

检查集群状态

要检查上述容器是否成功集群，可执行vmq-admin命令：

bash
docker exec vernemq1 vmq-admin cluster show
+--------------------+-------+
|        Node        |Running|
+--------------------+-------+
|VerneMQ@172.17.0.151| true  |
|VerneMQ@172.17.0.152| true  |
+--------------------+-------+

若在Kubernetes中使用DOCKER_VERNEMQ_DISCOVERY_KUBERNETES=1启动VerneMQ集群，可通过kubectl执行vmq-admin：

bash
kubectl exec vernemq-0 -- vmq-admin cluster show
+---------------------------------------------------+-------+
|                       Node                        |Running|
+---------------------------------------------------+-------+
|VerneMQ@vernemq-0.vernemq.default.svc.cluster.local| true  |
|VerneMQ@vernemq-1.vernemq.default.svc.cluster.local| true  |
+---------------------------------------------------+-------+

所有vmq-admin命令均可用。更多信息请查看[***]

在Consul + Nomad上自动集群

在Nomad中运行VerneMQ时，可利用Nomad填充的Consul服务目录，使VerneMQ容器自动组成集群。

在Job环境中设置DOCKER_VERNEMQ_DISCOVERY_CONSUL=1。确保epmd端口（4369）注册到特定服务，并将此服务名称设置到DOCKER_VERNEMQ_DISCOVERY_CONSUL_SERVICE_NAME环境变量中，且定义了健康检查（以便仅当VerneMQ容器实际监听此端口时才注册）。

以下是Nomad job中运行该容器的重要代码片段（此job不完整，仅展示自动发现设置）：

hcl
job "vernemq" {
  type = "service"

  group "mqtt" {
    task "mqtt" {
      driver = "docker"
      config {
        # 由于自动发现、名称和IP，我们使用主机网络
        # （获得与Kubernetes中clusterIP类似的路由）
        network_mode = "host"

        port_map {
          epmd                = 4369
        }
      }

      env {
        "DOCKER_IP_ADDRESS"                  = "${attr.unique.network.ip-address}"
        "DOCKER_VERNEMQ_NODENAME"            = "VerneMQ@${attr.unique.network.ip-address}"

        # VerneMQ集群（Consul+Nomad）
        "DOCKER_VERNEMQ_DISCOVERY_CONSUL"              = "1"
        "DOCKER_VERNEMQ_DISCOVERY_CONSUL_HOST"         = "${attr.unique.network.ip-address}"
        "DOCKER_VERNEMQ_DISCOVERY_CONSUL_SERVICE_NAME" = "mqtt-discovery"
        "DOCKER_VERNEMQ_DISCOVERY_CONSUL_STAGGER_IND"  = "${NOMAD_ALLOC_INDEX}"
      }

      resources {
        network {
          port "epmd" {
            static = 4369
          }
        }
      }

      service {
        # 此服务仅用于暴露其中一个MQTT broker的动态地址
        # 方便其他broker加入
        name = "mqtt-discovery"
        port = "epmd"

        check {
          type     = "tcp"
          port     = "epmd"
          interval = "10s"
          timeout  = "2s"
          initial_status = "critical"
        }
      }
    }
  }
}

自动发现的其他有用环境变量：

• DOCKER_VERNEMQ_DISCOVERY_CONSUL_HOST：用于向Consul服务目录发起API调用的主机
• DOCKER_VERNEMQ_DISCOVERY_CONSUL_PORT：允许自定义Consul API端口，默认向8500端口发送请求
• DOCKER_VERNEMQ_DISCOVERY_CONSUL_STAGGER_IND：用于在不同分配之间添加时间偏移：第二个分配等待一点时间确保第一个分配准备好接收加入节点，然后n+1节点比n节点等待更长时间，依此类推。

已知限制：

• 尚未处理Consul TLS和ACL
• 主机网络并非理想选择，计划后续改进

VerneMQ配置

vernemq.conf中所有可用的配置参数均可使用DOCKER_VERNEMQ前缀加上配置参数名来定义。例如：allow_anonymous=on对应-e "DOCKER_VERNEMQ_ALLOW_ANONYMOUS=on"，allow_register_during_netsplit=on对应-e "DOCKER_VERNEMQ_ALLOW_REGISTER_DURING_NETSPLIT=on"。所有可用配置参数可在[***]

日志

VerneMQ将崩溃和错误日志文件存储在/var/log/vernemq/，默认不将控制台日志写入磁盘以避免填满容器磁盘空间。但可通过设置环境变量DOCKER_VERNEMQ_LOG__CONSOLE为both来改变此行为，这会让VerneMQ将日志发送到stdout和/var/log/vernemq/console.log。更多信息请查看VerneMQ日志文档：[***]

备注

部分配置变量包含点.。例如，若要调整VerneMQ的日志级别，需使用-e "DOCKER_VERNEMQ_LOG.CONSOLE.LEVEL=debug"。但某些容器平台（如Kubernetes）不支持环境变量中的点和其他特殊字符。若在这类平台上，可将点替换为双下划线__。上述示例将变为-e "DOCKER_VERNEMQ_LOG__CONSOLE__LEVEL=debug"。

对于包含点的配置名称，存在一些例外情况。以下是示例：

文件基于认证

可通过添加用户和密码作为环境变量来设置文件基于认证：

DOCKER_VERNEMQ_USER_<用户名>='密码'

其中<用户名>是你要使用的用户名。可多次执行此操作以创建所需用户。用户名始终会转换为小写。

注意 - 密码中不能包含=字符。