Node Server

Concept

Node Server represents the physical proxy server infrastructure in the Helium telecom system. It is the actual backend server that handles proxy connections and processes user traffic.

Key Concepts

• Physical Infrastructure: Node Server is the actual server hardware/software that performs proxy operations
• Backend Component: Operates behind the scenes, not directly visible to end users
• Traffic Handler: Processes all user proxy connections and traffic routing
• Configuration Target: Holds server-side configuration that determines how the proxy server operates

Architecture Position

User Client → Node Client (User-facing) → Node Server (Infrastructure) → Internet

Node Server sits at the infrastructure layer, receiving connections from multiple Node Clients and handling the actual proxy work.

Relationship with Node Client

Configuration

Node Server supports two main configuration types through the NodeServerConfig enum:

Configuration Types

1. NewV2b (UniProxy)

Modern proxy configuration using the UniProxy protocol:

NodeServerConfig::NewV2b(Box<UniProxyProtocolConfig>)

Features:

• High-performance proxy protocol
• Built-in traffic reporting
• Advanced user management
• Speed limiting per user
• Device limiting

2. SSP (SSPanel Compatible)

Legacy SSPanel-compatible configuration:

NodeServerConfig::Ssp(Box<CustomConfig>)

Features:

• SSPanel API compatibility
• Traditional proxy methods
• Custom host configuration
• Legacy traffic reporting

Core Configuration Fields

pub struct NodeServer {
    pub id: i32,
    pub server_side_config: Json<NodeServerConfig>,  // Protocol configuration
    pub speed_limit: i64,                           // Per-user speed limit in Byte/s
    pub status: NodeServerStatus,                   // Online/Offline/Maintenance
    pub last_online_time: PrimitiveDateTime,        // Last heartbeat timestamp
}

Configuration Examples

These JSON examples show the API request format for creating Node Servers with different backend configurations.

Creating NewV2b Node Server

{
  "server_side_config": {
    "compatibility": "newv2b",
    "api_host": "127.0.0.1",
    "api_port": 8080,
    "node_id": 1,
    "cert_mode": "none",
    "cert_domain": "example.com",
    "cert_file": "",
    "key_file": "",
    "ca_file": "",
    "timeout": 30,
    "listen_ip": "0.0.0.0",
    "send_ip": "0.0.0.0",
    "device_limit": 0,
    "speed_limit": 0,
    "rule_list_path": "",
    "dns_type": "AsIs",
    "enable_dns": false,
    "disable_upload_traffic": false,
    "disable_get_rule": false,
    "disable_ivpn_check": false,
    "disable_memory_optimizations": false,
    "enable_reality_show": false,
    "enable_brutal": false,
    "brutal_debug": false,
    "enable_ip_sync": false,
    "ip_sync_interval": 60
  },
  "speed_limit": 1000000000
}

Key Configuration Points:

• compatibility: “newv2b” specifies UniProxy protocol backend
• speed_limit: 1GB/s total server capacity per user
• node_id: Must match the Node Server ID in database
• api_host/api_port: Backend API connection settings
• cert_mode: Certificate handling (“none”, “file”, “http”, “dns”)

Creating SSP Node Server

{
  "server_side_config": {
    "compatibility": "ssp",
    "host": "proxy.example.com",
    "port": 80,
    "node_id": 1,
    "key": "your-api-key",
    "speed_limit": 0,
    "device_limit": 0,
    "rule_list_path": "",
    "custom_config": {
      "offset_port_user": 0,
      "offset_port_node": 0,
      "server_key": "",
      "host": "proxy.example.com",
      "server_port": 443
    }
  },
  "speed_limit": 500000000
}

Key Configuration Points:

• compatibility: “ssp” specifies SSPanel-compatible backend
• speed_limit: 500MB/s total server capacity per user
• host: SSPanel API host
• key: Authentication key for SSPanel API
• custom_config: SSPanel-specific configuration options

Configuration Validation

The system provides configuration validation through the gRPC management API:

gRPC Service: helium.telecom_manage.NodeServerManage
Method: VerifyNodeServerConfig

Request:

message VerifyNodeServerConfigRequest {
  string config = 1;
}

Response:

message VerifyReply {
  bool valid = 1;
}

Example gRPC call:

grpcurl -plaintext \
  -d '{"config": "{\"compatibility\":\"newv2b\",\"api_host\":\"127.0.0.1\",\"api_port\":8080}"}' \
  localhost:50051 \
  helium.telecom_manage.NodeServerManage/VerifyNodeServerConfig

Frontend applications should validate server configurations before creating Node Servers to ensure proper backend protocol settings and prevent deployment failures.

JSON Schema Reference

For frontend developers, here are the key JSON structures:

Node Server Creation Request

{
  "server_side_config": {
    // Required: Backend protocol configuration
    "compatibility": "<string>" // Required: "newv2b" or "ssp"
    // Configuration fields vary by compatibility type
  },
  "speed_limit": "<integer>" // Required: Per-user speed limit in Byte/s
}

Compatibility Types

• “newv2b”: Modern UniProxy protocol backend
• “ssp”: Legacy SSPanel-compatible backend

NewV2b Configuration Schema

{
  "compatibility": "newv2b",
  "api_host": "<string>", // Backend API host
  "api_port": "<integer>", // Backend API port
  "node_id": "<integer>", // Must match database Node Server ID
  "cert_mode": "<string>", // Certificate mode: "none", "file", "http", "dns"
  "cert_domain": "<string>", // Domain for certificate
  "cert_file": "<string>", // Certificate file path
  "key_file": "<string>", // Private key file path
  "ca_file": "<string>", // CA certificate file path
  "timeout": "<integer>", // Request timeout in seconds
  "listen_ip": "<string>", // IP to bind for incoming connections
  "send_ip": "<string>", // IP to use for outgoing connections
  "device_limit": "<integer>", // Device limit per user (0 = no limit)
  "speed_limit": "<integer>", // Speed limit per user (0 = no limit)
  "rule_list_path": "<string>", // Path to routing rules file
  "dns_type": "<string>", // DNS resolution type
  "enable_dns": "<boolean>", // Enable DNS server
  "disable_upload_traffic": "<boolean>",
  "disable_get_rule": "<boolean>",
  "disable_ivpn_check": "<boolean>",
  "disable_memory_optimizations": "<boolean>",
  "enable_reality_show": "<boolean>",
  "enable_brutal": "<boolean>",
  "brutal_debug": "<boolean>",
  "enable_ip_sync": "<boolean>",
  "ip_sync_interval": "<integer>" // IP sync interval in seconds
}

SSP Configuration Schema

{
  "compatibility": "ssp",
  "host": "<string>", // SSPanel API host
  "port": "<integer>", // SSPanel API port
  "node_id": "<integer>", // Must match database Node Server ID
  "key": "<string>", // API authentication key
  "speed_limit": "<integer>", // Speed limit per user (0 = no limit)
  "device_limit": "<integer>", // Device limit per user (0 = no limit)
  "rule_list_path": "<string>", // Path to routing rules file
  "custom_config": {
    // SSPanel-specific settings
    "offset_port_user": "<integer>",
    "offset_port_node": "<integer>",
    "server_key": "<string>",
    "host": "<string>",
    "server_port": "<integer>"
  }
}

Management and Observability

Server Status Management

Node Servers have three possible states:

Status Values:

["online", "offline", "maintenance"]

Status Descriptions:

• “online”: Server is healthy and processing requests
• “offline”: Server missed heartbeat threshold
• “maintenance”: Server manually marked for maintenance

Status Transitions

• Online → Offline: Automatic when last_online_time exceeds offline_timeout
• Offline → Online: Automatic when server sends heartbeat
• Any → Maintenance: Manual admin action
• Maintenance → Online: Manual admin action + heartbeat

Heartbeat System

Node Servers maintain connectivity through heartbeat reporting via traffic upload APIs. The specific API endpoint depends on the server compatibility type:

• NewV2b servers: Use /api/v1/server/UniProxy/push (see NewV2b Traffic Reporting section)
• SSP servers: Use /mod_mu/users/traffic (see SSP Traffic Reporting section)

Heartbeat Behavior:

• Heartbeat is automatically updated when servers report traffic data
• last_online_time is set to current timestamp on each successful API call
• Failed API calls do not update heartbeat timestamp

Health Monitoring Configuration

Configure health check timeouts through system configuration:

{
  "node_health_check_config": {
    "offline_timeout": 600
  }
}

Configuration Fields:

• offline_timeout: Seconds after which a server is marked offline (default: 600 = 10 minutes)

Health Check Logic:

• If current_time - last_online_time > offline_timeout, server status becomes “offline”
• If current_time - last_online_time <= offline_timeout, server status becomes “online”

Automated Status Updates

The system runs automated background tasks for status management:

Automated Operations:

• Periodic Status Refresh: Runs every 5 minutes to update server statuses
• Offline Detection: Marks servers offline if last_online_time exceeds threshold
• Online Recovery: Automatically marks servers online when they resume heartbeat
• Status History: Records status change events for monitoring and analytics

Status Update API for Monitoring:

Status updates are handled automatically by the system background tasks. Administrative monitoring uses the gRPC management API:

gRPC Service: helium.telecom_manage.NodeServerManage
Method: ListNodeServers

Request:

message ListNodeServersRequest {
  int64 limit = 1;
  int64 offset = 2;
  optional NodeServerStatus filter_status = 3;
}

Response:

message ListNodeServersReply {
  repeated NodeServerSummary servers = 1;
}

message NodeServerSummary {
  int32 id = 1;
  NodeServerCompatibility compatibility = 2;
  NodeServerStatus status = 3;
  int64 last_online_time = 4;
  int64 client_number = 5;
}

enum NodeServerCompatibility {
  NODE_SERVER_COMPATIBILITY_NEW_V2B = 0;
  NODE_SERVER_COMPATIBILITY_SSP = 1;
}

Example gRPC call:

grpcurl -plaintext \
  -d '{"limit": 100, "offset": 0}' \
  localhost:50051 \
  helium.telecom_manage.NodeServerManage/ListNodeServers

Administrative Operations

Node Server management is restricted to system administrators through the management gRPC service. The system implements role-based access control (RBAC) with four distinct admin levels, each with specific capabilities.

Admin Levels and Permissions

Detailed Permission Matrix

Server Management Operations:

• List Servers (list_servers): ✅ SuperAdmin, ✅ Moderator, ✅ CustomerSupport
• Show Server Details (show_server): ✅ SuperAdmin, ✅ Moderator
• Create Server (create_server): ✅ SuperAdmin, ✅ Moderator
• Delete Server (delete_server): ✅ SuperAdmin, ✅ Moderator
• Verify Configuration (verify_server_config): ✅ SuperAdmin, ✅ Moderator

Access Control Features:

• All operations require valid admin authentication tokens
• Each administrative action is logged and auditable
• Server deletion is protected by dependency checking (cannot delete servers with active node clients)
• Configuration changes are validated before application
• Role-based restrictions prevent unauthorized access

Safety Mechanisms:

• Dependency validation prevents accidental service disruption
• Configuration validation ensures server stability
• Comprehensive audit logging tracks all administrative changes
• Graceful handling of server state transitions
• Permission checks occur before any operation execution

Traffic Monitoring

Node Servers automatically collect traffic statistics through API endpoints:

NewV2b Traffic Reporting

Servers push traffic data periodically using the UniProxy traffic upload API:

POST /api/v1/server/UniProxy/push?node_id=1&node_type=V2ray&token=your-server-token
Content-Type: application/json

{
  "123": [5000000, 1000000],
  "456": [8000000, 2000000]
}

Request Details:

• Path: /api/v1/server/UniProxy/push
• Authentication: Query parameters (node_id, node_type, token)
• Body Format: {"user_id": [download_bytes, upload_bytes]}
• Content-Type: application/json

Response:

HTTP 200 OK

SSP Traffic Reporting

SSPanel-compatible servers use the legacy traffic reporting API:

POST /mod_mu/users/traffic?node_id=1&key=your-api-key
Content-Type: application/json

[
  {
    "u": 123,
    "d": 1000000,
    "upload": 5000000
  },
  {
    "u": 456,
    "d": 2000000,
    "upload": 8000000
  }
]

Request Details:

• Path: /mod_mu/users/traffic
• Authentication: Query parameters (node_id, key)
• Body Format: Array of {"u": user_id, "d": download_bytes, "upload": upload_bytes}
• Content-Type: application/json

Response:

HTTP 200 OK

Observability Features

Status History Tracking

The system automatically records server status changes for monitoring and analytics:

Tracked Events:

• Status transitions (online ↔ offline ↔ maintenance)
• Uptime statistics and availability metrics
• Heartbeat intervals and response times
• Configuration change events

Status History API:

Status history is tracked automatically by the system. For administrative queries, use the gRPC management API:

gRPC Service: helium.telecom_manage.NodeServerManage
Method: ShowNodeServer

Request:

message ShowNodeServerRequest {
  int32 id = 1;
}

Response:

message NodeServerReply {
  int32 id = 1;
  int64 speed_limit = 2;
  string config = 3;
  NodeServerStatus status = 4;
  int64 last_online_time = 5;
}

enum NodeServerStatus {
  NODE_SERVER_STATUS_ONLINE = 0;
  NODE_SERVER_STATUS_OFFLINE = 1;
  NODE_SERVER_STATUS_MAINTENANCE = 2;
}

Example gRPC call:

grpcurl -plaintext \
  -d '{"id": 1}' \
  localhost:50051 \
  helium.telecom_manage.NodeServerManage/ShowNodeServer

Metrics and Logging

• Structured Logging: All operations use tracing for detailed logs
• Performance Metrics: Traffic throughput and response times
• Health Metrics: Heartbeat intervals and status transitions
• Error Tracking: Failed authentications and connection issues

When to Use Node Server vs Node Client

Use Node Server When:

1. Setting up new physical infrastructure

   gRPC Service: helium.telecom_manage.NodeServerManage
   Method: CreateNodeServer

   Request:

   message CreateNodeServerRequest {
     string config = 1;
     int64 speed_limit = 2;
   }
   

   Response:

   message AdminEditReply {
     AdminEditResult result = 1;
   }
   

   Example gRPC call:

   grpcurl -plaintext \
     -d '{"config": "{\"compatibility\":\"newv2b\",\"api_host\":\"127.0.0.1\",\"api_port\":8080}", "speed_limit": 10000000000}' \
     localhost:50051 \
     helium.telecom_manage.NodeServerManage/CreateNodeServer
   

2. Configuring proxy backend behavior

   • Protocol selection (UniProxy vs SSPanel)
   • Server-side performance settings
   • Traffic processing configuration

3. Managing physical resources

   • Server capacity planning
   • Geographic deployment
   • Infrastructure monitoring

4. Backend administration

   • Server health monitoring
   • Traffic aggregation
   • System maintenance

Use Node Client When:

1. Creating user-facing proxy endpoints

   gRPC Service: helium.telecom_manage.NodeClientManage
   Method: CreateNodeClient

   Request:

   message CreateNodeClientRequest {
     int32 server_id = 1;
     string name = 2;
     string traffic_factor = 3;
     int32 display_order = 4;
     string client_side_config = 5;
     repeated int32 available_groups = 6;
     optional helium.telecom.NodeMetadata metadata = 7;
   }
   

   Response:

   message AdminEditReply {
     AdminEditResult result = 1;
   }
   

   Example gRPC call:

   grpcurl -plaintext \
     -d '{"server_id": 1, "name": "US West Coast", "traffic_factor": "1.0", "display_order": 100, "available_groups": [2, 3, 4], "config": "{\"protocol\":\"Vmess\"}"}' \
     localhost:50051 \
     helium.telecom_manage.NodeClientManage/CreateNodeClient
   

2. Organizing user access

   • Different service tiers (Premium, Basic)
   • Geographic regions for users
   • Access control by user groups

3. Billing and traffic management

   • Different traffic factors per endpoint
   • User-specific speed limits
   • Package-based access control

4. User experience customization

   • Display names and ordering
   • Regional preferences
   • Service level differentiation

Typical Workflow

1. Infrastructure Setup: Create Node Servers for physical infrastructure
2. Service Configuration: Create multiple Node Clients pointing to each server
3. User Management: Assign users to appropriate Node Clients based on packages
4. Monitoring: Monitor Node Server health while tracking Node Client usage

Example Architecture

Physical Infrastructure Layer (Node Servers):
├── US-West-Server (NewV2b, 10GB/s capacity)
├── EU-Central-Server (NewV2b, 5GB/s capacity)
└── Asia-Pacific-Server (SSP, 3GB/s capacity)

User-Facing Layer (Node Clients):
├── US-West-Premium (→ US-West-Server, 2x traffic factor)
├── US-West-Standard (→ US-West-Server, 1x traffic factor)
├── EU-Premium (→ EU-Central-Server, 2x traffic factor)
├── EU-Standard (→ EU-Central-Server, 1x traffic factor)
├── Asia-Premium (→ Asia-Pacific-Server, 2x traffic factor)
└── Asia-Budget (→ Asia-Pacific-Server, 0.5x traffic factor)

This separation allows for:

• Flexible service offerings without infrastructure changes
• Independent scaling of physical and logical resources
• Simplified user management through logical groupings
• Cost-effective resource utilization across multiple service tiers

Security Considerations

Authentication

Node Servers authenticate using different methods depending on compatibility type:

NewV2b Authentication (Query Parameters)

POST /api/v1/server/UniProxy/push?node_id=1&node_type=V2ray&token=your-server-token

Authentication Process:

1. Server includes node_id, node_type, and token as query parameters
2. Backend validates token and node_id combination
3. If valid, request is processed and heartbeat updated
4. If invalid, request is rejected with 401 Unauthorized

SSP Authentication (Query Parameters)

POST /mod_mu/users/traffic?node_id=1&key=your-api-key

Authentication Process:

1. Server includes node_id and key as query parameters
2. Backend validates key and node_id combination
3. If valid, request is processed and heartbeat updated
4. If invalid, request is rejected with 401 Unauthorized

Authentication Configuration:

{
  "telecom_config": {
    "vpn_server_token": "your-secure-server-token-here"
  }
}

Note: The authentication tokens are configured per node server and validated against the vpn_server_token configuration. Both NewV2b and SSP servers use the same token validation mechanism, but with different request formats.

Access Control

• Server-side configuration is admin-only
• API endpoints require proper authentication
• Traffic data is validated before processing
• Heartbeat verification prevents spoofing

Data Protection

• All traffic statistics are aggregated and anonymized
• Configuration data is encrypted at rest
• API communications use secure channels
• User identification uses secure tokens

Troubleshooting

Common Issues

1. Server Shows Offline

   • Check heartbeat timing configuration
   • Verify server can reach the API endpoints
   • Confirm authentication tokens are correct
   • Review network connectivity

2. Traffic Not Reporting

   • Verify server configuration type matches API calls
   • Check traffic threshold filtering (>10KB)
   • Confirm database connectivity
   • Review authentication tokens

3. Configuration Validation Failures

   • Validate JSON syntax in server config
   • Check protocol-specific requirements
   • Verify all required fields are present
   • Test with minimal configuration first

4. Performance Issues

   • Monitor server resource utilization
   • Check speed_limit configuration
   • Review traffic patterns and peaks
   • Consider load balancing across servers

Debugging Tools

• Health Check API: Monitor server status programmatically
• Traffic Reports: Analyze throughput and usage patterns
• Status History: Review historical availability data
• Configuration Validation: Test configs before deployment
• Structured Logging: Detailed operation traces with tracing

Best Practices

• Monitor heartbeat intervals regularly
• Use automation for status management
• Implement proper alerting for offline servers
• Regular configuration backups
• Capacity planning based on traffic trends
• Geographic distribution for reliability