升级到 4.3 版本

以下内容仅针对从 4.2 升级到 4.3 的用户。

由于数据库架构和 Broker 间 API 更改，EMQX 4.3 节点将无法加入 4.2 集群。

推荐按以下步骤完成升级：

1. 从 4.2 任一节点导出数据（见下文）
2. 使用 4.3 的配置创建备用的 4.3 集群
3. 将导出数据导入至 4.3 任一节点，然后重启集群
4. 将流量从 4.2 集群切换至 4.3 集群
5. 关闭 4.2 集群

旧集群中存储在内置数据库（Mneisa）的数据可以通过 数据库迁移 来迁移至新集群。此外还有一些重要的 配置变更 和 行为变更，详见下文。

数据迁移

在升级前，应备在每个4.2版本的节点上对 data 目录中的数据进行备份。 根据不同的安装方式和配置，data 目录可能在一下这些位置

• 环境变量 EMQX_NODE__DATA_DIR 指向的位置
• 配置文件中 node.data_dir 指向的位置
• 在docker中运行的默认位置: /opt/emqx/data （通常是一个挂在的外部volume）
• 直接使用 zip 安装包的默认位置: <install-path>/data
• 使用RPM或DEB安装包安装的默认位置：/var/lib/emqx/

复制 Data 目录

从4.2升级到4.3前，如果4.3在另外一台主机，则需要将备份的data目录复制到新主机上。 但是 data/mnesia 目录除外（或者在复制之后删除）。

数据库迁移

注：详情请参阅 数据导入导出。

执行以下命令以导出数据：

$ emqx_ctl data export

这将生成一个名称中带有时间戳的 JSON 文件，该文件包含了旧集群的所有可迁移数据，可用于导入至新集群。

emqx_auth_mnesia 插件现在支持基于 clientid 和 username 的规则。而此前只支持一种类型的过滤器，如 etc/plugins/emqx_auth_mnesia.conf 文件中配置的那样。

为了正确导入来自旧版本 emqx_auth_mnesia 插件的数据，需要将该参数的值通过命令行参数选项传递给数据导入命令：

$ emqx_ctl data import <filename> --env '{"auth.mnesia.as":"username"}'

或者

$ emqx_ctl data import <filename> --env '{"auth.mnesia.as":"clientid"}'

重要的配置变更

• EMQX 现在默认尝试使用 TLS 1.3，请确保 openssl 是最新的(1.1.1)，否则可能需要更改 SSL 相关配置，例如从 listener.ssl.external.tls_versions 的列表中删除 tlsv1.3
• 新增 listener.ws.$zone.check_origin_enable listener.ws.$zone.allow_origin_absence 和 listener.ws.$zone.check_origins 配置以获得更好的 WebSocket 安全性。
• 配置项 listener.ws.$name.verify_protocol_header 由 listener.ws.external.fail_if_no_subprotocol 和 listener.ws.external.supported_subprotocols 替代。
• 配置项 node.heartbeat 不能被环境变量 EMQX_NODE__HEARTBEAT 覆盖，待修复，Github Issue#5929
• 支持设置 log.formatter = json 以 JSON 格式输出日志，但可能需要更多 CPU 资源
• 支持设置 log.single_line = true 以阻止单条日志发生换行。
• rpc.tcp_client_num 默认配置为 1。大于 1 的值可能会导致集群节点间传递消息时乱序。

重要的插件配置变更

emqx_auth_http

为了更容易理解，我们将使用关键字 REQUEST 来指代 auth_req、super_req 和 acl_req。

• auth.http.REQUEST 更名为 auth.http.REQUEST.url。
• auth.http.header.<Key> 更名为 auth.http.REQUEST.headers.<Key> = <Value>。即现在可以为每个 REQUEST 类型配置不同的 HTTP Headers。
• auth.http.REQUEST.content_type 更名为 auth.http.REQUEST.headers.content_type。
• auth.http.request.timeout 更名为 auth.http.timeout。
• auth.http.request.connect_timeout 更名为 auth.http.connect_timeout。
• 废弃 auth.http.request.retry_times，auth.http.request.retry_interval 和 auth.http.request.retry_backoff 配置项。
• 新增 auth.http.pool_size 以支持配置进程池大小。
• 新增 auth.http.enable_pipelining 以支持开启或关闭 HTTP Pipelining。
• 新增安全相关配置：auth.http.ssl.verify 和 auth.http.ssl.server_name_indication。

emqx_auth_mongo

• auth.mongo.login 更名为 auth.mongo.username
• auth.mongo.ssl_opts.* 更名为 auth.mongo.ssl.*

emqx_auth_pgsql

• auth.pgsql.ssl_opts.* 更名为 auth.mongo.pgsql.*

emqx_auth_redis

• SSL 配置现在按配置路径中的 .ssl 分组。例如auth.redis.cacertfile 现在是 auth.redis.ssl.cacertfile。

emqx_web_hook

注：规则引擎中的 Webhook 资源和操作可以通过数据库迁移命令进行迁移。

• web.hook.api.url 更名为 web.hook.url。
• web.hook.encode_payload 更名为 web.hook.body.encoding_of_payload_field
• 新增安全相关配置： web.hook.ssl.verify 和 web.hook.ssl.server_name_indication
• 新增 web.hook.pool_size 以支持配置进程池大小。
• 新增 web.hook.enable_pipelining 以支持开启或关闭 HTTP Pipelining。

重要的行为变更

• 日志时间戳现在是 RFC3339 格式，请确保您的日志索引器已准备好进行此更改。
• 共享订阅分发策略配置为 round_robin 时的行为变更为随机选择起始订阅者。
• 多语言扩展功能底层实现方式由 erlport 改为 gRPC，因此无法兼容基于 4.2 开发的 Java、Python 扩展代码。
• 新安装包不再支持 macOS 10.14 以下版本（不包括 10.14）。