feat(pd): add optional periodic partition leader balancing

hugegraph-pd/docs/architecture.md

@@ -399,11 +399,14 @@ Automated background tasks for cluster maintenance.
 **Scheduled Tasks**:
 - **Partition Patrol**: Periodically scan all partitions for health issues
 - **Balance Check**: Detect imbalanced partition distribution
+- **Leader Balance** (optional): Move partition leaders back toward an even spread across Stores
 - **Store Monitor**: Check store health and trigger failover
 - **Metrics Collection**: Aggregate cluster metrics
 
 **Configuration**:
 - `pd.patrol-interval`: Patrol interval in seconds (default: 1800)
+- `pd.balance-leader-enable`, `pd.balance-leader-interval`, `pd.balance-leader-max-skew`:
+  periodic leader balancing, off by default (see [configuration](configuration.md#pd-core-settings))
 
 #### KvService
 

hugegraph-pd/docs/configuration.md

@@ -183,6 +183,9 @@ pd:
   patrol-interval: 1800             # Partition rebalancing interval (seconds)
   initial-store-count: 1            # Minimum stores for cluster availability
   initial-store-list: 127.0.0.1:8500  # Auto-activated stores
+  balance-leader-enable: false      # Periodic partition leader balancing
+  balance-leader-interval: 300      # Seconds between leader balance checks
+  balance-leader-max-skew: 2        # Tolerated leader count spread across stores
 ```
 
 | Parameter | Type | Default | Description |
@@ -191,6 +194,9 @@ pd:
 | `pd.patrol-interval` | Integer | `1800` | Interval (in seconds) for partition health patrol and automatic rebalancing. Lower values = more frequent checks. |
 | `pd.initial-store-count` | Integer | `1` | Minimum number of Store nodes required for cluster to be operational. Set to expected initial store count. |
 | `pd.initial-store-list` | String | `127.0.0.1:8500` | Comma-separated list of Store gRPC addresses to auto-activate on startup. Useful for bootstrapping. |
+| `pd.balance-leader-enable` | Boolean | `false` | Run partition leader balancing periodically on the PD leader. When off, leaders move back only through a manual call: `/v1/task/balanceLeaders`, `/v1/balanceLeaders` or the `balanceLeaders` gRPC call. |
+| `pd.balance-leader-interval` | Integer | `300` | Seconds between periodic leader balance checks. Only read when `pd.balance-leader-enable` is `true`. Must be positive; otherwise PD logs a warning and does not run periodic balancing. |
+| `pd.balance-leader-max-skew` | Integer | `2` | A check balances leaders only when the most leaders on one store minus the fewest on another exceeds this value, and the leaders are not already where the balancer would put them (uneven shard placement can leave its best spread above this value). Must be `0` or more; otherwise PD logs a warning and does not run periodic balancing. |
 
 **Production Recommendations**:
 - `pd.data-path`: Use dedicated SSD with at least 50GB free space
@@ -199,6 +205,25 @@ pd:
   - Production: `1800` (30 minutes) to reduce overhead
   - Large clusters: `3600` (1 hour)
 - `pd.initial-store-count`: Set to expected initial store count (e.g., `3` for 3 stores)
+- `pd.balance-leader-enable`: After a Store restarts, its raft groups keep the leaders they elected
+  on the surviving Stores. Enable this so PD moves leaders back without a manual `balanceLeaders`
+  call. A check is skipped while any shard group is not in the `Normal` state, has sent no
+  partition heartbeat in the last 30 seconds, or has a replica that is not a Leader or Follower (a
+  membership change in progress); while a Store that holds a shard is not in the active-store list,
+  which it leaves `store.keepAlive-timeout` after its last heartbeat; and while a split, move or
+  shard balance task is running. A planned transfer is not sent if this PD is no longer the leader,
+  if its shard group changed after the check, if the target Store's persisted state is not `Up`
+  (for example `Exiting` while PD drains it, though it stays in the active-store list), or if the
+  target's applied index trails the leader's by more than an estimated 1000 entries. The indexes
+  come from each Store's last heartbeat, and a transfer is not sent when the target's or the leader
+  Store's heartbeat is more than 60 seconds old (two Store heartbeats). PD estimates the leader's
+  index at the time of the target's report from its average rate since an earlier heartbeat of the
+  same leader Store, which it keeps across checks that see the same heartbeat; when there is no
+  such sample, PD compares the indexes as reported. The leader stays where it is until a later
+  check. The estimate is best effort, not a strict bound: a write burst late in the interval can
+  keep a caught-up Store waiting for later checks, and a burst early in it can let a Store that
+  fell behind through, in which case JRaft ends the transfer after its timeout and the old leader
+  takes writes again.
 
 ### Store Management Settings