Poor man's ngrok

SSH 원격 포트 포워딩 기반의 자가 호스팅 멀티테넌트 리버스 터널 솔루션

pgrok은 SSH 프로토콜의 원격 포트 포워딩을 활용하여 로컬 개발 환경을 인터넷에 안전하게 노출해주는 도구입니다.

• 멀티테넌트: 하나의 서버에서 여러 사용자가 각자의 서브도메인을 가질 수 있습니다.
• OIDC 인증: Google, GitHub 등 SSO 제공업체를 통해 터널 접근을 제어합니다.
• HTTP/TCP 지원: 웹 사이트뿐만 아니라 DB 등 Raw TCP 트래픽도 터널링 가능합니다.
• 멀티 프로필: 클라이언트에서 여러 서버 설정을 프로필 형태로 관리할 수 있습니다.

1. 도메인: (예: example.com)
2. 공인 IP가 있는 서버 (VPS): (예: 111.33.5.14)
3. SSO 제공업체: OIDC 클라이언트(Google, Keycloak 등) 생성 필요.
4. PostgreSQL: 데이터 저장용 데이터베이스.

• A 레코드: example.com -> 111.33.5.14
• A 레코드 (Wildcard): *.example.com -> 111.33.5.14

서버 바이너리를 빌드하기 위해 프런트엔드 에셋을 먼저 빌드해야 합니다.

# 1. 프런트엔드 빌드
cd pgrokd/web
npm install && npm run build

# 2. 서버 바이너리 빌드
cd ../../
go build -o pgrokd ./pgrokd/cli

# 크로스 컴파일 (Windows에서 리눅스용 빌드)
$env:GOOS = "linux"; $env:GOARCH = "amd64"
go build -o pgrokd-linux-amd64 ./pgrokd/cli

pgrokd.yml 파일을 작성합니다 (IPv6 지원을 원할 경우 bind_addr를 [::]로 설정):

external_url: "http://example.com"
web:
  port: 3320
  bind_addr: "0.0.0.0" # IPv4/IPv6 공용은 "[::]" 사용
proxy:
  port: 3000
  bind_addr: "0.0.0.0" # IPv4/IPv6 공용은 "[::]" 사용
sshd:
  port: 2222
  bind_addr: "0.0.0.0" # IPv4/IPv6 공용은 "[::]" 사용
database:
  host: "localhost"
  # ... 나머지 DB 설정
identity_provider:
  # ... OIDC 설정

호스트에 바이너리를 직접 올려 실행할 경우, 설정 파일을 원하는 위치에 둔 뒤 --config로 지정하면 됩니다.

# 예시: Linux 서버
mkdir -p /etc/pgrokd
cp pgrokd.example.yml /etc/pgrokd/pgrokd.yml

# 설정 수정 후 실행
./pgrokd --config /etc/pgrokd/pgrokd.yml

주요 설정 항목은 다음과 같습니다.

• external_url: 사용자가 브라우저로 접속할 실제 주소
• proxy.domain: 터널 URL에 사용할 도메인
• database.*: PostgreSQL 접속 정보
• identity_provider.*: OIDC 로그인 설정

Caddy와 같은 리버스 프록시를 서버(포트 3000, 3320) 앞단에 배치하는 것을 권장합니다.

루트의 Dockerfile로 이미지를 빌드한 뒤 Docker Hub 저장소로 푸시할 수 있습니다.

# Docker Hub 로그인
docker login

# 이미지 빌드
docker build -f Dockerfile -t rhysho/pgrokd:v20260403 .

# Docker Hub 푸시
docker push rhysho/pgrokd:v20260403

docker-compose.yml에서 같은 이미지를 사용하려면 아래처럼 맞추면 됩니다.

services:
  pgrokd:
    image: "rhysho/pgrokd:v20260403"
    volumes:
      - "./deploy/pgrokd:/var/opt/pgrokd"

pgrokd 컨테이너는 /var/opt/pgrokd/pgrokd.yml을 읽으므로, 호스트에는 deploy/pgrokd/pgrokd.yml을 두면 됩니다.

Docker Compose로 실행할 때는 루트에 .env 파일을 두고, deploy/pgrokd/pgrokd.yml에 애플리케이션 설정을 채우면 됩니다.

# 예제 파일 복사
cp .env.example .env

# 필요하면 예제 설정을 참고해서 deploy/pgrokd/pgrokd.yml 수정
# PostgreSQL 계정과 비밀번호는 .env와 같은 값으로 맞춰야 함

docker compose up -d

.env에는 아래 값이 들어갑니다.

POSTGRES_USER=pgrok
POSTGRES_PASSWORD=change-me

deploy/pgrokd/pgrokd.yml에서는 최소한 아래 값을 실제 환경에 맞게 바꿔야 합니다.

• external_url
• proxy.domain
• database.user
• database.password
• identity_provider.issuer
• identity_provider.client_id
• identity_provider.client_secret

현재 compose 기준에서 database.host는 postgres, database.database는 pgrokd로 두면 됩니다.

사용 중인 OS에 맞게 바이너리를 빌드합니다.

# Windows
go build -o pgrok.exe ./pgrok/cli

# Linux/macOS
go build -o pgrok ./pgrok/cli

# 크로스 컴파일 (Windows에서 리눅스용 빌드)
$env:GOOS = "linux"; $env:GOARCH = "amd64"
go build -o pgrok-linux-amd64 ./pgrok/cli

init 명령어를 사용하여 서버 접속 정보를 저장합니다. 프로필 이름을 지정하지 않으면 자동으로 default 프로필로 저장됩니다.

# 기본(default) 프로필 생성
./pgrok init --remote-addr example.com:2222 --forward-addr 3000 --token {YOUR_TOKEN}

# 특정 업무용(work) 프로필 생성
./pgrok init --profile work --remote-addr work.com:2222 --forward-addr 8080 --token {WORK_TOKEN}

가장 간단한 실행 방법입니다. default 프로필을 사용하여 터널을 엽니다.

# 기본 설정으로 실행
./pgrok http

# 특정 로컬 포트를 지정하여 실행 (설정파일 값보다 우선)
./pgrok http 8080

저장해둔 특정 프로필을 호출하여 터널을 시작합니다.

./pgrok http --profile work

웹 트래픽이 아닌 환경(DB, SSH 등)을 터널링할 때 사용합니다.

./pgrok tcp 5432

별도의 클라이언트 설치 없이 표준 SSH 명령어로도 터널을 열 수 있습니다. (비밀번호 입력 시 발급받은 토큰 사용)

ssh -N -R 0::3000 example.com -p 2222