diff --git a/docs/deploy.md b/docs/deploy.md index d5bc1ca..09b4b9e 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -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. 백업 ### 우선순위