yy130202-tpx

v0.3.2

Published

8 days ago

Self-hosted CLI toolbox with secure reverse tunneling

0High
0Medium
0Low

yy130202

network tunnel reverse-proxy tcp udp cli

TBX Network Toolbox

tbx 是零运行时依赖的 Node.js 命令行网络工具箱。第一套完整能力是自托管反向隧道：公网服务端接受内网客户端主动建立的控制连接，再按需配对独立数据连接，将 TCP、UDP、HTTP 和 WebSocket 流量转发到内网服务。

仅用于你拥有或明确获准管理的主机、端口和网络。端口扫描命令只接受单个显式主机，单次最多 4096 个端口，不会自动遍历网段。

功能

反向隧道

TCP 端口暴露，支持并发上限、空闲超时、双向带宽限制和 PROXY Protocol v1。
UDP 转发，按公网来源维护独立会话，带会话上限与自动过期。
HTTP Host 和通配符 Host 路由，自动添加 X-Forwarded-*，支持自定义上游请求头。
WebSocket Upgrade 透明转发。
控制与数据连接分离，每个公网连接使用独立反向数据连接。
客户端指数退避重连、随机抖动、双向心跳与超时回收。
HMAC-SHA256 挑战应答，客户端令牌不通过网络发送；客户端同时验证服务端证明。
控制端 TLS、mTLS、HTTP 入口 TLS、本地目标 TLS。
IPv4/IPv6 CIDR allow/deny ACL，deny 优先。
服务端端口范围、客户端数、隧道数、连接数、UDP 会话数和帧大小策略。
管理 API、健康检查、Prometheus 指标、文本/JSON 日志和优雅退出。

网络诊断

dns：A、AAAA、MX、TXT、NS、SOA、SRV、PTR、CAA、NAPTR、ANY。
connect：TCP/TLS 连通性、DNS/TCP/TLS 分段耗时、ALPN 与证书摘要。
scan：显式主机的端口扫描、并发控制、服务名识别和开放/关闭/过滤分类。
http：HTTP 状态、跳转链、响应头、正文预览、DNS/TCP/TLS/首部/总耗时。
tls：协议、密码套件、临时密钥、ALPN、证书主题/签发者/指纹/剩余天数。
cidr：IPv4/IPv6 网络范围、掩码、广播、可用地址和包含判断。
interfaces：本机网卡、地址、CIDR、MAC 与 scope ID。
bridge tcp|udp：用户态四层桥接，支持来源 ACL、TCP 并发上限、UDP 会话隔离/回收、空闲超时和 TCP 带宽限制。
ping / trace：受限次数的 ICMP 检查和单目标路由跟踪。
routes / neighbors / sockets：查看系统路由表、ARP/NDP 邻居表及监听端口。
privileges：报告当前进程是否已通过 UAC 提升，不执行提权。
serve：启动本地 HTTP、TCP echo、UDP echo 实验服务，便于验证诊断命令和隧道。

终端体验

无参数启动或 tbx menu 进入交互菜单，并显示大幅 TBX 字符画与阴影标题。
TTY 自动启用 ANSI 颜色；NO_COLOR=1 禁色，FORCE_COLOR=1 强制颜色。
TBX_NO_BANNER=1 可关闭服务启动字符画。
所有 --json 输出保持纯 JSON，不混入颜色或 Banner。

架构

Public user                  Public server                     Private network
    |                             |                                  |
    +--- TCP/UDP/HTTP ----------> |                                  |
                                  | <==== outbound control ========= + client
                                  | ---- open request --------------> |
                                  | <==== authenticated data ======== |
                                  | <======= bidirectional =========> | local target

公网服务端必须能被客户端访问。该实现是中继式反向隧道，不依赖 UPnP，不修改路由器配置，也不需要客户端具有公网 IP。

环境与安装

Node.js >= 20.11，建议 Node.js 24 LTS。
无第三方运行时依赖。

cd C:\Users\admin\toolbox
npm link
tbx --help

不安装全局命令也可以直接运行：

node .\bin\tbx.js --help
npx yy130202-tpx

公网包发布到 npm 官方 Registry 后，任意安装 Node.js/npm/npx 的电脑都可以直接运行 npx yy130202-tpx。包名 tpx 已由其他 npm 用户持有，因此裸命令 npx tpx 不能指向本项目。

Windows Terminal 启动

可直接双击：

start.cmd：标准用户权限，在 Windows Terminal 打开菜单；未安装 Windows Terminal 时回退到普通命令提示符。
start-npx.cmd：通过本地 npx 包入口打开菜单。
start-admin.cmd：显示 Windows UAC 确认后，以管理员令牌打开菜单。

管理员启动器不会请求 SYSTEM、绕过 UAC、创建计划任务或永久修改系统。管理员令牌已经能够执行绝大多数网卡/路由诊断；SYSTEM 权限会显著扩大破坏面，因此不作为工具默认能力。

也可以在任意终端直接运行：

.\tbx.cmd menu
.\tbx.cmd --help

无需配置隧道即可先启动完整的本地实验目标：

.\tbx.cmd net serve

默认提供 http://127.0.0.1:3000、127.0.0.1:3001 TCP echo 和 127.0.0.1:3002 UDP echo。按 Ctrl+C 停止。

五分钟启动

在安全目录生成配对配置、客户端令牌和管理令牌：

tbx tunnel init --output-dir .\config --client-id edge-01 --host tunnel.example.com

生成器不会覆盖已有文件，除非显式传入 --force。默认 ACL 只允许回环来源，投入使用前应把 client.json 中的 ACL 改为可信公网出口 CIDR。

公网主机：

tbx tunnel check --config .\config\server.json --kind server
tbx tunnel server --config .\config\server.json

内网主机：

tbx tunnel check --config .\config\client.json --kind client
tbx tunnel doctor --config .\config\client.json
tbx tunnel client --config .\config\client.json

查看运行状态：

tbx tunnel status --url http://127.0.0.1:7400 --token-file .\config\admin.token
tbx tunnel status --url http://127.0.0.1:7400 --token-file .\config\admin.token --metrics

令牌与鉴权

生成新客户端凭据：

tbx tunnel token --client-id edge-02 --json

客户端保存原始 token；服务端只保存 tokenHash。握手证明包含服务端随机数、客户端 ID、时间戳、连接用途和数据请求 ID，因此抓到的证明不能作为静态令牌重放。未启用 TLS 时仍无法从链路直接取得令牌，但 TLS 才能同时抵御主动中间人和隐藏业务流量，生产环境应始终启用。

密钥配置支持三种来源，必须且只能选择一种：

{ "token": "literal-for-temporary-testing" }
{ "tokenEnv": "TBX_CLIENT_TOKEN" }
{ "tokenFile": "./client.token" }

配置中的字符串支持 ${NAME} 和 ${NAME:-default} 环境变量展开。

TLS 与 mTLS

服务端控制入口：

{
  "tls": {
    "enabled": true,
    "certFile": "./certs/server.crt",
    "keyFile": "./certs/server.key",
    "caFile": "./certs/client-ca.crt",
    "requestClientCert": true,
    "minVersion": "TLSv1.2"
  }
}

客户端：

{
  "tls": {
    "enabled": true,
    "caFile": "./certs/server-ca.crt",
    "certFile": "./certs/client.crt",
    "keyFile": "./certs/client.key",
    "servername": "tunnel.example.com",
    "rejectUnauthorized": true,
    "minVersion": "TLSv1.2"
  }
}

HTTP 公网入口使用与控制入口相同的服务端 TLS 字段。本地 TCP/HTTP 目标也可在 target.tls 中启用 TLS；自签名目标可以显式设置 rejectUnauthorized: false，但不建议用于生产。

隧道配置

TCP：

{
  "name": "ssh",
  "type": "tcp",
  "target": { "host": "127.0.0.1", "port": 22 },
  "remotePort": 10022,
  "proxyProtocol": false,
  "idleTimeoutMs": 300000,
  "bandwidthLimitKbps": 2048,
  "maxConnections": 32,
  "acl": { "allow": ["198.51.100.10/32"], "deny": [] }
}

UDP：

{
  "name": "game",
  "type": "udp",
  "target": { "host": "127.0.0.1", "port": 19132 },
  "remotePort": 10053,
  "acl": { "allow": ["198.51.100.0/24"], "deny": [] }
}

HTTP 与 WebSocket：

{
  "name": "app",
  "type": "http",
  "target": { "host": "127.0.0.1", "port": 3000 },
  "hosts": ["app.example.com", "*.preview.example.com"],
  "websocket": true,
  "preserveHost": true,
  "addHeaders": { "x-tunnel-client": "edge-01" },
  "acl": { "allow": [], "deny": ["192.0.2.44/32"] }
}

HTTP Host 必须解析到公网服务端。服务端按精确 Host 优先、最长通配符后缀其次进行路由。HTTP 入口终止公网 HTTP/HTTPS，再通过独立数据连接把 HTTP/1.1 请求发送到本地目标；WebSocket Upgrade 则透明桥接原始字节流。

remotePort: 0 可让操作系统分配临时端口，实际端口会出现在客户端日志和管理 API 中，适合测试。固定端口必须落在服务端 policy.allowedPortRanges 内。

网络工具示例

# DNS 与指定 DNS 服务器
tbx net dns example.com --type AAAA
tbx net dns example.com --type MX --server 1.1.1.1 --json

# TCP/TLS 分段耗时和证书
tbx net connect example.com 443 --tls
tbx net tls example.com 443 --servername example.com

# 单个显式目标，常用端口或自选端口
tbx net scan 192.168.1.10 --ports common
tbx net scan 192.168.1.10 --ports 22,80,443,8000-8100 --concurrency 64

# HTTP 状态、跳转、响应头和正文前 2048 字节
tbx net http https://example.com --follow 5 --headers
tbx net http https://example.com -X GET --body 2048 --json

# CIDR 与本机接口
tbx net cidr 10.20.30.40/24 --contains 10.20.30.99
tbx net cidr 2001:db8:abcd::1/48 --json
tbx net interfaces

# 路径、邻居、监听端口和当前权限
tbx net ping 192.168.1.1 --count 4
tbx net trace 192.168.1.1 --max-hops 16
tbx net routes
tbx net neighbors
tbx net sockets
tbx net privileges

scan 不支持 CIDR 或地址段作为目标，只解析一个主机名/IP；端口选择去重排序并限制为 4096 个。提高并发会增加本机文件描述符和目标负载，应按授权范围与环境容量设置。

TCP/UDP 用户态桥接

将回环 TCP 9000 桥接到实验服务 3001：

tbx net bridge tcp --listen-port 9000 --target-host 127.0.0.1 --target-port 3001

UDP 桥接：

tbx net bridge udp --listen-port 9001 --target-host 127.0.0.1 --target-port 3002

默认只监听 127.0.0.1，且 ACL 只允许 IPv4/IPv6 回环来源。需要从局域网访问时必须同时显式设置监听地址和可信来源，例如：

tbx net bridge tcp --listen-host 0.0.0.0 --listen-port 9000 --target-host 10.0.0.20 --target-port 443 --allow 192.168.1.0/24 --max-connections 64 --idle-timeout 120000

--allow any 会允许全部来源，只应在受控网络中使用。此功能是应用层/用户态的 TCP、UDP 四层转发，不等同于 Windows“网络连接”里的二层物理网桥；它不改网卡绑定、IP 转发、路由或防火墙，通常不需要管理员权限。

管理 API 与指标

GET /healthz：最小健康状态，不要求 Bearer 令牌。
GET /v1/status：客户端、隧道、监听地址、活动连接和流量统计。
GET /metrics：Prometheus 文本格式。

管理端口默认只监听 127.0.0.1。如果改为非回环地址，配置校验会强制要求 admin.auth。推荐通过 SSH、VPN 或反向代理访问管理端口，而不是直接暴露到公网。

主要指标包括：

tbx_connected_clients
tbx_registered_tunnels
tbx_active_connections
tbx_connections_total
tbx_connection_errors_total
tbx_bytes_total
tbx_udp_datagrams_total
tbx_auth_failures_total

Docker

准备 .env：

TBX_CLIENT_TOKEN_HASH=<64-character-sha256-hex>
TBX_ADMIN_TOKEN=<strong-random-token>

启动：

docker compose up -d --build

Compose 示例映射 TCP/UDP 10000-10100。如果修改 allowedPortRanges，必须同步修改容器端口映射。示例 ACL 使用文档保留网段 203.0.113.0/24，部署前必须替换。

服务化

Linux systemd 的核心命令：

[Service]
Type=simple
User=tbx
WorkingDirectory=/opt/toolbox
ExecStart=/usr/bin/node /opt/toolbox/bin/tbx.js tunnel server --config /etc/tbx/server.json
Restart=on-failure
RestartSec=3
Environment=TBX_NO_BANNER=1
NoNewPrivileges=true
PrivateTmp=true

Windows 可使用任务计划程序或现有服务包装器启动：

node C:\toolbox\bin\tbx.js tunnel client --config C:\ProgramData\tbx\client.json

安全基线

公网环境启用控制 TLS；高敏感环境同时启用 mTLS。
每台客户端使用独立随机令牌，服务端只保存 SHA-256 哈希；怀疑泄露时立即轮换。
为每条隧道配置可信来源 CIDR，不依赖应用自身登录作为唯一边界。
限制 allowedPortRanges、每客户端隧道数和每隧道连接数。
管理 API 保持回环监听并配置强随机令牌。
令牌使用环境变量或权限受限文件，不提交到版本库。
定期查看 tbx_auth_failures_total、连接错误和流量异常。
HTTP 自定义头拒绝换行，协议帧有大小上限，握手有时间戳窗口。

协议边界

控制面使用换行分隔 JSON；数据面握手完成后切换为原始字节流。
TCP/HTTP/WebSocket 每个公网连接分配一条独立数据连接，避免流间队头阻塞。
UDP 数据使用控制通道中的 Base64 帧，并按来源地址/端口维护会话；适合常规 UDP 服务，不适合超高包率媒体转发。
当前不实现无公网中继的 P2P 打洞，也不修改 NAT、UPnP、防火墙或系统路由。
HTTP 入口处理 HTTP/1.1；公网 HTTPS 可终止 TLS，WebSocket 可透明升级。

开发与验证

npm test
npm run test:coverage
npm run check

测试使用本机动态端口，不访问公网。覆盖鉴权、ACL、配置、CIDR、端口表达式、TCP 扫描、HTTP 探测、终端 Banner、TCP/UDP 用户态桥接，以及 TCP/UDP/HTTP/WebSocket/管理 API/指标的完整端到端链路。

bin/tbx.js                 CLI 入口
src/cli.js                 工具箱与隧道命令
src/net-cli.js             网络诊断命令
src/net-tools.js           网络诊断核心
src/net-bridge.js          TCP/UDP 用户态桥接
src/system-net.js          路由、邻居、端口、Ping/Trace 和权限查询
src/tunnel-server.js       公网服务端
src/tunnel-client.js       内网客户端
src/protocol.js            JSON 帧协议
src/security.js            令牌和双向 HMAC
src/terminal.js            ANSI 主题与阴影字符画
start.cmd                  普通权限双击启动
start-npx.cmd              本地 npx 双击启动
start-admin.cmd            UAC 管理员双击启动
examples/                  安全默认示例
test/                      单元与端到端测试