> For the complete documentation index, see [llms.txt](https://devcenter-help.nhn-commerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devcenter-help.nhn-commerce.com/other-guide/multi-server.md).

# 분산 환경 개발 가이드

### ℹ️ 목적

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

### ℹ️ 서버 구조

* 단일 서버 환경
  * 모든 요청이 하나의 서버에서 처리됩니다. 세션, 임시 파일, 로컬 변수 등이 동일 서버에 존재하므로 별도 고려가 필요 없습니다.
* 분산 웹(이벤트 서버) 환경
  * 분산 서버(A, B, C): 사용자 요청을 처리하는 서버. 요청마다 다른 서버로 라우팅될 수 있음
  * Origin 서버: 파일 저장, 데이터 원본을 관리하는 서버
* **분산 웹 환경에서는 동일 요청이 항상 같은 서버에서 처리된다는 보장이 없습니다.**
* 따라서 다음과 같은 경우 반드시 `api.{도메인}`을 사용해야 합니다.

### 🤔 `api.` 도메인이란

* 고도몰은 용도별로 서브도메인을 분리하여 운영합니다.
* `api.` 도메인으로 들어오는 요청은 **Origin 서버로 직접 라우팅**됩니다. 따라서 서버 간 상태 불일치 문제가 발생하지 않습니다.
* 사용자 정의 API 컨트롤러는 `module/Controller/Api` 경로에 생성하며
* `api.{도메인}/경로/파일명` 형식으로 접근합니다. 상세한 컨트롤러 생성 방법은 [컨트롤러 > API Controller](https://devcenter-help.nhn-commerce.com/guide/tuning/source-code/controller#api-controller) 를 참고하세요.

### 🧑🏻‍💻 개발 케이스

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

* 정기결제, 자동발송, 배치 처리 등 외부 cron에서 쇼핑몰 URL을 호출하는 경우
* \`[www.\`](http://www.`) 도메인을 사용하면 요청이 매번 다른 서버로 분산됩니다
* 잘못된 예
  * 분산 웹 환경에서 요청이 분산되어 상태 불일치 발생
  * <https://www.example.com/cron/auto_payment.php>
* 올바른 예
  * Origin 서버로 고정 라우팅
  * [https://api.example.com/cron/auto\_payment.php](<  https://api.example.com/cron/auto_payment.php>)

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

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

<table><thead><tr><th>항목</th><th>단일 웹</th><th width="180">분산 웹</th><th width="193.46484375">대응 방법</th></tr></thead><tbody><tr><td>파일 시스템 (임시 파일, 업로드 파일)</td><td>동일 디스크</td><td>서버별 별도 디스크</td><td><code>api.</code> 도메인 사용</td></tr><tr><td>PG 결제 토큰/인증값</td><td>동일 서버</td><td>생성 서버와 검증 서버 불일치 가능</td><td><code>api.</code> 도메인 사용</td></tr></tbody></table>

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

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

* 결제 요청 -> 결제 승인 콜백 -> 주문 완료 처리
* 파일 업로드 -> 업로드된 파일 참조

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

### 📢 주의사항

* `api.` 도메인의 SSL 인증서가 정상 설정되어 있어야 합니다. 관리자 > 기본설정 > 보안서버(SSL)에서 확인하세요.
* `api.` 도메인은 Origin 서버로 직접 연결되므로 과도한 트래픽을 `api.` 도메인으로 보내면 Origin 서버에 부하가 집중될 수 있습니다.&#x20;
* 일반 사용자 트래픽은 `www.` 또는 `m.`도메인을 유지하고 서버 간 상태 공유가 필요한 처리에만 `api.` 도메인을 사용하세요.