문제: 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개가 번역 전과 같음).
12 KiB
Fileserver runbook
runbook마다 그것을 시작하게 하는 metric과 그것을 해결하는 명령을 정확히 적는다. 시작 조건이 「누가 알아챘다」인 runbook은 대응할 수 없다. 그래서 아래 runbook은 모두 신호에서 시작한다.
저장소 가득 참
신호 — fileserver.quota{result="rejected"}가 오르거나 507 응답이 나온다.
저장 용량이 바닥났거나 high-water 보호 장치가 걸렸다. 업로드는 바이트를 쓰기 전에 거부되므로 망가진 것은 없다. 시스템이 끝낼 수 없는 일을 거절하고 있을 뿐이다.
curl -s $ADMIN/internal/fileserver/storage-health | jq '.usedFraction, .usableBytes'
curl -s -X POST "$ADMIN/internal/fileserver/uploads:cleanup?maxItems=500&maxBytes=10737418240"
curl -s "$ADMIN/internal/fileserver/orphans?limit=200" | jq '[.[].sizeBytes] | add'
cleanup 적체부터 비운다. 시스템이 이미 죽은 것으로 아는 공간을 되찾는다. 그다음에야 고아 맞춰 보기를 생각하고, dry run부터 한다.
고아 객체 증가
신호 — fileserver.cleanup{result="skipped"}가 오르거나, 고아 scan이 돌 때마다 더 많은 객체를 돌려준다.
물리 객체는 있는데 그것을 가리키는 metadata 기록이 없다. 당장 위험하지는 않다. 아무것도 그것을 내보내지 않는다. 하지만 용량을 끝없이 먹는다.
# 늘 먼저 본다. dryRun=false가 없는 reconcile은 실행이 아니라 계획이다.
curl -s -X POST "$ADMIN/internal/fileserver/orphans:reconcile" \
-H 'content-type: application/json' -d '{"limit":100}' | jq '.candidates'
# 방금 본 fingerprint만 적용한다.
curl -s -X POST "$ADMIN/internal/fileserver/orphans:reconcile" \
-H 'content-type: application/json' \
-d '{"dryRun":false,"limit":100,"maxBytes":1073741824,
"expectedFingerprints":["<dry run이 보여 준 값>"],"reasonCode":"ORPHAN_GROWTH_RUNBOOK"}'
fingerprint를 되돌려 보내는 것이 안전 장치다. scan과 적용 사이에 바뀐 객체는 지우지 않고 건너뛴다.
검증 적체
신호 — fileserver.verification.queue{age_bucket="old"}가 0이 아니거나, 파일이 VERIFYING에 머문다.
검증기가 느리거나 쓸 수 없다. 파일은 공개되지 않은 채 남는다. 맞는 실패 방향이다. RETRY 판정은 절대
ACCEPT가 되지 않는다.
curl -s $ADMIN/internal/fileserver/capabilities | jq '.storageType'
# 검증기가 회복되면 격리된 파일을 하나씩 다시 검사할 수 있다.
curl -s -X POST "$ADMIN/internal/fileserver/files/$FILE_ID:reverify"
검증을 꺼서 적체를 비우지 않는다. 받아들이는 판정 없이 READY가 된 파일은 나중에 검증받은 파일과 구분할 수 없다.
NFS 결과 모름
신호 — 실패 Envelope의 error.details에 "ambiguous": true가 있거나,
fileserver.transfer.interruption{reason="stale_handle"}이 나온다.
연산의 결과를 알 수 없다. 쓰기나 rename이 적용됐을 수 있는데 응답이 사라졌다. 이런 연산은 절대 자동으로 재시도하지 않는다.
# 복구 큐에 결정을 기다리는 파일이 있다.
curl -s "$ADMIN/internal/fileserver/uploads/incomplete?limit=100" | jq
맞춰 보기는 물리 크기와 digest를 기록과 비교하고, key·크기·digest· version 넷이 모두 맞을 때만 READY를 확정한다. 그보다 못한 것은 짐작하지 않고 보고한다.
PVC 다시 마운트
신호 — "atomic move", "same file store", "not writable"을 담은 시작 실패.
volume이 다른 곳에 다시 마운트돼서 probe가 필수 capability를 더는 증명하지 못한다. 애플리케이션은 원자적으로 게시할 수 없는 저장소로 내보내지 않고 요청을 거부한다.
# staging과 content가 같은 파일 저장소(같은 장치 번호)인지 pod 안에서 본다
kubectl exec <pod> -- stat -c %d /var/lib/backend/files/staging /var/lib/backend/files/content
docs/fileserver/storage-certification.md의 인증 절차로 지금 volume의 묶음(CSI driver, StorageClass,
접근 모드, backend, mount 옵션)을 다시 적고, 인증한 묶음과 비교한다. 하나라도 다르면 그것이 원인이다.
인증은 그 차이를 넘어 옮겨지지 않는다.
Nginx 위임 실패
신호 — fileserver.download.delegation{delegated="true"}인데 client에게 404가 보인다.
내부 location 설정이 잘못돼서 프록시가 넘겨받은 redirect를 풀지 못한다.
프록시 설정의 내부 location(기본 /__files/)이 아래 「운영 환경이 지켜야 할 조건」을 지키는지 본다.
curl -s $ADMIN/internal/fileserver/capabilities | jq '.capabilities.delegatedDownload'
위임을 끄는 것이 안전한 즉시 완화책이다. 애플리케이션이 직접 전송한다. 느리지만 맞다.
app.fileserver-platform.nginx.enabled=false
운영 환경이 지켜야 할 조건
이 repo는 프록시 설정 파일과 Kubernetes 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 그 파일은 서비스를 배포하는 쪽의 인프라 repo가 갖는다. 그 파일이 지켜야 할 조건은 아래다.
프런트 프록시(nginx X-Accel-Redirect 위임) — app.fileserver-platform.nginx.enabled=true일 때
- 내부 location(
app.fileserver-platform.nginx.internal-prefix, 기본/__files/)은internal이다. 클라이언트가 그 경로를 직접 부르면 404이고 content 폴더에 닿지 않는다. 애플리케이션이 준 내부 redirect로만 닿는다. - 그 location의
alias는 저장 루트의 content 폴더다(기본/var/lib/backend/files/content/). 애플리케이션은 절대 경로를 내보내지 않고 내부 접두사 아래 상대 URI만 내보낸다. 경로가 실제 위치가 되는 곳은 이alias뿐이다. - 앱으로 넘기는 요청에서 클라이언트가 보낸
X-Accel-Redirect헤더를 지운다. 남기면 호출자가 임의의 내부 객체를 가리킬 수 있다. - 업로드는 스트리밍으로 넘긴다(
proxy_request_buffering off, 본문 크기 제한은 애플리케이션이 정하므로 프록시는 막지 않는다). 프록시가 큰 본문을 디스크에 버퍼링하면 쓰기가 두 번 일어난다. - 내부 location 응답에
X-Content-Type-Options: nosniff를 붙이고, 앱이 정한Content-Disposition·Cache-Control·ETag를 그대로 넘긴다. 올라온 내용이 자기 형식을 스스로 정하게 두지 않는다.
Kubernetes 저장 volume
- PersistentVolumeClaim을 저장 루트(
/var/lib/backend/files)에 마운트하고, 접근 모드는ReadWriteOnce다.ReadWriteMany(여러 노드의 동시 쓰기)는 인증하지 않았다(support-matrix.md). - pod
securityContext.fsGroup을 이미지의 앱 그룹으로 둔다. 그래야 앱 계정이 volume에 쓸 수 있다. - 그 volume이
storage-certification.md의 인증 항목(같은 파일 저장소, 원자적 rename,O_EXCL생성)을 통과해야 한다. 기동 때FileserverStartupValidator도 같은 probe를 다시 돌린다.
정리 적체
신호 — fileserver.cleanup{result="deferred"}가 오르거나, 삭제는 계속되는데 회수한 바이트가 평평하다.
항목이 비워지는 것보다 빠르게 미뤄진다. 흔한 원인은 아직 살아 있는 writer lease가 staging 객체를 잡고 있는 것이다. 결함이 아니라 맞는 동작이다.
curl -s "$ADMIN/internal/fileserver/uploads/incomplete?limit=100" \
| jq '[.[] | select(.leaseUntil != null)] | length'
curl -s -X POST "$ADMIN/internal/fileserver/uploads:cleanup?maxItems=500&maxBytes=10737418240"
미룬 이유가 모두 ACTIVE_WRITER_LEASE면 그 업로드들이 만료되면서 적체는 스스로 풀린다. 적체를 비우려고
staging content를 지우지 않는다. 진행 중인 업로드가 망가진다.
Namespace 할당량 어긋남
신호 — namespace의 사용량(fileserver.quota 거부, 또는 아래 drift query)이 그 파일들이 실제로 가진 바이트와
다르다. 알려진 원인은 이력이다. 2026-11 성숙도 리뷰 전에는 move가 파일을 옮기면서 할당량은 옮기지 않았다.
그 수정 전에 옮긴 파일의 바이트는 아직 떠나온 namespace에 잡혀 있다. 그런 파일을 지우면 지금 있는 namespace에서
회수한다. 그 회수는 그 namespace의 다른 파일 몫을 최신 것부터 깎거나 0에서 멈추고, 어느 쪽이든 옛 몫은
남는다. 그 수정을 받기 전에 namespace를 넘어 파일을 옮긴 파생 서비스에는 이 어긋남이 있다. 그런 적이 없는
서비스에는 없어야 한다.
ledger가 같아야 하는 값: 할당량은 파일을 게시할 때 확정하고 cleanup이 content를 지울 때 회수한다. 그래서
namespace의 확정 바이트는 아직 DELETED가 아닌 게시된 파일 크기의 합이다. 아래 query가 둘을 비교한다.
아무것도 바꾸지 않는다.
WITH booked AS (
SELECT scope_value AS namespace, sum(committed_bytes) AS booked_bytes
FROM fs_quota_reservation
WHERE scope_type = 'namespace' AND status = 'COMMITTED'
GROUP BY scope_value),
held AS (
SELECT namespace, sum(actual_size) AS held_bytes
FROM fs_file
WHERE published_at IS NOT NULL AND state <> 'DELETED'
GROUP BY namespace)
SELECT coalesce(b.namespace, h.namespace) AS namespace,
coalesce(b.booked_bytes, 0) AS booked_bytes,
coalesce(h.held_bytes, 0) AS held_bytes,
coalesce(b.booked_bytes, 0) - coalesce(h.held_bytes, 0) AS drift_bytes
FROM booked b
FULL JOIN held h ON h.namespace = b.namespace
WHERE coalesce(b.booked_bytes, 0) <> coalesce(h.held_bytes, 0);
drift_bytes가 양수면 어떤 파일도 갖지 않은 잡힌 용량이다(파일이 떠나온 namespace). 음수면 아무도 잡지 않은
content다(파일이 도착한 namespace). 업로드, copy, move, cleanup이 도는 동안에는 진행 중인 일 때문에 어긋남이
보일 수 있다. 그러니 fileserver 쓰기를 멈춘 상태에서 판단한다.
namespace를 바로잡으려면 먼저 그 namespace로 가는 fileserver 쓰기를 모두 멈춘다. 업로드, copy, move, delete,
그리고 cleanup worker(APP_FILESERVER_PLATFORM_CLEANUP_ENABLED=false)다. 아래 문은 fs_file에서 다시 계산하므로,
두 단계 사이에 들어온 게시나 회수는 사라진다. 이 문은 그 namespace의 확정 행을 0으로 만들고, 다시 계산한 합계를
게시가 남기는 모양의 행 하나로 잡는다(COMMITTED, reserved_bytes 0, 바이트는 committed_bytes). 회수가 행을
깎은 뒤에는 행별 나눔에 의미가 없고, 강제는 합계만 읽는다. RESERVED 행(진행 중인 업로드)은 건드리지 않는다.
BEGIN;
SET LOCAL lock_timeout = '5s';
UPDATE fs_quota_reservation
SET committed_bytes = 0, version = version + 1, updated_at = now()
WHERE scope_type = 'namespace' AND scope_value = :'namespace'
AND status = 'COMMITTED' AND committed_bytes > 0;
INSERT INTO fs_quota_reservation (
reservation_id, scope_type, scope_value, reserved_bytes, committed_bytes,
expires_at, status, version, created_at, updated_at)
SELECT gen_random_uuid(), 'namespace', :'namespace', 0, held,
now(), 'COMMITTED', 0, now(), now()
FROM (SELECT coalesce(sum(actual_size), 0) AS held
FROM fs_file
WHERE namespace = :'namespace'
AND published_at IS NOT NULL AND state <> 'DELETED') AS recomputed
WHERE held > 0;
COMMIT;
psql -v namespace=<name>으로 돌리고 drift query를 다시 돌린다. 쓰기를 다시 열기 전에 그 namespace가 결과에서
사라져야 한다.