> 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.` 도메인을 사용하세요.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devcenter-help.nhn-commerce.com/other-guide/multi-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.