pgrok - 开源 ngrok 替代品，自建内网穿透工具

pgrok 是一个开源的 ngrok 替代品，让你通过自己的 VPS 将本地端口暴露到互联网，支持自动 HTTPS、交互式 TUI 仪表板和 HTTP 请求检查功能。

项目简介

pgrok 由 R44VC0RP 开发维护，是一个个人级别的内网穿透工具。与 ngrok 等商业服务不同，pgrok 让你完全掌控自己的隧道基础设施，无需依赖第三方服务。项目在 GitHub 上已获得 605+ stars，主要使用 TypeScript (50%)、Shell (34.2%) 和 Python (15.8%) 编写。

核心特性

• 自动 HTTPS：通过 Caddy 实现按需 TLS，自动为每个子域名申请和续期证书
• 交互式 TUI 仪表板：基于 OpenTUI 构建的实时仪表盘，显示连接状态、请求日志和统计信息
• SSH 反向隧道：利用 SSH 原生功能传输流量，无需额外的隧道软件
• HTTP 请求检查：实时查看经过隧道的所有 HTTP 请求，支持颜色编码的日志显示
• Let's Encrypt + ZeroSSL 双证书支持：当 Let's Encrypt 达到速率限制时自动回退到 ZeroSSL
• 单用户设计：专为个人开发者设计，配置简单，开箱即用

技术栈

• Caddy：VPS 端的反向代理和 HTTPS 终端，支持动态配置
• SSH 反向隧道：客户端与服务器之间的安全通信通道
• Python：服务器端动态路由配置脚本
• TypeScript + Bun：TUI 客户端，使用 OpenTUI 框架
• Docker Compose：服务器端服务编排

安装指南

前置要求

• 一台 VPS（任意提供商），开放 80 和 443 端口
• VPS 上安装 Docker 和 Docker Compose
• 一个你控制的域名
• Mac/Linux 系统上的 SSH 密钥（可运行 ssh-keygen 生成）

1. DNS 配置

在你的 DNS 提供商（Cloudflare、Vercel、Namecheap 等）添加通配符 A 记录：

2. 客户端安装（Mac/Linux）

curl -fsSL https://raw.githubusercontent.com/R44VC0RP/pgrok/main/install.sh | bash -s client

安装器会自动：

• 检测你的 SSH 密钥
• 构建并安装 pgrok 命令
• 将服务器设置命令复制到剪贴板（包含你的 SSH 密钥）

3. 服务器设置

SSH 登录到你的 VPS，粘贴步骤 2 中复制的命令，或运行：

curl -fsSL https://raw.githubusercontent.com/R44VC0RP/pgrok/main/install.sh | sudo bash -s server

该脚本会安装 Caddy、配置 SSH 隧道、添加你的 SSH 密钥并启动所有服务。

快速开始

# 暴露本地开发服务器
pgrok myapp 4000  # -> https://myapp.yourdomain.com

# 暴露 API 服务
pgrok api 3000    # -> https://api.yourdomain.com

# 任何子域名都可以即时使用
pgrok staging 8080  # -> https://staging.yourdomain.com

# 调试模式 - 退出时输出原始隧道日志
pgrok myapp 4000 --print-logs

按 Ctrl+C 停止，路由会自动清理。

更新后重新构建二进制文件：

./setup.sh client --rebuild

TUI 仪表板功能

pgrok 的 TUI 仪表板提供实时监控：

会话状态

• Connecting：正在连接服务器
• Provisioning TLS：正在申请 TLS 证书
• Online：隧道已就绪
• Error：连接出错

连接统计

• 总请求数
• 打开的连接数
• 请求速率（1分钟/5分钟）
• 响应时间分位数（p50/p90）

HTTP 请求日志（颜色编码）

• 请求方法：GET（蓝色）、POST（紫色）、PUT/PATCH（黄色）、DELETE（红色）
• 状态码：2xx（绿色）、3xx（青色）、4xx（黄色）、5xx（红色）
• 响应时间：<100ms（绿色）、100-500ms（黄色）、>500ms（红色）

工作原理

1. Caddy 在 VPS 上处理 HTTPS，使用按需 TLS —— 证书按子域名自动申请
2. SSH 反向隧道 传输流量，无需额外的隧道软件
3. Python 脚本 在服务器上动态配置 Caddy 路由，当隧道连接/断开时自动更新
4. TUI 客户端（基于 OpenTUI）提供实时仪表板，包含请求检查和连接统计

SSL 证书申请流程

1. 请求到达 myapp.yourdomain.com
2. Caddy 询问 pgrok-ask："我应该为这个域名申请证书吗？"
3. pgrok-ask 验证它是 *.yourdomain.com 的单级子域名
4. Caddy 使用 HTTP-01 挑战获取证书 —— 优先尝试 Let's Encrypt，速率受限时回退到 ZeroSSL
5. 证书被缓存并自动续期
6. TUI 客户端在隧道设置期间触发证书预配，确保打开 URL 前证书已就绪

安全配置

• 仅支持 SSH 密钥认证（无密码）
• 专用的 pgrok 用户，SSH 受限（仅允许远程转发）
• Caddy 管理 API 仅监听 localhost（不暴露到外部）
• SSH 隧道仅绑定到 localhost（GatewayPorts no）
• pgrok-ask 防止证书滥用 —— 仅允许单级子域名

配置文件

客户端配置（~/.pgrok/config）

PGROK_HOST=your-vps-ip
PGROK_DOMAIN=yourdomain.com
PGROK_USER=pgrok
PGROK_SSH_KEY=~/.ssh/id_ed25519

服务器端文件（/opt/pgrok/）

服务器端脚本（/usr/local/bin/）

故障排查

TUI 卡在 "connecting"

• 使用 --print-logs 运行，按 Ctrl+C，检查 /tmp/pgrok-debug.log
• 验证 SSH 连接：ssh pgrok@your-vps-ip echo ok

卡在 "provisioning TLS..."

• Let's Encrypt 可能达到速率限制（每周 50 个证书）。ZeroSSL 回退会处理这种情况
• 检查 Caddy 日志：docker compose logs caddy（在 /opt/pgrok 目录）

SSL 证书错误

• 验证 pgrok-ask 是否运行：systemctl status pgrok-ask
• 确保 80 和 443 端口开放
• Cloudflare 代理（橙色云）必须对通配符记录关闭

开发环境

cd client/tui
bun install
bun run index.ts myapp 4000  # 开发模式
bun run build                # 编译二进制文件
bun run tsc --noEmit         # 类型检查

已知限制

• 单用户设计（个人工具，非多租户）
• 仅支持 Mac 和 Linux（不支持 Windows）
• 无自动重连功能（连接断开后需重启 pgrok）
• 突然断开连接可能导致陈旧路由（下次连接时自修复）
• 仅支持 HTTP 请求日志（WebSocket 透传可用但不会被记录）

项目链接

• GitHub 仓库：https://github.com/R44VC0RP/pgrok
• 许可证：MIT

总结

pgrok 是一个轻量级、自托管的 ngrok 替代品，适合希望完全掌控内网穿透基础设施的开发者。通过结合 Caddy 的自动 HTTPS、SSH 反向隧道的安全性和 OpenTUI 的交互式界面，pgrok 提供了一个功能完整且易于使用的解决方案。