본문으로 바로가기 본문 바로가기
WIKI 기술 지식 베이스

배포 문제 해결하기

원문 보기 위키 갱신

이 페이지에서는 Fly.io에서 사람들이 가장 자주 겪는 문제와 해결 방법을 다룹니다. 오류 코드부터 배포 실패, 콜드 스타트, 머신 수명 주기, 네트워킹, 데이터베이스 연결까지 상황별로 정리했으니 내 문제를 찾아 바로 대처해 보세요.

출처: 문서

본문

이 페이지에서는 Fly.io에서 사람들이 가장 자주 겪는 문제와 해결 방법을 다룹니다. 여기에 없는 문제라면 커뮤니티 포럼을 확인해 보세요.

먼저 이렇게 해 보세요

오류가 명확하지 않다면 여기서 시작하세요.

  • flyctl 업데이트: fly version update — 오래된 버전은 이상한 실패를 일으킵니다.
  • 진단 실행: fly doctor — WireGuard, IP, Docker를 확인합니다.
  • fly.toml 검토: fly config validate를 실행해 문법과 구성 오류를 잡아내세요. 형식, 포트 번호, 최근 변경 사항을 구성 참조와 대조해 확인하세요.
  • 로그 확인: 한 터미널에서 fly logs를 실행하면서 다른 터미널에서 명령을 실행하세요. 더 자세히 보려면 LOG_LEVEL=debug fly deploy.
  • SSH 접속: fly ssh console (특정 머신을 고르려면 -s 사용).

내 문제 찾기

오류 코드

502 Bad Gateway

Fly 프록시가 머신에 도달했지만 앱이 올바르게 응답하지 않았습니다. 일반적인 원인:

먼저 fly logs를 확인하세요. 배포 직후에 502가 보이면 앱에 시작 시간이 더 필요할 수 있습니다 — 헬스 체크 유예 기간을 늘리세요. 간헐적으로 발생한다면 로그에서 OOM 킬을 확인하거나 SSH로 들어가 free나 htop으로 메모리 사용량을 확인하세요.

OOM 킬은 프록시 입장에서는 크래시로 보입니다. 머신의 메모리가 부족하다면 RAM을 추가하세요.

503 Service Unavailable

정상 머신이 없습니다. 머신이 모두 중지됐거나, 헬스 체크에 실패했거나, 지역 문제가 있거나 그중 하나입니다.

fly status

머신이 started로 표시되는데도 503이 계속 나온다면 헬스 체크가 실패하고 있을 가능성이 높습니다. fly checks list를 실행해 헬스 체크 결과를 확인하세요. "connection refused" 같은 오류는 fly logs에 나타나지 않습니다. 둘 다 확인해 보세요. 헬스 체크 실패를 참조하세요.

모든 머신이 중지되어 있고 자동 시작이 깨워 주기를 기대한다면 [[services]] 또는 [http_service] 구성을 확인하세요 — 프록시가 트래픽을 어디로 라우팅할지 알아야만 자동 시작이 동작합니다. Autostart and autostop을 참조하세요.

Registry 401 오류

failed to push registry: 401 Unauthorized

이 오류는 fly deploy 중에 나타납니다. 두 가지 가능한 원인:

  1. 인증 토큰이 오래됐습니다. 해결 방법:
fly auth logout
fly auth login
  1. Fly 레지스트리 장애가 있습니다. status.flyio.net을 확인하세요. 진행 중인 장애가 있으면 기다리거나 업데이트를 구독하세요.

이미지 크기 제한이 8GB라는 점에 주의하세요. 이미지가 이 한도를 초과하면 push가 실패합니다.

403 Forbidden

403은 다양한 곳에서 발생할 수 있습니다:

앱의 CORS 구성에서: Fly 프록시는 CORS를 강제하지 않고 WAF 역할도 하지 않습니다. 403 Invalid CORS request가 보인다면 이는 Fly가 아니라 애플리케이션의 CORS 미들웨어에서 오는 것입니다. 앱의 CORS 구성을 확인하고 클라이언트가 보내는 Origin 헤더가 허용된 오리진 목록에 있는지 확인하세요.

타사 API에서 (아웃바운드): 앱이 외부 API를 호출하다가 403을 받는다면 타사가 Fly의 IP 범위를 차단하고 있을 수 있습니다. Cloudflare로 보호되는 서비스에서 흔한 일입니다. 해결 방법: fly ips allocate-egress로 앱 범위의 egress IP를 할당해 아웃바운드 트래픽이 허용 목록에 추가할 수 있는 일관된 IP에서 나오게 하거나, 타사 서비스에 문의하세요. 앱 범위 egress IP와 일부 주의사항에 대해 더 읽어볼 수 있습니다.

객체 스토리지에서: S3 호환 스토리지는 권한 문제가 있으면 403을 반환합니다. 버킷 정책, 액세스 키, 지역 구성을 다시 확인하세요.

Cloudflare 사용 시 520 오류

520은 Cloudflare 전용 코드입니다: "웹 서버가 예상치 못한 응답을 반환했습니다." Fly 앞에 Cloudflare를 두고 있을 때 이는 보통 Fly의 프록시가 Cloudflare가 이해하지 못하는 응답 헤더를 보냈기 때문입니다. TE: trailers 헤더가 알려진 원인입니다.

Cloudflare를 사용한다면:

  • SSL 모드를 **Full (strict)**로 설정하세요
  • Cloudflare 프록시 설정을 확인하세요
  • 520이 간헐적이라면 앱의 특정 응답 헤더와 관련이 있을 수 있습니다

참고: Cloudflare 자체가 다운되면 Cloudflare 뒤에 있는 Fly 호스팅 앱도 다운됩니다. Fly는 여전히 실행 중입니다 — 앞에 있는 CDN이 다운된 것입니다.

배포 실패

빌드 멈춤: Waiting for depot builder...

원격 빌드는 Depot을 사용합니다. Depot에 문제가 있으면 fly deploy가 멈춥니다.

빠른 해결책 — 레거시 원격 빌더로 전환:

fly deploy --depot=false

이렇게 하면 Depot을 우회하지만 여전히 원격으로 빌드합니다. 원격 빌드가 완전히 다운된 경우에는 자신의 머신에서 빌드하세요:

fly deploy --local-only

이 경우 로컬에 Docker가 설치되어 있어야 합니다. 업로드가 더 느리지만 어떤 원격 빌드 인프라에도 의존하지 않습니다.

빌드가 exit code: 1로 실패한다면 이는 Dockerfile 문제입니다 — Fly의 문제가 아닙니다. 로컬에서 디버그하세요:

docker build .

릴리스 명령 실패

릴리스 명령(Release commands)은 앱이 시작되기 전에 임시 머신에서 실행됩니다.

error running release_command machine: machine not found

이것은 보통 플랫폼 타이밍 문제입니다. 배포를 다시 시도하세요. 그래도 지속되면 fly logs를 확인해 릴리스 명령 머신이 왜 일찍 종료되는지 확인하세요.

failed to get manifest

이미지가 아직 레지스트리에 전파되지 않았습니다. 이는 2단계 배포(한 명령에서 빌드+push, 다른 명령에서 배포)에서 발생합니다. 단계 사이에 약 1분 기다리거나 다시 시도하세요.

컨테이너 레지스트리 속도 제한

too many requests

Fly에는 Docker Hub pull을 위한 캐싱 프록시가 있어서 Docker Hub 속도 제한이 빌드에 거의 영향을 주지 않습니다. 하지만 다른 레지스트리(예: GitHub Container Registry)에 호스팅된 이미지는 이 캐시를 거치지 않아 속도 제한에 걸릴 수 있습니다.

옵션:

  • 로컬로 빌드: fly deploy --local-only
  • 레거시 빌더 사용: fly deploy --depot=false
  • 프라이빗 레지스트리나 Docker Hub(캐시 혜택을 받는 곳)에 이미지를 push한 다음 fly deploy --image <your-registry/image:tag>로 배포

시크릿 또는 환경 변수 누락

앱이 시작 시 구성 누락을 호소하며 크래시한다면:

fly secrets list
fly config env

fly secrets set으로 설정한 시크릿은 런타임 시 환경 변수로 사용할 수 있습니다. 빌드 시점에는 사용할 수 없습니다. 빌드 시점에 필요한 값이라면 fly.toml에서 [build.args]를 사용하세요. 빌드 시점 시크릿에 대해 더 알아보려면 여기를 참조하세요.

이미지 크기 제한

머신에는 8GB 루트파일시스템 한도가 있습니다.

이미지가 너무 크다면:

  • 멀티 스테이지 Docker 빌드를 사용해 빌드 의존성을 제거하세요
  • 큰 자산을 볼륨이나 객체 스토리지로 옮기세요
  • 실수로 포함된 파일을 확인하세요 — .dockerignore를 추가하세요

빌드팩 배포

빌드팩도 작동하지만 Dockerfile이 더 안정적이고 더 많은 제어를 제공합니다. 빌드팩 문제가 생긴다면 전환을 고려해 보세요. fly launch 명령은 대부분의 프레임워크에 대해 Dockerfile을 생성합니다.

앱이 올바른 주소에서 수신 대기하지 않음

배포 중에 이 경고를 보게 됩니다:

WARNING The app is not listening on the expected address
and will not be reachable by fly-proxy.

앱은 fly.toml의 internal_port가 지정한 포트에서 0.0.0.0(localhost도, 127.0.0.1도 아님)에서 수신 대기해야 합니다.

fly.toml이 다음과 같다면:

[http_service]
  internal_port = 8080

앱은 0.0.0.0:8080에서 수신 대기해야 합니다.

흔한 실수:

  • 127.0.0.1 또는 localhost에서 수신 — 이는 머신 내부에서 온 연결만 허용합니다. Fly 프록시는 외부에서 연결하므로 앱에 도달할 수 없습니다. 일부 프레임워크(Rails, Django, Next.js)는 기본적으로 localhost를 사용합니다. 호스트를 명시적으로 0.0.0.0로 설정하세요.
  • 포트 불일치 — 앱은 3000에서 수신 대기하는데 internal_port가 8080입니다. 하나를 골라 일치시키세요.

프레임워크 예시:

Rails:

bin/rails server -b 0.0.0.0 -p 8080

Express / Fastify (Node.js):

// Express
app.listen(8080, '0.0.0.0')

// Fastify
fastify.listen({ port: 8080, host: '0.0.0.0' })

Flask / Django (via Gunicorn):

gunicorn --bind 0.0.0.0:8080 myapp:app

프로덕션에서 Flask나 Django의 내장 개발 서버를 사용하지 마세요. Gunicorn이나 다른 WSGI 서버를 사용하세요.

FastAPI (Uvicorn):

uvicorn main:app --host 0.0.0.0 --port 8080

헬스 체크 실패

헬스 체크는 Fly 프록시에게 머신이 트래픽을 받을 준비가 되었는지 알려줍니다. 머신이 헬스 체크에 실패하면 프록시는 그 머신으로 요청 라우팅을 중지합니다. 모든 머신이 헬스 체크에 실패하면 사용자는 503을 받습니다. 헬스 체크가 어떻게 동작하는지에 대한 전체 내용은 Health checks를 참조하세요.

메모리 부족 또는 CPU 높음

앱이 OOM이 나면 머신이 크래시하고 정의상 헬스 체크가 실패합니다.

fly machine status <machine-id>

OOM 킬 이벤트를 찾으세요. 해결: 메모리를 추가하세요.

fly scale memory 512

CPU 집약적 앱의 경우 적절한 머신 크기를 선택했는지 확인하세요. CPU와 RAM은 사전 정의된 조합으로 함께 확장됩니다.

유예 기간(Grace period)

헬스 체크가 시작되기 전에 앱에 시작 시간이 필요합니다. 실패한 헬스 체크는 재시도되지만, 각 실패는 다음 시도 전에 백오프를 추가합니다. 앱이 healthy가 되기까지 너무 오래 걸리면 배포가 실패할 수 있습니다.

첫 체크를 지연시키도록 유예 기간을 설정하세요:

[[services.tcp_checks]]
  grace_period = "10s"

시작이 느린 앱(Rails, Django, 대형 JVM 앱)이라면 15-30초가 필요할 수 있습니다. 확실하지 않다면 10s로 시작하고 배포가 계속 실패하면 늘리세요.

기타 헬스 체크 실패

  • 차단된 accept 루프: 앱의 메인 스레드가 바빠서 새 연결을 수락할 수 없습니다. CPU 작업을 백그라운드 스레드/워커로 옮기세요.
  • 200이 아닌 응답: HTTP 헬스 체크는 200을 기대합니다. 헬스 체크 엔드포인트가 리다이렉트, 인증 도전, 오류를 반환하면 체크가 실패합니다. 항상 200을 반환하는 전용 /healthz 엔드포인트를 사용하세요.
  • 시작 시 앱 패닉: fly logs에서 스택 트레이스를 확인하세요. 크래시를 고치세요. Fly에서만(로컬이 아닌) 발생한다면 시크릿과 환경 변수를 확인하세요.

암시적인 체크에 의존하지 말고 명시적인 HTTP 헬스 체크를 정의하세요:

[[services.http_checks]]
  grace_period = "10s"
  interval = "15s"
  method = "GET"
  path = "/healthz"
  timeout = "5s"

콜드 스타트

배포 후 또는 중지된 머신이 깨어날 때 첫 요청은 느립니다. 이는 예상된 일입니다 — 머신이 부팅하고 앱이 초기화해야 하기 때문입니다.

콜드 스타트 영향 줄이기:

  • 프록시가 앱을 기다리도록 헬스 체크에 유예 기간을 설정하세요. 유예 기간 참조.
  • [http_service] 구성에서 min_machines_running = 1로 머신 하나를 항상 유지하세요. 이렇게 하면 최소 하나의 머신이 항상 실행됩니다.
  • 콜드 스타트 지연이 깨어나는 속도보다 중요하다면 suspend 대신 stop을 사용하세요. suspend는 재개가 빠르지만 클럭 문제가 있습니다.
  • 시작을 가볍게 하세요. 무거운 프레임워크의 경우 필수가 아닌 초기화를 미루세요. 헬스 체크 엔드포인트가 전체 앱이 준비되기 전에 응답하게 하세요.

배포 후 첫 요청이 항상 실패한다면(느린 것뿐 아니라) 유예 기간이 너무 짧은 것입니다. 프록시가 요청을 보내지만 앱이 준비되지 않아 요청이 타임아웃됩니다.

머신 수명 주기 문제

갇힌 머신

머신은 때때로 상태(replacing, starting, created)에 갇혀 명령에 응답하지 않게 됩니다.

순서대로 시도해 보세요:

  1. 재시작:
fly machine restart <machine-id>
  1. 강제 업데이트 (아무 메타데이터 변경이든 플랫폼 상태를 풀어줄 수 있습니다):
fly machine update <machine-id> --yes --metadata foo=bar
  1. 강제 파괴 (극단적인 방법 — 머신을 파괴합니다):
fly machine destroy --force <machine-id>

강제 파괴 후에는 다시 스케일 업해 교체하세요:

fly scale count <n>

머신이 시작 직후 중지됨

머신이 시작하자마자 중지된다면 앱의 프로세스가 종료되고 있는 것입니다. 머신이 실행할 것이 없어서 종료합니다.

  • Dockerfile에 명시적인 CMD가 있는지 확인하세요. 기본 이미지 기본값에 의존하지 마세요.
  • 로컬에서 테스트: docker run <your-image>. Docker에서 즉시 종료된다면 Fly에서도 즉시 종료됩니다.
  • fly logs에서 앱의 종료 코드와 오류 출력을 확인하세요.

일시 중지 vs 중지

stop은 VM을 종료합니다. suspend는 메모리를 디스크에 스냅샷했다가 나중에 재개합니다 — 깨어나는 것이 더 빠르지만 트레이드오프가 있습니다.

클럭 문제: 머신이 일시 중지에서 재개될 때 시스템 클럭이 잠시 틀립니다. 머신이 일시 중지됐던 시각인 것으로 생각합니다. 이로 인해 깨지는 것:

  • JWT 검증 — 토큰이 미래에 발급된 것처럼 보임 (nbf 클레임 실패)
  • Cron 작업 — 스케줄된 작업이 잘못된 시간에 실행됨
  • 캐시 TTL — 만료 시간이 어긋남
  • TLS 인증서 검증 — 인증서 타임스탬프가 일치하지 않음

클럭은 빠르게 스스로 교정되지만, 앱이 재개 후 처음 몇 순간에 타임스탬프를 확인한다면 문제가 생깁니다.

해결: 앱이 JWT, 시간 민감 스케줄링, 시작 시 인증서 검증을 사용한다면 suspend 대신 stop을 사용하세요:

[http_service]
  auto_stop_machines = "stop"

또는 JWT 검증에 클럭 오차 허용(몇 초의 여유)을 추가하세요.

init 프로세스

Fly는 머신이 시작될 때 런타임에 가벼운 init 프로세스를 주입합니다. 이미지를 수정하지 않습니다 — VM 안의 앱 앞에서 실행됩니다.

이 init이 처리하는 것:

  • 고아가 된 자식 프로세스 수거 (PID 1의 책임)
  • 호스트에서 앱으로 시그널 전달
  • 네트워킹과 볼륨 마운트 설정
  • 깔끔한 종료 조율

Dockerfile에 tini, dumb-init, s6-overlay는 필요 없습니다. Fly의 init이 이러한 책임을 모두 다룹니다. 이미 있다면 두는 것도 문제되지 않습니다 — 그냥 중복일 뿐입니다.

Fly의 init은 비활성화하거나 교체할 수 없습니다. 앱이 시작되기 전에 설정 스크립트가 필요하다면, 설정을 실행한 다음 앱을 exec하는 Docker ENTRYPOINT 스크립트를 사용하세요.

네트워킹과 연결

사용자 지정 도메인과 TLS

사용자 지정 도메인에 TLS 오류가 표시된다면 활성 확인을 해 보세요:

fly certs show <hostname>

A 및 AAAA 레코드가 모두 있거나, Fly를 가리키는 단일 CNAME 레코드가 필요합니다 (CNAME과 A/AAAA를 섞지 마세요).

Cloudflare를 사용하시나요? Fly의 TLS 문제 대부분은 Cloudflare 뒤의 도메인과 관련이 있습니다. 더 디버그하기 전에 Understanding Cloudflare를 읽어보세요. 다른 모든 설정에 대해서는 Custom domains를 참조하세요.

Flycast (내부 로드 밸런싱)

Flycast는 사설 네트워크를 통해 Fly 앱 사이에서 트래픽을 라우팅합니다. 두 가지 주의사항:

force\_https는 false여야 합니다. Flycast는 HTTP 전용입니다. force_https를 사용하지 마세요:

# Wrong for Flycast
[http_service]
  force_https = true

# Right for Flycast
[http_service]
  force_https = false

일반 TCP 서비스는 [http_service]가 아니라 protocol = "tcp"인 [[services]]가 필요합니다:

[[services]]
  internal_port = 8080
  protocol = "tcp"

  [[services.ports]]
    handlers = []
    port = 4321

아웃바운드 연결

공유 IPv4에서 원시 TCP는 동작하지 않습니다. Fly의 공유 IPv4 주소는 프록시를 사용하며, 가상 호스트 트래픽을 라우팅하려면 SNI(TLS에서)나 Host 헤더(HTTP에서)가 필요합니다. 암호화되지 않은 Redis, 25번 포트의 SMTP, 원시 소켓 연결 같은 비 HTTP, 비 TLS TCP 연결은 공유 IP에서 프록시가 어느 앱으로 라우팅할지 식별할 수 없어 실패합니다.

해결 방법:

  • 전용 IPv4 할당: fly ips allocate-v4 — 앱에 자체 IP를 주므로 가상 호스트 라우팅이 필요 없습니다
  • Fly 사설 네트워크의 서비스에는 .internal 주소 사용 — 이는 프록시를 완전히 우회합니다

SMTP: 아웃바운드 이메일에 문제가 있다면 머신에서 직접 보내는 대신 트랜잭션 이메일 서비스(Postmark, Resend, SendGrid 같은)를 사용하는 것을 권장합니다.

CORS 문제

앱에 대한 POST 요청이 403을 반환한다면 거의 확실히 앱의 CORS 미들웨어 문제입니다. Fly 프록시는 WAF가 없고 CORS를 강제하지 않습니다.

  • 클라이언트가 보내는 Origin 헤더가 앱의 허용 오리진 목록에 있는지 확인하세요
  • 앱이 사전 요청(OPTIONS) 응답에서 올바른 Access-Control-Allow-Origin 헤더를 반환하는지 확인하세요
  • curl로는 동작하는데 브라우저에서 실패한다면, 이는 Fly 문제가 아니라 앱의 CORS 문제임을 확인시켜 줍니다

데이터베이스 연결

Managed Postgres

MPG 클러스터는 Fly의 사설 네트워크에서 실행되며 공개 인터넷에서 접근할 수 없습니다. 연결 문자열은 .flympg.net 도메인을 사용하며, 이는 사설 네트워크 주소로 해석됩니다. 전체 내용은 Create and connect to MPG를 참조하세요.

로컬 머신에서 연결하려면:

  • 대화형 psql: fly mpg connect
  • localhost로 프록시: fly mpg proxy — 로컬 포트를 데이터베이스로 전달
  • WireGuard: 조직의 사설 네트워크에 연결한 다음 .flympg.net 연결 문자열을 직접 사용. 이 참조 가이드에서 자세히 읽어보세요.

fly mpg proxy가 타임아웃되면 먼저 fly mpg connect를 시도해 클러스터가 정상인지 확인하세요.

Redis와 Valkey

Fly 사설 네트워크에서는 IPv6가 필요합니다. 대부분의 Redis 클라이언트는 기본적으로 IPv4를 사용합니다. I/O 오류로 연결이 실패한다면:

// ioredis — set family: 6
const redis = new Redis(process.env.REDIS_URL, {
  family: 6,
  maxRetriesPerRequest: null,
  enableReadyCheck: false,
});

Fly의 Upstash Redis는 공개 TLS 엔드포인트가 아니라 IPv6를 통한 내부 엔드포인트를 사용하세요.

볼륨과 디스크 오류

unable to read superblock 같은 파일시스템 오류가 보인다면 볼륨이 손상된 것입니다. 드물지만 하드 크래시 후 발생할 수 있습니다.

스냅샷이 활성화되어 있다면:

fly volumes list
fly volumes snapshots list <volume-id>
fly volumes create <name> --snapshot-id <snapshot-id> --region <region>

스냅샷이 없다면 데이터를 복구하지 못할 수 있습니다. 소중한 데이터가 있는 볼륨에는 항상 스냅샷을 활성화하세요. Volume snapshots 참조.

대시보드와 계정 접근

로그인 불가 (GitHub SSO)

GitHub SSO가 작동을 멈추고 대시보드에 접근할 수 없다면:

  • CLI에서 fly auth logout 후 fly auth login을 시도하세요
  • 계정에서 SSO를 제거해야 한다면 **billing@fly.io**에 이메일을 보내세요 — SSO 변경 전에 소유권을 확인합니다

토큰 문제

토큰을 만들거나 관리할 수 없다면:

fly tokens list

특정 flyctl 버전에 토큰 관리 버그가 간헐적으로 나타납니다. 먼저 flyctl을 업데이트하세요. fly tokens create가 실패하면 커뮤니티 포럼에서 버전의 알려진 문제를 확인하세요.

지역 문제

Fly는 17개 지역의 배어메탈에서 실행됩니다. 개별 호스트나 지역이 나머지와 무관하게 문제가 있을 수 있습니다.

먼저 상태를 확인하세요: status.flyio.net

한 지역에서만 앱이 다운됐는데 상태 페이지가 정상이라면, 문제가 특정 호스트에만 해당할 수 있습니다. 실행:

fly status

머신이 어느 지역에 있고 정상인지 확인하세요.

완화: 여러 지역에 배포하세요. 모든 머신이 iad에 있는데 iad에 문제가 생기면 앱이 다운됩니다. 지역에 걸쳐 분산하세요:

fly scale count 2 --region iad,ord

데이터베이스의 경우 두 번째 지역에 읽기 복제본을 유지하세요. 지연 시간이 중요한 앱은 사용자와 가까운 지역을 고르세요 — 서유럽은 lhr과 ams, 아시아 태평양은 nrt와 sin.

지역이 다운됐고 긴급하게 배포해야 한다면 정상 지역으로 스케일하세요:

fly scale count 1 --region ord

관련 주제

더 알아보기 (Learn more)