PortBuddy 内网穿透工具技术分析

一、概述

1. 简介

A. 是什么

PortBuddy 是一个内网穿透工具，类似于 ngrok，可以将本地主机或私有网络中开放的端口暴露到公共互联网。它作为一个安全隧道运行，为本地服务提供公共 URL 访问能力。

B. 核心价值

• 快速暴露本地服务到公网，无需复杂的网络配置
• 支持 HTTP、TCP、UDP 多种协议
• 自动 SSL 加密，保障传输安全
• 提供静态子域名和自定义域名支持

C. 应用场景

• Web 应用开发和测试
• Webhook 回调测试
• 本地数据库远程访问
• 实时应用程序演示
• 团队协作开发

2. 技术栈

A. 后端技术

• Java 25
• Spring Boot 3.5.7
• Spring WebFlux（响应式网关）
• GraalVM（原生可执行文件）

B. 前端技术

• React
• TypeScript
• TailwindCSS

C. 基础设施

• Docker & Docker Compose
• Eureka（服务发现）
• 自定义 SSL 证书管理

二、核心功能

1. 多协议支持

A. HTTP 隧道

默认模式，自动获取 HTTPS 公共地址，支持 Websocket。

B. TCP 隧道

适用于数据库、SSH 等长连接服务。

C. UDP 隧道

支持 UDP 协议服务的暴露。

2. 安全特性

A. SSL 默认启用

所有 HTTP 隧道自动配置 SSL 证书。

B. 密码保护

支持为隧道设置访问密码，保护敏感服务。

3. 自定义配置

A. 静态子域名

可请求固定的子域名，便于分享和记忆。

B. 自定义域名

支持绑定自己的域名。

三、系统架构

1. 模块组成

graph TB
    subgraph 客户端
        CLI[CLI 客户端<br/>GraalVM 原生]
    end

    subgraph 服务端
        Gateway[API Gateway<br/>Webflux]
        Server[Server<br/>Spring Boot]
        NetProxy[网络代理<br/>TCP/UDP]
        SSL[SSL 证书服务]
        Eureka[服务发现<br/>Eureka]
        Web[Web 控制台<br/>React]
    end

    CLI -->|HTTPS| Gateway
    Gateway --> Server
    Gateway --> NetProxy
    Server --> Eureka
    Server --> SSL
    Web --> Gateway
    Web --> Server

2. 模块说明

A. CLI 客户端

基于 Java 25 和 GraalVM 构建的轻量级命令行应用，可编译为原生可执行文件。

B. Server 服务

Spring Boot 3.5.7 构建，负责 API 接口和隧道管理。

C. NetProxy 网络代理

高性能 TCP/UDP 代理服务，处理实际的数据转发。

D. Gateway 网关

基于 Webflux 的响应式 API 网关，负责请求路由。

E. SSL 证书服务

自动化 SSL 证书的申请、续期和管理。

F. Web 控制台

React 构建的 Web 管理界面，支持隧道、订阅、团队成员管理。

G. Eureka 服务发现

实现服务间的自动发现和注册。

四、工作流程

1. 隧道建立流程

sequenceDiagram
    participant C as CLI 客户端
    participant G as API Gateway
    participant S as Server
    participant P as NetProxy
    participant U as 用户

    C->>G: 1. 认证（API Token）
    G->>S: 2. 验证 Token
    S-->>G: 3. 返回用户信息
    C->>G: 4. 请求创建隧道
    G->>S: 5. 分配端口/域名
    S->>P: 6. 配置代理规则
    P-->>S: 7. 确认配置
    S-->>G: 8. 返回公共地址
    G-->>C: 9. 返回隧道信息
    U->>P: 10. 访问公共地址
    P->>C: 11. 转发到本地服务

2. 数据转发机制

A. HTTP 模式

请求通过公共 HTTPS 地址进入，经过网关路由到对应的隧道代理，再转发到本地服务。

B. TCP/UDP 模式

建立 TCP/UDP 连接到分配的公共地址和端口，NetProxy 负责将流量转发到本地服务。

五、CLI 使用

1. 安装与认证

A. 下载 CLI

根据平台（Windows、Linux、Mac）下载对应的 portbuddy 可执行文件。

B. 初始化认证

portbuddy init {YOUR_API_TOKEN}

API Token 在 portbuddy.dev 控制台生成。

2. 暴露端口

A. HTTP 模式（默认）

portbuddy http 3000

输出：http://localhost:3000 exposed to: https://abc123.portbuddy.dev

B. TCP 模式

portbuddy tcp localhost:5432

输出：tcp localhost:5432 exposed to: net-proxy-3.portbuddy.dev:43452

C. UDP 模式

portbuddy udp localhost:53

3. 高级选项

Usage: portbuddy [options] [mode] [host:][port]

Modes:
  http (default), tcp, udp

Options:
  -d,  --domain=<domain>        请求静态子域名（如 my-app）
  -pr, --port-reservation=<hp>  指定 TCP/UDP 端口预留 host:port
  -pc, --passcode=<passcode>    设置隧道访问密码
  -v,  --verbose                启用详细日志
  -h,  --help                   显示帮助信息
  -V,  --version                显示版本信息

A. 静态子域名

portbuddy -d my-app http 3000

B. 密码保护

portbuddy -pc mysecret http 3000

六、订阅计划

1. 计划对比

七、技术特点分析

1. 架构优势

A. 微服务设计

各模块职责清晰，便于独立部署和扩展。

B. 响应式编程

使用 Webflux 构建网关，支持高并发场景。

C. 原生编译

CLI 使用 GraalVM 编译为原生可执行文件，启动快、资源占用低。

2. 与同类产品对比

A. 对比 ngrok

• 相似功能：多协议支持、SSL 自动配置
• 差异点：PortBuddy 采用 Java 技术栈，提供自托管能力

B. 对比 frp

• frp 需要自己部署服务端
• PortBuddy 提供云端服务，降低使用门槛

3. 技术亮点

A. Java 25 前沿技术

使用最新 Java 版本，体现对前沿技术的拥抱。

B. 服务发现集成

使用 Eureka 实现服务间动态发现，提高系统弹性。

C. 自动化 SSL

SSL 证书服务实现自动申请和续期，降低运维成本。

八、开发与部署

1. 开发环境要求

• Java 25
• Docker & Docker Compose
• Spring Boot 3
• Maven 3.9+
• Node.js & npm（Web 模块）

2. 构建项目

mvn clean install

3. 运行完整服务

docker-compose up

九、总结

PortBuddy 是一个设计现代化的内网穿透工具，采用 Java 生态最新技术栈，提供完整的微服务架构。其 CLI 客户端使用 GraalVM 原生编译，确保轻量和快速启动。服务端采用 Spring Boot 3 + Webflux 组合，支持高并发场景。对于需要快速暴露本地服务的开发者来说，是一个值得考虑的 ngrok 替代方案。

参考资料

1. PortBuddy GitHub 仓库
2. PortBuddy 官方网站