update(shared subscription): Add dispatch strategy

dir.yaml

@@ -835,8 +835,8 @@
    title_cn: 版本发布历史
    collapsed: true
    children:
-       - title_en: EMQX Enterprise Release Notes
-         title_cn: EMQX 企业版版本发布历史
+       - title_en: Release Notes
+         title_cn: 版本发布历史
          collapsed: true
          path: changes/all-changes-ee
          children:

en_US/messaging/mqtt-shared-subscription.md

@@ -13,7 +13,7 @@ You can use client tools to connect to EMQX and try this messaging service. This
 
 ## Shared Subscription for Groups
 
-You can enable a shared subscription for groups of subscribers by adding the prefixed `$share/<group-name>` to the original topic. The group name can be any string. EMQX forwards messages to different groups at the same time and subscribers belonging to the same group receive messages with load balancing.
+You can enable a shared subscription for groups of subscribers by adding the prefixed `$share/<group-name>` to the original topic. The group name can be any string. EMQX forwards messages to different groups at the same time, and subscribers belonging to the same group receive messages with load balancing.
 
 For example, if subscribers `s1`, `s2`, and `s3` are members of group `g1`, subscribers `s4` and `s5` are members of group `g2`, and all subscribers subscribe to the original topic `t1`. The shared subscription topics must be `$share/g1/t1` and `$share/g2/t1`. When EMQX publishes a message `msg1` to the original topic `t1`:
 
@@ -37,6 +37,46 @@ When clients use MQTT v5, it is a good practice to set a short session expiry in
 
 For more information on the persistent session, see [MQTT Persistent Session and Clean Session Explained](https://www.emqx.com/en/blog/mqtt-session).
 
+## Configure Shared Subscription Strategy
+
+EMQX allows fine-grained control over how messages are distributed to subscribers within a shared subscription group. This behavior is defined by the Shared Subscription Strategy, which determines the algorithm used to select the subscriber that receives each message. By tuning this strategy, you can optimize message flow for different workloads, client deployment patterns, and cluster topologies.
+
+### Shared Subscription Dispatch Strategy
+
+The Shared Subscription Dispatch Strategy determines how EMQX distributes messages among subscribers within a shared subscription group.
+
+You can configure this using the `mqtt.shared_subscription_strategy` option.
+
+| Strategy                    | Description                                                  |
+| --------------------------- | ------------------------------------------------------------ |
+| **`random`**                | Randomly selects one subscriber in the group for each message. This provides even distribution overall but may not be deterministic. |
+| **`round_robin`** (default) | Messages are delivered to subscribers in turn within each shared subscription group. EMQX maintains a separate round-robin position for each publishing client, so messages from different publishers may still be delivered to the same subscriber consecutively. |
+| **`round_robin_per_group`** | Similar to `round_robin`, but the round-robin progress is tracked independently on each node. This means messages published from different nodes in a cluster may be delivered to the same subscriber. Useful for clustered deployments where each node handles separate publisher loads. |
+| **`sticky`**                | Continuously dispatches messages to the same subscriber until the subscriber disconnects or its session ends. This strategy helps avoid unnecessary re-processing or cross-client state sharing by keeping message flows on a single subscriber whenever possible.<br />The initial subscriber is determined by the `mqtt.shared_subscription_initial_sticky_pick` setting. |
+| **`local`**                 | Prefers delivering messages to subscribers connected to the same node where the message is processed. If no local subscribers exist, EMQX randomly selects a subscriber from the cluster. This reduces inter-node traffic and latency. |
+| **`hash_clientid`**         | Uses a hash of the publisher’s Client ID to consistently route all messages from that publisher to the same subscriber. This strategy provides deterministic routing for per-client data streams. |
+| **`hash_topic`**            | Uses a hash of the publishing topic to route all messages with the same topic name to the same subscriber. Useful for topic-based message sharding and stateful processing. |
+
+> EMQX tracks dispatch state, such as round-robin positions or sticky subscriber assignments, per publisher connection. When a publishing client disconnects and reconnects, this state is reset and reinitialized.
+
+### Initial Sticky Pick
+
+When the shared subscription strategy is set to `sticky`, EMQX determines the initial subscriber to receive the messages based on `mqtt.shared_subscription_initial_sticky_pick`.
+
+This setting controls whether EMQX prefers local subscribers, uses hashing for deterministic routing, or selects randomly.
+
+### Configure Dispatch Strategy via Dashboard
+
+You can configure these options in the EMQX Dashboard:
+
+1. Navigate to **Management** -> **MQTT Settings** -> **General**.
+2. Ensure **Allowed Shared Subscription** is enabled.
+3. Select the desired **Shared Subscription Strategy** from the dropdown list. The default option is `round_robin`.
+4. If the selected strategy is `sticky`, choose an appropriate **Shared Subscription Initial Sticky Pick** method. The default option is `random`.
+5. Click **Save Changes**.
+
+These settings take effect immediately and allow EMQX to adjust its message dispatching logic without requiring client-side configuration changes.
+
 ## Try Shared Subscription with MQTTX Desktop
 
 :::tip Prerequisites

zh_CN/messaging/mqtt-shared-subscription.md

@@ -35,6 +35,46 @@ EMQX 实现了 MQTT 的共享订阅功能。共享订阅是一种订阅模式，
 
 更多关于持久会话功能的信息，参阅 [MQTT 持久会话与 Clean Session 详解](https://www.emqx.com/zh/blog/mqtt-session)。
 
+## 配置共享订阅策略
+
+EMQX 允许对共享订阅组内消息的分发方式进行精细控制。共享订阅策略用于定义 EMQX 在多个订阅者之间选择消息接收者所采用的算法。通过调整该策略，您可以根据不同的工作负载、客户端部署模式以及集群拓扑来优化消息流转效果。
+
+### 共享订阅调度策略
+
+共享订阅调度策略定义了 EMQX 在共享订阅组中如何选择具体的订阅者来接收消息。
+
+您可以通过配置项 `mqtt.shared_subscription_strategy` 来设置该策略。
+
+| 策略                        | 说明                                                         |
+| --------------------------- | ------------------------------------------------------------ |
+| **`random`**                | 在每次消息分发时，从共享订阅组内随机选择一个订阅者，实现整体上较为均匀但不可预测的消息分发。 |
+| **`round_robin`**（默认）   | 在共享订阅组内按顺序轮询将消息分发给订阅者。EMQX 为每个发布客户端独立维护轮询进度，因此来自不同发布者的消息可能连续被投递到同一个订阅者。 |
+| **`round_robin_per_group`** | 与 `round_robin` 类似，但轮询进度在每个节点上独立维护。这意味着来自集群中不同节点的消息可能仍会被投递到同一个订阅者。该策略适用于多节点集群场景，每个节点可独立处理部分发布者负载。 |
+| **`sticky`**                | 在订阅者保持连接的情况下，消息会持续分发到同一个订阅者，直到该订阅者断开连接或会话结束。此策略通过将消息流保持在单一订阅者上，避免重复处理或跨订阅者共享状态。<br />首次选择的订阅者由配置项 `mqtt.shared_subscription_initial_sticky_pick` 决定。 |
+| **`local`**                 | 优先将消息分发给当前节点上的本地订阅者。如果没有本地订阅者，EMQX 将随机选择集群中其他节点的订阅者，从而降低跨节点流量与延迟。 |
+| **`hash_clientid`**         | 基于发布客户端的 Client ID 计算哈希值，将同一发布者的所有消息始终路由到同一个订阅者，实现确定性、稳定的消息路由。该策略适用于按客户端维度进行有状态处理的场景。 |
+| **`hash_topic`**            | 基于发布主题名称计算哈希值，将相同主题的所有消息路由到同一个订阅者。该策略适用于基于主题分片（sharding）或需要稳定消息处理的场景。 |
+
+> EMQX 会为每个发布客户端独立维护分发状态（例如轮询进度或 Sticky 订阅者分配情况）。当发布客户端断开并重新连接后，该状态会被重置并重新初始化，消息分发将重新开始。
+
+### 初始 Sticky 选择策略
+
+当共享订阅策略设置为 `sticky` 时，EMQX 需要确定应将首次消息流关联到哪个订阅者。EMQX 会根据配置项 `mqtt.shared_subscription_initial_sticky_pick` 来确定首次接收消息的订阅者。
+
+该设置可控制 EMQX 是优先选择本地订阅者、基于哈希算法进行确定性选择，还是随机选择订阅者。
+
+### 通过 Dashboard 配置策略
+
+您可以通过 EMQX Dashboard 配置这些策略：
+
+1. 导航至 **管理** -> **MQTT 配置** -> **通用**。
+2. 确保**允许共享订阅**已启用。
+3. 从下拉列表中选择所需的**共享订阅策略**。默认为 `round_robin`。
+4. 如果选择了 `sticky`，需配置合适的**共享订阅初始 Sticky 选择策略**。默认为 `random`。
+5. 点击**保存修改**。
+
+这些设置会立即生效，使 EMQX 能够调整消息调度逻辑，而无需客户端进行任何额外配置。
+
 ## 使用 MQTTX Desktop 尝试共享订阅
 
 :::tip 前置准备