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:
+36
-1
@@ -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. 백업
|
||||
|
||||
### 우선순위
|
||||
|
||||
|
||||
Reference in New Issue
Block a user