ngrok 사용법 - 로컬 서버 외부 공개하는 법 완벽 가이드

안녕하세요, 우리들의 주파수 구독자 여러분! 로컬에서 띄운 웹 서버를 다른 사람에게 바로 보여주고 싶은데, 공유기 설정은 건드리기 싫을 때가 있습니다. 카카오톡 로그인 콜백 테스트, 웹훅(Webhook) 수신, 거래처에 데모 공유까지 — 이럴 때 가장 빠른 해법이 ngrok입니다. 설치부터 HTTPS 공개, 자주 막히는 지점, 대안 툴 비교까지 한 번에 정리했습니다.

1. ngrok이란?

ngrok은 내 컴퓨터(localhost)에서 돌아가는 서버를 외부 인터넷에서 접속 가능한 주소로 즉시 연결해주는 터널링 도구입니다. 공유기 포트포워딩, 고정 IP, 방화벽 설정 없이도 명령어 한 줄로 https://랜덤문자열.ngrok-free.app 같은 공개 URL이 생성됩니다.

이럴 때 씁니다:

• 결제 모듈(토스페이먼츠, 포트원 등)·카카오 로그인처럼 외부 서버가 내 로컬로 콜백을 보내야 할 때
• 깃허브·슬랙 웹훅(Webhook)을 로컬에서 받아서 디버깅할 때
• 고객·팀원에게 배포 전 데모를 빠르게 보여줄 때
• 모바일 기기에서 내 PC의 개발 서버에 접속해 테스트할 때

운영 서버를 영구적으로 공개하는 용도는 아닙니다. 그 목적이라면 실제 호스팅이나 포트포워딩, Tailscale 같은 상시 연결 솔루션이 맞습니다.

2. 설치하는 법

Windows

1. ngrok 공식 사이트에서 Windows용 zip을 받는다.
2. 압축을 풀면 ngrok.exe 하나만 들어 있다. 원하는 폴더(예: C:\ngrok)에 둔다.
3. 매번 경로를 입력하기 번거로우면 해당 폴더를 환경변수 PATH에 추가한다.
   • 시작 메뉴 → “환경 변수 편집” 검색 → 시스템 변수의 Path → 새로 만들기 → C:\ngrok 추가

또는 choco install ngrok (Chocolatey)로도 설치 가능합니다.

macOS

brew install ngrok

Linux (Debian/Ubuntu)

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update && sudo apt install ngrok

3. 계정 연결 (authtoken 등록)

ngrok은 2023년부터 무료 플랜도 회원가입이 필수입니다. 익명 터널은 더 이상 지원하지 않습니다.

1. ngrok 대시보드에서 가입(구글 계정으로 가능).
2. 로그인 후 Your Authtoken 메뉴에서 토큰 문자열을 복사.
3. 터미널에서 1회만 등록하면 이후 계속 유지됩니다.

ngrok config add-authtoken <복사한_토큰>

등록된 설정은 ~/.config/ngrok/ngrok.yml(macOS/Linux) 또는 %USERPROFILE%\AppData\Local\ngrok\ngrok.yml(Windows)에 저장됩니다.

4. 기본 사용법 — 로컬 서버 공개하기

로컬에서 웹 서버가 3000번 포트로 떠 있다고 가정합니다(React, Express, Flask, Spring 등 무엇이든 상관없습니다).

ngrok http 3000

실행하면 터미널에 아래와 같은 화면이 뜹니다.

Session Status                online
Account                       [email protected] (Plan: Free)
Version                       3.x.x
Region                        Asia Pacific (ap)
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://a1b2-c3d4-e5f6.ngrok-free.app -> http://localhost:3000

Connections                   ttl     opn     rt1     rt5     p50     p90
                               0       0       0.00    0.00    0.00    0.00

Forwarding에 표시된 https://a1b2-c3d4-e5f6.ngrok-free.app 주소가 바로 외부에서 접속 가능한 공개 URL입니다. 이 주소를 그대로 브라우저·모바일·협력사에 공유하면 내 로컬 서버로 요청이 전달됩니다.

포트 번호만 바꿔서 다른 서비스도 공개 가능: HTTP API 서버가 8080이면 ngrok http 8080, 로컬 웹소켓 서버도 동일하게 작동합니다.

요청 로그 확인하기

ngrok http 3000을 실행한 상태에서 브라우저로 http://127.0.0.1:4040에 접속하면, **들어온 요청·응답을 실시간으로 확인하고 재전송(Replay)**할 수 있는 웹 대시보드가 열립니다. 웹훅 디버깅할 때 특히 유용합니다 — 요청이 왔는지, 어떤 payload였는지 바로 확인됩니다.

5. 자주 쓰는 옵션

설정을 매번 입력하기 귀찮다면 ngrok.yml에 저장해두고 한 번에 실행할 수도 있습니다.

version: "3"
agent:
    authtoken: <토큰>
tunnels:
  web:
    proto: http
    addr: 3000
  api:
    proto: http
    addr: 8080

ngrok start --all   # yml에 등록한 터널을 전부 실행

6. 무료 플랜 제약 사항

무료 플랜은 테스트·디버깅용으로는 충분하지만, URL이 매번 바뀌는 점이 가장 큰 불편입니다. 카카오 로그인 콜백 URL처럼 사전 등록이 필요한 경우라면, 터널을 재시작할 때마다 콜백 주소를 다시 등록해야 합니다. 이 경우 유료 플랜의 고정 도메인을 쓰거나, 아래 대안 툴을 검토하는 것이 낫습니다.

7. 포트포워딩과 뭐가 다른가요?

상시 운영 서비스(홈서버, 게임 서버 등)를 공개하려면 공유기 포트포워딩 가이드를 참고하세요. 테스트·디버깅 목적이라면 ngrok이 압도적으로 빠릅니다.

8. 대안 툴 비교

이미 Tailscale을 쓰고 있다면 Funnel 기능으로 바로 공개할 수 있어 편리합니다. 완전 무료로 고정 주소가 필요하다면 Cloudflare Tunnel이 유리하지만, 초기 설정(도메인 Cloudflare 연결)이 필요합니다. 빠르게 한 번 테스트만 하고 끝낼 거라면 ngrok이나 localtunnel이 가장 간단합니다.

9. 자주 묻는 질문 (FAQ)

Q. ngrok 실행할 때마다 URL이 바뀌는데 고정할 수 없나요? 무료 플랜에서는 불가능합니다. 유료 플랜(Personal 이상)에서 고정 서브도메인 또는 커스텀 도메인을 연결할 수 있습니다.

Q. “ngrok 경고 페이지”가 떠서 당황스러워요. 무료 플랜 터널에 처음 접속하는 사용자에게는 “이 사이트는 ngrok을 통해 제공됩니다”라는 안내 페이지가 한 번 뜹니다. 정상적인 동작이며, 버튼을 누르면 실제 페이지로 넘어갑니다. 제거하려면 유료 플랜이 필요합니다.

Q. 방화벽이나 백신이 ngrok을 차단해요. 일부 백신이 터널링 도구를 의심 프로세스로 분류할 수 있습니다. 공식 사이트에서 받은 바이너리인지 확인하고, 필요시 예외 처리하세요. 회사 네트워크에서는 보안 정책상 아웃바운드 연결 자체가 막혀 있을 수도 있습니다.

Q. HTTPS가 자동으로 적용되나요? 네. ngrok http 명령 하나로 HTTP·HTTPS 포워딩 URL이 모두 발급됩니다. 별도 인증서 설정이 필요 없습니다.

Q. 로컬 서버가 떠 있지 않은데 ngrok만 실행하면 되나요? 안 됩니다. ngrok은 터널(연결 통로)만 만들어줄 뿐, 요청을 받아 처리하는 건 여전히 로컬에서 돌아가는 서버입니다. 먼저 로컬 서버를 실행한 뒤 ngrok을 실행해야 합니다.

Q. 보안은 괜찮은가요? 임시 테스트 목적이라면 무방하지만, 터널이 열려 있는 동안 해당 URL을 아는 사람은 누구나 접근 가능합니다. 민감한 데이터를 다루는 서버라면 --basic-auth 옵션으로 접근을 제한하거나, 테스트가 끝나면 즉시 터널을 종료(Ctrl+C)하세요.

10. 핵심 요약

• ngrok은 로컬 서버를 외부에 즉시 공개하는 터널링 도구로, 포트포워딩 없이 명령어 한 줄(ngrok http 포트번호)로 HTTPS 공개 URL을 받을 수 있다.
• 사용 전 회원가입 + authtoken 등록(ngrok config add-authtoken)이 필수다.
• 무료 플랜은 URL이 매번 바뀌고 트래픽·경고 페이지 제약이 있으니, 고정 주소가 필요하면 유료 플랜이나 Cloudflare Tunnel·Tailscale Funnel을 검토한다.
• 상시 운영 서비스는 포트포워딩이, 임시 테스트·웹훅 디버깅은 ngrok이 적합하다.
• http://127.0.0.1:4040 웹 대시보드로 요청 로그를 실시간 확인할 수 있어 디버깅에 특히 유용하다.

댓글

🖼 이미지/GIF

등록

처음 쓰는 닉네임이면 자동 등록됩니다. 같은 닉네임 재사용/삭제엔 같은 비밀번호를 입력하세요.

불러오는 중…