scififarms/technocore-vernemq

docker-vernemq

什么是VerneMQ？

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

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

如何使用此镜像

1. 接受VerneMQ最终用户许可协议（EULA）

注意： 使用官方Docker镜像前，您必须接受VerneMQ最终用户许可协议。您可以通过此处了解如何接受该协议。

2. 使用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。

3. 使用纯Docker命令

bash
docker run -e "DOCKER_VERNEMQ_ACCEPT_EULA=yes" --name vernemq1 -d vernemq/vernemq

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

bash
docker run -p 1883:1883 -e "DOCKER_VERNEMQ_ACCEPT_EULA=yes" --name vernemq1 -d vernemq/vernemq

这将启动一个新节点，在1883端口监听MQTT连接，在8080端口监听WebSocket上的MQTT连接。但此时代理无法对连接的客户端进行身份验证。要允许***客户端，请使用DOCKER_VERNEMQ_ALLOW_ANONYMOUS=on环境变量：

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

自动加入VerneMQ集群

这允许新启动的容器自动加入VerneMQ集群。假设您已按上述示例启动第一个节点，您可以按以下方式自动加入集群（当前由单个容器'vernemq1'组成）：

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

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

4. 在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集群成为可能。

5. 使用Docker Swarm

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

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

yaml
version: "3.7"
services:
  vmq0:
    image: vernemq/vernemq
    environment:
      DOCKER_VERNEMQ_SWARM: 1
  vmq:
    image: vernemq/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命令均可用。更多信息请参见[***]

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_<USERNAME>='password'

其中<USERNAME>是您要使用的用户名。可以根据需要多次执行此操作以创建所需用户。用户名将始终以小写创建。

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