fastapi cors 오류 해결: 실무 적용 가이드와 체크리스트

fastapi cors 오류 해결이 필요한 상황

fastapi cors 오류 해결을 위해 이 글에서는 발생 원인 분석, 실무 적용 코드, 배포/보안 주의점과 체크리스트를 제공합니다. 프론트엔드에서 401/403 또는 CORS 관련 브라우저 오류가 뜰 때 정확히 어디를 고쳐야 하는지 단계별로 알 수 있습니다.

fastapi cors 오류 해결 핵심 개념

CORS(Cross-Origin Resource Sharing)는 브라우저가 다른 출처의 리소스 접근을 제어하는 메커니즘입니다. 서버는 응답 헤더로 어떤 출처를 허용할지 명시해야 하며, FastAPI는 Starlette 기반으로 CORS 미들웨어를 제공합니다. 미들웨어 순서, 인증 헤더 처리, 프리플라이트(OPTIONS) 응답이 중요합니다.

fastapi cors 오류 해결 실무 예제

아래 예제는 FastAPI에 CORS 미들웨어를 올바르게 설정하는 실무 코드입니다. 도메인 허용 리스트, 허용 메서드, 허용 헤더를 명시적으로 설정합니다.

# app/main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

origins = [
    "https://example.com",
    "https://admin.example.com",
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    allow_headers=["Authorization", "Content-Type"],
)

@app.get("/ping")
async def ping():
    return {"ok": True}

• 프리플라이트 요청(OPTIONS)은 FastAPI가 자동 응답합니다. 그러나 라우터에서 OPTIONS를 가로채면 응답이 달라질 수 있으니 주의하세요.
• allow_credentials=True인 경우 allow_origins에 "*"를 사용할 수 없습니다. 구체적 도메인을 명시하세요.

언제 쓰면 좋고 언제 피해야 할까

• 언제 쓰면 좋은가:
  • 프론트엔드가 다른 도메인에서 API를 호출할 때
  • 인증 정보(쿠키/Authorization)를 함께 전송해야 할 때
• 언제 피해야 하는가:
  • 모든 도메인을 무차별 허용("*")하면 보안 위험이 높을 때
  • 단순한 퍼블릭 데이터로 인증을 요구하지 않는 경우에는 불필요한 복잡성을 초래할 때

비교: 설정 방식 판단 기준표

성능·보안·운영 주의점

• 보안
  • allow_origins에 모든 도메인("*")를 넣으면 악의적 사이트에서 API 호출이 가능해집니다. 인증을 사용하는 경우에는 명시적 도메인 리스트를 사용하세요.
  • Authorization 헤더를 허용할 때는 토큰 유효성 검사를 철저히 하세요.
• 성능
  • CORS 미들웨어 자체는 경량이지만 프리플라이트 요청이 빈번하면 추가 요청이 발생해 지연이 생깁니다. 필요한 메서드와 헤더만 허용해 프리플라이트 빈도를 줄이세요.
• 운영
  • 환경별(개발/스테이징/프로덕션)로 allow_origins를 분리해 관리하세요.
  • 로깅: 프리플라이트/실패 요청을 로깅해 문제 발생 시 빠르게 원인을 찾을 수 있도록 설정하세요.

실무 체크리스트

• allow_origins에 프로덕션 도메인만 포함했는가?
• allow_credentials를 True로 할 경우 도메인이 와일드카드인지 확인했는가?
• 프리플라이트(OPTIONS) 요청이 올바르게 처리되는가?
• 서버 측에서 Authorization/Cookie 유효성 검사를 수행하는가?
• 배포 환경별 설정을 분리했는가?
• 브라우저 콘솔과 네트워크 탭에서 CORS 에러 원문을 확인했는가?

디버깅 팁과 추가 예제

• 브라우저 네트워크 탭에서 OPTIONS 요청과 응답 헤더(Access-Control-Allow-Origin 등)를 확인하세요.
• 로컬 개발시 프론트엔드와 백엔드를 동일 출처로 묶어 임시로 문제를 우회할 수 있습니다.

예: uvicorn으로 실행하는 경우

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

자주 묻는 질문

Q1: allow_origins에 ''를 사용해도 되나요? A1: 인증이 필요 없는 퍼블릭 API라면 가능하지만, 쿠키나 Authorization을 사용하는 경우 보안상 권장되지 않습니다. allow_credentials=True이면 ''를 사용하면 안 됩니다.

Q2: 프리플라이트 응답이 500 에러가 나요. 원인은? A2: 라우터나 미들웨어에서 OPTIONS를 처리하면서 예외가 발생할 수 있습니다. 미들웨어 순서와 라우터 핸들러를 확인하고, 로그에서 에러 스택을 확인하세요.

Q3: 프록시(예: nginx)가 CORS에 영향을 주나요? A3: 예. 프록시에서 응답 헤더를 덮어쓰거나 제거하면 CORS 동작에 영향을 줄 수 있습니다. 프록시 설정에서 Access-Control-* 헤더를 유지하도록 설정하세요.

Q4: 여러 서브 도메인을 허용하려면 어떻게 하나요? A4: origins 리스트에 각 도메인을 명시하거나 환경 변수를 사용해 동적으로 로드하세요. 와일드카드를 사용한 패턴 매칭은 CORS 미들웨어에서 기본 지원하지 않습니다.

정리

• fastapi cors 오류 해결은 CORS 개념 이해와 미들웨어 설정이 핵심입니다.
• allow_origins와 allow_credentials 설정을 환경별로 분리하세요.
• 프리플라이트 요청과 응답 헤더를 브라우저 네트워크 탭으로 확인하세요.
• 실무 체크리스트를 통해 배포 전 설정을 검증하세요.
• 보안과 성능을 고려해 불필요한 허용을 최소화하세요.