Merge pull request #2785 from emqx/20241219-r58-mqtt-static-clientid

feat: static clientids for MQTT connector

en_US/data-integration/data-bridge-mqtt.md

@@ -47,9 +47,9 @@ Before creating an MQTT Broker data integration, you need to obtain the connecti
 
 The data integration provides good compatibility and support for EMQX or other standard MQTT servers. If you need to connect to other types of MQTT services, you can refer to their relevant documentation to obtain the connection information. Generally, most IoT platforms provide standard MQTT access methods, and you can convert device information into the aforementioned MQTT connection information based on their guidance.
 
-:::tip Note 
+:::tip Note
 
-When EMQX is running in cluster mode or when a connection pool is enabled, using the same client ID to connect multiple nodes to the same MQTT service usually leads to device conflicts. Therefore, the MQTT message bridge currently does not support setting a fixed client ID. 
+When EMQX is running in cluster mode or when a connection pool is enabled, using the same client ID to connect multiple nodes to the same MQTT service usually leads to device conflicts. Therefore, the MQTT message bridge currently does not support setting a fixed client ID.
 
 :::
 
@@ -63,7 +63,7 @@ This section guides you on how to configure a connection with a remote MQTT serv
 4. Enter a **name** for the connector, which must be a combination of upper/lower case letters and numbers, for example, `my_mqtt_bridge`.
 5. Configure the connection information:
    - **MQTT Broker**: Only supports MQTT over TCP/TLS. Set this to `broker.emqx.io:1883`.
-   - **ClientID Prefix**: This can be left blank. In actual use, specifying a client ID prefix can facilitate client management. EMQX will automatically generate client IDs based on the client ID prefix and the size of the connection pool.
+   - **ClientID Prefix**: This can be left blank. In actual use, specifying a client ID prefix can facilitate client management. EMQX will automatically generate client IDs based on the client ID prefix and the size of the connection pool. For more information, see [Connection Pool and Client ID Generation Rules](#connection-pool-and-client-id-generation-rules).
    - **Username** and **Password**: These can be left blank, as authentication is not required for this server.
 
 Leave the other configurations as default and click the **Create** button to complete the creation of the Connector. The Connector can be used for both Sink and Source. Next, you can create data bridge rules based on this Connector.
@@ -93,6 +93,20 @@ To address this issue, from version 5.7.1 onwards, EMQX has implemented the foll
   - **Prefix up to 19 bytes**: The prefix is preserved, and the remainder of the client ID is hashed into a 4-byte space capping the length within 23 bytes.
   - **Prefix of 20 bytes or more**: EMQX will use the configured prefix, and no longer attempts to shorten the client ID.
 
+### Configure Static Client IDs
+
+In some use cases, you may only have a finite set of client IDs to use in an integration. In this case, it is possible to assign static client ID sets to individual nodes while configuring the connector. To configure static client IDs, provide a list of client IDs for each node in your EMQX cluster during the Connector setup. Below is an example configuration:
+
+| Node            | Client IDs               |
+| :-------------- | ------------------------ |
+| `emqx@10.0.0.1` | `clientid1`, `clientid3` |
+| `emqx@10.0.0.2` | `clientid2`              |
+| `emqx@10.0.0.3` | `clientid4`, `clientid5` |
+
+Static client IDs can only be configured through the configuration file and are not available for setup through the Dashboard UI. You can define the `static_clientids` parameter for each node individually in configuration files.
+
+If static client IDs are configured, only MQTT connections using these client IDs will be started. Any configurations for dynamic client IDs, such as `pool_size` or `clientid_prefix`, will not take effect.
+
 ## Create a Rule with MQTT Broker Sink
 
 This section demonstrates how to create a rule for specifying data to be forwarded to a remote MQTT service.
@@ -101,7 +115,7 @@ This section demonstrates how to create a rule for specifying data to be forward
 
 2. Click **Create** at the top right of the page.
 
-3. Enter the rule ID `my_rule`. 
+3. Enter the rule ID `my_rule`.
 
 4. In the **SQL Editor**, enter the rule to store MQTT messages from the `t/#` topic to the remote MQTT server. The rule SQL is as follows:
 
@@ -186,7 +200,7 @@ This section demonstrates how to create a rule for forwarding data from a remote
 
 8. Configure the Source information to complete the subscription from the external MQTT service to EMQX:
 
-   - **Topic**: The subscription topic, supporting the use of `+` and `#` wildcards. 
+   - **Topic**: The subscription topic, supporting the use of `+` and `#` wildcards.
 
      ::: tip
 
@@ -266,4 +280,3 @@ You can use [MQTTX CLI](https://mqttx.app/zh/cli) to test the configured rule fo
    [2024-1-31] [16:49:22] › topic: sub/f/1
    payload: I'm from broker.emqx.io
    ```
-

zh_CN/data-integration/data-bridge-mqtt.md

@@ -66,7 +66,7 @@ EMQX 运行在集群模式下或启用连接池时，多个节点使用相同的
 5. 填写连接相关配置：
 
    - **MQTT 服务地址**：仅支持 MQTT over TCP/TLS，此处设为 `broker.emqx.io:1883`。
-   - **客户端 ID 前缀**：此处可以留空，实际使用中，指定客户端 ID 前缀可以便于客户端管理，EMQX 会根据客户端 ID 前缀和连接池大小自动生成客户端 ID。
+   - **客户端 ID 前缀**：此处可以留空，实际使用中，指定客户端 ID 前缀可以便于客户端管理，EMQX 会根据客户端 ID 前缀和连接池大小自动生成客户端 ID，具体规则，参考[连接池与客户端 ID 生成规则](#连接池与客户端-id-生成规则)。
    - **用户名**和**密码**：此处可以留空，该服务器不需要认证。
 
 其他配置保持默认即可，点击**创建**按钮完成连接器创建。连接器能够同时用于 Sink 和 Source。接下来，您可以基于此连接器创建数据桥接规则。
@@ -96,6 +96,20 @@ myprefix:foo2bd61c44:1
   - **前缀不超过 19 个字节**：保留前缀，并将其余部分散列到 4 字节以内，总长度限制在 23 个字节。
   - **前缀为 20 个或更多字节**：EMQX 将完全使用配置的前缀，不再尝试缩短客户端 ID。
 
+### 配置静态客户端 ID
+
+在某些使用场景中，您可能只需要在集成中使用有限的一组客户端 ID。在这种情况下，可以在配置连接器时，将静态客户端 ID 分配给集群中每个节点。以下是一个示例配置：
+
+| 节点            | 客户端 ID                |
+| --------------- | ------------------------ |
+| `emqx@10.0.0.1` | `clientid1`, `clientid3` |
+| `emqx@10.0.0.2` | `clientid2`              |
+| `emqx@10.0.0.3` | `clientid4`, `clientid5` |
+
+静态客户端 ID 只能通过配置文件进行设置，无法通过 Dashboard UI 配置。您可以在配置文件中为每个节点单独定义 `static_clientids` 参数。
+
+如果配置了静态客户端 ID，则只有使用这些客户端 ID 的 MQTT 连接会被启动。任何动态客户端 ID 的配置（例如 `pool_size` 或 `clientid_prefix`）将不再生效。
+
 ## 创建 MQTT 服务 Sink 规则
 
 本节演示了如何创建一条规则来指定需要转发至远程 MQTT 服务的数据。