上级 项目
type
status
date
slug
summary
password
子级 项目
tags
category

NodePass is a secure, efficient TCP/UDP tunneling solution that delivers fast, reliable access across network restrictions using pre-established TLS/TCP connections.
一套通用TCP/UDP隧道解决方案,免配置单文件多模式,采用控制数据双路分离架构,内置零延迟自适应连接池,实现跨网络限制的快速安全访问。
官方网站:https://nodepass.eu
NodePass是一款通用、轻量的TCP/UDP隧道解决方案。它基于创新的三层架构(服务器-客户端-主控)构建,优雅地实现了控制与数据通道的分离,同时提供直观的零配置命令语法。系统通过预建立连接的主动连接池消除了延迟,结合分级TLS安全选项与优化的数据传输机制,性能表现卓越。其最具特色的功能之一是TCP与UDP之间的无缝协议转换,让应用能够跨越协议受限的网络进行通信。其能够智能适应网络波动,即使在复杂环境中也能保持稳定性能,同时高效利用系统资源。无论是穿越防火墙和NAT,还是连接复杂的代理配置,它都为DevOps专业人员和系统管理员提供了一个兼具先进功能与卓越易用性的完美平衡方案。
核心特性
高性能隧道
使用Go语言实现的轻量级隧道,具有极低的延迟和高吞吐量,支持大规模并发连接。
三层架构
创新的主控、服务端、客户端三层架构,实现灵活的网络拓扑和统一管理。
多协议支持
支持TCP和UDP协议,满足不同应用场景的网络需求,具有灵活的配置选项。
安全可靠
内置TLS加密和认证机制,确保数据传输的安全性和完整性,防止未授权访问。
易于配置
简单的命令行界面无需配置文件,使部署和管理变得简单高效,适合各技术水平用户。
跨平台兼容
支持Linux、Windows、macOS等操作系统,可以在各种环境中无缝部署和运行。
NodePass架构

数据传输流程
NodePass在实例之间建立点对点双向数据流:
控制通道
- 用于信令的非加密TCP连接
- 隧道生命周期内的持久连接
- 基于URL的信令协议
- 协调连接隧道建立
数据通道
- 可配置的TLS加密(3种模式)
- 按需为每个连接创建
- 高效的连接池系统
- 同时支持TCP和UDP协议
安全特性
模式 0
非加密数据传输(最快,安全性最低)
模式 1
自签名证书加密(良好安全性,无验证)
模式 2
已验证证书加密(最高安全性,需要有效证书)
这种点对点架构使NodePass能够灵活适应各种网络环境,通过增强的安全性和协议转换实现端点之间的高效数据传输。
安装指南
使用不同方法安装 NodePass 的详细说明。选择最适合您环境和需求的安装方式。
系统要求
- Go 1.24或更高版本(从源代码构建时需要)
- 服务器和客户端端点之间的网络连接
- 绑定1024以下端口可能需要管理员权限
安装方法
方式1:预编译二进制文件
开始使用 NodePass 的最简单方法是为您的平台下载预编译的二进制文件。
- 访问 GitHub 上的发布页面
- 下载适合您操作系统的二进制文件(Windows、macOS、Linux)
- 如有必要,解压缩档案
- 使二进制文件可执行(Linux/macOS):
- 将二进制文件移动到PATH中的位置:
- Linux/macOS:
sudo mv nodepass /usr/local/bin/
- Windows:将位置添加到PATH环境变量
方式2:使用Go安装
如果您的系统上已安装Go,可以使用
go install
命令:此命令下载源代码,编译它,并将二进制文件安装到您的Go bin目录中(通常是
$GOPATH/bin
)。方式3:从源代码构建
对于最新的开发版本或自定义构建:
方式4:使用容器镜像
NodePass在GitHub容器注册表中提供容器镜像,非常适合容器化环境:
方式5:使用管理脚本(仅限Linux)
对于Linux系统,提供了一个交互式管理脚本,便于安装和服务管理:
此脚本提供了一个交互式菜单,可以:
- 安装或更新NodePass
- 创建和配置多个nodepass服务
- 管理(启动/停止/重启/删除)nodepass服务
- 自动设置systemd服务
- 使用可自定义选项配置客户端和服务器模式
验证安装
安装后,通过检查版本来验证NodePass是否正确安装:

NodePass API参考
概述
NodePass在主控模式(Master Mode)下提供了RESTful API,使前端应用能够以编程方式进行控制和集成。本节提供API端点、集成模式和最佳实践的全面文档。
主控模式API
当NodePass以主控模式(
master://
)运行时,它会暴露REST API,允许前端应用:- 创建和管理NodePass服务器和客户端实例
- 监控连接状态和统计信息
- 控制运行中的实例(启动、停止、重启)
- 通过参数配置行为
基本URL
其中:
<api_addr>
是主控模式URL中指定的地址(例如0.0.0.0:9090
)
<prefix>
是可选的API前缀(如果未指定,则使用随机生成的ID作为前缀)
注意: 如果不指定自定义前缀,系统会自动生成一个随机前缀以增强安全性。生成的前缀将显示在启动日志中。
启动主控模式
使用默认设置启动主控模式的NodePass:
使用自定义API前缀和启用TLS:
可用端点

API认证
主控API目前尚未实现认证机制。在生产环境部署时,建议:
- 使用带有认证的反向代理
- 通过网络策略限制访问
- 启用TLS加密(
tls=1
或tls=2
)
前端集成指南
在将NodePass与前端应用集成时,请考虑以下重要事项:
实例持久化
NodePass主控模式现在支持使用gob序列化格式进行实例持久化。实例及其状态会保存到与可执行文件相同目录下的
nodepass.gob
文件中,并在主控重启时自动恢复。主要持久化特性:
- 实例配置自动保存到磁盘
- 实例状态(运行/停止)得到保留
- 流量统计数据在重启之间保持
- 重启后无需手动重新注册
注意: 虽然实例配置现在已经持久化,前端应用仍应保留自己的实例配置记录作为备份策略。
实例生命周期管理
为了合理管理生命周期:
- 创建:存储实例配置和URL
- 状态监控:定期轮询状态
- 控制操作:启动、停止、重启实例
流量统计
主控API提供流量统计数据,但需要注意以下重要事项:
- 启用调试模式:流量统计功能仅在启用调试模式时可用。
如果未启用调试模式,API将不会收集或返回流量统计数据。
- 基本流量指标:NodePass周期性地提供TCP和UDP流量在入站和出站方向上的累计值,前端应用需要存储和处理这些值以获得有意义的统计信息。
- 数据持久化:由于API只提供累计值,前端必须实现适当的存储和计算逻辑。
实例ID持久化
由于NodePass现在使用gob格式持久化存储实例状态,实例ID在主控重启后不再发生变化。这意味着:
- 前端应用可以安全地使用实例ID作为唯一标识符
- 实例配置、状态和统计数据在重启后自动恢复
- 不再需要实现实例ID变化的处理逻辑
这极大简化了前端集成,消除了以前处理实例重新创建和ID映射的复杂性。
API端点文档
有关详细的API文档(包括请求和响应示例),请使用
/v1/docs
端点提供的内置Swagger UI文档。这个交互式文档提供了以下全面信息:- 可用的端点
- 必需的参数
- 响应格式
- 请求和响应示例
- 架构定义
访问Swagger UI
要访问Swagger UI文档:
例如:

Swagger UI提供了一种方便的方式,直接在浏览器中探索和测试API。您可以针对运行中的NodePass主控实例执行API调用,并查看实际响应。
最佳实践
可扩展管理
对于管理多个NodePass实例:
- 批量操作:实现批量操作以管理多个实例
- 连接池化:对API请求使用连接池
- 缓存:缓存实例详情以减少API调用
监控和健康检查
实现全面监控:
- API健康检查:验证主控API是否响应
- 实例健康检查:监控单个实例健康状态
总结
NodePass主控模式API提供了强大的接口,用于以编程方式管理NodePass实例。在与前端应用集成时,特别注意:
- 实例持久化 - 存储配置并处理重启
- 实例ID持久化 - 使用实例ID作为唯一标识符
- 适当的错误处理 - 从API错误中优雅恢
- 流量统计 - 收集并可视化连接指标(需要启用调试模式)
配置选项
NodePass采用极简方法进行配置,所有设置都通过命令行参数和环境变量指定。本指南说明所有可用的配置选项,并为各种部署场景提供建议。
日志级别
NodePass提供五种日志详细级别,控制显示的信息量:
debug
:详细调试信息 - 显示所有操作和连接
info
:一般操作信息(默认) - 显示启动、关闭和关键事件
warn
:警告条件 - 仅显示不影响核心功能的潜在问题
error
:错误条件 - 仅显示影响功能的问题
fatal
:致命条件 - 仅显示导致终止的严重错误
您可以在命令URL中设置日志级别:
TLS加密模式
对于服务器和主控模式,NodePass为数据通道提供三种TLS安全级别:
- 模式0:无TLS加密(明文TCP/UDP)
- 最快性能,无开销
- 数据通道无安全保护(仅在受信任网络中使用)
- 模式1:自签名证书(自动生成)
- 设置简单的良好安全性
- 证书自动生成且不验证
- 防止被动窃听
- 模式2:自定义证书(需要
crt
和key
参数)
- 具有证书验证的最高安全性
- 需要提供证书和密钥文件
- 适用于生产环境
TLS模式1示例(自签名):
TLS模式2示例(自定义证书):
环境变量
可以使用环境变量微调NodePass行为。以下是所有可用变量的完整列表,包括其描述、默认值以及不同场景的推荐设置。



连接池调优
连接池参数是性能调优中最重要的设置之一:
池容量设置
NP_MIN_POOL_CAPACITY
:确保最小可用连接数
- 太低:流量高峰期延迟增加,因为必须建立新连
- 太高:维护空闲连接浪费资源
- 推荐起点:平均并发连接的25-50%
NP_MAX_POOL_CAPACITY
:防止过度资源消耗,同时处理峰值负载
- 太低:流量高峰期连接失败
- 太高:潜在资源耗尽影响系统稳定性
- 推荐起点:峰值并发连接的150-200%
池间隔设置
NP_MIN_POOL_INTERVAL
:控制连接创建尝试之间的最小时间
- 太低:可能以连接尝试压垮网络
- 推荐范围:根据网络延迟,500ms-2s
NP_MAX_POOL_INTERVAL
:控制连接创建尝试之间的最大时间
- 太高:流量高峰期可能导致池耗尽
- 推荐范围:根据预期流量模式,3s-10s
连接管理
NP_SEMAPHORE_LIMIT
:控制最大并发隧道操作数
- 太低:流量高峰期拒绝连接
- 太高:太多并发goroutine可能导致内存压力
- 推荐范围:大多数应用1000-5000,高吞吐量场景更高
UDP设置
对于严重依赖UDP流量的应用:
NP_UDP_DATA_BUF_SIZE
:UDP数据包缓冲区大小
- 对于发送大UDP数据包的应用增加此值
- 默认值(8192)适用于大多数情况
- 考虑为媒体流或游戏服务器增加到16384或更高
NP_UDP_READ_TIMEOUT
:UDP读取操作超时
- 对于高延迟网络或响应时间慢的应用增加此值
- 对于需要快速故障转移的低延迟应用减少此值
NP_UDP_DIAL_TIMEOUT
:UDP拨号超时
- 对于高延迟网络增加此值
- 对于需要快速连接的应用减少此值
服务管理设置
NP_REPORT_INTERVAL
:控制健康状态报告频率
- 较低值提供更频繁的更新但增加日志量
- 较高值减少日志输出但提供较少的即时可见性
NP_RELOAD_INTERVAL
:控制检查TLS证书变更的频率
- 较低值更快检测证书变更但增加文件系统操作
- 较高值减少开销但延迟检测证书更新
NP_SERVICE_COOLDOWN
:尝试服务重启前的等待时间
- 较低值更快尝试恢复但可能在持续性问题情况下导致抖动
- 较高值提供更多稳定性但从瞬态问题中恢复较慢
NP_SHUTDOWN_TIMEOUT
:关闭期间等待连接关闭的最长时间
- 较低值确保更快关闭但可能中断活动连接
- 较高值允许连接有更多时间完成但延迟关闭
配置配置文件
以下是常见场景的推荐环境变量配置:
高吞吐量配置
对于需要最大吞吐量的应用(如媒体流、文件传输):
低延迟配置
对于需要最小延迟的应用(如游戏、金融交易):
资源受限配置
对于在资源有限系统上的部署(如IoT设备、小型VPS):
使用示例
本页提供了NodePass在各种部署场景中的实际示例。这些示例涵盖了常见用例,可以根据您的具体需求进行调整。
基本服务器设置与TLS选项
示例1:无TLS加密
当速度比安全性更重要时 (例如,在受信任网络中):
这会启动一个NodePass服务器,它:
- 在所有接口的10101端口上监听隧道连接
- 将流量转发到localhost:8080
- 使用debug日志记录详细信息
- 不对数据通道使用加密(最快性能)
示例2:自签名证书
为了平衡安全性和易于设置 (推荐大多数情况):
此配置:
- 自动生成自签名证书
- 提供加密而无需证书管理
- 保护数据流量免受被动窃听
- 适用于内部或测试环境
示例3:自定义域名证书
对于需要验证证书的生产环境:
这一设置:
- 使用您提供的TLS证书和私钥
- 提供具有证书验证的最高安全级别
- 适合生产环境和面向公众的服务
- 允许客户端验证服务器的身份
连接到NodePass服务器
示例4:基本客户端连接
使用默认设置连接到NodePass服务器:
此客户端:
- 连接到server.example.com:10101的NodePass服务器
- 将接收到的流量转发到localhost:8080
- 自动采用服务器的TLS安全策略
- 使用默认的info日志级别
示例5:带调试日志的客户端
用于故障排除连接问题:
这启用了详细输出,有助于识别:
- 连接建立问题
- 信号处理
- 数据传输详情
- 错误情况
通过防火墙访问数据库
示例6:数据库隧道
启用对防火墙后的数据库服务器的安全访问:
此配置:
- 创建到PostgreSQL数据库(端口5432)的加密隧道
- 允许安全访问数据库而不直接将其暴露于互联网
- 使用自签名证书加密所有数据库流量
- 使远程数据库在客户端上显示为本地服务
安全的微服务通信
示例7:服务间通信
启用微服务之间的安全通信:
此设置:
- 在两个微服务之间创建安全通道
- 使用自定义证书进行服务身份验证
- 将日志限制为仅警告和错误
- 使服务A的API在服务B上显示为本地服务
物联网设备管理
示例8:物联网网关
创建物联网设备的中央访问点:
此配置:
- 使分布式物联网设备能够安全连接到中央服务器
- 使用自签名证书提供足够的安全性
- 允许嵌入式设备安全地暴露其本地Web界面
- 通过单一端点集中设备管理
多环境开发
示例9:开发环境访问
通过隧道访问不同的开发环境:
此设置:
- 创建对多个环境(生产、开发、测试)的安全访问
- 根据环境敏感性使用不同级别的日志记录
- 使开发人员能够访问环境而无需直接网络暴露
- 将远程服务映射到不同的本地端口,便于识别
容器部署
示例10:容器化NodePass
在Docker环境中部署NodePass:
此配置:
- 在服务之间创建容器化隧道
- 使用Docker网络连接容器
- 仅向主机公开必要端口
- 提供对内部Web服务的安全访问
主控API管理
示例11:集中管理
为多个NodePass实例设置中央控制器:
然后您可以通过API调用管理实例:
此设置:
- 为所有NodePass实例提供中央管理界面
- 允许动态创建和控制隧道
- 提供用于自动化和集成的RESTful API
- 包含内置的Swagger UI,位于http://localhost:9090/api/v1/docs
示例12:自定义API前缀
为主控模式使用自定义API前缀:
这允许:
- 与现有API网关集成
- 用于安全或组织目的的自定义URL路径
故障排除指南
本指南帮助您诊断并解决使用NodePass时可能遇到的常见问题。对于每个问题,我们提供可能的原因和逐步解决方案。
连接问题
无法建立隧道连接
症状:客户端无法连接到服务器的隧道端点,或连接立即断开。
可能的原因和解决方案:
- 网络连接问题
- 使用
ping
或telnet
验证与服务器地址的基本连接 - 检查指定的端口是否可达:
telnet server.example.com 10101
- 确保没有防火墙阻止隧道端口(通常为10101)
- 服务器未运行
- 在Linux/macOS上使用
ps aux | grep nodepass
验证NodePass服务器是否运行 - 检查服务器日志中的任何启动错误
- 尝试重启服务器进程
- 地址错误
- 仔细检查客户端命令中的隧道地址格式
- 确保使用了正确的主机名/IP和端口
- 如果使用DNS名称,验证它们是否解析为正确的IP地址
- TLS配置不匹配
- 如果服务器需要TLS但客户端不支持,连接将失败
- 检查服务器日志中的TLS握手错误
- 如果使用TLS模式2,确保证书配置正确
数据未通过隧道流动
症状:隧道连接已建立,但应用程序数据未到达目的地。
可能的原因和解决方案:
- 目标服务未运行
- 验证目标服务在服务器和客户端两侧是否运行
- 检查是否可以在本地直接连接到该服务
- 端口冲突
- 确保目标端口没有被其他应用程序占用
- 使用
netstat -tuln
检查端口使用情况
- 协议不匹配
- 验证您是否在隧道传输正确的协议(TCP与UDP)
- 某些应用程序需要特定的协议支持
- 目标地址错误
- 仔细检查服务器和客户端命令中的目标地址
- 对于服务器端目标,确保它们可从服务器访问
- 对于客户端目标,确保它们可从客户端访问
连接稳定性问题
症状:隧道最初工作但频繁断开或变得无响应。
可能的原因和解决方案:
- 网络不稳定
- 检查您的网络中是否有数据包丢失或高延迟
- 考虑为生产部署使用更稳定的网络连接
- 资源限制
- 监控客户端和服务器的CPU和内存使用情况
- 如果资源耗尽,调整池参数(参见性能部分)
- 在Linux/macOS上使用
ulimit -n
检查文件描述符限制
- 超时配置
- 如果使用具有慢响应时间的UDP,调整
UDP_READ_TIMEOUT
- 考虑在操作系统级别调整TCP keepalive设置以支持长寿命连接
- 服务器过载
- 检查服务器日志中的连接过载迹象
- 调整
MAX_POOL_CAPACITY
和SEMAPHORE_LIMIT
以处理负载 - 考虑用多个NodePass实例水平扩展
证书问题
TLS握手失败
症状:连接尝试因TLS握手错误而失败。
可能的原因和解决方案:
- 无效证书
- 验证证书有效性:
openssl x509 -in cert.pem -text -noout
- 确保证书没有过期
- 检查证书是否针对正确的域名/IP颁发
- 证书文件丢失或无法访问
- 确认证书和密钥的文件路径正确
- 验证文件权限允许NodePass进程读取它们
- 通过文本编辑器打开证书检查文件是否损坏
- 证书信任问题
- 如果使用自定义CA,确保它们被正确信任
- 对于自签名证书,确认使用TLS模式1
- 对于验证证书,确保CA链完整
- 密钥格式问题
- 确保私钥格式正确(通常为PEM)
- 检查私钥是否有密码保护(不直接支持)
证书更新问题
症状:证书更新后,安全连接开始失败。
可能的原因和解决方案:
- 新证书未加载
- 重启NodePass强制加载新证书
- 检查
RELOAD_INTERVAL
是否设置正确以自动检测变更
- 证书链不完整
- 确保证书文件中包含完整的证书链
- 验证链顺序:首先是您的证书,然后是中间证书
- 密钥不匹配
- 验证新证书是否与私钥匹配:
- 如果输出不同,证书和密钥不匹配
性能优化
高延迟
症状:连接工作但有明显延迟。
可能的原因和解决方案:
- 池配置
- 增加
MIN_POOL_CAPACITY
以准备更多连接 - 减少
MIN_POOL_INTERVAL
以更快创建连接 - 如果连接队列堆积,调整
SEMAPHORE_LIMIT
- 网络路径
- 检查网络拥塞或高延迟链路
- 考虑将NodePass部署在更靠近客户端或服务器的位置
- 使用traceroute识别潜在瓶颈
- TLS开销
- 如果需要极低延迟且安全性不太重要,考虑使用TLS模式0
- 为了平衡,使用带会话恢复的TLS模式1
- 资源竞争
- 确保主机系统有足够的CPU和内存
- 检查是否有其他进程竞争资源
- 考虑为高流量部署使用专用主机
CPU使用率高
症状:NodePass进程消耗过多CPU资源。
可能的原因和解决方案:
- 池抖动
- 如果池不断创建和销毁连接,调整时间
- 增加
MIN_POOL_INTERVAL
以减少连接创建频率 - 为
MIN_POOL_CAPACITY
和MAX_POOL_CAPACITY
找到良好平衡
- 过度日志记录
- 在生产环境中将日志级别从debug降低到info或warn
- 检查日志是否写入缓慢设备
- TLS开销
- TLS握手需要大量CPU;考虑会话缓存
- 如果证书验证不太重要,使用TLS模式1而不是模式2
- 流量体积
- 高吞吐量可能导致CPU饱和
- 考虑跨多个NodePass实例分配流量
- 对于非常高的吞吐量,可能需要垂直扩展(更多CPU核心)
内存泄漏
症状:NodePass内存使用随时间持续增长。
可能的原因和解决方案:
- 连接泄漏
- 确保
SHUTDOWN_TIMEOUT
足够长以正确关闭连接 - 检查自定义脚本或管理代码中的错误处理
- 使用系统工具如
netstat
监控连接数量
- 池大小问题
- 如果
MAX_POOL_CAPACITY
非常大,内存使用会更高 - 监控实际池使用情况与配置容量
- 根据实际并发连接需求调整容量
- 调试日志
- 在高流量场景中,大量调试日志可能消耗内存
- 在生产环境中使用适当的日志级别
UDP特定问题
UDP数据丢失
症状:UDP数据包无法通过隧道可靠转发。
可能的原因和解决方案:
- 缓冲区大小限制
- 如果UDP数据包较大,增加
UDP_DATA_BUF_SIZE
- 默认8192字节对某些应用程序可能太小
- 超时问题
- 如果响应较慢,增加
UDP_READ_TIMEOUT
- 对于响应时间变化的应用程序,找到最佳平衡点
- 高数据包率
- UDP一次处理一个数据报;非常高的速率可能导致问题
- 考虑为高流量UDP应用增加池容量
- 协议期望
- 一些UDP应用期望特定的数据包顺序或时序行为
- NodePass提供尽力转发,但无法保证超出网络提供的UDP属性
UDP连接跟踪
症状:UDP会话过早断开或无法建立。
可能的原因和解决方案:
- 连接映射
- 验证客户端配置是否符合服务器期望
- 检查防火墙是否超时UDP会话跟踪
- 应用UDP超时
- 一些应用有内置UDP会话超时
- 可能需要调整应用特定的keepalive设置
主控API问题
API可访问性问题
症状:无法连接到主控API端点。
可能的原因和解决方案:
- 端点配置
- 验证主控命令中的API地址和端口
- 检查API服务器是否绑定到正确的网络接口
- TLS配置
- 如果使用HTTPS(TLS模式1或2),确保客户端工具支持TLS
- 对于测试,使用
curl -k
跳过证书验证
- 自定义前缀问题
- 如果使用自定义API前缀,确保所有请求中都包含它
- 检查API客户端和脚本中的URL格式
实例管理失败
症状:无法通过API创建、控制或删除实例。
可能的原因和解决方案:
- JSON格式问题
- 验证请求体是有效的JSON
- 检查API请求中的必填字段
- URL解析问题
- 确保实例URL格式正确,必要时进行URL编码
- 验证URL参数使用正确格式
- 实例状态冲突
- 无法删除运行中的实例,必须先停止
- 在执行操作前先用GET检查当前实例状态
- 权限问题
- 确保NodePass主控具有创建进程的足够权限
- 检查任何引用的证书或密钥的文件系统权限
- 作者:团子
- 链接:https://ikun.su///article/NodePass
- 声明:本文采用 CC BY-NC-SA 4.0 许可协议,转载请注明出处。
相关文章