문제: docs/fileserver 아래 살아 있는 문서 8개가 영어였다(language 예외). 번역하며 본 주장 중 지금 코드와 다른 것이 있었다. - design-deviations.md: 지운 `FileStateMachine`·`FileserverStorageConfiguration`· content-store SPI 넷(`AsyncContentStore` 등)을 지금 있는 것처럼 적었다. 고정 테스트로 없는 `SampleApplicationContextTest`·`LocalOrphanScanAdapterTest`· `FileserverRoundTripContractTest`를 댔다. JPA 저장소가 persistence-jpa에 있다고 했지만 지금은 persistence-fileserver의 `FileserverJpaPersistenceConfig` 조건 하나 뒤에 있다. 지운 reactive transport가 아직 스트리밍한다고 했다. - security.md: 「익명 읽기를 켜면」이라고 했지만 설정 스위치가 없다 (`FileserverSecurityConfiguration`이 늘 false로 만든다). 이름 `ContentDispositionFactory`는 지금 `HttpContentDispositionFactory`다. - upgrade-guide.md: batch 실패를 `results[].problem`으로, 결과 모름을 problem document로 읽으라고 했다. 지금은 `results[].error`와 Envelope `error.details.ambiguous`다. 확인 명령이 Fileserver 테스트가 없는 `:app-bootstrap:test --tests '*Fileserver*'`와 fileserver 코드가 없는 `:application-core:check`·`:adapter:inbound:web:check`를 돌렸다. - operations.md: 「NFS 결과 모름」 신호를 problem document로 적었다(지금은 Envelope). 고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 지원 등급 이름(Stable, Beta, Limited, Compatibility, Experimental)은 표와 테스트가 읽는 꼬리표라 원문으로 둔다(messaging 지원 매트릭스와 같다). configuration.md의 절 제목은 테스트가 읽는 「… — `key`」 꼴을 지킨다. 위 불일치는 코드에 맞춰 고쳤다. 테스트: FileserverDocumentationCoverageTest가 runbook 제목 일곱과 「Explicitly not claimed」를 영어 문자열로 단언했다. 같은 계약(runbook마다 제목이 있고, 주장하지 않는 것을 따로 밝힌다)을 한국어 제목 `## 저장소 가득 참` 등과 `## 주장하지 않는 것`으로 단언한다. 제목 앞에 `## `를 붙여 본문 어딘가에 낱말만 있어도 통과하던 것을 제목으로 좁혔다. metric 이름·CI job·endpoint·설정 key 단언은 그대로다. 버린 대안: runbook 제목을 영어로 남기기. 살아 있는 문서를 한국어로 쓴다는 소유자 결정과 맞지 않는다. 위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다. 검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0). 테스트의 단언을 같은 정규식으로 문서에 돌려 보았다(runbook 제목·job 존재·설정 key 44개가 번역 전과 같음).
203 lines
13 KiB
Markdown
203 lines
13 KiB
Markdown
# 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)에 적었다.
|