docs: add support for target address group to enable load balancing and high availability

Author: yosebyte

docs/en/configuration.md

@@ -264,6 +264,63 @@ nodepass "server://0.0.0.0:10101/0.0.0.0:8080?log=info&tls=1&proxy=1&rate=100"
 - The header format follows the HAProxy PROXY protocol v1 specification
 - If the target service doesn't support PROXY protocol, connections may fail or behave unexpectedly
 
+## Target Address Groups and Load Balancing
+
+NodePass supports configuring multiple target addresses to achieve high availability and load balancing. Target address groups are only applicable to the egress side (the final destination of traffic) and should not be used on the ingress side.
+
+### Target Address Group Configuration
+
+Target address groups are configured by separating multiple addresses with commas. NodePass automatically performs round-robin and failover across these addresses:
+
+```bash
+# Server with multiple backend targets (forward mode, mode=2)
+nodepass "server://0.0.0.0:10101/backend1.example.com:8080,backend2.example.com:8080,backend3.example.com:8080?mode=2&tls=1"
+
+# Client with multiple local services (single-end forwarding mode, mode=1)
+nodepass "client://127.0.0.1:1080/app1.local:8080,app2.local:8080?mode=1"
+```
+
+### Rotation Strategy
+
+NodePass employs a Round-Robin algorithm that combines failover and load balancing features:
+
+- **Load Balancing**: After each successful connection establishment, automatically switches to the next target address for even traffic distribution
+- **Failover**: When a connection to an address fails, immediately tries the next address to ensure service availability
+- **Automatic Recovery**: Failed addresses are retried in subsequent rotation cycles and automatically resume receiving traffic after recovery
+
+### Use Cases
+
+Target address groups are suitable for the following scenarios:
+
+- **High Availability Deployment**: Multiple backend servers for automatic failover
+- **Load Balancing**: Even traffic distribution across multiple backend instances
+- **Canary Releases**: Gradually shifting traffic to new service versions
+- **Geographic Distribution**: Selecting optimal paths based on network topology
+
+### Important Notes
+
+- **Egress Only**: Target address groups can only be configured at the final traffic destination
+  - ✓ Server forward mode (mode=2): `server://0.0.0.0:10101/target1:80,target2:80`
+  - ✓ Client single-end forwarding mode (mode=1): `client://127.0.0.1:1080/target1:80,target2:80`
+  - ✗ Tunnel addresses do not support: Do not use multi-address configuration for tunnel addresses
+  
+- **Address Format**: All addresses must use the same port or explicitly specify the port for each address
+- **Protocol Consistency**: All addresses in the group must support the same protocol (TCP/UDP)
+- **Thread Safety**: Rotation index uses atomic operations, supporting high-concurrency scenarios
+
+Example configurations:
+
+```bash
+# Correct example: Server with 3 backend web servers
+nodepass "server://0.0.0.0:10101/web1.internal:8080,web2.internal:8080,web3.internal:8080?mode=2&log=info"
+
+# Correct example: Client with 2 local database instances
+nodepass "client://127.0.0.1:3306/db-primary.local:3306,db-secondary.local:3306?mode=1&log=warn"
+
+# Incorrect example: Do not use multi-address for tunnel addresses (will cause parsing errors)
+# nodepass "server://host1:10101,host2:10101/target:8080"  # ✗ Wrong usage
+```
+
 ## URL Query Parameter Scope and Applicability
 
 NodePass allows flexible configuration via URL query parameters. The following table shows which parameters are applicable in server, client, and master modes:

docs/en/examples.md

@@ -235,9 +235,84 @@ This setup:
 - Enables developers to access environments without direct network exposure
 - Maps remote services to different local ports for easy identification
 
+## High Availability and Load Balancing
+
+### Example 14: Multi-Backend Server Load Balancing
+
+Use target address groups for even traffic distribution and automatic failover:
+
+```bash
+# Server side: Configure 3 backend web servers
+nodepass "server://0.0.0.0:10101/web1.internal:8080,web2.internal:8080,web3.internal:8080?mode=2&tls=1&log=info"
+
+# Client side: Connect to server
+nodepass "client://server.example.com:10101/127.0.0.1:8080?log=info"
+```
+
+This configuration:
+- Automatically distributes traffic across 3 backend servers using round-robin for load balancing
+- Automatically switches to other available servers when one backend fails
+- Automatically resumes sending traffic to recovered servers
+- Uses TLS encryption to secure the tunnel
+
+### Example 15: Database Primary-Replica Failover
+
+Configure primary and replica database instances for high availability access:
+
+```bash
+# Client side: Configure primary and replica database addresses (single-end forwarding mode)
+nodepass "client://127.0.0.1:3306/db-primary.local:3306,db-secondary.local:3306?mode=1&log=warn"
+```
+
+This setup:
+- Prioritizes connections to primary database, automatically switches to replica on primary failure
+- Single-end forwarding mode provides high-performance local proxy
+- Application requires no modification for transparent failover
+- Logs only warnings and errors to reduce output
+
+### Example 16: API Gateway Backend Pool
+
+Configure multiple backend service instances for an API gateway:
+
+```bash
+# Server side: Configure 4 API service instances
+nodepass "server://0.0.0.0:10101/api1.backend:8080,api2.backend:8080,api3.backend:8080,api4.backend:8080?mode=2&tls=1&rate=200&slot=5000"
+
+# Client side: Connect from API gateway
+nodepass "client://apigateway.example.com:10101/127.0.0.1:8080?rate=100&slot=2000"
+```
+
+This configuration:
+- 4 API service instances form backend pool with round-robin request distribution
+- Server limits bandwidth to 200 Mbps with maximum 5000 concurrent connections
+- Client limits bandwidth to 100 Mbps with maximum 2000 concurrent connections
+- Single instance failure doesn't affect overall service availability
+
+### Example 17: Geo-Distributed Services
+
+Configure multi-region service nodes to optimize network latency:
+
+```bash
+# Server side: Configure multi-region nodes
+nodepass "server://0.0.0.0:10101/us-west.service:8080,us-east.service:8080,eu-central.service:8080?mode=2&log=debug"
+```
+
+This setup:
+- Configures 3 service nodes in different regions
+- Round-robin algorithm automatically distributes traffic across regions
+- Debug logging helps analyze traffic distribution and failure scenarios
+- Suitable for globally distributed application scenarios
+
+**Target Address Group Best Practices:**
+- **Address Count**: Recommend configuring 2-5 addresses; too many increases failure detection time
+- **Health Checks**: Ensure backend services have their own health check mechanisms
+- **Port Consistency**: All addresses use the same port or explicitly specify port for each address
+- **Monitoring & Alerts**: Configure monitoring systems to track failover events
+- **Testing & Validation**: Verify failover and load balancing behavior in test environments before deployment
+
 ## PROXY Protocol Integration
 
-### Example 14: Load Balancer Integration with PROXY Protocol
+### Example 18: Load Balancer Integration with PROXY Protocol
 
 Enable PROXY protocol support for integration with load balancers and reverse proxies:
 
@@ -256,7 +331,7 @@ This configuration:
 - Compatible with HAProxy, Nginx, and other PROXY protocol aware services
 - Useful for maintaining accurate access logs and IP-based access controls
 
-### Example 15: Reverse Proxy Support for Web Applications
+### Example 19: Reverse Proxy Support for Web Applications
 
 Enable web applications behind NodePass to receive original client information:
 
@@ -280,7 +355,7 @@ This setup:
 - Supports compliance requirements for connection auditing
 - Works with web servers that support PROXY protocol (Nginx, HAProxy, etc.)
 
-### Example 16: Database Access with Client IP Preservation
+### Example 20: Database Access with Client IP Preservation
 
 Maintain client IP information for database access logging and security:
 
@@ -307,7 +382,7 @@ Benefits:
 
 ## Container Deployment
 
-### Example 17: Containerized NodePass
+### Example 21: Containerized NodePass
 
 Deploy NodePass in a Docker environment:
 
@@ -342,7 +417,7 @@ This configuration:
 
 ## Master API Management
 
-### Example 18: Centralized Management
+### Example 22: Centralized Management
 
 Set up a central controller for multiple NodePass instances:
 
@@ -379,7 +454,7 @@ This setup:
 - Offers a RESTful API for automation and integration
 - Includes a built-in Swagger UI at http://localhost:9090/api/v1/docs
 
-### Example 19: Custom API Prefix
+### Example 23: Custom API Prefix
 
 Use a custom API prefix for the master mode:
 
@@ -398,7 +473,7 @@ This allows:
 - Custom URL paths for security or organizational purposes
 - Swagger UI access at http://localhost:9090/admin/v1/docs
 
-### Example 20: Real-time Connection and Traffic Monitoring
+### Example 24: Real-time Connection and Traffic Monitoring
 
 Monitor instance connection counts and traffic statistics through the master API:
 

docs/zh/configuration.md

@@ -264,6 +264,63 @@ nodepass "server://0.0.0.0:10101/0.0.0.0:8080?log=info&tls=1&proxy=1&rate=100"
 - 头部格式遵循HAProxy PROXY协议v1规范
 - 如果目标服务不支持PROXY协议，将导致连接失败
 
+## 目标地址组与负载均衡
+
+NodePass支持配置多个目标地址以实现高可用性和负载均衡。目标地址组功能仅适用于出口端（流量最终到达的目的地），不应在入口端使用。
+
+### 目标地址组配置
+
+目标地址组通过逗号分隔多个地址来配置，NodePass会自动在这些地址之间进行轮询和故障转移：
+
+```bash
+# 服务端配置多个后端目标（正向模式，mode=2）
+nodepass "server://0.0.0.0:10101/backend1.example.com:8080,backend2.example.com:8080,backend3.example.com:8080?mode=2&tls=1"
+
+# 客户端配置多个本地服务（单端转发模式，mode=1）
+nodepass "client://127.0.0.1:1080/app1.local:8080,app2.local:8080?mode=1"
+```
+
+### 轮询策略
+
+NodePass采用轮询（Round-Robin）算法，结合故障转移和负载均衡特性：
+
+- **负载均衡**：每次成功建立连接后，自动切换到下一个目标地址，实现流量均匀分布
+- **故障转移**：当某个地址连接失败时，立即尝试下一个地址，确保服务高可用
+- **自动恢复**：失败的地址会在轮询周期中重新尝试，故障恢复后自动接入流量
+
+### 使用场景
+
+目标地址组适用于以下场景：
+
+- **高可用性部署**：多个后端服务器实现故障自动切换
+- **负载均衡**：流量均匀分布到多个后端实例
+- **灰度发布**：逐步将流量切换到新版本服务
+- **地域分布**：根据网络拓扑选择最优路径
+
+### 重要说明
+
+- **仅适用于出口**：目标地址组只能配置在流量的最终目的地
+  - ✓ 服务端正向模式（mode=2）：`server://0.0.0.0:10101/target1:80,target2:80`
+  - ✓ 客户端单端转发模式（mode=1）：`client://127.0.0.1:1080/target1:80,target2:80`
+  - ✗ 隧道地址不支持：不要在隧道地址使用多地址配置
+  
+- **地址格式**：所有地址必须使用相同的端口或明确指定每个地址的端口
+- **协议一致性**：地址组中的所有地址必须支持相同的协议（TCP/UDP）
+- **线程安全**：轮询索引使用原子操作，支持高并发场景
+
+示例配置：
+
+```bash
+# 正确示例：服务端配置3个后端Web服务器
+nodepass "server://0.0.0.0:10101/web1.internal:8080,web2.internal:8080,web3.internal:8080?mode=2&log=info"
+
+# 正确示例：客户端配置2个本地数据库实例
+nodepass "client://127.0.0.1:3306/db-primary.local:3306,db-secondary.local:3306?mode=1&log=warn"
+
+# 错误示例：不要在隧道地址使用多地址（会导致解析错误）
+# nodepass "server://host1:10101,host2:10101/target:8080"  # ✗ 错误用法
+```
+
 ## URL查询参数配置及作用范围
 
 NodePass支持通过URL查询参数进行灵活配置，不同参数在 server、client、master 模式下的适用性如下表：
@@ -282,7 +339,6 @@ NodePass支持通过URL查询参数进行灵活配置，不同参数在 server
 | `slot`    | 最大连接数限制       | `65536`   |   O    |   O    |   X    |
 | `proxy`   | PROXY协议支持        | `0`       |   O    |   O    |   X    |
 
-
 - O：参数有效，推荐根据实际场景配置
 - X：参数无效，忽略设置