# EMQX Cloud V5 升级至 V6 指南

作为 EMQX 专有版用户，您可以将 EMQX 从 V5 版本升级到 V6 版本。想要查看当前的 EMQX 版本号，可以在部署详情页点击**设置**按钮进入部署信息页面。

EMQX V6 延续 V5 的核心架构和使用方式，并新增或增强了命名空间、日志追踪、历史事件、BigQuery 数据集成、Snowflake Streaming 数据集成和 MQTT Source 等能力。您可以查阅[全新功能](https://docs.emqx.com/zh/cloud/latest/new_features.html)获取更多详细信息。

::: tip 适用范围

EMQX V6 仅支持专有版和弹性专有版 Broker 部署。Serverless 部署不支持选择 EMQX 版本。

:::

## 升级前期准备

1. 请确认客户端已配置自动重连机制，并为升级期间的短暂连接中断做好准备。
2. 建议记录升级前的关键业务基线，包括在线客户端数量、消息收发速率、认证成功率、规则及数据集成状态，便于升级后核对。
3. 我们的 SRE 团队将在升级前检查部署状态和特殊配置。如发现可能影响升级的情况，将提前与您沟通。

## 数据迁移与保留内容

升级过程中，我们将为您保留以下配置：

- MQTT 连接地址及端口
- 认证及授权配置
- 数据集成配置，包括连接器、规则、Source 和 Sink
- TLS 证书信息
- 保留消息
- 网络管理相关配置，包括 NAT 网关、内部接入点、PrivateLink 和 VPC Peering

V5 升级至 V6 不要求像 V4 升级那样进行大范围 API、认证授权和数据集成架构兼容性改造。对于通过工单配置的特殊参数，仍应以 SRE 团队的升级前检查结果为准。

## 升级过程影响

1. 升级过程预计持续 15–25 分钟，升级期间服务不停机。
2. 系统将在升级期间创建持续 **2 小时** 的维护窗口。在维护窗口内，如因升级导致服务不可用，不计入 SLA 可用性统计范围。
3. 升级期间可能会出现 2–3 次短时断连。如果设备已配置自动重连，将不会影响正常使用。
4. **请注意，如果客户端 `clean session` 为 `false`，原有会话将在升级后被丢弃。如需保留会话，请提前告知我们。**

## 升级后流程

### 升级后验证

1. EMQX Cloud SRE 团队将在升级后检查部署日志和指标是否正常。
2. 请您根据升级前记录的业务基线完成验证，重点检查：
   - 客户端是否能够自动重连
   - 客户端认证和授权是否正常
   - 订阅是否恢复，消息收发是否正常
   - 规则、连接器、Source 和 Sink 是否正常运行
   - TLS 连接及自定义证书是否正常
   - 监控指标和告警是否符合预期
3. 如发现任何异常，请立即与我们联系解决。

### 回滚机制

- 我们提供 24 小时的回滚窗口，可在确认前从 V6 回滚至 V5。
- 回滚过程预计持续 15–25 分钟，回滚期间服务不停机。
- 回滚期间所有客户端连接将断开 1–2 次。
- 持久会话状态无法保留，客户端重连后将创建新会话。

## V6 版本核心功能介绍

### V6 特有能力

::: tip 提示

以下功能仅适用于支持 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 服务桥接更灵活。

## 升级确认

请您确认升级时间窗口，并确保相关业务和运维人员在升级期间保持可联系。我们将全程为您提供技术支持，确保升级顺利完成。