문제: 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개가 번역 전과 같음).
13 KiB
Fileserver 설정
아래 key는 모두 app.fileserver-platform 아래에 있다(환경 변수 형태는 APP_FILESERVER_PLATFORM_*).
app.fileserver-platform.enabled가 false인 동안에는 이 key들을 아예 바인딩하지 않는다. 바인딩하는
auto-configuration이 처리되지 않기 때문이다. 그래서 아무도 켜지 않은 블록의 잘못된 값이 시작을 실패시키지
않는다. 켜면 바인딩은 엄격하다. 접두사 아래의 모르는 key는 무시하지 않고 거부한다. 기본값은 보수적인 쪽이다.
- admin plane은 꺼져 있다.
- 백그라운드 회수는 켜져 있다(꺼 두면 volume이 찬다).
- copy와 move는 기본 namespace로만 쓸 수 있다.
- 권한을 느슨하게 풀어 주는 대체 경로는 없다.
capability를 켜는 것은 의도한 행동이고, 그것이 여는 면 하나하나도 그렇다.
시작에 필요한 최소 설정
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에 적었다.