From 62adee55afecd73454538a2936a5872f58b59217 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9D=90=98=F0=9D=90=A8=F0=9D=90=AC=F0=9D=90=9E?= =?UTF-8?q?=F0=9D=90=9B=F0=9D=90=B2=F0=9D=90=AD=F0=9D=90=9E?= <54016243+yosebyte@users.noreply.github.com> Date: Mon, 16 Jun 2025 03:35:42 +0000 Subject: [PATCH 1/4] refactor: rename variables for clarity in data exchange logging --- internal/common.go | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/internal/common.go b/internal/common.go index ff78acda..d0b2a17e 100644 --- a/internal/common.go +++ b/internal/common.go @@ -456,10 +456,10 @@ func (c *Common) commonTCPLoop() { c.logger.Debug("Starting exchange: %v <-> %v", remoteConn.LocalAddr(), targetConn.LocalAddr()) // 交换数据 - bytesReceived, bytesSent, _ := conn.DataExchange(remoteConn, targetConn) + rx, tx, _ := conn.DataExchange(remoteConn, targetConn) // 交换完成，广播统计信息 - c.logger.Event("Exchange complete: TRAFFIC_STATS|TCP_RX=%v|TCP_TX=%v|UDP_RX=0|UDP_TX=0", bytesReceived, bytesSent) + c.logger.Event("Exchange complete: TRAFFIC_STATS|TCP_RX=%v|TCP_TX=%v|UDP_RX=0|UDP_TX=0", rx, tx) }(targetConn) } } @@ -618,10 +618,10 @@ func (c *Common) commonTCPOnce(id string) { c.logger.Debug("Starting exchange: %v <-> %v", remoteConn.LocalAddr(), targetConn.LocalAddr()) // 交换数据 - bytesReceived, bytesSent, _ := conn.DataExchange(remoteConn, targetConn) + rx, tx, _ := conn.DataExchange(remoteConn, targetConn) // 交换完成，广播统计信息 - c.logger.Event("Exchange complete: TRAFFIC_STATS|TCP_RX=%v|TCP_TX=%v|UDP_RX=0|UDP_TX=0", bytesReceived, bytesSent) + c.logger.Event("Exchange complete: TRAFFIC_STATS|TCP_RX=%v|TCP_TX=%v|UDP_RX=0|UDP_TX=0", rx, tx) } // commonUDPOnce 共用处理单个UDP请求 @@ -743,10 +743,10 @@ func (c *Common) singleTCPLoop() error { c.logger.Debug("Starting exchange: %v <-> %v", tunnelConn.LocalAddr(), targetConn.LocalAddr()) // 交换数据 - bytesReceived, bytesSent, _ := conn.DataExchange(tunnelConn, targetConn) + rx, tx, _ := conn.DataExchange(tunnelConn, targetConn) // 交换完成，广播统计信息 - c.logger.Event("Exchange complete: TRAFFIC_STATS|TCP_RX=%v|TCP_TX=%v|UDP_RX=0|UDP_TX=0", bytesReceived, bytesSent) + c.logger.Event("Exchange complete: TRAFFIC_STATS|TCP_RX=%v|TCP_TX=%v|UDP_RX=0|UDP_TX=0", rx, tx) }(tunnelConn) } } From d3a2ad9cc275e3a2c3cd6fde197b22bd049d1e1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9D=90=98=F0=9D=90=A8=F0=9D=90=AC=F0=9D=90=9E?= =?UTF-8?q?=F0=9D=90=9B=F0=9D=90=B2=F0=9D=90=AD=F0=9D=90=9E?= <54016243+yosebyte@users.noreply.github.com> Date: Mon, 16 Jun 2025 08:53:40 +0000 Subject: [PATCH 2/4] refactor: update pool capacity handling in client and common packages --- internal/client.go | 9 +++++---- internal/common.go | 35 +++++++++++++++++++++++++++-------- 2 files changed, 32 insertions(+), 12 deletions(-) diff --git a/internal/client.go b/internal/client.go index 55268171..7c1474bb 100644 --- a/internal/client.go +++ b/internal/client.go @@ -33,6 +33,7 @@ func NewClient(parsedURL *url.URL, logger *logs.Logger) *Client { }, tunnelName: parsedURL.Hostname(), } + client.getPoolCapacity(parsedURL) client.getAddress(parsedURL) return client } @@ -80,8 +81,8 @@ func (c *Client) start() error { // 初始化连接池 c.tunnelPool = pool.NewClientPool( - minPoolCapacity, - maxPoolCapacity, + c.minPoolCapacity, + c.maxPoolCapacity, minPoolInterval, maxPoolInterval, reportInterval, @@ -102,8 +103,8 @@ func (c *Client) start() error { // 初始化连接池 c.tunnelPool = pool.NewClientPool( - minPoolCapacity, - maxPoolCapacity, + c.minPoolCapacity, + c.maxPoolCapacity, minPoolInterval, maxPoolInterval, reportInterval, diff --git a/internal/common.go b/internal/common.go index d0b2a17e..f923fd17 100644 --- a/internal/common.go +++ b/internal/common.go @@ -38,6 +38,8 @@ type Common struct { targetUDPConn *net.UDPConn // 目标UDP连接 targetUDPSession sync.Map // 目标UDP会话 tunnelPool *pool.Pool // 隧道连接池 + minPoolCapacity int // 最小池容量 + maxPoolCapacity int // 最大池容量 semaphore chan struct{} // 信号量通道 bufReader *bufio.Reader // 缓冲读取器 signalChan chan string // 信号通道 @@ -49,17 +51,15 @@ type Common struct { // 配置变量，可通过环境变量调整 var ( semaphoreLimit = getEnvAsInt("NP_SEMAPHORE_LIMIT", 1024) // 信号量限制 - minPoolCapacity = getEnvAsInt("NP_MIN_POOL_CAPACITY", 16) // 最小池容量 - maxPoolCapacity = getEnvAsInt("NP_MAX_POOL_CAPACITY", 1024) // 最大池容量 - udpDataBufSize = getEnvAsInt("NP_UDP_DATA_BUF_SIZE", 8192) // UDP数据缓冲区大小 - udpReadTimeout = getEnvAsDuration("NP_UDP_READ_TIMEOUT", 15*time.Second) // UDP读取超时 - udpDialTimeout = getEnvAsDuration("NP_UDP_DIAL_TIMEOUT", 15*time.Second) // UDP拨号超时 - tcpReadTimeout = getEnvAsDuration("NP_TCP_READ_TIMEOUT", 15*time.Second) // TCP读取超时 - tcpDialTimeout = getEnvAsDuration("NP_TCP_DIAL_TIMEOUT", 15*time.Second) // TCP拨号超时 + udpDataBufSize = getEnvAsInt("NP_UDP_DATA_BUF_SIZE", 8192) // UDP缓冲区大小 + udpReadTimeout = getEnvAsDuration("NP_UDP_READ_TIMEOUT", 10*time.Second) // UDP读取超时 + udpDialTimeout = getEnvAsDuration("NP_UDP_DIAL_TIMEOUT", 10*time.Second) // UDP拨号超时 + tcpReadTimeout = getEnvAsDuration("NP_TCP_READ_TIMEOUT", 10*time.Second) // TCP读取超时 + tcpDialTimeout = getEnvAsDuration("NP_TCP_DIAL_TIMEOUT", 10*time.Second) // TCP拨号超时 minPoolInterval = getEnvAsDuration("NP_MIN_POOL_INTERVAL", 1*time.Second) // 最小池间隔 maxPoolInterval = getEnvAsDuration("NP_MAX_POOL_INTERVAL", 5*time.Second) // 最大池间隔 reportInterval = getEnvAsDuration("NP_REPORT_INTERVAL", 5*time.Second) // 报告间隔 - serviceCooldown = getEnvAsDuration("NP_SERVICE_COOLDOWN", 5*time.Second) // 服务冷却时间 + serviceCooldown = getEnvAsDuration("NP_SERVICE_COOLDOWN", 3*time.Second) // 服务冷却时间 shutdownTimeout = getEnvAsDuration("NP_SHUTDOWN_TIMEOUT", 5*time.Second) // 关闭超时 ReloadInterval = getEnvAsDuration("NP_RELOAD_INTERVAL", 1*time.Hour) // 重载间隔 ) @@ -92,6 +92,25 @@ func xor(data []byte) []byte { return data } +// getPoolCapacity 获取连接池容量设置 +func (c *Common) getPoolCapacity(parsedURL *url.URL) { + if min := parsedURL.Query().Get("min"); min != "" { + if value, err := strconv.Atoi(min); err == nil && value > 0 { + c.minPoolCapacity = value + } + } else { + c.minPoolCapacity = 64 + } + + if max := parsedURL.Query().Get("max"); max != "" { + if value, err := strconv.Atoi(max); err == nil && value > 0 { + c.maxPoolCapacity = value + } + } else { + c.maxPoolCapacity = 8192 + } +} + // getAddress 解析和设置地址信息 func (c *Common) getAddress(parsedURL *url.URL) { // 解析隧道地址 From 77a3307af7aecc93ab8277f8ede833dbf590ed8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9D=90=98=F0=9D=90=A8=F0=9D=90=AC=F0=9D=90=9E?= =?UTF-8?q?=F0=9D=90=9B=F0=9D=90=B2=F0=9D=90=AD=F0=9D=90=9E?= <54016243+yosebyte@users.noreply.github.com> Date: Mon, 16 Jun 2025 09:12:35 +0000 Subject: [PATCH 3/4] docs: add connection pool capacity parameters to configuration and usage guides --- docs/en/configuration.md | 57 ++++++++++++++++++++++++++------------ docs/en/usage.md | 46 ++++++++++++++++++------------- docs/zh/configuration.md | 59 ++++++++++++++++++++++++++++------------ docs/zh/usage.md | 30 +++++++++++++++----- 4 files changed, 131 insertions(+), 61 deletions(-) diff --git a/docs/en/configuration.md b/docs/en/configuration.md index b25e548a..957505db 100644 --- a/docs/en/configuration.md +++ b/docs/en/configuration.md @@ -46,6 +46,19 @@ Example with TLS Mode 2 (custom certificate): nodepass server://0.0.0.0:10101/0.0.0.0:8080?tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem ``` +## Connection Pool Capacity Parameters + +Connection pool capacity can be configured via URL query parameters: + +- `min`: Minimum connection pool capacity (default: 64) +- `max`: Maximum connection pool capacity (default: 8192) + +Example: +```bash +# Set minimum pool to 32 and maximum to 4096 +nodepass client://server.example.com:10101/127.0.0.1:8080?min=32&max=4096 +``` + ## Environment Variables NodePass behavior can be fine-tuned using environment variables. Below is the complete list of available variables with their descriptions, default values, and recommended settings for different scenarios. @@ -53,32 +66,30 @@ NodePass behavior can be fine-tuned using environment variables. Below is the co | Variable | Description | Default | Example | |----------|-------------|---------|---------| | `NP_SEMAPHORE_LIMIT` | Maximum number of concurrent connections | 1024 | `export NP_SEMAPHORE_LIMIT=2048` | -| `NP_MIN_POOL_CAPACITY` | Minimum connection pool size | 16 | `export NP_MIN_POOL_CAPACITY=32` | -| `NP_MAX_POOL_CAPACITY` | Maximum connection pool size | 1024 | `export NP_MAX_POOL_CAPACITY=4096` | | `NP_UDP_DATA_BUF_SIZE` | Buffer size for UDP packets | 8192 | `export NP_UDP_DATA_BUF_SIZE=16384` | -| `NP_UDP_READ_TIMEOUT` | Timeout for UDP read operations | 15s | `export NP_UDP_READ_TIMEOUT=30s` | -| `NP_TCP_READ_TIMEOUT` | Timeout for TCP read operations | 15s | `export NP_TCP_READ_TIMEOUT=30s` | -| `NP_UDP_DIAL_TIMEOUT` | Timeout for establishing UDP connections | 15s | `export NP_UDP_DIAL_TIMEOUT=30s` | -| `NP_TCP_DIAL_TIMEOUT` | Timeout for establishing TCP connections | 15s | `export NP_TCP_DIAL_TIMEOUT=30s` | +| `NP_UDP_READ_TIMEOUT` | Timeout for UDP read operations | 10s | `export NP_UDP_READ_TIMEOUT=30s` | +| `NP_UDP_DIAL_TIMEOUT` | Timeout for establishing UDP connections | 10s | `export NP_UDP_DIAL_TIMEOUT=30s` | +| `NP_TCP_READ_TIMEOUT` | Timeout for TCP read operations | 10s | `export NP_TCP_READ_TIMEOUT=30s` | +| `NP_TCP_DIAL_TIMEOUT` | Timeout for establishing TCP connections | 10s | `export NP_TCP_DIAL_TIMEOUT=30s` | | `NP_MIN_POOL_INTERVAL` | Minimum interval between connection creations | 1s | `export NP_MIN_POOL_INTERVAL=500ms` | | `NP_MAX_POOL_INTERVAL` | Maximum interval between connection creations | 5s | `export NP_MAX_POOL_INTERVAL=3s` | | `NP_REPORT_INTERVAL` | Interval for health check reports | 5s | `export NP_REPORT_INTERVAL=10s` | -| `NP_SERVICE_COOLDOWN` | Cooldown period before restart attempts | 5s | `export NP_SERVICE_COOLDOWN=3s` | +| `NP_SERVICE_COOLDOWN` | Cooldown period before restart attempts | 3s | `export NP_SERVICE_COOLDOWN=5s` | | `NP_SHUTDOWN_TIMEOUT` | Timeout for graceful shutdown | 5s | `export NP_SHUTDOWN_TIMEOUT=10s` | | `NP_RELOAD_INTERVAL` | Interval for cert/pool reload | 1h | `export NP_RELOAD_INTERVAL=30m` | ### Connection Pool Tuning -The connection pool parameters are among the most important settings for performance tuning: +The connection pool parameters are important settings for performance tuning: #### Pool Capacity Settings -- `NP_MIN_POOL_CAPACITY`: Ensures a minimum number of available connections +- `min` (URL parameter): Ensures a minimum number of available connections - Too low: Increased latency during traffic spikes as new connections must be established - Too high: Wasted resources maintaining idle connections - Recommended starting point: 25-50% of your average concurrent connections -- `NP_MAX_POOL_CAPACITY`: Prevents excessive resource consumption while handling peak loads +- `max` (URL parameter): Prevents excessive resource consumption while handling peak loads - Too low: Connection failures during traffic spikes - Too high: Potential resource exhaustion affecting system stability - Recommended starting point: 150-200% of your peak concurrent connections @@ -157,9 +168,13 @@ Here are some recommended environment variable configurations for common scenari For applications requiring maximum throughput (e.g., media streaming, file transfers): +URL parameters: +```bash +nodepass client://server.example.com:10101/127.0.0.1:8080?min=128&max=8192 +``` + +Environment variables: ```bash -export NP_MIN_POOL_CAPACITY=64 -export NP_MAX_POOL_CAPACITY=4096 export NP_MIN_POOL_INTERVAL=500ms export NP_MAX_POOL_INTERVAL=3s export NP_SEMAPHORE_LIMIT=8192 @@ -171,13 +186,17 @@ export NP_REPORT_INTERVAL=10s For applications requiring minimal latency (e.g., gaming, financial trading): +URL parameters: +```bash +nodepass client://server.example.com:10101/127.0.0.1:8080?min=256&max=4096 +``` + +Environment variables: ```bash -export NP_MIN_POOL_CAPACITY=128 -export NP_MAX_POOL_CAPACITY=2048 export NP_MIN_POOL_INTERVAL=100ms export NP_MAX_POOL_INTERVAL=1s export NP_SEMAPHORE_LIMIT=4096 -export NP_UDP_READ_TIMEOUT=10s +export NP_UDP_READ_TIMEOUT=5s export NP_REPORT_INTERVAL=1s ``` @@ -185,9 +204,13 @@ export NP_REPORT_INTERVAL=1s For deployment on systems with limited resources (e.g., IoT devices, small VPS): +URL parameters: +```bash +nodepass client://server.example.com:10101/127.0.0.1:8080?min=16&max=512 +``` + +Environment variables: ```bash -export NP_MIN_POOL_CAPACITY=8 -export NP_MAX_POOL_CAPACITY=256 export NP_MIN_POOL_INTERVAL=2s export NP_MAX_POOL_INTERVAL=10s export NP_SEMAPHORE_LIMIT=512 diff --git a/docs/en/usage.md b/docs/en/usage.md index 22bef223..f09fb3ed 100644 --- a/docs/en/usage.md +++ b/docs/en/usage.md @@ -1,34 +1,31 @@ # Usage Instructions -NodePass creates tunnels with an unencrypted TCP control channel and configurable TLS #### Examples - -```bash -# Client single-end forwarding mode - Local proxy listening on port 1080, forwarding to target server -nodepass client://127.0.0.1:1080/target.example.com:8080?log=debug - -# Connect to NodePass server and automatically adopt its TLS security policy - Client sends mode -nodepass client://server.example.com:10101/127.0.0.1:8080 - -# Connect with debug logging - Client receives mode -nodepass client://server.example.com:10101/192.168.1.100:8080?log=debug -```n options for data exchange. This guide covers the three operating modes and explains how to use each effectively. +NodePass creates tunnels with an unencrypted TCP control channel and configurable TLS encryption options for data exchange. This guide covers the three operating modes and explains how to use each effectively. ## Command Line Syntax The general syntax for NodePass commands is: ```bash -nodepass :///?log=&tls=&crt=&key= +nodepass :///?log=&tls=&crt=&key=&min=&max= ``` Where: - ``: Specifies the operating mode (`server`, `client`, or `master`) - ``: The tunnel endpoint address for control channel communications - ``: The destination address for business data with bidirectional flow support (or API prefix in master mode) -- ``: Log verbosity level (`debug`, `info`, `warn`, `error`, or `event`) -- ``: TLS security level for data channels (`0`, `1`, or `2`) - server/master modes only -- ``: Path to certificate file (when `tls=2`) - server/master modes only -- ``: Path to private key file (when `tls=2`) - server/master modes only + +### Query Parameters + +Common query parameters: +- `log=`: Log verbosity level (`debug`, `info`, `warn`, `error`, or `event`) +- `min=`: Minimum connection pool capacity (default: 64, client mode only) +- `max=`: Maximum connection pool capacity (default: 8192, client mode only) + +TLS-related parameters (server/master modes only): +- `tls=`: TLS security level for data channels (`0`, `1`, or `2`) +- `crt=`: Path to certificate file (when `tls=2`) +- `key=`: Path to private key file (when `tls=2`) ## Operating Modes @@ -87,7 +84,7 @@ nodepass "server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=2&crt=/path/to/cer Client mode connects to a NodePass server and supports bidirectional data flow forwarding. ```bash -nodepass client:///?log= +nodepass client:///?log=&min=&max= ``` #### Parameters @@ -95,6 +92,8 @@ nodepass client:///?log= - `tunnel_addr`: Address of the NodePass server's tunnel endpoint to connect to (e.g., 10.1.0.1:10101) - `target_addr`: The destination address for business data with bidirectional flow support (e.g., 127.0.0.1:8080) - `log`: Log level (debug, info, warn, error, event) +- `min`: Minimum connection pool capacity (default: 64) +- `max`: Maximum connection pool capacity (default: 8192) #### How Client Mode Works @@ -121,11 +120,20 @@ In client mode, NodePass supports three operating modes: #### Examples ```bash -# Connect to a NodePass server and automatically adopt its TLS security policy - Client sends mode +# Client single-end forwarding mode - Local proxy listening on port 1080, forwarding to target server +nodepass client://127.0.0.1:1080/target.example.com:8080?log=debug + +# Connect to a NodePass server and adopt its TLS security policy - Client sends mode nodepass client://server.example.com:10101/127.0.0.1:8080 # Connect with debug logging - Client receives mode nodepass client://server.example.com:10101/192.168.1.100:8080?log=debug + +# Custom connection pool capacity - High performance configuration +nodepass client://server.example.com:10101/127.0.0.1:8080?min=128&max=4096 + +# Resource-constrained configuration - Small connection pool +nodepass client://server.example.com:10101/127.0.0.1:8080?min=16&max=512&log=info ``` ### Master Mode (API) diff --git a/docs/zh/configuration.md b/docs/zh/configuration.md index 12a49034..d5381e44 100644 --- a/docs/zh/configuration.md +++ b/docs/zh/configuration.md @@ -46,6 +46,19 @@ TLS模式2示例（自定义证书）： nodepass server://0.0.0.0:10101/0.0.0.0:8080?tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem ``` +## 连接池容量参数 + +连接池容量可以通过URL查询参数进行配置： + +- `min`: 最小连接池容量（默认: 64） +- `max`: 最大连接池容量（默认: 8192） + +示例： +```bash +# 设置最小连接池为32，最大为4096 +nodepass client://server.example.com:10101/127.0.0.1:8080?min=32&max=4096 +``` + ## 环境变量 可以使用环境变量微调NodePass行为。以下是所有可用变量的完整列表，包括其描述、默认值以及不同场景的推荐设置。 @@ -53,32 +66,30 @@ nodepass server://0.0.0.0:10101/0.0.0.0:8080?tls=2&crt=/path/to/cert.pem&key=/pa | 变量 | 描述 | 默认值 | 示例 | |----------|-------------|---------|---------| | `NP_SEMAPHORE_LIMIT` | 最大并发连接数 | 1024 | `export NP_SEMAPHORE_LIMIT=2048` | -| `NP_MIN_POOL_CAPACITY` | 最小连接池大小 | 16 | `export NP_MIN_POOL_CAPACITY=32` | -| `NP_MAX_POOL_CAPACITY` | 最大连接池大小 | 1024 | `export NP_MAX_POOL_CAPACITY=4096` | | `NP_UDP_DATA_BUF_SIZE` | UDP数据包缓冲区大小 | 8192 | `export NP_UDP_DATA_BUF_SIZE=16384` | -| `NP_UDP_READ_TIMEOUT` | UDP读取操作超时 | 15s | `export NP_UDP_READ_TIMEOUT=30s` | -| `NP_TCP_READ_TIMEOUT` | TCP读取操作超时 | 15s | `export NP_TCP_READ_TIMEOUT=30s` | -| `NP_UDP_DIAL_TIMEOUT` | UDP拨号超时 | 15s | `export NP_UDP_DIAL_TIMEOUT=30s` | -| `NP_TCP_DIAL_TIMEOUT` | TCP拨号超时 | 15s | `export NP_TCP_DIAL_TIMEOUT=30s` | +| `NP_UDP_READ_TIMEOUT` | UDP读取操作超时 | 10s | `export NP_UDP_READ_TIMEOUT=30s` | +| `NP_UDP_DIAL_TIMEOUT` | UDP连接建立超时 | 10s | `export NP_UDP_DIAL_TIMEOUT=30s` | +| `NP_TCP_READ_TIMEOUT` | TCP读取操作超时 | 10s | `export NP_TCP_READ_TIMEOUT=30s` | +| `NP_TCP_DIAL_TIMEOUT` | TCP连接建立超时 | 10s | `export NP_TCP_DIAL_TIMEOUT=30s` | | `NP_MIN_POOL_INTERVAL` | 连接创建之间的最小间隔 | 1s | `export NP_MIN_POOL_INTERVAL=500ms` | | `NP_MAX_POOL_INTERVAL` | 连接创建之间的最大间隔 | 5s | `export NP_MAX_POOL_INTERVAL=3s` | | `NP_REPORT_INTERVAL` | 健康检查报告间隔 | 5s | `export NP_REPORT_INTERVAL=10s` | -| `NP_SERVICE_COOLDOWN` | 重启尝试前的冷却期 | 5s | `export NP_SERVICE_COOLDOWN=3s` | +| `NP_SERVICE_COOLDOWN` | 重启尝试前的冷却期 | 3s | `export NP_SERVICE_COOLDOWN=5s` | | `NP_SHUTDOWN_TIMEOUT` | 优雅关闭超时 | 5s | `export NP_SHUTDOWN_TIMEOUT=10s` | | `NP_RELOAD_INTERVAL` | 证书/连接池重载间隔 | 1h | `export NP_RELOAD_INTERVAL=30m` | ### 连接池调优 -连接池参数是性能调优中最重要的设置之一： +连接池参数是性能调优中的重要设置： #### 池容量设置 -- `NP_MIN_POOL_CAPACITY`：确保最小可用连接数 - - 太低：流量高峰期延迟增加，因为必须建立新连接 +- `min` (URL参数)：确保最小可用连接数 + - 太低：流量高峰期延迟增加，因为必须建立新连接 - 太高：维护空闲连接浪费资源 - 推荐起点：平均并发连接的25-50% -- `NP_MAX_POOL_CAPACITY`：防止过度资源消耗，同时处理峰值负载 +- `max` (URL参数)：防止过度资源消耗，同时处理峰值负载 - 太低：流量高峰期连接失败 - 太高：潜在资源耗尽影响系统稳定性 - 推荐起点：峰值并发连接的150-200% @@ -157,9 +168,13 @@ nodepass server://0.0.0.0:10101/0.0.0.0:8080?tls=2&crt=/path/to/cert.pem&key=/pa 对于需要最大吞吐量的应用（如媒体流、文件传输）： +URL参数： +```bash +nodepass client://server.example.com:10101/127.0.0.1:8080?min=128&max=8192 +``` + +环境变量： ```bash -export NP_MIN_POOL_CAPACITY=64 -export NP_MAX_POOL_CAPACITY=4096 export NP_MIN_POOL_INTERVAL=500ms export NP_MAX_POOL_INTERVAL=3s export NP_SEMAPHORE_LIMIT=8192 @@ -171,13 +186,17 @@ export NP_REPORT_INTERVAL=10s 对于需要最小延迟的应用（如游戏、金融交易）： +URL参数： +```bash +nodepass client://server.example.com:10101/127.0.0.1:8080?min=256&max=4096 +``` + +环境变量： ```bash -export NP_MIN_POOL_CAPACITY=128 -export NP_MAX_POOL_CAPACITY=2048 export NP_MIN_POOL_INTERVAL=100ms export NP_MAX_POOL_INTERVAL=1s export NP_SEMAPHORE_LIMIT=4096 -export NP_UDP_READ_TIMEOUT=10s +export NP_UDP_READ_TIMEOUT=5s export NP_REPORT_INTERVAL=1s ``` @@ -185,9 +204,13 @@ export NP_REPORT_INTERVAL=1s 对于在资源有限系统上的部署（如IoT设备、小型VPS）： +URL参数： +```bash +nodepass client://server.example.com:10101/127.0.0.1:8080?min=16&max=512 +``` + +环境变量： ```bash -export NP_MIN_POOL_CAPACITY=8 -export NP_MAX_POOL_CAPACITY=256 export NP_MIN_POOL_INTERVAL=2s export NP_MAX_POOL_INTERVAL=10s export NP_SEMAPHORE_LIMIT=512 diff --git a/docs/zh/usage.md b/docs/zh/usage.md index e63441d6..ff10aa56 100644 --- a/docs/zh/usage.md +++ b/docs/zh/usage.md @@ -7,17 +7,25 @@ NodePass创建一个带有未加密TCP控制通道的隧道，并为数据交换 NodePass命令的一般语法是： ```bash -nodepass :///?log=&tls=&crt=&key= +nodepass :///?log=&tls=&crt=&key=&min=&max= ``` 其中： - ``：指定操作模式（`server`、`client`或`master`） - ``：控制通道通信的隧道端点地址 - ``：业务数据的目标地址，支持双向模式（或在master模式下的API前缀） -- ``：日志详细级别（`debug`、`info`、`warn`、`error`或`event`） -- ``：数据通道的TLS安全级别（`0`、`1`或`2`）- 仅适用于server/master模式 -- ``：证书文件路径（当`tls=2`时）- 仅适用于server/master模式 -- ``：私钥文件路径（当`tls=2`时）- 仅适用于server/master模式 + +### 查询参数说明 + +通用查询参数： +- `log=`：日志详细级别（`debug`、`info`、`warn`、`error`或`event`） +- `min=`：最小连接池容量（默认：64，仅适用于client模式） +- `max=`：最大连接池容量（默认：8192，仅适用于client模式） + +TLS相关参数（仅适用于server/master模式）： +- `tls=`：数据通道的TLS安全级别（`0`、`1`或`2`） +- `crt=`：证书文件路径（当`tls=2`时） +- `key=`：私钥文件路径（当`tls=2`时） ## 运行模式 @@ -76,7 +84,7 @@ nodepass "server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=2&crt=/path/to/cer 客户端模式连接到NodePass服务端并支持双向数据流转发。 ```bash -nodepass client:///?log= +nodepass client:///?log=&min=&max= ``` #### 参数 @@ -84,6 +92,8 @@ nodepass client:///?log= - `tunnel_addr`：要连接的NodePass服务端隧道端点地址(例如, 10.1.0.1:10101) - `target_addr`：业务数据的目标地址，支持双向数据流模式(例如, 127.0.0.1:8080) - `log`：日志级别(debug, info, warn, error, event) +- `min`：最小连接池容量（默认：64） +- `max`：最大连接池容量（默认：8192） #### 客户端模式工作原理 @@ -113,11 +123,17 @@ nodepass client:///?log= # 客户端单端转发模式 - 本地代理监听1080端口，转发到目标服务器 nodepass client://127.0.0.1:1080/target.example.com:8080?log=debug -# 连接到NodePass服务端并自动采用其TLS安全策略 - 客户端发送模式 +# 连接到NodePass服务端并采用其TLS安全策略 - 客户端发送模式 nodepass client://server.example.com:10101/127.0.0.1:8080 # 使用调试日志连接 - 客户端接收模式 nodepass client://server.example.com:10101/192.168.1.100:8080?log=debug + +# 自定义连接池容量 - 高性能配置 +nodepass client://server.example.com:10101/127.0.0.1:8080?min=128&max=4096 + +# 资源受限配置 - 小型连接池 +nodepass client://server.example.com:10101/127.0.0.1:8080?min=16&max=512&log=info ``` ### 主控模式 (API) From 74a371831e869944348ac000babef1c5d4f0c901 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9D=90=98=F0=9D=90=A8=F0=9D=90=AC=F0=9D=90=9E?= =?UTF-8?q?=F0=9D=90=9B=F0=9D=90=B2=F0=9D=90=AD=F0=9D=90=9E?= <54016243+yosebyte@users.noreply.github.com> Date: Mon, 16 Jun 2025 09:46:47 +0000 Subject: [PATCH 4/4] chore(readme): introducing NodePanel in NodePass Ecosystem --- README.md | 4 +++- README_zh.md | 8 +++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b00539d0..c2d2e00a 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ nodepass "server://:10101/127.0.0.1:8080?log=debug&tls=1" **Client Mode** ```bash -nodepass client://server.example.com:10101/127.0.0.1:8080 +nodepass "client://server:10101/127.0.0.1:8080?min=128" ``` **Master Mode (API)** @@ -83,6 +83,8 @@ The [NodePassProject](https://github.com/NodePassProject) organization develops - **[NodePassDash](https://github.com/NodePassProject/NodePassDash)**: A modern NodePass management interface that provides master management, instance management, traffic statistics, history records, and more. +- **[NodePanel](https://github.com/NodePassProject/NodePanel)**: A lightweight frontend panel that provides visual tunnel management, deployable on Vercel or Cloudflare Pages. + - **[npsh](https://github.com/NodePassProject/npsh)**: A convenient script that provides simple and easy-to-use installation, configuration, and management functionality for NodePass master API mode. ## 💬 Discussion diff --git a/README_zh.md b/README_zh.md index c66956eb..ac94c9e7 100644 --- a/README_zh.md +++ b/README_zh.md @@ -57,7 +57,7 @@ nodepass "server://:10101/127.0.0.1:8080?log=debug&tls=1" **客户端模式** ```bash -nodepass client://server.example.com:10101/127.0.0.1:8080 +nodepass "client://server:10101/127.0.0.1:8080?min=128" ``` **主控模式 (API)** @@ -81,9 +81,11 @@ nodepass "master://:10101/api?log=debug&tls=1" [NodePassProject](https://github.com/NodePassProject) 组织开发了各种前端应用和辅助工具来增强 NodePass 体验： -- **[NodePassDash](https://github.com/NodePassProject/NodePassDash)**: 一个现代化的 NodePass 管理界面，提供主控管理、实例管理、流量统计、历史记录等功能。 +- **[NodePassDash](https://github.com/NodePassProject/NodePassDash)**: 现代化的 NodePass 管理界面，提供主控管理、实例管理、流量统计、历史记录等功能。 -- **[npsh](https://github.com/NodePassProject/npsh)**: 一个便捷的脚本，为 NodePass master API 模式提供简单易用的安装、配置和管理功能。 +- **[NodePanel](https://github.com/NodePassProject/NodePanel)**: 轻量化的前端面板，提供可视化的隧道管理功能，在 Vercel 或 Cloudflare Pages 轻松部署。 + +- **[npsh](https://github.com/NodePassProject/npsh)**: 便捷的一键脚本，为 NodePass master API 模式提供简单易用的安装、配置和管理功能。 ## 💬 讨论