CORS 개념부터 Docker 해결까지 ( CORS 문제 )

KUN·2025년 6월 19일

계기

이 문제를 겪으며,
왜 이런 오류가 발생했는지, 그리고 어떻게 해결할 수 있는지에 대해 근본적인 이해가 필요하다고 느꼈다.
따라서 이번 글에서는 CORS의 개념부터 발생 원인, 그리고 Docker 환경에서의 해결 방안까지 정리해보고자 한다.

목표

CORS란 무엇인지 개념적으로 이해한다.
CORS 에러가 발생하는 원인을 정리한다.
Docker 기반 개발 환경에서 CORS 문제를 해결하는 방법을 정리한다.

CORS?

MDN - CORS

CORS란, 웹 브라우저에서 다른 출처의 리소스에 접근하려 할 때 
보안 상 제한을 두는 정책을 완화하기 위한 메커니즘이다.

즉, 서버가 명시적으로 허용한 경우에만, 브라우저는 다른 출처의 요청을 허용합니다.

쉽게 비유해보면 다음과 같다.

당신은 삼성 직원이고, 택배를 현대 사무실로 보내려고 한다.
하지만 현대 건물은 외부인 출입이 금지되어 있다. ( CORS 문제 발생 )
이때 현대 보안팀이 삼성에서 오는 택배는 허가 목록(허용 헤더)에 포함되어 있다면
비로소 당신의 택배가 정상적으로 현대에 들어갈 수 있다.

왜 CORS 에러가 발생하나?

위의 내용을 가져와보면 보안 정책 때문에 발생한다고 명시되어 있다.
하지만, 이 정책이 구체적으로 무엇을 의미하는지,
어떤 조건에서 CORS 에러가 발생하는지 정확히 이해할 필요가 있다.

하지만, 정확히 출처, 허용헤더 라는 것이 뭔지?
그리고 추가로 무엇을 더 알아야하는지?

출처

브라우저는 요청을 보낼 때, 출처가 다르면 보안을 위해 요청을 차단한다.

프로토콜 (http, https)
호스트(도메인) (example.com, localhost)
포트 번호 (3000, 8080 등)

ex>
http://localhost:3000 (프론트)
http://localhost:8080 (백엔드)
이 둘의 포트가 다르다. 
출처가 다르니, CORS 문제가 발생한다.

허용헤더

MDN - CORS-safelisted request header

CORS 상황에서 브라우저가 다른 출처로 요청을 보낼 때,
서버가 응답에 추가로 보내는 특별한 헤더들을 말한다.
이 헤더들이 있어야 브라우저가 차단하지 않는다.

Access‑Control‑Allow‑Headers
이 헤더는 Preflight 요청에 대한 응답으로, 실제 요청 시 " 어떤 요청 헤더들을 허용할까? " 라는 정보를 브라우저에 전달한다.
Access‑Control‑Allow‑Origin
어떤 출처에서 오는 요청을 허용할지 명시하는 헤더이다.
또는 특정 도메인 형태로 설정할 수 있다.
Access‑Control‑Allow‑Credentials
인증 정보(쿠키, Authorization 헤더 등)를 포함한 요청에 대해 서버가 이를 허용할지 여부를 지정하는 헤더이다.

해결법

백엔드에서 해결하는 방법

매우 간단하게 해결했다.
Spring Boot에서는 WebMvcConfigurer를 사용해 전역적으로 CORS 설정이 가능하다.

CORS 가 뜨지않는다.

Docker 에서 해결하는 방법

프로젝트 root 에 docker-compose.yml 을 추가한다.

내부에 연결되는 네트워크를 설정한다.

ex)
version: '3.8'

services:
  backend:
    image: outsourcing-backend:latest
    ports:
      - "8080:8080"
    environment:
        - DB_NAME=????
        - DB_USER=????
        - DB_PASSWORD=???
        - JWT_SECRET_KEY=??????
    networks:
      - app-net

  frontend:
    image: dannyseo4284/taskflow-frontend-integration:latest
    ports:
      - "3100:3000"
    networks:
      - app-net

networks:
  app-net: