# 自动订阅

::: tip

自动订阅功能在 Serverless 部署中不可用。

:::

自动订阅是 EMQX Cloud 支持的一项 MQTT 增强功能。当启用自动订阅功能后，客户端在成功连接时会自动订阅预定义的主题，而无需发送 `SUBSCRIBE` 请求，EMQX Cloud 会自动处理订阅过程。

在 EMQX 5.0 之前，该功能被称为代理订阅。

## 在控制台中配置自动订阅

1. 进入 EMQX Cloud 控制台，选择您的部署实例。在左侧菜单中，点击**监控** -> **自动订阅**。

2. 在**自动订阅**页面，点击右上角的**+ 添加**按钮。

3. 在**添加自动订阅**对话框的**主题**中，输入测试主题 `a/1`，其他设置保持默认。

   - **主题（Topic）**：输入客户端将自动订阅的主题。可以使用占位符动态构建主题，详细信息请参见[占位符](#占位符)。
   - **QoS**：指定主题的服务质量等级，可选值：`0`、`1`、`2`。
   - **禁止本地转发**：可选值：`False` 或 `True`。
   - **发布时状态保留**：指定是否保留发送到该主题的消息，可选值：`False` 或 `True`。
   - **保留消息处理**：可选值：`0`、`1`、`2`。

   <img src="./_assets/add_auto_subscription.png" alt="add_auto_subscription" style="zoom:80%;" />

   点击**确认**按钮，即可成功创建自动订阅主题 `a/1`。

现在，自动订阅功能已启用。新连接的客户端在连接至 EMQX Cloud 后，将自动订阅 `a/1` 主题。

## 使用 MQTTX 体验自动订阅

在[控制台中配置自动订阅](#在控制台中配置自动订阅)章节中，`a/1` 主题已配置为自动订阅主题。以下步骤演示客户端在连接至 EMQX 平台后自动订阅该主题的过程。

1. 打开 [MQTTX Web](https://mqttx.app/web-client#/recent_connections)。

2. 点击**新建连接**，创建一个发布端（Publisher）客户端，并进行以下配置：

   - **名称**：输入 `Demo`。
   - **主机**：输入**部署概览**页面 **MQTT 连接信息**部分的地址。
   - **端口**：输入 `8084`。
   - **用户名**和**密码**：在**访问控制** -> **认证**页面配置身份认证信息，并在此输入相应的认证信息。

   其他设置保持默认，点击**连接**。

3. 创建另一个 MQTT 客户端连接，命名为 `Subscriber`。

4. 在**连接**面板中选择 `Demo` 客户端，在**主题**输入框中输入 `a/1`，然后发送一条消息到该主题。

   - `Subscriber` 客户端无需手动订阅 `a/1`，即可自动接收该消息。
   - `Demo` 客户端也会收到该消息，因为它也是新连接的客户端，并自动订阅了 `a/1`。

   ::: tip

   在发布/订阅模式中，客户端既可以是消息的发送者，也可以是订阅者。

   :::

5. 返回 EMQX Cloud 控制台，在左侧菜单中点击**监控** -> **订阅**，可以看到两个客户端已自动订阅 `a/1` 主题。

   ![auto_subscribe_subscriptions](./_assets/auto_subscribe_subscriptions.png)

## 占位符

自动订阅功能支持**占位符**，用于**动态构建主题**。占位符格式为 `${}`，支持的变量如下：

- **`${clientid}`**：客户端 ID。
- **`${username}`**：客户端用户名。
- **`${host}`**：客户端连接到 EMQX Cloud 时的 IP 地址。

**示例**：
当客户端 ID 为 `emqx_c`，且配置的自动订阅主题为 `a/${clientid}`，则该客户端在连接 EMQX Cloud 后会自动订阅 `a/emqx_c` 主题。