@@ -692,12 +692,47 @@ nodepass "client://127.0.0.1:1080/app1.local:8080,app2.local:8080?mode=1"
692692
693693### Rotation Strategy
694694
695- NodePass employs a Round-Robin algorithm that combines failover and load balancing features :
695+ NodePass provides three load balancing strategies controlled by the ` lbs ` parameter :
696696
697+ ** Strategy 0 (Round-Robin):**
697698- ** Load Balancing** : After each successful connection establishment, automatically switches to the next target address for even traffic distribution
698699- ** Failover** : When a connection to an address fails, immediately tries the next address to ensure service availability
699700- ** Automatic Recovery** : Failed addresses are retried in subsequent rotation cycles and automatically resume receiving traffic after recovery
700701
702+ ** Strategy 1 (Optimal-Latency):**
703+ - ** Intelligent Routing** : Periodically probes targets and automatically selects the one with the lowest latency for connections.
704+ - ** Sticky Selection** : Once the optimal target is chosen, subsequent connections within the cycle preferentially use that target.
705+ - ** Automatic Filtering** : Unhealthy targets are automatically excluded from routing and re-evaluated only after recovery.
706+ - ** Failover** : If the optimal target fails, other targets are tried in order to ensure successful connections.
707+
708+ ** Strategy 2 (Primary-Backup):**
709+ - ** Priority-Based** : Always attempts to connect to the first address (primary); only uses backups when primary fails
710+ - ** Failover** : On primary failure, switches to the next available backup address
711+ - ** Scheduled Fallback** : Automatically attempts to return to primary address at fixed intervals
712+ - ** Intelligent Degradation** : On fallback failure, automatically uses the highest available priority address
713+
714+ Example configurations:
715+
716+ ``` bash
717+ # Round-robin (lbs=0, cycles through targets on each connection)
718+ nodepass " server://0.0.0.0:10101/backend1:8080,backend2:8080,backend3:8080?lbs=0"
719+
720+ # Optimal-latency (lbs=1, automatically routes to fastest target)
721+ nodepass " server://0.0.0.0:10101/backend1:8080,backend2:8080,backend3:8080?lbs=1"
722+
723+ # Primary-backup (lbs=2, primary priority and scheduled fallback)
724+ nodepass " server://0.0.0.0:10101/primary:8080,backup1:8080,backup2:8080?lbs=2"
725+
726+ # Custom fallback interval of 2 minutes
727+ export NP_FALLBACK_INTERVAL=2m
728+ nodepass " server://0.0.0.0:10101/main.com:443,spare1.com:443,spare2.com:443?lbs=2"
729+ ```
730+
731+ Choose the appropriate strategy based on your needs:
732+ - ** Use lbs=0** for even load distribution across all backends
733+ - ** Use lbs=1** for intelligent routing to the lowest latency target
734+ - ** Use lbs=2** for primary-backup scenarios with automatic failback
735+
701736### Use Cases
702737
703738Target address groups are suitable for the following scenarios:
@@ -743,6 +778,7 @@ NodePass allows flexible configuration via URL query parameters. The following t
743778| ` key ` | Custom key path | N/A | File path | O | X | O |
744779| ` dns ` | DNS cache TTL | ` 5m ` | ` 30s ` /` 5m ` /` 1h ` etc. | O | O | X |
745780| ` sni ` | Server Name Indication | ` none ` | Hostname | X | O | X |
781+ | ` lbs ` | Load balancing strategy | ` 0 ` | ` 0 ` /` 1 ` /` 2 ` | O | O | X |
746782| ` min ` | Minimum pool capacity | ` 64 ` | Positive integer | X | O | X |
747783| ` max ` | Maximum pool capacity | ` 1024 ` | Positive integer | O | X | X |
748784| ` mode ` | Run mode control | ` 0 ` | ` 0 ` /` 1 ` /` 2 ` | O | O | X |
@@ -787,6 +823,7 @@ NodePass behavior can be fine-tuned using environment variables. Below is the co
787823| ` NP_MIN_POOL_INTERVAL ` | Minimum interval between connection creations | 100ms | ` export NP_MIN_POOL_INTERVAL=200ms ` |
788824| ` NP_MAX_POOL_INTERVAL ` | Maximum interval between connection creations | 1s | ` export NP_MAX_POOL_INTERVAL=3s ` |
789825| ` NP_REPORT_INTERVAL ` | Interval for health check reports | 5s | ` export NP_REPORT_INTERVAL=10s ` |
826+ | ` NP_FALLBACK_INTERVAL ` | Primary-backup fallback interval | 5m | ` export NP_FALLBACK_INTERVAL=2m ` |
790827| ` NP_SERVICE_COOLDOWN ` | Cooldown period before restart attempts | 3s | ` export NP_SERVICE_COOLDOWN=5s ` |
791828| ` NP_SHUTDOWN_TIMEOUT ` | Timeout for graceful shutdown | 5s | ` export NP_SHUTDOWN_TIMEOUT=10s ` |
792829| ` NP_RELOAD_INTERVAL ` | Interval for cert reload/state backup | 1h | ` export NP_RELOAD_INTERVAL=30m ` |
0 commit comments