# Fileserver 설정 아래 key는 모두 `app.fileserver-platform` 아래에 있다(환경 변수 형태는 `APP_FILESERVER_PLATFORM_*`). `app.fileserver-platform.enabled`가 false인 동안에는 이 key들을 아예 바인딩하지 않는다. 바인딩하는 auto-configuration이 처리되지 않기 때문이다. 그래서 아무도 켜지 않은 블록의 잘못된 값이 시작을 실패시키지 않는다. 켜면 바인딩은 엄격하다. 접두사 아래의 모르는 key는 무시하지 않고 거부한다. 기본값은 보수적인 쪽이다. - admin plane은 꺼져 있다. - 백그라운드 회수는 켜져 있다(꺼 두면 volume이 찬다). - copy와 move는 기본 namespace로만 쓸 수 있다. - 권한을 느슨하게 풀어 주는 대체 경로는 없다. capability를 켜는 것은 의도한 행동이고, 그것이 여는 면 하나하나도 그렇다. ## 시작에 필요한 최소 설정 ```yaml app: fileserver-platform: enabled: true instance-id: ${HOSTNAME} # writer lease 소유자. 노드마다 달라야 한다 storage: root: /var/lib/backend/files # 절대 경로. webroot·설정 폴더 밖 security: access-policy: role-based # 또는 직접 만든 FileAccessPolicyPort bean observability: fingerprint-key: ${FILESERVER_FINGERPRINT_KEY} ``` 아래 중 하나라도 빠지거나 안전하지 않으면 기능을 줄여 돌지 않고 시작이 실패한다. | 조건 | 왜 치명적인가 | | --- | --- | | `security.access-policy`가 `required`로 남았는데 `FileAccessPolicyPort` bean이 없다 | 기본으로 허락하는 파일 capability는 시작을 거부하는 것보다 나쁘다 | | metric이 켜졌는데 `observability.fingerprint-key`가 없다 | 셀 수 있는 식별자를 key 없이 digest하면 되돌릴 수 있다 | | 저장 루트가 필수 capability probe를 통과하지 못한다 | 원자적으로 만들지 못하거나, staging과 content를 한 FileStore에 두지 못하거나, symlink를 거부하지 못하는 volume은 기능이 줄어든 것이 아니라 안전하지 않은 것이다 | | probe가 원자적 move를 증명하지 못한 volume에 `storage.publish-mode: atomic-move-required` | 설정한 보장을 지킬 수 없다 | | `prod` profile에서 `security.access-policy: unenforced` | 개발 때 편했던 값이 승격까지 살아남으면 안 된다 | ## 권한 — `security` | Key | 기본값 | 뜻 | | --- | --- | --- | | `access-policy` | `required` | `required`(bean을 직접 준다), `role-based`, `unenforced` | | `read-roles` | `ROLE_FILE_READ` | metadata 읽기와 다운로드를 허락한다 | | `write-roles` | `ROLE_FILE_WRITE` | create, append, finalize, delete, copy, move를 허락한다 | | `admin-roles` | `ROLE_FILE_ADMIN` | reverify와 force-delete를 허락하고, servlet chain에서 `/internal/fileserver/**`를 막는다 | 이 role들은 각 연산 안에서 등급(tier)을 정한다. 그 앞에서는 연산마다 use case가 `file:*` 권한을 가지고, web 어댑터의 method security가 그 권한을 `app.authz.role-permissions`와 대조한다. `security.yml`은 `file:read`를 `ROLE_FILE_READ`에, `file:upload`·`file:delete`·`file:copy`·`file:move`를 `ROLE_FILE_WRITE`에, `file:admin`을 `ROLE_FILE_ADMIN`에 준다. 여기서 등급 role의 이름을 바꾸면 거기서도 새 이름을 대응시켜야 한다. 아니면 등급을 보기도 전에 호출자가 거부된다(`docs/fileserver/design-deviations.md` §5). 익명 읽기 스위치는 없다. 모든 Fileserver 경로는 애플리케이션 정책을 보기 전에 servlet chain이 인증한다. 그래서 그런 설정은 transport가 이미 거부한 권한을 설명할 수밖에 없다. 접근을 허락하는 것처럼 읽히지만 허락하지 않는 설정이 된다. 세 등급은 서로 물려받지 않는다. admin role은 data plane으로 삭제할 수 없고, write role은 management plane에 닿을 수 없다. 「삭제할 수 있으면 강제 삭제도 할 수 있다」는 role 모델이면 감사하지 않는 plane을 거쳐 감사하는 plane에 닿게 된다. `unenforced`는 모든 것을 허락한다. 개발자가 role 모델을 정하기 전에 업로드와 다운로드를 시험해 보라고 있는 값이다. 운영 profile에서는 거부한다. ## 저장소 — `storage` | Key | 기본값 | 뜻 | | --- | --- | --- | | `root` | `/var/lib/backend/files` | 절대 경로. 경로가 존재하는 유일한 곳 | | `publish-mode` | `atomic-move-preferred` | `atomic-move-required`, `atomic-move-preferred`, `metadata-pointer` | | `buffer-size` | `128KB` | 모든 전송 할당의 상한. 메모리는 파일 크기에 따라 늘지 않는다 | | `forbidden-root-ancestors` | `/app,/etc,/usr/share/nginx/html` | 저장 루트가 그 아래 있으면 안 되는 root(webroot, 설정 폴더) | `root`는 절대 경로여야 한다. 상대 경로는 프로세스 작업 폴더를 기준으로 풀리고, 그 폴더는 container와 테스트에서 다르다. 그래서 바인딩할 때 거부한다. 예전 key 셋은 없어지고 상수로 고정됐다: staging과 content는 FileStore 하나를 같이 쓴다, symbolic link는 절대 따라가지 않는다, 객체와 그 폴더는 READY 전에 sync한다. 셋 다 원자적 게시와 namespace 경계가 기대는 불변식이다. 그중 하나를 끌 수 있는 배포는 같은 이름과 같은 테스트로 다른 capability를 돌리는 셈이다. 저장소 provider를 고르는 key도 없다. 구현이 정확히 하나이고, 허용 값이 하나뿐인 `type` key는 아무도 지키지 않는 교체 가능성의 약속이다. ## 업로드, 다운로드, 전송 | Key | 기본값 | 뜻 | | --- | --- | --- | | `upload.max-file-size` | `100MB` | 넘을 수 없는 상한. `spring.servlet.multipart.max-file-size`도 이 값으로 정한다 | | `upload.max-request-size` | `110MB` | 요청 전체 크기. `max-file-size` 이상이어야 한다 | | `upload.initial-reservation` | `8MB` | 길이를 모를 때 예약하는 할당량 | | `upload.ttl` | `1h` | 이어 올리기 업로드를 다시 잡을 수 있는 기간 | | `upload.reservation-ttl` | `24h` | 정산하지 않은 할당량 예약이 남는 기간 | | `upload.lease-duration` | `30s` | writer lease. 이 값의 1/3마다 갱신한다 | | `upload.max-parts` | `16` | multipart part 개수 상한 | | `upload.require-content-length` | `false` | chunked raw 업로드를 거부한다 | | `download.cache-control` | `private, no-store` | 모든 content 응답에 붙인다 | | `download.inline-allowed` | `false` | 스크립트가 될 수 있는 content는 이 값과 상관없이 늘 첨부 파일이다 | | `download.max-ranges` | `1` | 여러 범위 응답은 켜야 생긴다 | | `download.max-range-bytes` | `100MB` | 범위 응답 하나가 덮을 수 있는 총 바이트 | | `download.zero-copy-enabled` | `true` | 큰 평문 응답을 kernel에 넘긴다 | | `download.zero-copy-minimum-bytes` | `16MB` | 이보다 작으면 syscall 준비 비용이 아끼는 것보다 크다 | | `transfer.core-size` / `max-size` / `queue-capacity` | `8` / `32` / `64` | blocking 전송 pool의 상한 | | `transfer.await-seconds` | `300` | 전송 하나가 pool 스레드를 잡을 수 있는 시간 | zero copy는 헤더도 상태 코드도 바꾸지 않는다. 저장소가 거절하면(읽을 수 없는 영역, 지원하지 않는 backend) 응답을 스트리밍으로 보내고, 바이트는 똑같다. ## 검증 — `verification` | Key | 기본값 | 뜻 | | --- | --- | --- | | `timeout` | `5s` | 검증기 하나의 상한 | | `require-media-type-verdict` | `false` | 형식을 정하지 못한 파일을 거부한다 | | `inline-safe-profile` | `false` | 스크립트가 될 수 있는 content를 격리하지 않고 받는다 | `inline-safe-profile: true`는 다운로드를 믿을 수 있는 origin에서 inline으로 절대 내보내지 않을 때만 쓴다. ## 할당량과 허가 — `quota` | Key | 기본값 | 뜻 | | --- | --- | --- | | `instance-upload-permits` | `16` | 이 노드가 받는 동시 업로드 수 | | `scope-upload-permits` | `4` | 호출자(principal) 하나가 받는 동시 업로드 수. 넘으면 재시도할 수 있는 `429` | | `direct-download-permits` | `64` | 위임하지 않은 동시 다운로드 수 | | `soft-high-water` | `0.70` | 압박을 보고하기 시작하는 저장소 사용 비율 | | `hard-high-water` | `0.85` | 업로드와 copy를 거부하는 저장소 사용 비율 | | `namespace-limit` | 없음(제한 없음) | namespace 하나가 가질 수 있는 최대 바이트. 살아 있는 예약과 확정 사용량의 합이다. 이를 넘길 create, copy, move는 기록·바이트·namespace가 바뀌기 전에 `QUOTA_EXCEEDED`(413)로 거부한다 | `namespace-limit`은 할당량 ledger가 보고한 사용량과 비교한 뒤 예약한다. transaction 하나 안에서 하지만 namespace별 lock은 없다. 그래서 같은 순간에 허가된 예약들은 자기 크기만큼까지 한도를 넘을 수 있고, 그다음 예약은 거부된다. 정확한 상한이 필요한 서비스는 자기 persistence 어댑터에 그 lock을 더한다. 다른 namespace로의 move는 ledger에서 파일의 바이트를 함께 옮긴다. 기록을 옮기는 transaction 안에서 대상의 한도를 확인하고, 대상 쪽에 확정 사용량으로 올리고, 원래 쪽에서 회수한다. 거부된 move는 파일과 두 namespace의 사용량을 그대로 둔다. 저장소 사용 비율을 읽지 못하면 허가 단계는 그것을 모름으로 보고 high-water 규칙을 적용하지 않는다. 지어낸 `0`은 보호 장치를 조용히 끄고, 지어낸 `1`은 syscall 하나 실패로 capability를 내린다. ## 백그라운드 회수 — `cleanup` | Key | 기본값 | 뜻 | | --- | --- | --- | | `enabled` | `true` | 이 노드에서 cleanup worker를 돌린다. `false`면 시작할 때 경고를 남긴다 | | `interval` | `60s` | batch 사이의 고정 지연. 고정 주기가 아니다 | | `max-items` | `100` | batch 하나가 가져갈 수 있는 항목 수 | | `max-bytes` | `1GB` | batch 하나가 회수할 수 있는 바이트 | | `retry-backoff` | `5m` | 실패한 항목이 다시 차례가 될 때까지 기다리는 시간 | worker는 기본으로 켜져 있다. cleanup 큐가 이름 댄 것만 지운다. worker가 없으면 취소·만료된 staging, 거부· 삭제된 content가 hard high-water가 모든 업로드를 막을 때까지 volume에 남는다. 노드 하나가 worker를 끌 수 있다(예: 다른 노드가 돌릴 때). 그러면 시작할 때 `app.fileserver-platform.cleanup.enabled=false`를 이름 댄 `WARN`을 남긴다. worker가 없는 노드도 cleanup 항목을 큐에 넣는다. 다른 노드나 운영자가 회수한다. (경고 대신 필수 「이유」 key를 두는 안도 검토했지만 버렸다. 시작 경고를 끄는 것 말고는 효과가 없는 설정을 worker 아닌 모든 노드가 들고 다니게 된다.) 여덟 번 실패한 항목은 영원히 재시도하지 않고 내려놓는다. 버리지 않고 세워 두므로 운영자에게는 계속 보인다. 매 회차는 이런 일도 한다. - `expiresAt`이 지난 업로드를 만료시킨다(기록은 `EXPIRED`가 되고 staging 바이트는 큐에 들어간다). - admin plane이 격리로 내린 고아 객체를 지운다. - 오래된 `UPLOADED`/`VERIFYING`/`FAILED` 기록에 대해 맞춰 보기를 돌린다. 그래서 결과를 모르는 게시가 운영자 없이 정리된다. ## Copy와 move 대상 `app.fileserver-platform.target-namespaces`(`APP_FILESERVER_PLATFORM_TARGET_NAMESPACES`, 쉼표 목록, 기본은 비어 있음)는 늘 허용되는 `default-namespace` 말고 copy와 move가 쓸 수 있는 namespace를 적는다. copy나 move의 대상 namespace는 요청 본문에서 오고, namespace는 할당량을 묶는 단위이기도 하다. 그 밖의 대상은 바이트가 움직이거나 예약을 잡기 전에 `ACCESS_DENIED`로 거부한다. ## Management plane — `admin` | Key | 기본값 | 뜻 | | --- | --- | --- | | `enabled` | `false` | `/internal/fileserver/**`를 연다 | | `orphan-minimum-age` | `1h` | 참조 없는 객체가 scan에 이름이 오르기 전에 존재해야 하는 시간 | content를 게시하는 것과 그 기록을 확정하는 것은 두 단계다. `orphan-minimum-age`보다 어린 것은 버려진 것이 아니라 확정 중인 것으로 본다. 이 값을 줄이면 동시 업로드가 고아처럼 보인다. ## 프런트 프록시 위임 — `nginx` | Key | 기본값 | 뜻 | | --- | --- | --- | | `enabled` | `false` | 본문 대신 `X-Accel-Redirect`를 내보낸다 | | `internal-prefix` | `/__files/` | content root로 풀리는 `internal` location이어야 한다 | | `object-suffix` | `.bin` | 프록시가 붙이는 배치 접미사 | | `minimum-size` | `16MB` | 이보다 작으면 애플리케이션이 직접 전송한다 | 위임은 권한 확인과 READY 관문을 지난 뒤에만 정한다. 그래서 내부 redirect는 호출자가 이미 읽어도 되는 content만 가리킬 수 있다. ## 프로토콜 — `tus` | Key | 기본값 | 뜻 | | --- | --- | --- | | `enabled` | `false` | tus 1.0 endpoint를 연다 | HTTPbis resumable-upload draft-12 면은 실험 단계이고 [support-matrix.md](support-matrix.md)에 적었다.