Cycle 3: FastAPI 백엔드 배포

백엔드 배포가 다른 이유

Frontend

정적 파일 (HTML/CSS/JS)
CDN에 업로드만 하면 됨
서버 프로세스 불필요

Backend

서버 프로세스 실행 필요
요청마다 코드 실행
상태 관리, DB 연결

백엔드는 컨테이너로 패키징하면 어떤 서버에서든 동일하게 실행할 수 있습니다.

Docker 기초

Dockerfile 작성

Dockerfile

# Python 이미지 사용
FROM python:3.11-slim

# 작업 디렉토리 설정
WORKDIR /app

# 의존성 먼저 설치 (캐시 활용)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 소스 코드 복사
COPY . .

# 포트 노출
EXPOSE 8080

# 앱 실행
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

로컬에서 테스트

터미널

# 이미지 빌드
docker build -t my-api .

# 컨테이너 실행
docker run -p 8080:8080 my-api

# http://localhost:8080 에서 확인

멀티스테이지 빌드 (선택)

이미지 크기를 줄이려면 멀티스테이지 빌드를 사용합니다.

Dockerfile (멀티스테이지)

# 빌드 스테이지
FROM python:3.11-slim as builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt

# 실행 스테이지
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /root/.local /root/.local
COPY . .
ENV PATH=/root/.local/bin:$PATH
EXPOSE 8080
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

Cloud Run 배포

1 gcloud CLI 설치

터미널

# macOS
brew install google-cloud-sdk

# 로그인
gcloud auth login

# 프로젝트 설정
gcloud config set project YOUR_PROJECT_ID

2 이미지 빌드 및 푸시

터미널

# Cloud Build로 빌드 + Artifact Registry에 푸시
gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/my-api

3 Cloud Run 배포

터미널

gcloud run deploy my-api \
  --image gcr.io/YOUR_PROJECT_ID/my-api \
  --platform managed \
  --region asia-northeast3 \
  --allow-unauthenticated

--allow-unauthenticated: 인증 없이 접근 가능 (공개 API용)

4 환경 변수 설정

터미널

gcloud run deploy my-api \
  --image gcr.io/YOUR_PROJECT_ID/my-api \
  --set-env-vars="DATABASE_URL=postgresql://...,API_KEY=secret"

시크릿 관리

민감한 정보는 환경 변수 대신 Secret Manager를 사용하세요.

운영 기초

헬스체크 엔드포인트

Cloud Run은 / 경로로 헬스체크를 수행합니다. 별도의 헬스체크 엔드포인트를 만드는 것이 좋습니다.

main.py

from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
def health_check():
    return {"status": "healthy"}

@app.get("/")
def root():
    return {"message": "Hello, World!"}

로그 확인

터미널

# Cloud Run 로그 확인
gcloud run services logs read my-api --region asia-northeast3

# 실시간 로그 스트리밍
gcloud run services logs tail my-api --region asia-northeast3

CORS 설정

프론트엔드와 백엔드 도메인이 다르면 CORS 설정이 필요합니다.