CORS Error 해결하기: FastAPI와 프론트엔드 연동 시 발생한 이슈와 해결 방법

요즘 프로젝트를 하면서 FastAPI Router를 개발하면서 생긴 Trouble Shooting에 데하여 한번 적어보려고 합니다.

FastAPI와 Swagger를 사용하여 VLM 영상 처리 서버를 개발하고, 이를 AWS EC2에 배포하여 Docker 이미지로 빌드하고 컨테이너를 실행했습니다. 서버 자체는 정상적으로 작동했지만, 프론트엔드와 연동했을 때 예상치 못한 CORS(Cross-Origin Resource Sharing) 에러를 마주하게 되었습니다.

 

이 글에서는 CORS 에러가 발생한 원인과 이를 어떻게 해결했는지, 그리고 운영 환경에서의 보안 고려 사항에 대해 자세히 다뤄보겠습니다.

---

브라우저에서의 CORS 에러

프론트엔드 애플리케이션을 연결하면서, http://localhost:5173에서 FastAPI 서버(http://43.202.66.178:8000)로 API 요청을 보냈을 때 다음과 같은 CORS 오류가 발생했습니다:

Access to fetch at 'http://43.202.66.178:8000/api/video/receive-video/' from origin 'http://localhost:5173' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

이 에러로 인해 AI Server에서 프론트엔드및 백엔드 API에 접근할 수 없었다는 문제가 생겼습니다.

브라우저가 다른 출처(Origin)에서 리소스를 요청했으나, 서버가 이를 허용하지 않았기 때문에 발생합니다.

---

CORS란 무엇인가?

CORS(Cross-Origin Resource Sharing)는 교차 출처 자원 공유를 의미하며, 웹 브라우저에서 보안상의 이유로 도메인 간의 요청을 제한하는 정책입니다. 즉, 한 도메인에서 로드된 웹 페이지가 다른 도메인의 자원에 접근하려고 할 때, 브라우저는 보안을 위해 이를 차단합니다.

 

예를 들어, 프론트엔드가 http://localhost:5173에서 실행되고 백엔드가 http://43.202.66.178:8000에 있을 때, 두 도메인은 서로 다르므로 브라우저는 기본적으로 이러한 요청을 허용하지 않습니다.

 

기본적으로 웹 브라우저는 보안상의 이유로 동일 출처 정책(Same-Origin Policy)을 따르며, 다른 출처의 리소스에 대한 접근을 제한합니다. CORS는 이러한 제한을 완화하여 필요한 경우에만 리소스 접근을 허용할 수 있게 합니다.

---

문제의 원인

Access to fetch at 'http://43.202.66.178:8000/api/video/receive-video/' from origin 'http://localhost:5173' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

브라우저에서 발생한 에러 메시지를 분석해보면, 서버 응답에 Access-Control-Allow-Origin 헤더가 없기 때문에 브라우저가 요청을 차단하고 있다는 것을 알 수 있습니다. 이는 서버가 CORS 정책을 적절하게 설정하지 않았음을 의미합니다.

---

해결 방법

FastAPI에서 CORS 문제를 해결하기 위해 CORSMiddleware를 사용할 수 있습니다.
CORSMiddleware를 설정하는 방법에는 두 가지가 있습니다.

1. 특정 프론트엔드 URL을 allow_origins에 명시적으로 지정하기
2. allow_origins를 "*"로 설정하여 모든 출처를 허용하기

이 두 가지 방법 중 첫 번째는 보안상 더 안전하지만, 두 번째 방법은 개발 과정에서 빠르게 문제를 해결할 수 있습니다.

1. FastAPI의 CORSMiddleware 설정

FastAPI는 starlette.middleware.cors.CORSMiddleware를 통해 CORS 설정을 간편하게 처리할 수 있습니다.
다음은 두 가지 설정 방법에 대한 예제입니다.

첫 번째 방법: 특정 출처(origin)를 명시적으로 허용

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

origins = [
    "<http://frontend-app.yourdomain.com>",
    "<http://frontend-app2.yourdomain.com:7000>"
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,  # 특정 출처만 허용
    allow_methods=["*"],    # 모든 HTTP 메소드 허용
    allow_headers=["*"],    # 모든 헤더 허용
    allow_credentials=True, # 자격 증명 허용 (필요 시)
)

두 번째 방법: 모든 출처 허용

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],    # 모든 출처 허용
    allow_methods=["*"],    # 모든 HTTP 메소드 허용
    allow_headers=["*"],    # 모든 헤더 허용
    allow_credentials=False, # 자격 증명 비허용
)

주의: allow_origins 를 "*" 로 설정하면 allow_credentials 를 반드시 False 로 설정해야 합니다.
이는 보안상의 이유로 브라우저에서 요구하는 CORS 정책에 따른 것입니다.

2. 보안 고려사항

운영 환경에서는 보안을 강화하기 위해 두 번째 방법인 모든 출처 허용은 피하고, 첫 번째 방법처럼 정확한 프론트엔드 URL만을 allow_origins에 명시적으로 지정하는 것이 권장됩니다.

모든 출처를 허용하면 의도치 않은 출처에서도 API에 접근할 수 있게 되어 보안 취약점이 발생할 수 있습니다.

운영 환경 설정 예시

origins = [
    "<https://frontend-app.yourdomain.com>",
    "<https://frontend-app2.yourdomain.com>"
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,  # 특정 출처만 허용
    allow_methods=["GET", "POST", "PUT", "DELETE"],  # 필요한 메소드만 허용
    allow_headers=["Content-Type", "Authorization"], # 필요한 헤더만 허용
    allow_credentials=True,  # 필요 시
)

---

코드 구현

CORS 문제를 해결하기 위해 FastAPI의 CORSMiddleware를 설정하였습니다. 아래는 해당 설정과 관련된 예시 코드입니다.

CORS Middleware 설정

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# 개발 환경에서는 모든 출처를 허용
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 모든 출처 허용
    allow_methods=["*"],
    allow_headers=["*"],
    allow_credentials=False,  # 자격 증명 비허용
)

API 엔드포인트 구현

from fastapi import APIRouter, UploadFile, File, HTTPException, Response
import uuid
import os
import logging

router = APIRouter()
logger = logging.getLogger(__name__)
UPLOAD_DIR = "/path/to/upload"

class UploadResponse(BaseModel):
    video_id: str
    message: str

@router.post("/receive-video/", response_model=UploadResponse)
async def receive_video_endpoint(response: Response, file: UploadFile = File(...)):
    """
    비디오 파일을 업로드 받아 저장하고, video_id를 반환합니다.
    """

    # 응답 헤더에 CORS 설정 추가 (보조적인 조치)
    response.headers["Access-Control-Allow-Origin"] = "*"
    response.headers["Access-Control-Allow-Credentials"] = "False"

    # 요청 수신 로그
    logger.info("receive_video_endpoint called")
    logger.info(f"Received file: {file.filename}")

    # 지원하는 파일 형식 확인
    ALLOWED_EXTENSIONS = {"webm", "mp4", "mov", "avi", "mkv"}
    file_extension = file.filename.split(".")[-1].lower()
    if file_extension not in ALLOWED_EXTENSIONS:
        logger.warning(f"지원하지 않는 파일 형식: {file_extension}")
        raise HTTPException(status_code=400, detail="지원하지 않는 파일 형식입니다.")

    # 고유한 video_id 생성
    video_id = uuid.uuid4().hex

    # 비디오 파일 저장 경로 설정
    video_filename = f"{video_id}.{file_extension}"
    file_path = os.path.join(UPLOAD_DIR, video_filename)

    # 비디오 파일 저장
    try:
        with open(file_path, "wb") as buffer:
            buffer.write(await file.read())
        logger.info(f"비디오 파일 저장 완료: {file_path}")
    except Exception as e:
        logger.error(f"파일 저장 중 오류 발생: {e}")
        raise HTTPException(status_code=500, detail=f"파일 저장 중 오류 발생: {e}")

    return UploadResponse(
        video_id=video_id,
        message="비디오 업로드 완료. 피드백 데이터를 받으려면 /send-feedback/{video_id} 엔드포인트를 호출하세요."
    )

주요 포인트

• CORS Middleware 설정: 모든 출처를 허용하도록 설정하였으나, 이는 개발 환경에서만 사용하고, 운영 환경에서는 특정 출처만 허용하도록 변경해야 합니다.
• 응답 헤더 설정: response.headers를 통해 추가적인 CORS 헤더를 설정할 수 있습니다. 그러나 이는 미들웨어 설정과 함께 사용하는 것은 권장되지 않으며, 미들웨어 설정만으로 충분히 처리할 수 있습니다.
• 파일 업로드 로직: 비디오 파일을 받아 지정된 디렉토리에 저장하고, 고유한 video_id를 생성하여 클라이언트에 반환합니다.

---

운영 환경에서의 보안 고려 사항

개발 단계에서는 모든 출처를 허용하는 것이 편리할 수 있지만, 운영 환경에서는 보안에 큰 위험을 초래할 수 있습니다.

왜 모든 출처를 허용하면 안 될까?

• 보안 위험 증가: 모든 도메인에서 서버에 요청을 보낼 수 있으므로, 악의적인 사이트에서 서버를 오용할 수 있습니다.
• 크로스 사이트 요청 위조(CSRF) 공격 가능성: 인증 정보가 필요한 API의 경우, 공격자가 사용자의 브라우저를 통해 서버에 임의의 요청을 보낼 수 있습니다.

올바른 접근 방법

운영 환경에서는 허용할 출처를 명시적으로 지정해야 합니다:

origins = [
    "<https://your-frontend-domain.com>",
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,  # 필요한 경우 True로 설정
    allow_methods=["GET", "POST"],  # 허용할 HTTP 메서드 제한
    allow_headers=["Content-Type", "Authorization"],  # 필요한 헤더만 허용
)

이를 통해 서버는 지정된 도메인에서 오는 요청만 허용하게 됩니다.

---

추가적인 고려 사항: 응답 헤더 수동 설정 피하기

처음에는 각 엔드포인트의 응답 헤더에 직접 CORS 관련 헤더를 추가하려고 했습니다:

response.headers["Access-Control-Allow-Origin"] = "*"

하지만 이는 권장되지 않는 방법입니다.

• 유지 보수 어려움: 각 엔드포인트마다 헤더를 수동으로 설정하면 코드가 복잡해지고 오류가 발생할 가능성이 높습니다.
• 미들웨어 활용: FastAPI의 CORSMiddleware는 CORS 설정을 중앙에서 관리하므로, 코드의 일관성과 유지 보수성이 향상됩니다.

CORS 에러는 프론트엔드와 백엔드의 도메인이 다를 때 발생하는 일반적인 문제입니다. 이를 해결하기 위해서는 서버에서 적절한 CORS 설정을 해야 하며, FastAPI에서는 CORSMiddleware를 사용하여 쉽게 이를 관리할 수 있습니다.

핵심 요점

• 개발 환경에서는 모든 출처를 허용하되, 운영 환경에서는 반드시 허용할 출처를 명시적으로 지정해야 합니다.
• allow_credentials 설정에 유의해야 하며, allow_origins가 "*"일 때는 allow_credentials를 False로 설정해야 합니다.
• 응답 헤더를 수동으로 설정하기보다는 CORSMiddleware를 사용하여 중앙에서 관리하는 것이 좋습니다.

---

참고 자료

• FastAPI 공식 문서 - CORS
• Understanding CORS
• Starlette CORS Middleware

Middleware - Starlette

 

Cross-Origin Resource Sharing (CORS) - HTTP | MDN

 

CORS (Cross-Origin Resource Sharing) - FastAPI