For the complete documentation index, see llms.txt. This page is also available as Markdown.

분산 환경 개발 가이드

ℹ️ 목적

  • 고도몰은 트래픽 분산을 위해 분산 웹(이벤트 서버) 환경도 제공합니다.

  • 분산 웹(이벤트 서버) 환경의 상점에서 외부 cron 호출, 자동결제, 파일 업로드 등 서버 간 상태 공유가 필요한 기능을 사용자 정의 개발할 경우, 이 문서의 내용을 반드시 확인하시기 바랍니다.

ℹ️ 서버 구조

  • 단일 서버 환경

    • 모든 요청이 하나의 서버에서 처리됩니다. 세션, 임시 파일, 로컬 변수 등이 동일 서버에 존재하므로 별도 고려가 필요 없습니다.

  • 분산 웹(이벤트 서버) 환경

    • 분산 서버(A, B, C): 사용자 요청을 처리하는 서버. 요청마다 다른 서버로 라우팅될 수 있음

    • Origin 서버: 파일 저장, 데이터 원본을 관리하는 서버

  • 분산 웹 환경에서는 동일 요청이 항상 같은 서버에서 처리된다는 보장이 없습니다.

  • 따라서 다음과 같은 경우 반드시 api.{도메인}을 사용해야 합니다.

🤔 api. 도메인이란

  • 고도몰은 용도별로 서브도메인을 분리하여 운영합니다.

  • api. 도메인으로 들어오는 요청은 Origin 서버로 직접 라우팅됩니다. 따라서 서버 간 상태 불일치 문제가 발생하지 않습니다.

  • 사용자 정의 API 컨트롤러는 module/Controller/Api 경로에 생성하며

  • api.{도메인}/경로/파일명 형식으로 접근합니다. 상세한 컨트롤러 생성 방법은 컨트롤러 > API Controller 를 참고하세요.

🧑🏻‍💻 개발 케이스

1. 외부 cron에서 URL을 호출하는 경우

2. 서버 간 상태 공유가 필요한 처리

  • 다음 항목들은 서버 로컬에 저장되므로 분산 웹 환경에서 서버 간 공유되지 않습니다.

항목
단일 웹
분산 웹
대응 방법

파일 시스템 (임시 파일, 업로드 파일)

동일 디스크

서버별 별도 디스크

api. 도메인 사용

PG 결제 토큰/인증값

동일 서버

생성 서버와 검증 서버 불일치 가능

api. 도메인 사용

3. 서버 간 순서 보장이 필요한 처리

분산 웹 환경에서는 동일 사용자의 연속 요청이 같은 서버로 가지 않을 수 있습니다.

  • 결제 요청 -> 결제 승인 콜백 -> 주문 완료 처리

  • 파일 업로드 -> 업로드된 파일 참조

이러한 처리가 하나의 트랜잭션으로 이루어져야 한다면, api. 도메인을 사용하여 Origin 서버에서 일관되게 처리되도록 해야 합니다.

📢 주의사항

  • api. 도메인의 SSL 인증서가 정상 설정되어 있어야 합니다. 관리자 > 기본설정 > 보안서버(SSL)에서 확인하세요.

  • api. 도메인은 Origin 서버로 직접 연결되므로 과도한 트래픽을 api. 도메인으로 보내면 Origin 서버에 부하가 집중될 수 있습니다.

  • 일반 사용자 트래픽은 www. 또는 m.도메인을 유지하고 서버 간 상태 공유가 필요한 처리에만 api. 도메인을 사용하세요.

Last updated