# EMQX Cloud V4 升级至 V6 指南

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

EMQX V6 在 V4 稳定高效的基础上进行了全面增强：优化了认证授权、监控指标、保留消息和数据集成能力，并新增或增强了命名空间、日志追踪、历史事件、BigQuery 数据集成和 Snowflake Streaming 数据集成等能力。您可以查阅[全新功能](https://docs.emqx.com/zh/cloud/latest/new_features.html)获取更多详细信息。

::: tip 适用范围

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

:::

## 升级前期准备

1. 请至少提前 3 天[联系我们](./feature/tickets.md)安排升级，我们将与您沟通升级注意事项及时间窗口。
2. 请全面阅读并理解本文档，尤其是不兼容变更部分。如有任何疑问，可随时通过工单与我们交流。
3. 我们的 SRE 团队将对您的部署进行全面评估。如存在特殊配置或潜在影响，将在“特殊情况说明”中反馈，您可据此决定是否继续升级。
4. 如果业务系统调用了 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 解析逻辑，请您在升级前完成兼容性验证。
  - 详细对比请参考：
    - [V4 API 文档](https://docs.emqx.com/zh/cloud/v4/api/dedicated.html)
    - [最新版本 API 文档](https://docs.emqx.com/zh/cloud/latest/api/dedicated.html)
- **外部扩展认证变更**：配置字段及查询响应要求发生变化，您需要按照[扩展认证](https://docs.emqx.com/zh/cloud/latest/deployments/custom_auth.html)文档进行修改。
- **数据集成部分兼容性**：
  - 未绑定任何规则的资源，升级后将不会被保留。请在升级前检查并确认这些资源是否仍需使用。
  - 规则下的失败备选动作将不会被保留。V6 使用新的数据集成架构，不再支持失败备选动作功能。
  - 空 Action，即未关联任何资源或动作的 Action，将在升级过程中自动删除。
  - 使用 `WHERE` 语句的部分 Rule SQL 与新版本不兼容，升级后可能需要手动调整规则语法。例如，在判断字段值是否存在时，V4 使用 `<> "undefined"`，新版本需要使用 `is_null` 进行判断。

## 升级过程影响评估

1. 升级过程预计持续 15–25 分钟，其中预计会出现约 **5–15 分钟** 的服务停机时间。
2. 系统将在升级期间创建持续 **2 小时** 的维护窗口。在维护窗口内，如因升级或兼容性问题导致服务不可用，不计入 SLA 可用性统计范围。
3. 升级期间所有客户端连接将断开 1–2 次，请确保客户端已配置自动重连机制。
4. 设置 `clean session = false` 的客户端会话将无法保留；客户端重连后将创建新会话。

## 升级后流程

### 升级后验证

1. EMQX Cloud SRE 团队将在升级后检查部署日志和指标是否正常。
2. 请您务必全面测试业务功能，特别是：
   - HTTP API 调用是否已更新为新路径及新的 API Key/Secret Key
   - HTTP API 返回结构与业务系统解析逻辑是否兼容
   - 默认及扩展认证授权是否正常
   - 数据集成连接器、规则、Source 和 Sink 是否正常运行
   - 客户端连接、订阅和消息收发是否正常
   - TLS 连接及自定义证书是否正常
3. 如发现任何异常，请立即与我们联系解决。

### 回滚机制

- 我们提供 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 文档](https://docs.emqx.com/zh/cloud/latest/api/dedicated.html)中的 Authentication 部分。

### 访问控制优化

- “认证鉴权”功能更名为“访问控制”。
- 升级将完整迁移默认认证授权的数据及扩展认证授权的配置。
- 外部认证授权功能细分为“外部认证”和“外部授权”，入口分别移至“客户端认证”和“客户端授权”中的“扩展认证”。
- 可手动调整认证链中各认证模块的优先顺序。
- 客户端授权中的默认授权规则可在客户端 ID、用户名和全部用户三个层级进行权限控制设置。同一客户端或用户名的授权信息将显示在页面中对应的标签下。

### 监控功能重构

- 原“监控界面”下的实时指标迁移至“指标界面”，可选择查看实时指标和时间轴数据。
- 原“监控界面”下的客户端管理与订阅管理独立放置在“监控”下的“客户端”和“订阅”界面。
- 新增“保留消息管理”界面，支持查询和删除保留消息。

### 数据集成架构升级

#### 规则、Source 和 Sink 架构调整

::: tip 兼容性说明

升级至 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 特有能力

::: 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 服务桥接更灵活。

## 升级确认

请您在完全理解上述升级内容和潜在风险后，与我们联系确认升级时间。我们将全程为您提供技术支持，确保升级顺利完成。