# 서비스 파일 업로드 413 오류 수정 (Nginx client_max_body_size)

**날짜:** 2026-03-18
**작업자:** Claude Code

---

## 변경 개요

서비스(React) 수입검사 입력 모달에서 5MB PNG 파일 업로드 시 `413 Content Too Large` 오류 발생.
개발서버 Nginx의 `dev.codebridge-x.com` 서버 블록에 `client_max_body_size` 미설정으로 기본값 1MB가 적용되어 있었다.

---

## 1. 원인 분석

### 1.1 오류 내용

```
POST https://dev.codebridge-x.com/material/receiving-management/119?mode=view 413 (Content Too Large)
```

### 1.2 요청 흐름 및 차단 지점

```
브라우저 → Nginx (dev.codebridge-x.com) → Next.js 서버 액션 → API 서버
             ↑
          🔴 여기서 차단 (client_max_body_size 기본값 1MB)
```

### 1.3 기존 설정 비교

| 서버 블록 | `client_max_body_size` | 상태 |
|-----------|----------------------|------|
| `api.codebridge-x.com` | 210M | ✅ 정상 |
| `admin.codebridge-x.com` | 210M | ✅ 정상 |
| `dev.codebridge-x.com` | **미설정 (기본 1MB)** | ❌ 누락 |

---

## 2. 수정 내용

### 2.1 개발서버 Nginx 설정 변경

| 항목 | 변경 전 | 변경 후 |
|------|---------|---------|
| `client_max_body_size` | 미설정 (1MB) | **20M** |

**수정 파일**: `/etc/nginx/sites-enabled/codebridge-x` (개발서버)

```nginx
# HTTPS: Vite dev server (dev.codebridge-x.com)
server {
    server_name dev.codebridge-x.com;

    client_max_body_size 20M;  # ← 추가됨

    error_log  /var/log/nginx/dev_codebridge-x_error.log warn;
    access_log /var/log/nginx/dev_codebridge-x_access.log;
    ...
}
```

### 2.2 적용

```bash
sudo nginx -t        # 설정 검증 통과
sudo systemctl reload nginx  # 적용
```

---

## 3. 파일 업로드 용량 제한 전체 현황

| 계층 | 제한값 | 설정 위치 |
|------|--------|----------|
| React FileDropzone | 10MB | `react/src/components/ui/file-dropzone.tsx` |
| Next.js Server Actions | 10MB | `react/next.config.ts` → `bodySizeLimit: '10mb'` |
| Nginx (dev.codebridge-x.com) | **20MB** | `/etc/nginx/sites-enabled/codebridge-x` |
| PHP upload_max_filesize | 20MB | `docker/api/uploads.ini` |
| Laravel Validation | 20MB | `api/config/filesystems.php` → `max_file_size` |

> **실효적 최대 업로드 크기**: 10MB (Next.js bodySizeLimit이 가장 작은 제한)

---

## 4. 운영서버 배포 시 확인 사항

> **경고: 운영서버 Nginx에도 동일 설정이 필요할 수 있다.**

운영서버(`codebridge-x.com`)의 React Nginx 서버 블록에도 `client_max_body_size`가 설정되어 있는지 확인 필요.
미설정 시 동일한 413 오류 발생.

```nginx
# 운영서버 Nginx 확인 필요
server {
    server_name codebridge-x.com;
    client_max_body_size 20M;  # ← 확인/추가 필요
    ...
}
```

---

## 관련 문서

- `dev/deploys/ops-manual/11-server-setup.md` — 서버 Nginx 설정 가이드

---

**최종 업데이트**: 2026-03-18