docs(upload): 업로드 한도 정책 + 책임 경계 + 정책식 문서화

Phase B 로 확립된 업로드 size 정책을 deploy.md 에 섹션으로 정리:
- config.yaml `upload` 블록 (단일 진실 공급원)
- 4 레이어 책임 경계 (home-caddy / FastAPI / /config/public / UploadDropzone)
- 정책식: `proxy max_size ≥ upload.max_bytes * content_length_slack_ratio`
- 다른 배수("1.1배" 등) 혼용 금지
- /api/config/public scope 제약 (민감정보 금지 / 프론트 필수 기준)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Hyungi Ahn
2026-04-17 08:07:24 +09:00
parent d2aa6c7c41
commit 0807574986
+36 -1
View File
@@ -139,7 +139,42 @@ Docker 내부에서 APScheduler로 관리 (launchd 대체):
| */5분 | file_watcher | 상시 |
| */10분 | processing_queue consumer | 상시 |
## 7.
## 7. 업로드 한도 정책
업로드 크기 제한의 단일 진실 공급원은 `config.yaml``upload` 블록.
```yaml
upload:
max_bytes: 100000000 # 100 MB (SI). authoritative policy value.
content_length_slack_ratio: 1.05 # multipart 오버헤드 여유.
stream_chunk_bytes: 1048576 # 1 MiB 단위 스트리밍 read/write.
```
### 책임 경계
| 레이어 | 역할 | 값 출처 |
|---|---|---|
| home-caddy (edge proxy) | DoS 방어선 | infra config |
| FastAPI `POST /api/documents/` | **authoritative policy enforcement** (스트리밍 누적 검사, 413) | `upload.max_bytes` |
| `GET /api/config/public` | 프론트용 공개 값 노출 | `upload.max_bytes` 재사용 |
| 프론트 `UploadDropzone.svelte` | **pre-check UX** (드롭 시 즉시 차단) | API 응답 구독 (fallback 100MB) |
### 정책식 (단일 기준)
> **proxy `request_body max_size` ≥ `upload.max_bytes * upload.content_length_slack_ratio`**
현재 기본값 기준 → 최소 proxy 한도 **105,000,000 바이트 (≈105MB SI)**. home-caddy 도
이 식을 만족해야 하며, 다른 배수("1.1배" 등) 를 별도로 관리하지 말 것.
### `GET /api/config/public` 범위 제한
이 엔드포인트는 **민감정보 없는 프론트 필수 설정만** 제공. 임의의 서버 설정을
프론트에 노출하는 범용 창구로 확장 금지. 필드 추가 시 리뷰 기준:
1. 민감정보 포함 여부 (비밀/내부 정책/경로 등 배제)
2. 프론트 동작 필수 여부 (UI 가 실제로 소비하지 않으면 불추가)
## 8. 백업
### 우선순위