ServBay에서 사이트의 CORS(크로스 오리진 리소스 공유) 설정하기

현대 웹 개발에서 프론트엔드 애플리케이션(일반적으로 하나의 도메인에서 실행)과 백엔드 API 또는 기타 서비스(다른 도메인이나 포트에서 실행되는 경우) 간의 통신이 빈번하게 이뤄집니다. 브라우저의 동일 출처 정책은 보안을 위해 이러한 크로스 도메인 요청을 기본적으로 차단합니다. CORS(크로스 오리진 리소스 공유)는 서버가 어떤 출처의 접근을 허용하는지 선언할 수 있는 표준 메커니즘으로, 안전하게 크로스 도메인 상호작용을 실현해줍니다.

이 문서에서는 ServBay의 사용자 인터페이스를 통해 로컬 웹 개발 환경에서 사이트의 CORS를 쉽고 편리하게 설정·활성화하는 방법을 안내합니다.

CORS란 무엇인가요?

**CORS(크로스 오리진 리소스 공유)**는 HTTP 헤더 기반의 메커니즘으로, 서버가 스스로의 출처 외에 어떤 도메인/프로토콜/포트에서 리소스 로드를 허용할지 명시합니다. 웹페이지가 본인과 다른 출처의 리소스에 접근하려 할 때, 브라우저는 "크로스 도메인 HTTP 요청"을 수행하게 됩니다. 브라우저의 동일 출처 정책상, 이런 요청은 기본적으로 차단됩니다. CORS는 서버와 브라우저 간의 커뮤니케이션 방법을 제공하여, 해당 요청이 안전하게 이루어질 수 있는지 결정합니다.

왜 개발자는 CORS를 설정해야 할까요?

프론트엔드와 백엔드가 분리된 애플리케이션 예시(예: 프론트엔드는 app.servbay.demo, 백엔드 API는 api.servbay.demo), 또는 프론트엔드가 제3자 API를 호출해야 할 때 브라우저의 동일 출처 정책으로 인해 요청이 차단될 수 있습니다. CORS 설정을 통해 브라우저에 '특정 프론트엔드 출처의 접근이 허용된다'고 알려 요청 실패 문제를 해결할 수 있습니다.

CORS의 핵심 HTTP 응답 헤더 이해하기

서버가 크로스 도메인 요청에 응답할 때, 특정 Access-Control-* HTTP 헤더들을 포함합니다. 브라우저는 이 헤더의 값을 바탕으로 해당 크로스 도메인 요청을 허용할지 판단합니다. ServBay에서 설정할 수 있는 주요 CORS 파라미터(즉, 다음 HTTP 응답 헤더)는 다음과 같습니다.

1. Access-Control-Allow-Origin

   • 역할: 가장 핵심적인 CORS 헤더로, 리소스 접근을 허용할 출처(하나 또는 복수 도메인)를 지정합니다.
   • 가능 값:
     • *: 모든 도메인에서의 접근을 허용합니다. 중요: 편리하지만, 프로덕션 환경에서는 권장하지 않습니다. 모든 사이트가 임의로 리소스에 접근할 수 있어 보안상 위험합니다.
     • https://servbay.demo: 오직 이 출처의 요청만 허용합니다.
     • https://servbay.demo https://api.servbay.demo: 여러 출처를 허용하며, 공백으로 구분합니다.
   • 주의: 크로스 도메인 요청에 쿠키나 HTTP 인증정보(예: Access-Control-Allow-Credentials: true 설정) 전달이 필요하다면 Access-Control-Allow-Origin을 *로 설정할 수 없고, 반드시 특정 출처를 지정해야 합니다.

2. Access-Control-Allow-Methods

   • 역할: 크로스 도메인 요청에서 사용할 수 있는 HTTP 메서드(GET, POST, PUT, DELETE, OPTIONS 등)를 지정합니다.
   • 가능 값: 예: GET, POST, PUT, DELETE, OPTIONS 등(쉼표로 분리)
   • 주의: 일부 "단순하지 않은 요청"(예를 들어, PUT/DELETE 메서드 사용 혹은 커스텀 헤더 포함)에는 브라우저가 사전 "옵션(preflight)" 요청(OPTIONS 메서드)을 먼저 보냅니다. 서버는 해당 요청에 대해 Access-Control-Allow-Methods와 같은 헤더로 어떤 메서드를 쓸 수 있는지 명확히 지정해야 합니다. 보통 OPTIONS는 반드시 포함해야 합니다.

3. Access-Control-Allow-Headers

   • 역할: 크로스 도메인 요청에서 허용할 커스텀 HTTP 요청 헤더를 명시합니다.
   • 가능 값: 예: Content-Type, Authorization, X-Requested-With 등(쉼표로 분리)
   • 주의: 프론트엔드 요청에 기본 단순 헤더(예: Accept, Accept-Language, Content-Language, 혹은 Content-Type이 application/x-www-form-urlencoded, multipart/form-data, text/plain 중 하나인 경우)를 제외한 다른 헤더가 있을 경우, 브라우저는 사전(preflight) 요청을 보내며, 반드시 허용할 커스텀 헤더를 이곳에 업데이트해야 합니다.

4. Access-Control-Allow-Credentials

   • 역할: 크로스 도메인 요청에 쿠키, 클라이언트의 SSL 인증서, HTTP 인증정보 등 사용자 인증 정보를 포함하는 것을 허용할지 여부입니다.
   • 가능 값: true 또는 false
   • 주요 주의사항: true로 설정했다면 위에서 설명한 것처럼 Access-Control-Allow-Origin의 값은 반드시 *가 아니고 구체적인 출처여야 합니다. 아울러, 클라이언트 코드(브라우저 JavaScript)도 요청할 때 xhr.withCredentials = true 또는 fetch(url, { credentials: 'include' })처럼 명시해야 합니다.

ServBay에서 CORS 활성화 및 설정

ServBay는 각 사이트별로 독립적으로 CORS 설정을 손쉽게 지정할 수 있는 직관적인 그래픽 인터페이스를 제공합니다. 과정은 다음과 같습니다.

1. ServBay 실행 및 사이트 목록 진입: ServBay 프로그램을 실행합니다. 메인 화면의 좌측 네비게이션 바에서 "사이트"를 클릭하세요. ServBay에 등록된 모든 로컬 사이트 목록이 보입니다.

2. CORS를 설정할 사이트 선택: 목록에서 CORS 옵션을 활성화하고 싶은 사이트를 찾아 해당 이름을 클릭하여 상세 설정 화면으로 들어갑니다.

3. CORS 설정 항목 찾아 활성화: 사이트 설정 중간 영역에서 "CORS" 섹션을 아래로 내려 찾아보세요. 기본값으로는 CORS가 비활성화되어 있습니다. 해당 스위치 버튼을 클릭하여 "꺼짐"에서 "켜짐"으로 변경하세요. 활성화 이후부터는 하단의 설정 항목들이 입력 가능해집니다.

4. Access-Control-Allow-Origin 구성: "Access-Control-Allow-Origin" 입력란에 리소스 접근을 허용할 하나 이상의 출처를 입력하세요. 복수 출처일 경우, 공백으로 구분합니다. 예시: https://frontend.servbay.demo https://anotherapp.servbay.demo
   프로덕션에서는 * 사용을 가급적 피하세요.

5. Access-Control-Allow-Methods 구성: "Access-Control-Allow-Methods" 입력란에는 허용할 HTTP 메서드 목록을 쉼표로 구분하여 입력합니다. 예: GET, POST, PUT, DELETE, OPTIONS
   애플리케이션에서 사용하는 모든 메서드를 반드시 포함하고, 사전(preflight) 요청을 위해 OPTIONS 포함이 권장됩니다.

6. Access-Control-Allow-Headers 구성: "Access-Control-Allow-Headers" 입력란에는 허용할 커스텀 HTTP 요청 헤더 목록을 쉼표로 구분하여 입력합니다. 예: Content-Type, Authorization, X-Custom-Header
   실제로 애플리케이션에서 사용하는 헤더만 입력하세요.

7. Access-Control-Allow-Credentials 설정(선택 사항): 크로스 도메인 요청에 쿠키나 HTTP 인증정보 전달이 필요하다면 "Allow-Credentials" 스위치를 클릭하여 "켜짐" 상태로 변경하세요. 중요: 이 옵션을 사용하면 4단계에서 Access-Control-Allow-Origin은 절대 *가 되어선 안 됩니다.

8. 변경사항 저장: 모든 CORS 설정을 마쳤다면, 우측 하단의 "저장" 버튼을 반드시 클릭하여 변경사항을 반영하세요. ServBay가 자동으로 웹 서버(Caddy/Nginx 등) 구성을 업데이트하니 직접 재시작할 필요가 없습니다.

설정 예시

다음 이미지는 "ServBay Demo Website"라는 사이트에서 CORS를 어떻게 설정할 수 있는지 보여줍니다.

위 설정을 기준으로:

• Access-Control-Allow-Origin: https://frontend.servbay.demo https://api.servbay.demo
• Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization
• Allow-Credentials: 활성화(true)

즉, https://frontend.servbay.demo와 https://api.servbay.demo 이 두 출처에서 오는 요청만 "ServBay Demo Website" 리소스에 접근할 수 있습니다. 허용된 메서드는 GET, POST, PUT, DELETE, OPTIONS이며, 요청은 Content-Type, Authorization 헤더를 포함할 수 있고, Cookie 등 인증 정보 전달도 허용됩니다.

주의사항 및 베스트 프랙티스

• 보안 우선: 개발/테스트 환경에서는 Access-Control-Allow-Origin: *이 편리할 수 있지만, 프로덕션에서는 반드시 실제로 필요한 출처로 제한해 보안을 강화하세요.
• 사전(preflight) 요청 이해: 사전 요청(OPTIONS 메서드)이 어떻게 작동하는지 이해하는 것은 CORS 문제 디버깅에 매우 중요합니다. 서버(ServBay 설정)가 사전 요청에 올바른 헤더로 응답하는지 확인하세요.
• 브라우저 캐시: 브라우저가 CORS 정책을 캐시할 수 있습니다. ServBay에서 CORS 설정을 변경한 뒤에도 문제가 계속된다면, 캐시 삭제 또는 시크릿 모드로 테스트해보세요.
• 애플리케이션 레벨 CORS: 일부 웹 프레임워크(예: Laravel, Express.js, Spring Boot 등)에서도 애플리케이션 레벨에서 자체적으로 CORS를 설정할 수 있습니다. ServBay의 CORS 설정은 웹 서버(Caddy/Nginx) 단에서 적용되며, 일반적으로 이 설정이 애플리케이션 레벨보다 우선합니다. 복잡한 상황에서는 웹 서버와 코드를 모두 점검하거나 조율할 필요가 있습니다.
• 디버깅 툴: 브라우저 개발자 도구(대부분 F12) 네트워크(Network) 탭에서 크로스 도메인 요청과 응답의 HTTP 헤더를 직접 확인할 수 있습니다. CORS 정책이 제대로 적용되고 있는지, 요청 실패 이유가 무엇인지 쉽게 파악할 수 있습니다.

자주 묻는 질문(FAQ)

Q: 안내대로 CORS를 설정했는데도 크로스 도메인 요청이 실패합니다. 왜 그런가요?

A: 아래 단계별로 체크해보세요.

1. 브라우저 콘솔/네트워크 탭 확인: 크롬 및 대부분의 브라우저는 CORS 관련 오류 메시지를 콘솔에, 요청 및 응답 헤더를 네트워크 탭에 표시합니다. 응답에 올바른 Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers 헤더가 포함되었고 값이 프론트엔드 요청과 일치하는지 확인하세요.
2. 출처 주소 체크: Access-Control-Allow-Origin 내 출처 주소(프로토콜/도메인/포트)가 프론트엔드 애플리케이션의 요청 출처와 완전히 일치하는지 확인하세요.
3. 메서드·헤더 확인: Access-Control-Allow-Methods에 사용하는 HTTP 메서드가 들어있고, Access-Control-Allow-Headers에 모든 커스텀 헤더가 포함되어 있는지 점검하세요.
4. 인증 관련: Cookie 등 인증정보가 필요한 경우 ServBay에서 Allow-Credentials 활성화 및 Access-Control-Allow-Origin을 *가 아니라 특정 출처로 설정해야 합니다. 프런트엔드 코드도 반드시 해당 옵션(예: withCredentials = true)을 명시해야 합니다.
5. 사전(preflight) 요청: 단순하지 않은 요청의 경우 브라우저가 OPTIONS 메서드로 사전 요청을 보내는지, 서버가 이에 필요 헤더로 응답하는지 확인하세요.
6. 설정 저장: ServBay에서 수정 후 "저장" 버튼을 꼭 눌렀는지 확인하세요.

Q: 모든 사이트에 전역적으로 CORS 정책을 설정할 수 있나요?

A: ServBay의 CORS 설정은 사이트별로 별도 관리됩니다. 이는 더 큰 유연성과 보안을 제공합니다. 현재 UI에서는 전역 CORS 설정 기능은 제공하지 않으므로, 여러 사이트에 공통 정책을 적용하려면 각각 별도로 설정해야 합니다.

Q: ServBay는 내부적으로 어떻게 CORS 설정을 적용하나요?

A: ServBay는 내부적으로 Caddy 또는 Nginx 웹서버를 사용합니다. ServBay UI에서 CORS 설정을 하면, ServBay가 이를 자동으로 Caddyfile 또는 Nginx 구성 지시문으로 변환합니다. 파일의 관리/서버 재로드도 자동으로 처리되므로 사용자가 직접 수정할 필요가 없습니다.

마치며

ServBay의 직관적인 UI를 사용하면 로컬 개발 환경에서 각 사이트별로 손쉽게 CORS를 활성화하고 설정할 수 있습니다. 이를 통해 크로스 도메인 접근 문제를 효과적으로 해결할 수 있습니다. Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers, Access-Control-Allow-Credentials 등 핵심 헤더를 정확히 이해하고 올바르게 설정하면 보다 안전하고 원활하게 크로스 도메인 요청을 처리할 수 있습니다. 본 가이드와 주의사항을 참고하면 더욱 효율적인 로컬 웹 개발이 가능합니다.