권혁성
0ace50b006
- Phase 0: INDEX.md 전면 재작성, CLAUDE.md→INDEX.md 통합 삭제 - Phase 0: front/→guides/ 이관(5개 파일), changes/ D7 포맷 통일(3개) - Phase 0: guides/ai-config-설정.md→ai-config-settings.md D3 통일 - Phase 2: architecture/+specs/→system/ 이관(6개 이동, 4개 폐기) - Phase 2: 13개 파일 경로 참조 수정 (specs/→system/, architecture/→system/) - Phase 4: 7개 파일 11개 교차참조 깨진 링크 수정 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
271 lines
9.7 KiB
Markdown
271 lines
9.7 KiB
Markdown
# Nginx & FastCGI 초보자 가이드
|
|
|
|
> **작성일**: 2026-02-22
|
|
> **대상**: SAM 프로젝트에 새로 합류한 개발자
|
|
|
|
> **서버 인프라 학습 시리즈** | Part 2 of 3
|
|
> [1. 서버 동작 원리](server-how-it-works.md) → **2. Nginx & FastCGI** → [3. PHP-FPM](php-fpm-guide.md)
|
|
|
|
---
|
|
|
|
## 1. 개요
|
|
|
|
### 1.1 이 문서의 목적
|
|
|
|
"Nginx가 뭐지?", "FastCGI가 뭐지?" — 이 두 질문에 답하는 문서다.
|
|
[서버 동작 원리 가이드](server-how-it-works.md)와 [PHP-FPM 가이드](php-fpm-guide.md)에서 간략히 언급한 내용을 **깊이 파고든다**.
|
|
|
|
### 1.2 핵심 한 줄 정리
|
|
|
|
- **Nginx** = 요청을 받아서 적절한 곳에 전달하는 **교통 경찰**
|
|
- **FastCGI** = Nginx와 PHP-FPM이 대화하는 **통신 규약(프로토콜)**
|
|
|
|
---
|
|
|
|
## 2. Nginx란?
|
|
|
|
### 2.1 웹서버가 하는 일
|
|
|
|
웹서버는 브라우저의 요청을 받아서 응답을 돌려주는 프로그램이다.
|
|
|
|
```
|
|
브라우저: "index.html 주세요"
|
|
웹서버: "여기 있습니다" (파일 내용 전송)
|
|
```
|
|
|
|
### 2.2 Nginx의 정체
|
|
|
|
Nginx(엔진엑스)는 **고성능 웹서버이자 리버스 프록시**다. 2004년 러시아 개발자 이고르 시소예프가 만들었다.
|
|
|
|
**비유**: 대형 호텔의 프런트 데스크
|
|
|
|
```
|
|
┌─────────────────────────────────────────────┐
|
|
│ Nginx (프런트 데스크) │
|
|
│ │
|
|
│ 손님(브라우저)이 오면: │
|
|
│ │
|
|
│ "이미지 주세요" → 직접 서빙 (정적 파일) │
|
|
│ "PHP 실행해줘" → PHP-FPM에 전달 (FastCGI) │
|
|
│ "React 페이지" → Node.js에 전달 (프록시) │
|
|
│ "API 호출" → API 서버에 전달 (프록시) │
|
|
└─────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 2.3 Nginx vs Apache
|
|
|
|
| 항목 | Nginx | Apache |
|
|
|------|-------|--------|
|
|
| 아키텍처 | **이벤트 기반** (비동기) | 프로세스/스레드 기반 |
|
|
| 동시 접속 | 수만 개 가능 | 수천 개 수준 |
|
|
| 메모리 | 적게 사용 | 많이 사용 |
|
|
| 정적 파일 | **매우 빠름** | 보통 |
|
|
| PHP 실행 | 직접 불가 (FastCGI 필요) | mod_php로 직접 가능 |
|
|
| SAM에서 | **사용 중** | 사용 안 함 |
|
|
|
|
**왜 SAM은 Nginx를 쓰는가**: 서버 스펙(2코어/3.8GB)이 제한적이므로, 적은 메모리로 5개 서비스를 동시 라우팅할 수 있는 Nginx가 적합하다.
|
|
|
|
### 2.4 Nginx의 3가지 역할
|
|
|
|
```
|
|
역할 1 — 정적 파일 서빙: logo.png → Nginx가 직접 전송 (PHP 개입 없음)
|
|
역할 2 — 리버스 프록시: PHP 요청 → PHP-FPM, React 요청 → Node.js
|
|
역할 3 — SSL 종료: HTTPS(암호화) → Nginx에서 해독 → 내부는 HTTP(평문)
|
|
```
|
|
|
|
---
|
|
|
|
## 3. FastCGI란?
|
|
|
|
### 3.1 먼저 CGI를 이해하자
|
|
|
|
**CGI**(Common Gateway Interface)는 웹서버가 외부 프로그램을 실행하는 규약이다. 1993년에 만들어졌다.
|
|
|
|
```
|
|
브라우저 → 웹서버 → "PHP 프로그램을 실행해서 결과를 줘"
|
|
↓
|
|
[새 프로세스 생성] → PHP 실행 → 결과 → [프로세스 종료]
|
|
```
|
|
|
|
**문제**: 요청마다 프로세스를 새로 생성하고 종료한다. 100명이 동시에 접속하면 100개 프로세스가 생겼다 사라진다. **느리고 비효율적**이다.
|
|
|
|
### 3.2 FastCGI가 해결한 것
|
|
|
|
**FastCGI**는 1996년에 CGI의 문제를 해결하기 위해 만들어졌다. 핵심 차이:
|
|
|
|
```
|
|
[CGI] 요청 → 프로세스 생성 → 실행 → 종료 → 요청 → 생성 → 실행 → 종료
|
|
[FastCGI] 프로세스가 미리 떠 있음 → 요청 → 실행 → 대기 → 요청 → 실행 → 대기
|
|
```
|
|
|
|
**비유**: CGI는 택시(매번 부르고 보냄), FastCGI는 전용 기사(항상 대기 중).
|
|
|
|
### 3.3 FastCGI는 프로토콜이다
|
|
|
|
FastCGI는 프로그램이 아니라 **통신 규약(프로토콜)**이다. HTTP처럼 "이렇게 데이터를 주고받자"는 약속이다.
|
|
|
|
```
|
|
┌──────────┐ ┌──────────┐
|
|
│ Nginx │ ── FastCGI 규약 ── │ PHP-FPM │
|
|
│ (클라이언트) │ │ (서버) │
|
|
└──────────┘ └──────────┘
|
|
```
|
|
|
|
- HTTP: 브라우저와 웹서버 사이의 규약
|
|
- **FastCGI**: 웹서버와 애플리케이션 서버 사이의 규약
|
|
- 둘은 다른 프로토콜이다 (FastCGI는 바이너리, HTTP는 텍스트)
|
|
|
|
### 3.4 FastCGI가 전달하는 정보
|
|
|
|
Nginx가 PHP-FPM에 보내는 주요 파라미터:
|
|
|
|
| 파라미터 | 의미 | 예시 |
|
|
|---------|------|------|
|
|
| `SCRIPT_FILENAME` | 실행할 PHP 파일 | `/var/www/mng/public/index.php` |
|
|
| `REQUEST_METHOD` | HTTP 메서드 | `GET`, `POST` |
|
|
| `QUERY_STRING` | URL 파라미터 | `page=1&sort=name` |
|
|
| `HTTP_HOST` | 도메인 | `mng.sam.kr` |
|
|
|
|
PHP에서 `$_SERVER['REQUEST_METHOD']`, `$_GET` 등으로 접근하는 값이 바로 이것이다.
|
|
|
|
---
|
|
|
|
## 4. Nginx + FastCGI 동작 원리
|
|
|
|
### 4.1 전체 흐름
|
|
|
|
`https://mng.sam.kr/orders?page=2` 접속 시:
|
|
|
|
```
|
|
브라우저 →① HTTPS → Nginx(도메인 라우팅) →② try_files → index.php
|
|
→③ FastCGI → PHP-FPM(:9000) →④ Laravel → DB → HTML →⑤ 응답 역순
|
|
```
|
|
|
|
### 4.2 Nginx 설정 해부
|
|
|
|
SAM의 MNG 설정에서 FastCGI 관련 부분:
|
|
|
|
```nginx
|
|
# docker/nginx/nginx.conf (외부 Nginx — MNG 섹션)
|
|
|
|
location / {
|
|
try_files $uri $uri/ /index.php?$query_string;
|
|
# ① ② ③
|
|
}
|
|
|
|
location ~ \.php$ {
|
|
include fastcgi_params; # ④
|
|
fastcgi_pass mng:9000; # ⑤
|
|
fastcgi_param SCRIPT_FILENAME /var/www/mng/public$fastcgi_script_name; # ⑥
|
|
fastcgi_param PATH_INFO $fastcgi_path_info; # ⑦
|
|
fastcgi_param HTTPS on; # ⑧
|
|
fastcgi_read_timeout 300s; # ⑨
|
|
}
|
|
```
|
|
|
|
**핵심 줄 해설**:
|
|
|
|
- ①②③ `try_files`: 파일 있으면 직접 서빙, 없으면 `index.php`로 (Laravel 진입점)
|
|
- ⑤ `fastcgi_pass mng:9000`: **핵심! FastCGI 요청을 mng 컨테이너 9000번 포트로 전달**
|
|
- ⑥ `SCRIPT_FILENAME`: PHP-FPM이 실행할 파일의 절대 경로
|
|
- ⑧ `HTTPS on`: PHP에서 HTTPS 요청으로 인식하도록 설정
|
|
- ⑨ `fastcgi_read_timeout`: PHP 응답 대기 최대 300초
|
|
|
|
### 4.3 왜 index.php 하나로 모든 요청을 처리하는가
|
|
|
|
Laravel은 **프론트 컨트롤러 패턴**을 사용한다. `/orders`, `/users/123` 등 모든 URL이 `public/index.php`를 통과하고, Laravel 라우터가 적절한 컨트롤러로 분배한다. `try_files` 설정이 이를 가능하게 한다.
|
|
|
|
---
|
|
|
|
## 5. SAM의 Nginx 구조
|
|
|
|
### 5.1 2계층 Nginx
|
|
|
|
SAM은 Nginx가 **2단계**로 작동한다:
|
|
|
|
```
|
|
브라우저 → [1계층: 외부 Nginx (sam-nginx-1)] → SSL 종료 + 도메인 라우팅
|
|
│ │
|
|
▼ ▼
|
|
[2계층: sam-mng-1] [2계층: sam-api-1]
|
|
Nginx(:80) Nginx(:80)
|
|
↓ FastCGI ↓ FastCGI
|
|
PHP-FPM(:9000) PHP-FPM(:9000)
|
|
```
|
|
|
|
### 5.2 도메인별 라우팅 정리
|
|
|
|
| 도메인 | 1계층(외부 Nginx) 동작 | 프로토콜 |
|
|
|--------|----------------------|---------|
|
|
| `mng.sam.kr` | `fastcgi_pass mng:9000` | **FastCGI** |
|
|
| `api.sam.kr` | `fastcgi_pass api:9000` | **FastCGI** |
|
|
| `dev.sam.kr` | `proxy_pass react:3000` | HTTP 프록시 |
|
|
| `sales.sam.kr` | `proxy_pass sales:80` | HTTP 프록시 |
|
|
| `5130.sam.kr` | `proxy_pass php73:80` | HTTP 프록시 |
|
|
|
|
> **핵심**: PHP 서비스는 **FastCGI**로, Node.js/레거시 서비스는 **HTTP 프록시**로 연결한다.
|
|
|
|
---
|
|
|
|
## 6. 자주 묻는 질문
|
|
|
|
### 6.1 "FastCGI와 HTTP 프록시의 차이는?"
|
|
|
|
| 항목 | FastCGI | HTTP 프록시 |
|
|
|------|---------|-----------|
|
|
| 프로토콜 | 바이너리 (FastCGI) | 텍스트 (HTTP) |
|
|
| 용도 | PHP-FPM 등 CGI 호환 앱 | Node.js, 일반 웹서버 |
|
|
| Nginx 설정 | `fastcgi_pass` | `proxy_pass` |
|
|
| SAM에서 | MNG, API | React, Sales, 5130 |
|
|
|
|
### 6.2 "try_files가 뭔가요?"
|
|
|
|
Nginx가 파일을 찾는 순서를 지정한다:
|
|
|
|
```nginx
|
|
try_files $uri $uri/ /index.php?$query_string;
|
|
```
|
|
|
|
1. `$uri` — `/orders.html` 파일이 있는가? → 없다
|
|
2. `$uri/` — `/orders/` 디렉토리가 있는가? → 없다
|
|
3. `/index.php?$query_string` — index.php로 넘긴다 (Laravel이 처리)
|
|
|
|
### 6.3 "SCRIPT_FILENAME은 왜 설정하나?"
|
|
|
|
PHP-FPM은 어떤 PHP 파일을 실행할지 알아야 한다. Nginx가 FastCGI 파라미터로 알려준다.
|
|
|
|
```nginx
|
|
fastcgi_param SCRIPT_FILENAME /var/www/mng/public$fastcgi_script_name;
|
|
# /orders 요청 시 → /var/www/mng/public/index.php
|
|
```
|
|
|
|
이 설정이 잘못되면 "File not found" 에러가 발생한다.
|
|
|
|
### 6.4 "502/504 에러가 나면?"
|
|
|
|
| 에러 | 원인 | 대응 |
|
|
|------|------|------|
|
|
| **502 Bad Gateway** | PHP-FPM이 죽었거나 연결 불가 | `docker ps`, `docker logs` 확인 |
|
|
| **504 Gateway Timeout** | PHP 처리가 너무 오래 걸림 | `fastcgi_read_timeout` 증가 또는 코드 최적화 |
|
|
|
|
---
|
|
|
|
## 관련 문서
|
|
|
|
**학습 시리즈**:
|
|
|
|
| 순서 | 문서 | 설명 |
|
|
|------|------|------|
|
|
| Part 1 | [server-how-it-works.md](server-how-it-works.md) | 서버 동작 원리 전체 흐름 (이전) |
|
|
| Part 3 | [php-fpm-guide.md](php-fpm-guide.md) | PHP-FPM 프로세스 관리 심화 (다음) |
|
|
|
|
**참고 문서**:
|
|
|
|
| 문서 | 설명 |
|
|
|------|------|
|
|
| [docker-setup.md](../system/docker-setup.md) | Docker 환경 설정값 상세 |
|
|
|
|
---
|
|
|
|
**최종 업데이트**: 2026-02-22
|