FastAPI 백엔드 최적화: Supabase에서 로컬 PostgreSQL로 DB 마이그레이션 및 트러블슈팅 (asyncpg, 524 에러) 경험기

👤 인스피

조회 수 13

1. 첫 번째 삽질: 환경변수(.env)를 바꿨는데 왜 접속을 못 하니? (Connection refused)

가장 먼저 겪은 황당한 문제는 DB 연결 오류였습니다. 로컬 서버에 PostgreSQL을 무사히 설치하고, .env 파일의 DB 접속 URL 포트를 클라우드용 포트에서 로컬 기본 포트인 5432로 변경했습니다. 그리고 서버를 재시작했는데... 화면에 끔찍한 에러가 출력되었습니다.

Connection refused: Cannot connect to port 6543

분명 .env에는 5432로 적어두었는데, 서버는 계속해서 엉뚱한 6543 포트를 찾으며 연결을 거부하고 있었습니다. 캐시를 지워보고 컨테이너를 껐다 켜봐도 소용이 없었습니다. 도대체 어디서 포트 번호가 꼬인 것일까요?

저는 리눅스 터미널을 열고 grep 명령어를 빼들었습니다. grep -rn "6543" . (현재 폴더와 하위 폴더에서 6543이라는 텍스트를 모두 찾아라!)

검색 결과는 충격적이었습니다. 과거에 Supabase 외부 커넥션 풀링(Connection Pooling)을 세팅할 때, database.py 파일 깊숙한 곳에 URL 문자열 중 .replace(":5432/", ":6543/")을 통해 강제로 포트를 변환해버리는 하드코딩 로직을 제가 직접 짜두고 까맣게 잊고 있었던 것입니다. 이 하드코딩된 줄을 찾아내어 깔끔하게 삭제하고 나니, 그제야 FastAPI가 로컬 DB(5432)에 정상적으로 뿌리를 내리기 시작했습니다. 과거의 제가 만든 함정에 제가 빠진 셈이죠.

2. 두 번째 삽질: 성능의 한계 돌파, 비동기 드라이버(asyncpg)로의 전환

로컬 DB로 연결은 성공했지만, 대량의 트래픽을 감당하기 위해 저는 기존에 사용하던 동기식 드라이버인 psycopg 대신, 파이썬에서 가장 빠른 비동기 PostgreSQL 드라이버인 asyncpg로 엔진을 교체하기로 했습니다.

하지만 드라이버를 바꾸자 이번에는 SQLAlchemy 설정에서 호환성 에러가 뿜어져 나왔습니다. 기존 동기식에서 잘 작동하던 커넥션 타임아웃이나 서버 세팅 인수들이 asyncpg 규격과 맞지 않았기 때문입니다. 공식 문서를 뒤져가며 database.py의 connect_args 설정을 비동기 규격에 맞게 튜닝했습니다.

이 튜닝을 거친 후, 비동기 처리의 마법이 시작되었습니다. 데이터베이스를 기다리느라 멈춰있던 백엔드 스레드들이 자유롭게 풀려나면서, 서버의 동시 처리 능력이 차원이 다르게 쾌적해졌습니다.

3. 세 번째 삽질: 클라우드플레어(Cloudflare) 524 에러의 늪

마침내 아키텍처 세팅을 끝내고, 봇을 가동하여 수십 개의 게시글을 한 번에 벌크 인서트(Bulk Insert) 하는 테스트를 진행했습니다. 그런데 업로드 도중 갑자기 웹 화면에 'Cloudflare 524 A timeout occurred' 에러가 뜨면서 중복 게시글이 올라가는 치명적인 버그가 발생했습니다.

원인은 백엔드의 '처리 시간'이었습니다. 벌크 업로드를 할 때 단순히 DB에 텍스트만 넣는 것이 아니라, 외부 번역 API를 호출하고 이미지를 리사이징하는 무거운 작업이 포함되어 있었습니다. 이 작업이 100초를 넘어가자, 서버 앞단을 지키고 있던 클라우드플레어가 "서버가 죽은 것 같으니 연결을 끊겠다"라며 100초 타임아웃(524 에러)을 발생시킨 것입니다.

서버는 뒤에서 계속 글을 쓰고 있는데 프론트엔드 연결만 끊기니, 봇은 "업로드 실패인가?" 하고 글을 또다시 전송하여 중복 포스팅이 일어난 것이었죠. 이를 해결하기 위한 아키텍처 최적화는 의외로 간단했습니다.

자동화 스크립트가 한 번에 전송하는 청크 사이즈(Chunk Size, 전송 단위)를 기존 20개에서 5개로 대폭 줄였습니다. 한 번에 5개씩만 번역하고 DB에 밀어 넣도록 쪼개어 처리하니, API 응답 시간이 20초 이내로 단축되어 클라우드플레어의 100초 타임아웃 장벽을 완벽하게 피해 갈 수 있었습니다.

맺으며: 로컬 DB 회귀가 가져온 엄청난 결실

길고 험난했던 트러블슈팅을 마치고 나니, 결과는 상상 이상이었습니다. 데이터베이스가 외부 네트워크를 타지 않고 로컬(localhost) 내부에서 즉각적으로 통신하게 되면서 DB 응답 속도가 비약적으로 상승했습니다.

무엇보다 수십 개의 게시글과 썸네일 미디어를 다루고, 4~16분 간격으로 예약 발행하는 아주 무거운 자동화 봇 로직을 3개 이상 동시에 돌려도 서버 자원(CPU, RAM)이 넉넉하게 유지되었습니다. 외부 클라우드 DB의 커넥션 한계에 벌벌 떨던 과거와는 완벽하게 작별한 것입니다.

클라우드가 무조건 정답은 아닙니다. 현재 서비스의 트래픽 패턴과 자동화 로직의 성격에 따라, 때로는 이렇게 온프레미스(로컬) 환경으로 묵직하게 시스템을 옮기는 것이 최고의 아키텍처가 될 수 있음을 뼈저리게 배운 소중한 경험이었습니다.

❓ 자주 묻는 질문 (FAQ)

Q1. Supabase(클라우드)에서 로컬 DB로 이전하면 백업은 어떻게 하나요?

A. 로컬 DB의 가장 큰 단점은 백업을 직접 해야 한다는 것입니다. 저는 리눅스 cron 탭과 pg_dump 명령어를 활용하여 매일 새벽 3시에 데이터베이스를 덤프(백업)하고, 그 파일을 AWS S3나 별도의 외부 스토리지로 자동 전송하도록 스크립트를 작성하여 안전하게 보관하고 있습니다.

Q2. Cloudflare 524 에러를 막기 위해 클라우드플레어 설정을 늘릴 수는 없나요?

A. 무료 플랜(Free)이나 프로 플랜 사용자 기준, 클라우드플레어의 100초 타임아웃(524)은 하드 리밋(Hard Limit)으로 설정되어 있어 사용자가 임의로 늘릴 수 없습니다. 엔터프라이즈(Enterprise) 요금제에서만 조절이 가능하므로, 백엔드 로직 자체를 100초 이내로 응답하도록 쪼개는 것(Chunking)이 유일하고 올바른 해결책입니다.

Q3. 비동기 `asyncpg` 드라이버를 쓰면 무조건 빨라지나요?

A. I/O 바운드 작업(DB를 찔러놓고 기다리는 시간)이 많은 웹 서버라면 동시성 처리가 좋아져서 극적인 성능 향상을 볼 수 있습니다. 하지만, 파이썬 코드 전체가 async/await 구조로 완벽하게 짜여 있지 않고 중간에 블로킹(Blocking) 코드가 섞여 있다면 오히려 성능이 저하될 수 있으니 도입 전 아키텍처 점검이 필수적입니다.