NodePass：一款安全、高效的TCP/UDP隧道解决方案

Published:

原文链接

🔗 NodePass

GitHub release Go Version Go Report Card

nodepass

Language: English | 简体中文

NodePass is an elegant, efficient TCP tunneling solution that creates secure communication bridges between network endpoints. By establishing an unencrypted TCP control channel, NodePass facilitates seamless data transfer through otherwise restricted network environments while offering configurable security options for the data channel. Its server-client architecture allows for flexible deployment scenarios, enabling access to services across firewalls, NATs, and other network barriers. With its intelligent connection pooling, minimal resource footprint, and straightforward command syntax, NodePass provides developers and system administrators with a powerful yet easy-to-use tool for solving complex networking challenges without compromising on security or performance.

📋 Table of Contents

✨ Features

nodepass

📋 Requirements

📥 Installation

💾 Option 1: Pre-built Binaries

Download the latest release for your platform from our releases page.

🔧 Option 2: Using Go Install

go install github.com/yosebyte/nodepass/cmd/nodepass@latest

🛠️ Option 3: Building from Source

# Clone the repository
git clone https://github.com/yosebyte/nodepass.git

# Build the binary
cd nodepass
go build -o nodepass ./cmd/nodepass

# Optional: Install to your GOPATH/bin
go install ./cmd/nodepass

🐳 Option 4: Using Container Image

NodePass is available as a container image on GitHub Container Registry:

# Pull the container image
docker pull ghcr.io/yosebyte/nodepass:latest

# Run in server mode
docker run -d --name nodepass-server -p 10101:10101 -p 8080:8080 \
  ghcr.io/yosebyte/nodepass server://0.0.0.0:10101/0.0.0.0:8080

# Run in client mode
docker run -d --name nodepass-client \
  -e MIN_POOL_CAPACITY=32 \
  -e MAX_POOL_CAPACITY=512 \
  -p 8080:8080 \
  ghcr.io/yosebyte/nodepass client://nodepass-server:10101/127.0.0.1:8080

📜 Option 5: Using Management Script

For Linux systems, you can use our interactive management script for easy installation and service management:

bash <(curl -sL https://cdn.yobc.de/shell/nodepass.sh)

This script provides an interactive menu to:

🚀 Usage

NodePass creates a tunnel with an unencrypted TCP control channel and configurable TLS encryption options for the data exchange channel. It operates in two complementary modes:

🖥️ Server Mode

nodepass server://<tunnel_addr>/<target_addr>?log=<level>&tls=<mode>&crt=<cert_file>&key=<key_file>

In server mode, NodePass:

  1. Listens for TCP tunnel connections (control channel) on tunnel_addr
  2. Listens for incoming TCP and UDP traffic on target_addr
  3. When a connection arrives at target_addr, it signals the connected client through the unencrypted TCP tunnel
  4. Creates a data channel for each connection with the specified TLS encryption level

Example:

# No TLS encryption for data channel
nodepass server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=0

# Self-signed certificate (auto-generated)
nodepass server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=1

# Custom domain certificate
nodepass server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem

📱 Client Mode

nodepass client://<tunnel_addr>/<target_addr>?log=<level>

In client mode, NodePass:

  1. Connects to the server’s unencrypted TCP tunnel endpoint (control channel) at tunnel_addr
  2. Listens for signals from the server through this control channel
  3. When a signal is received, establishes a data connection with the TLS security level specified by the server
  4. Creates a local connection to target_addr and forwards traffic

Example:

# Connect to a NodePass server and automatically adopt its TLS security policy
nodepass client://10.1.0.1:10101/127.0.0.1:8080?log=info

⚙️ Configuration

NodePass uses a minimalist approach with command-line parameters and environment variables:

📝 Log Levels

🔧 Environment Variables

VariableDescriptionDefaultExample
SEMAPHORE_LIMITMaximum number of concurrent connections1024export SEMAPHORE_LIMIT=2048
MIN_POOL_CAPACITYMinimum connection pool size16export MIN_POOL_CAPACITY=32
MAX_POOL_CAPACITYMaximum connection pool size1024export MAX_POOL_CAPACITY=4096
UDP_DATA_BUF_SIZEBuffer size for UDP packets8192export UDP_DATA_BUF_SIZE=16384
UDP_READ_TIMEOUTTimeout for UDP read operations5sexport UDP_READ_TIMEOUT=10s
REPORT_INTERVALInterval for health check reports5sexport REPORT_INTERVAL=10s
SERVICE_COOLDOWNCooldown period before restart attempts5sexport SERVICE_COOLDOWN=3s
SHUTDOWN_TIMEOUTTimeout for graceful shutdown5sexport SHUTDOWN_TIMEOUT=10s

📚 Examples

🔐 Basic Server Setup with TLS Options

# Start a server with no TLS encryption for data channel
nodepass server://0.0.0.0:10101/127.0.0.1:8080?log=debug&tls=0

# Start a server with auto-generated self-signed certificate
nodepass server://0.0.0.0:10101/127.0.0.1:8080?log=debug&tls=1

# Start a server with custom domain certificate
nodepass server://0.0.0.0:10101/127.0.0.1:8080?log=debug&tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem

🔌 Connecting to a NodePass Server

# Connect to a server (automatically adopts the server's TLS security policy)
nodepass client://server.example.com:10101/127.0.0.1:8080

# Connect with debug logging
nodepass client://server.example.com:10101/127.0.0.1:8080?log=debug

🗄 Database Access Through Firewall

# Server side (outside secured network) with TLS encryption
nodepass server://:10101/127.0.0.1:5432?tls=1

# Client side (inside the firewall)
nodepass client://server.example.com:10101/127.0.0.1:5432

🔒 Secure Microservice Communication

# Service A (providing API) with custom certificate
nodepass server://0.0.0.0:10101/127.0.0.1:8081?log=warn&tls=2&crt=/path/to/service-a.crt&key=/path/to/service-a.key

# Service B (consuming API)
nodepass client://service-a:10101/127.0.0.1:8082

📡 IoT Device Management

# Central management server
nodepass server://0.0.0.0:10101/127.0.0.1:8888?log=info&tls=1

# IoT device
nodepass client://mgmt.example.com:10101/127.0.0.1:80

🧪 Multi-environment Development

# Production API access tunnel
nodepass client://tunnel.example.com:10101/127.0.0.1:3443

# Development environment
nodepass server://tunnel.example.com:10101/127.0.0.1:3000

# Testing environment
nodepass server://tunnel.example.com:10101/127.0.0.1:3001?log=warn&tls=1

🐳 Container Deployment

# Create a network for the containers
docker network create nodepass-net

# Deploy NodePass server with self-signed certificate
docker run -d --name nodepass-server \
  --network nodepass-net \
  -p 10101:10101 \
  ghcr.io/yosebyte/nodepass server://0.0.0.0:10101/web-service:80?log=info&tls=1

# Deploy a web service as target
docker run -d --name web-service \
  --network nodepass-net \
  nginx:alpine

# Deploy NodePass client
docker run -d --name nodepass-client \
  -p 8080:8080 \
  ghcr.io/yosebyte/nodepass client://nodepass-server:10101/127.0.0.1:8080?log=info

# Access the web service via http://localhost:8080

🔍 How It Works

NodePass creates a network architecture with separate channels for control and data:

  1. Control Channel (Tunnel):

    • Unencrypted TCP connection between client and server
    • Used exclusively for signaling and coordination
    • Maintains persistent connection for the lifetime of the tunnel

  2. Data Channel (Target):

    • Configurable TLS encryption options:

      • Mode 0: Unencrypted data transfer (fastest, least secure)
      • Mode 1: Self-signed certificate encryption (good security, no verification)
      • Mode 2: Verified certificate encryption (highest security, requires valid certificates)

    • Created on-demand for each connection or datagram

    • Used for actual application data transfer

  3. Server Mode Operation:

    • Listens for control connections on the tunnel endpoint
    • When traffic arrives at the target endpoint, signals the client via the control channel
    • Establishes data channels with the specified TLS mode when needed

  4. Client Mode Operation:

    • Connects to the server’s control channel
    • Listens for signals indicating incoming connections
    • Creates data connections using the TLS security level specified by the server
    • Forwards data between the secure channel and local target

  5. Protocol Support:

    • TCP: Full bidirectional streaming with persistent connections
    • UDP: Datagram forwarding with configurable buffer sizes and timeouts

🔄 Data Transmission Flow

NodePass establishes a bidirectional data flow through its tunnel architecture, supporting both TCP and UDP protocols:

Server-Side Flow

  1. Connection Initiation:

    [Target Client] → [Target Listener] → [Server: Target Connection Created]
    • For TCP: Client establishes persistent connection to target listener
    • For UDP: Server receives datagrams on UDP socket bound to target address

  2. Signal Generation:

    [Server] → [Generate Unique Connection ID] → [Signal Client via Unencrypted TCP Tunnel]
    • For TCP: Generates a //<connection_id>#1 signal
    • For UDP: Generates a //<connection_id>#2 signal when datagram is received

  3. Connection Preparation:

    [Server] → [Create Remote Connection in Pool with Configured TLS Mode] → [Wait for Client Connection]
    • Both protocols use the same connection pool mechanism with unique connection IDs
    • TLS configuration applied based on the specified mode (0, 1, or 2)

  4. Data Exchange:

    [Target Connection] ⟷ [Exchange/Transfer] ⟷ [Remote Connection]
    • For TCP: Uses conn.DataExchange() for continuous bidirectional data streaming
    • For UDP: Individual datagrams are forwarded with configurable buffer sizes

Client-Side Flow

  1. Signal Reception:

    [Client] → [Read Signal from TCP Tunnel] → [Parse Connection ID]
    • Client differentiates between TCP and UDP signals based on URL scheme

  2. Connection Establishment:

    [Client] → [Retrieve Connection from Pool] → [Connect to Remote Endpoint]
    • Connection management is protocol-agnostic at this stage

  3. Local Connection:

    [Client] → [Connect to Local Target] → [Establish Local Connection]
    • For TCP: Establishes persistent TCP connection to local target
    • For UDP: Creates UDP socket for datagram exchange with local target

  4. Data Exchange:

    [Remote Connection] ⟷ [Exchange/Transfer] ⟷ [Local Target Connection]
    • For TCP: Uses conn.DataExchange() for continuous bidirectional data streaming
    • For UDP: Reads single datagram, forwards it, waits for response with timeout, then returns response

Protocol-Specific Characteristics

Both protocols benefit from the same secure signaling mechanism through the TCP tunnel, ensuring protocol-agnostic control flow with protocol-specific data handling.

📡 Signal Communication Mechanism

NodePass uses a sophisticated URL-based signaling protocol through the TCP tunnel:

Signal Types

  1. Tunnel Signal:

    • Format: //<port>#<tls>
    • Purpose: Informs the client about the server’s remote endpoint port and tls code
    • Timing: Sent on tunnel handshake

  2. TCP Launch Signal:

    • Format: //<connection_id>#1
    • Purpose: Requests the client to establish a TCP connection for a specific ID
    • Timing: Sent when a new TCP connection to the target service is received

  3. UDP Launch Signal:

    • Format: //<connection_id>#2
    • Purpose: Requests the client to handle UDP traffic for a specific ID
    • Timing: Sent when UDP data is received on the target port

Signal Flow

  1. Signal Generation:

    • Server creates URL-formatted signals for specific events
    • Signal is terminated with a newline character for proper parsing

  2. Signal Transmission:

    • Server writes signals to the TCP tunnel connection
    • Uses a mutex to prevent concurrent writes to the tunnel

  3. Signal Reception:

    • Client uses a buffered reader to read signals from the tunnel
    • Signals are trimmed and parsed into URL format

  4. Signal Processing:

    • Client places valid signals in a buffered channel (signalChan)
    • A dedicated goroutine processes signals from the channel
    • Semaphore pattern prevents signal overflow

  5. Signal Execution:

    • Remote signals update the client’s remote address configuration
    • Launch signals trigger the clientOnce() method to establish connections

Signal Resilience

🔌 Connection Pool Architecture

NodePass implements an efficient connection pooling system for managing network connections:

Pool Design

  1. Pool Types:

    • Client Pool: Pre-establishes connections to the remote endpoint
    • Server Pool: Manages incoming connections from clients

  2. Pool Components:

    • Connection Storage: Thread-safe map of connection IDs to net.Conn objects
    • ID Channel: Buffered channel for available connection IDs
    • Capacity Management: Dynamic adjustment based on usage patterns
    • Connection Factory: Customizable connection creation function

Connection Lifecycle

  1. Connection Creation:

    • Connections are created up to the configured capacity
    • Each connection is assigned a unique ID
    • IDs and connections are stored in the pool

  2. Connection Acquisition:

    • Client retrieves connections using connection IDs
    • Server retrieves the next available connection from the pool
    • Connections are validated before being returned

  3. Connection Usage:

    • Connection is removed from the pool when acquired
    • Used for data exchange between endpoints
    • No connection reuse (one-time use model)

  4. Connection Termination:

    • Connections are closed after use
    • Resources are properly released
    • Error handling ensures clean termination

Pool Management

  1. Capacity Control:

    • MIN_POOL_CAPACITY: Ensures minimum available connections
    • MAX_POOL_CAPACITY: Prevents excessive resource consumption
    • Dynamic scaling based on demand patterns

  2. Pool Managers:

    • ClientManager(): Maintains the client connection pool
    • ServerManager(): Manages the server connection pool

  3. One-Time Connection Pattern: Each connection in the pool follows a one-time use pattern:

    • Created and placed in the pool
    • Retrieved once for a specific data exchange
    • Never returned to the pool (prevents potential data leakage)
    • Properly closed after use

  4. Automatic Pool Size Adjustment:

    • Pool capacity dynamically adjusts based on real-time usage patterns
    • If connection creation success rate is low (<20%), capacity decreases to minimize resource waste
    • If connection creation success rate is high (>80%), capacity increases to accommodate higher traffic
    • Gradual scaling prevents oscillation and provides stability
    • Respects configured minimum and maximum capacity boundaries
    • Scales down during periods of low activity to conserve resources
    • Scales up proactively when traffic increases to maintain performance
    • Self-tuning algorithm that adapts to varying network conditions
    • Separate adjustment logic for client and server pools to optimize for different traffic patterns

  5. Efficiency Considerations:

    • Pre-establishment reduces connection latency
    • Connection validation ensures only healthy connections are used
    • Proper resource cleanup prevents connection leaks
    • Interval-based pool maintenance balances resource usage with responsiveness
    • Optimized connection validation with minimal overhead

💡 Common Use Cases

🔧 Troubleshooting

📜 Connection Issues

🚀 Performance Optimization

Connection Pool Tuning

Network Configuration

Resource Allocation

Monitoring Recommendations

Advanced Scenarios

👥 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

💬 Discussion

Thank you to all the developers and users in the NodeSeek community for your feedbacks. Feel free to reach out anytime with any technical issues.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⭐ Stargazers

Stargazers over time

Previous Post
LibreTV: 一键部署的免费在线视频搜索与观看平台
Next Post
digiKam：全功能开源数字照片管理应用程序