EMQX Cloud V4 升级至 V6 指南
作为 EMQX 专有版用户，您可以将 EMQX 从 V4 版本升级到 V6 版本。想要查看当前的 EMQX 版本号，可以在部署详情页点击设置按钮进入部署信息页面。
EMQX V6 在 V4 稳定高效的基础上进行了全面增强：优化了认证授权、监控指标、保留消息和数据集成能力，并新增或增强了命名空间、日志追踪、历史事件、BigQuery 数据集成和 Snowflake Streaming 数据集成等能力。您可以查阅全新功能获取更多详细信息。
适用范围
EMQX V6 仅支持专有版和弹性专有版 Broker 部署。Serverless 部署不支持选择 EMQX 版本。
升级前期准备
- 请至少提前 3 天联系我们安排升级，我们将与您沟通升级注意事项及时间窗口。
- 请全面阅读并理解本文档，尤其是不兼容变更部分。如有任何疑问，可随时通过工单与我们交流。
- 我们的 SRE 团队将对您的部署进行全面评估。如存在特殊配置或潜在影响，将在“特殊情况说明”中反馈，您可据此决定是否继续升级。
- 如果业务系统调用了 V4 HTTP API，或使用了外部认证授权及复杂数据集成，请在升级前完成 V6 环境兼容性验证。
数据迁移与保留内容
升级过程中，我们将为您保留以下配置：
- MQTT 连接地址及端口
- 所有认证及授权条目
- 数据集成配置，包括资源、规则和动作，详见下方兼容性说明
- TLS 证书信息
- 保留消息
- 网络管理相关配置，包括 NAT 网关、内部接入点、PrivateLink 和 VPC Peering
不兼容变更
- 功能移除：V6 版本不再支持设备影子服务。
- 特殊配置变更：之前通过工单申请的特殊配置，例如额外端口、ACL 白名单等，可能受到影响。SRE 团队将在升级前详细说明具体影响。
- HTTP API 变更：
API 访问前缀由
/api变更为/api/v5。V4 中的 API Key 和 Secret Key 无法迁移，升级后需要重新创建，并同步更新业务系统中的 API 地址及认证信息。
多个 API 请求路径发生变化，包括消息发布、客户端查询、节点管理等功能。
除 API 路径变化外，部分 API 的请求体、响应结构、HTTP 状态码、错误码、字段名称、字段类型及时间格式也存在兼容性变化。
这些变更可能影响现有业务系统的 API 解析逻辑，请您在升级前完成兼容性验证。
详细对比请参考：
- 外部扩展认证变更：配置字段及查询响应要求发生变化，您需要按照扩展认证文档进行修改。
- 数据集成部分兼容性：
- 未绑定任何规则的资源，升级后将不会被保留。请在升级前检查并确认这些资源是否仍需使用。
- 规则下的失败备选动作将不会被保留。V6 使用新的数据集成架构，不再支持失败备选动作功能。
- 空 Action，即未关联任何资源或动作的 Action，将在升级过程中自动删除。
- 使用
WHERE语句的部分 Rule SQL 与新版本不兼容，升级后可能需要手动调整规则语法。例如，在判断字段值是否存在时，V4 使用<> "undefined"，新版本需要使用is_null进行判断。
升级过程影响评估
- 升级过程预计持续 15–25 分钟，其中预计会出现约 5–15 分钟 的服务停机时间。
- 系统将在升级期间创建持续 2 小时 的维护窗口。在维护窗口内，如因升级或兼容性问题导致服务不可用，不计入 SLA 可用性统计范围。
- 升级期间所有客户端连接将断开 1–2 次，请确保客户端已配置自动重连机制。
- 设置
clean session = false的客户端会话将无法保留；客户端重连后将创建新会话。
升级后流程
升级后验证
- EMQX Cloud SRE 团队将在升级后检查部署日志和指标是否正常。
- 请您务必全面测试业务功能，特别是：
- HTTP API 调用是否已更新为新路径及新的 API Key/Secret Key
- HTTP API 返回结构与业务系统解析逻辑是否兼容
- 默认及扩展认证授权是否正常
- 数据集成连接器、规则、Source 和 Sink 是否正常运行
- 客户端连接、订阅和消息收发是否正常
- TLS 连接及自定义证书是否正常
- 如发现任何异常，请立即与我们联系解决。
回滚机制
- 我们提供 24 小时的回滚窗口，可在确认前从 V6 回滚至 V4。
- 回滚过程预计持续 15–25 分钟，将有约 3–5 分钟的服务中断。
- 回滚期间所有客户端连接将断开 1–2 次。
- 设置
clean session = false的客户端会话将无法保留。
V6 版本核心功能变更详解
本节将详细介绍从 V4 升级至 V6 后的功能增强、架构优化以及对应的控制台界面变更。
证书管理增强
V6 部署默认配置单向 TLS 证书，即连接域名通配证书，您可直接使用 8883 和 8084 端口进行 TLS 连接。自定义 TLS 证书将替换这些端口的默认证书，删除自定义证书后将恢复默认部署连接地址的证书。
HTTP API 变更
- API 请求端点由
https://xxx/api变为https://xxx/api/v5。 - V4 中的 API Key 和 Secret Key 无法迁移，升级后需要重新创建。
- 除 API 请求路径变化外，部分 API 的请求体、响应结构、HTTP 状态码、错误码、字段名称、字段类型及时间格式也存在兼容性变化。
如果您的业务系统依赖现有 V4 API 返回结构，请务必在升级前完成兼容性测试。详情请参阅最新版本 API 文档中的 Authentication 部分。
访问控制优化
- “认证鉴权”功能更名为“访问控制”。
- 升级将完整迁移默认认证授权的数据及扩展认证授权的配置。
- 外部认证授权功能细分为“外部认证”和“外部授权”，入口分别移至“客户端认证”和“客户端授权”中的“扩展认证”。
- 可手动调整认证链中各认证模块的优先顺序。
- 客户端授权中的默认授权规则可在客户端 ID、用户名和全部用户三个层级进行权限控制设置。同一客户端或用户名的授权信息将显示在页面中对应的标签下。
监控功能重构
- 原“监控界面”下的实时指标迁移至“指标界面”，可选择查看实时指标和时间轴数据。
- 原“监控界面”下的客户端管理与订阅管理独立放置在“监控”下的“客户端”和“订阅”界面。
- 新增“保留消息管理”界面，支持查询和删除保留消息。
数据集成架构升级
规则、Source 和 Sink 架构调整
兼容性说明
升级至 V6 后，请注意以下规则兼容性变化：
- 空 Action 将在升级过程中自动删除。
- 使用
WHERE语句的部分 Rule SQL 与 V6 不兼容，升级后可能需要手动调整规则语法。例如，在判断字段值是否存在时，V4 使用<> "undefined"，V6 需要使用is_null进行判断。
- 规则与动作进行了逻辑拆分，提供更灵活的配置方式。
- Sink 用于将数据转发到外部服务。
- Source 用于将外部服务的数据接入 EMQX，类似 V4 的 MQTT Subscribe 插件。
- 不再支持备选动作功能。
数据集成能力扩展
- 数据转发新增 Elasticsearch、Azure Event Hubs、Amazon Kinesis、SysKeeper 转发器等集成。
- 数据持久化新增 Apache IoTDB、GreptimeDB、Amazon S3 等集成。
- 支持从消息队列服务和 MQTT 服务导入数据，例如 Kafka Consumer 和 MQTT Source。
- V6 进一步新增 BigQuery 和 Snowflake Streaming 数据集成，详见下方“V6 特有能力”。
数据智能中心升级
数据智能中心是智能数据处理的一站式解决方案，可用于管理 Schema、进行数据校验并实时转换数据。此功能可简化 MQTT 数据流处理，提升数据标准化和业务集成能力。
如果您在 V4 版本中配置了 Schema Registry，升级后将自动开通数据智能中心。
V6 特有能力
提示
以下功能仅适用于支持 EMQX V6 的专有版和弹性专有版部署。具体功能可用性以部署所运行的 V6 小版本、区域及控制台显示为准。
| V6 特有能力 | 对用户的实际价值 |
|---|---|
| 命名空间 | 为多租户场景提供资源和权限隔离，可按租户、团队或业务单元组织规则、连接器、动作等资源，降低相互影响，并简化统一集群下的运维管理。 |
| 日志追踪 | 可按客户端、主题、客户端 IP、规则 ID 收集 debug 日志，无须打开整个部署的详细日志，适合定点排障。 |
| 历史事件 | 保留近期的连接、认证、订阅事件，用于定位连接失败、异常断开、认证失败、订阅不生效。 |
| BigQuery 数据集成 | 通过规则引擎和 BigQuery Sink 将 MQTT 数据写入 BigQuery，方便 SQL 分析与报表。 |
| Snowflake Streaming 数据集成 | 通过规则引擎和 Snowflake Streaming Sink 低延迟写入 Snowflake 表。 |
命名空间
命名空间用于增强多租户管理和资源隔离能力。管理员可按租户、部门或业务单元划分资源范围，并对命名空间内的规则、连接器和动作进行独立管理。对于在同一部署中承载多个团队或客户的场景，可减少资源误操作和跨租户影响。
日志追踪
日志追踪允许用户在控制台中按指定 MQTT 客户端、主题、客户端 IP 或规则 ID 收集 debug 级别日志。相比为整个部署开启详细日志，该方式范围更精确，对正常业务的干扰更小，适合复现和定位单个客户端、主题或规则链路问题。
历史事件
历史事件记录近期的客户端连接、认证和订阅事件，可用于回溯以下问题：
- 客户端连接失败或异常断开
- 客户端认证失败
- 订阅创建失败或未生效
- 连接和订阅行为的时间线核查
BigQuery 数据集成
通过规则引擎筛选、处理 MQTT 消息，再由 BigQuery Sink 写入 Google BigQuery。适用于海量 IoT 数据的 SQL 分析、数据仓储和报表场景。
Snowflake Streaming 数据集成
通过 Snowflake Streaming Sink 将 MQTT 数据低延迟写入 Snowflake 表，适用于需要近实时数据入仓、分析和业务洞察的场景。
MQTT Source 增强
V6 的 MQTT Source 支持使用共享订阅主题减少重复消息，并支持配置 MQTT 5.0 订阅选项，例如“禁止本地转发”和“保留发布时 Retain 标志”，使远程 MQTT 服务桥接更灵活。
升级确认
请您在完全理解上述升级内容和潜在风险后，与我们联系确认升级时间。我们将全程为您提供技术支持，确保升级顺利完成。