[tool] Ngrok 란? - 로컬 서버의 외부 포트열기

Posted Nov 15, 2024 Updated Jan 29, 2025

By 뱅가드

6 min read

NGROK: 로컬 애플리케이션을 외부에 노출시키는 간단한 방법

Ngrok은 로컬 환경에서 실행 중인 애플리케이션을 외부 네트워크에 노출할 수 있게 해주는 터널링 도구입니다. 주로 개발 및 디버깅 목적으로 사용되며, SSL 암호화 및 보안 인증을 제공하여 안전한 연결을 보장합니다. 이 글에서는 Ngrok의 작동 원리, 설치 방법, 사용 사례, 명령어, 고급 설정까지 체계적으로 다룹니다.

1. Ngrok이란 무엇인가?

Ngrok은 로컬 호스트를 외부에서 접근 가능하도록 만들어주는 서비스입니다. HTTP, HTTPS, TCP 트래픽을 로컬 환경으로 터널링하여 외부에D서 안전하게 접근할 수 있도록 지원합니다.

주요 기능:
- 로컬 웹 서버를 인터넷에 노출
- SSL 인증서 자동 제공
- 실시간 요청/응답 디버깅
- 비밀번호 및 IP 화이트리스트를 통한 보안 강화
활용 사례:
- 웹훅(Webhook) 테스트
- 외부 클라이언트와의 협업 (디자인 및 기능 데모)
- IoT 기기의 원격 제어
- 클라우드 환경에서 미리보기 제공

2. Ngrok 설치하기

2.1. 시스템 요구사항

Ngrok은 대부분의 운영 체제에서 실행할 수 있습니다. 공식적으로 지원하는 환경은 다음과 같습니다:

Windows
macOS
Linux

2.2. 설치 과정

공식 웹사이트에서 다운로드
- Ngrok 다운로드 페이지에서 운영 체제에 맞는 바이너리를 다운로드합니다.
설치
- 다운로드한 파일을 실행 가능하도록 설정합니다.
  1 chmod +x ngrok
- 시스템 경로에 파일을 복사하여 어디서나 실행할 수 있도록 설정합니다.
  1 sudo mv ngrok /usr/local/bin
Ngrok 인증
- Ngrok 계정을 생성하고 로그인한 뒤, 대시보드에서 Authtoken을 복사합니다.
- 터미널에서 다음 명령어를 실행하여 인증합니다.
  1 ngrok config add-authtoken <your-authtoken>

3. Ngrok 사용 방법

3.1. HTTP/HTTPS 터널링

로컬에서 실행 중인 웹 서버(예: http://localhost:8080)를를/) 외부에서 접근 가능하도록 설정합니다.

ngrok http 8080

출력 예시:

ngrok                                                                              
Session Status                online                                              
Account                       example@gmail.com (Plan: Free)                      
Version                       3.x.x                                              
Region                        United States (us)                                 
Web Interface                 http://127.0.0.1:4040                              
Forwarding                    http://1234abcd.ngrok.io -> http://localhost:8080   
                              https://1234abcd.ngrok.io -> http://localhost:8080  

위와 같은 URL을 사용하면 외부에서도 로컬 서버에 접근할 수 있습니다.

3.2. TCP 터널링

TCP 프로토콜 기반의 서비스(예: 데이터베이스)를 외부에 노출하려면 다음 명령어를 사용합니다.

ngrok tcp 3306

결과: tcp://1.tcp.ngrok.io:12345와 같은 주소가 제공됩니다.

3.3. Subdomain 설정

Ngrok의 무료 버전은 무작위 URL을 제공합니다. 특정 서브도메인을 사용하려면 유료 플랜이 필요합니다.

ngrok http -subdomain=myapp 8080

결과: https://myapp.ngrok.io

4. 고급 설정

4.1. Ngrok 구성 파일

Ngrok은 기본 설정을 자동화하기 위해 YAML 형식의 구성 파일을 제공합니다.

파일 위치:
- macOS/Linux: ~/.ngrok2/ngrok.yml
- Windows: %USERPROFILE%\.ngrok2\ngrok.yml

구성 예시:

  
authtoken: <your-authtoken>
region: ap
tunnels:
  web:
    proto: http
    addr: 8080
  database:
    proto: tcp
    addr: 3306

명령어 없이 설정된 터널을 실행하려면:
1 ngrok start web database

4.2. 보안 강화

HTTP Basic Authentication:

  
ngrok http -auth="user:password" 8080

IP 화이트리스트: YAML 파일에서 IP 제한을 설정할 수 있습니다.

  
tunnels:
  secure:
    proto: http
    addr: 8080
    host_header: rewrite
    inspect: false
    auth: "user:password"
    ip_whitelist: ["203.0.113.0/24", "198.51.100.42"]

5. 디버깅 및 모니터링

Ngrok은 로컬 웹 인터페이스를 통해 실시간 트래픽을 확인할 수 있습니다.

URL: http://127.0.0.1:4040
기능
:
- 요청/응답 로그 보기
- 데이터 페이로드 검사
- 재요청(Retry) 기능

6. 주요 Ngrok 명령어 요약

명령어	설명
`ngrok http 8080`	HTTP 터널 생성
`ngrok tcp 3306`	TCP 터널 생성
`ngrok start <name>`	구성 파일의 특정 터널 실행
`ngrok config add-authtoken`	Authtoken 등록
`ngrok status`	현재 세션 상태 확인

7. 유료 플랜의 장점

Ngrok은 무료로도 충분히 강력하지만, 유료 플랜에서는 더 많은 기능을 제공합니다:

사용자 정의 도메인
트래픽 용량 증가
팀 관리 기능

8. 문제 해결

8.1. “Tunnel not found” 오류

원인: 세션이 만료되었거나 터널이 종료되었습니다.
해결: Ngrok 명령어를 재실행하세요.

8.2. 특정 포트에서 연결이 안 됨

원인: 방화벽 설정 또는 포트 충돌 문제
해결: 방화벽 설정을 확인하거나 다른 포트를 사용하세요.

웹 서버

Web

This post is licensed under CC BY 4.0 by the author.