pgrok开发环境搭建：本地调试与集成测试完整流程

【免费下载链接】pgrok Poor man's ngrok - a multi-tenant HTTP/TCP reverse tunnel solution through SSH remote port forwarding 项目地址: https://gitcode.com/gh_mirrors/pg/pgrok

pgrok是一个多租户HTTP/TCP反向隧道解决方案，通过SSH远程端口转发实现。本文将详细介绍如何搭建完整的pgrok开发环境，包括本地调试和集成测试的完整流程。无论你是新手开发者还是经验丰富的工程师，都能通过本指南快速上手pgrok项目的开发工作。

为什么需要本地开发环境？🚀

搭建本地开发环境对于pgrok项目开发至关重要。通过本地环境，你可以：

1. 实时调试：快速测试代码变更，无需部署到远程服务器
2. 集成测试：运行完整的端到端测试，确保功能正常
3. 快速迭代：缩短开发反馈周期，提高开发效率
4. 学习项目架构：深入理解pgrok的各个组件如何协同工作

前置依赖安装指南📦

开始搭建pgrok开发环境前，需要安装以下依赖：

• Git (v2或更高版本)：用于代码版本控制
• Go (v1.20或更高版本)：pgrok后端的主要编程语言
• pnpm (v8或更高版本)：前端包管理器
• Task (v3)：任务运行器，简化开发流程
• Overmind (v2)：进程管理器，管理多个服务
• PostgreSQL (v10或更高版本)：数据库服务

在macOS上，可以使用Homebrew一键安装：

brew install git go pnpm go-task overmind postgresql@15
brew services start postgresql@15

确保psql命令行工具在$PATH中可用。

数据库初始化配置步骤🔧

pgrok依赖PostgreSQL数据库存储配置和用户信息。按以下步骤初始化数据库：

# 为当前Unix用户创建数据库
createdb

# 创建超级用户pgrokd并设置密码
createuser --superuser pgrokd
psql -c "ALTER USER pgrokd WITH PASSWORD 'pgrokd';"

# 创建pgrokd数据库，指定所有者
createdb --owner=pgrokd --encoding=UTF8 --template=template0 pgrokd

获取源代码与项目结构📁

克隆pgrok项目代码，建议使用浅克隆以节省时间：

git clone --depth 10 https://gitcode.com/gh_mirrors/pg/pgrok.git
cd pgrok

项目主要目录结构如下：

• pgrok/cli：客户端命令行工具源码
• pgrokd/cli：服务器端命令行工具源码
• pgrokd/web：Web管理界面前端代码
• internal/：内部共享库和工具函数
• integration-tests/：集成测试相关代码

配置文件设置与说明⚙️

在项目根目录创建pgrokd.yml配置文件，这是开发环境的核心配置：

external_url: "http://localhost:3320"
web:
  port: 3320
proxy:
  port: 3000
  scheme: "http"
  domain: "localhost:3000"
sshd:
  port: 2222

database:
  host: "localhost"
  port: 5432
  user: "pgrokd"
  password: "pgrokd"
  database: "pgrokd"

identity_provider:
  type: "oidc"
  display_name: "OIDC"
  issuer: "http://localhost:9833"
  client_id: "winnerwinner"
  client_secret: "chickendinner"
  field_mapping:
    identifier: "email"
    display_name: "name"
    email: "email"

这个配置启用了本地OIDC认证服务器，简化了开发环境的认证流程。

启动开发服务器的完整流程🚀

使用Overmind启动所有开发服务器：

overmind start

这个命令会启动三个关键服务：

1. pgrokd服务器：主服务器进程，监听3320端口
2. Web前端开发服务器：Vite开发服务器，热重载前端代码
3. 模拟OIDC服务器：本地OIDC认证服务器，监听9833端口

启动成功后，访问 http://localhost:3320 即可看到pgrok的Web管理界面。

集成测试环境搭建🧪

pgrok提供了完整的集成测试套件，确保各项功能正常工作。运行集成测试需要指定-long标志：

cd integration-tests
go test -v -long

集成测试会：

1. 启动模拟OIDC服务器
2. 构建并启动pgrokd服务器
3. 构建并启动pgrok客户端
4. 执行HTTP和TCP隧道测试
5. 验证动态转发功能

测试代码位于integration-tests/main_test.go，包含了完整的端到端测试场景。

前端开发环境配置🎨

pgrok的Web界面使用React + TypeScript + TailwindCSS构建。前端开发环境配置如下：

cd pgrokd/web
pnpm install  # 安装依赖
pnpm run dev  # 启动开发服务器

前端开发时，所有请求都会通过pgrokd的Web服务器代理，无需直接访问Vite服务器。这种配置简化了开发流程，确保前后端API调用的一致性。

客户端开发与测试🔧

pgrok客户端支持HTTP和TCP隧道功能。在开发环境中测试客户端：

# 构建客户端
task build-pgrok

# 运行HTTP隧道
./.bin/pgrok http --config pgrok.example.yml

# 运行TCP隧道  
./.bin/pgrok tcp --config pgrok.example.yml

客户端配置文件示例位于pgrok.example.yml，可以根据需要修改远程地址、转发地址和认证令牌。

常见问题与解决方案🔍

端口冲突问题

如果遇到端口冲突（2222、3000、3320、9833），可以修改pgrokd.yml中的端口配置。

数据库连接失败

确保PostgreSQL服务正在运行，并且数据库用户pgrokd有正确的权限。

认证失败

开发环境使用模拟OIDC服务器，确保其正常运行。可以检查integration-tests/oidc-server/目录下的代码。

前端热重载不工作

检查Vite服务器是否正常启动，可以通过查看Overmind的日志输出确认。

开发工作流最佳实践✨

1. 代码变更测试：使用task build-pgrok和task build-pgrokd快速构建二进制文件
2. 自动重启：Overmind会自动监视文件变化并重启相关服务
3. 集成测试：每次重大变更后运行集成测试确保兼容性
4. 前端开发：修改前端代码后，Vite会自动热更新，无需手动刷新
5. 配置管理：使用版本控制跟踪pgrokd.yml的变更

总结与下一步📚

通过本指南，你已经成功搭建了完整的pgrok开发环境。现在你可以：

• 修改后端Go代码并实时测试
• 开发前端React组件
• 运行集成测试验证功能
• 调试HTTP/TCP隧道问题

pgrok的模块化架构使得各个组件可以独立开发和测试。建议从internal/目录开始探索共享库，然后逐步深入到pgrok/cli和pgrokd/cli的具体实现。

记住，开发环境的稳定运行是高效开发的基础。如果遇到问题，可以参考项目的Procfile和Taskfile.yaml文件，了解各个服务的启动顺序和依赖关系。

祝你开发顺利！🎉

【免费下载链接】pgrok Poor man's ngrok - a multi-tenant HTTP/TCP reverse tunnel solution through SSH remote port forwarding 项目地址: https://gitcode.com/gh_mirrors/pg/pgrok