# Fileserver runbook runbook마다 그것을 시작하게 하는 metric과 그것을 해결하는 명령을 정확히 적는다. 시작 조건이 「누가 알아챘다」인 runbook은 대응할 수 없다. 그래서 아래 runbook은 모두 신호에서 시작한다. ## 저장소 가득 참 **신호** — `fileserver.quota{result="rejected"}`가 오르거나 `507` 응답이 나온다. 저장 용량이 바닥났거나 high-water 보호 장치가 걸렸다. 업로드는 바이트를 쓰기 전에 거부되므로 망가진 것은 없다. 시스템이 끝낼 수 없는 일을 거절하고 있을 뿐이다. ```bash 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 기록이 없다. 당장 위험하지는 않다. 아무것도 그것을 내보내지 않는다. 하지만 용량을 끝없이 먹는다. ```bash # 늘 먼저 본다. 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":[""],"reasonCode":"ORPHAN_GROWTH_RUNBOOK"}' ``` fingerprint를 되돌려 보내는 것이 안전 장치다. scan과 적용 사이에 바뀐 객체는 지우지 않고 건너뛴다. ## 검증 적체 **신호** — `fileserver.verification.queue{age_bucket="old"}`가 0이 아니거나, 파일이 VERIFYING에 머문다. 검증기가 느리거나 쓸 수 없다. 파일은 공개되지 않은 채 남는다. 맞는 실패 방향이다. `RETRY` 판정은 절대 `ACCEPT`가 되지 않는다. ```bash 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이 적용됐을 수 있는데 응답이 사라졌다. 이런 연산은 절대 자동으로 재시도하지 않는다. ```bash # 복구 큐에 결정을 기다리는 파일이 있다. 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를 더는 증명하지 못한다. 애플리케이션은 원자적으로 게시할 수 없는 저장소로 내보내지 않고 요청을 거부한다. ```bash # staging과 content가 같은 파일 저장소(같은 장치 번호)인지 pod 안에서 본다 kubectl exec -- 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/`)이 아래 「운영 환경이 지켜야 할 조건」을 지키는지 본다. ```bash curl -s $ADMIN/internal/fileserver/capabilities | jq '.capabilities.delegatedDownload' ``` 위임을 끄는 것이 안전한 즉시 완화책이다. 애플리케이션이 직접 전송한다. 느리지만 맞다. ```bash app.fileserver-platform.nginx.enabled=false ``` ## 운영 환경이 지켜야 할 조건 이 repo는 프록시 설정 파일과 Kubernetes 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 그 파일은 서비스를 배포하는 쪽의 인프라 repo가 갖는다. 그 파일이 지켜야 할 조건은 아래다. **프런트 프록시(nginx `X-Accel-Redirect` 위임)** — `app.fileserver-platform.nginx.enabled=true`일 때 1. 내부 location(`app.fileserver-platform.nginx.internal-prefix`, 기본 `/__files/`)은 `internal`이다. 클라이언트가 그 경로를 직접 부르면 404이고 content 폴더에 닿지 않는다. 애플리케이션이 준 내부 redirect로만 닿는다. 2. 그 location의 `alias`는 저장 루트의 content 폴더다(기본 `/var/lib/backend/files/content/`). 애플리케이션은 절대 경로를 내보내지 않고 내부 접두사 아래 상대 URI만 내보낸다. 경로가 실제 위치가 되는 곳은 이 `alias`뿐이다. 3. 앱으로 넘기는 요청에서 클라이언트가 보낸 `X-Accel-Redirect` 헤더를 지운다. 남기면 호출자가 임의의 내부 객체를 가리킬 수 있다. 4. 업로드는 스트리밍으로 넘긴다(`proxy_request_buffering off`, 본문 크기 제한은 애플리케이션이 정하므로 프록시는 막지 않는다). 프록시가 큰 본문을 디스크에 버퍼링하면 쓰기가 두 번 일어난다. 5. 내부 location 응답에 `X-Content-Type-Options: nosniff`를 붙이고, 앱이 정한 `Content-Disposition`· `Cache-Control`·`ETag`를 그대로 넘긴다. 올라온 내용이 자기 형식을 스스로 정하게 두지 않는다. **Kubernetes 저장 volume** 1. PersistentVolumeClaim을 저장 루트(`/var/lib/backend/files`)에 마운트하고, 접근 모드는 `ReadWriteOnce`다. `ReadWriteMany`(여러 노드의 동시 쓰기)는 인증하지 않았다(`support-matrix.md`). 2. pod `securityContext.fsGroup`을 이미지의 앱 그룹으로 둔다. 그래야 앱 계정이 volume에 쓸 수 있다. 3. 그 volume이 `storage-certification.md`의 인증 항목(같은 파일 저장소, 원자적 rename, `O_EXCL` 생성)을 통과해야 한다. 기동 때 `FileserverStartupValidator`도 같은 probe를 다시 돌린다. ## 정리 적체 **신호** — `fileserver.cleanup{result="deferred"}`가 오르거나, 삭제는 계속되는데 회수한 바이트가 평평하다. 항목이 비워지는 것보다 빠르게 미뤄진다. 흔한 원인은 아직 살아 있는 writer lease가 staging 객체를 잡고 있는 것이다. 결함이 아니라 맞는 동작이다. ```bash 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가 둘을 비교한다. 아무것도 바꾸지 않는다. ```sql 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` 행(진행 중인 업로드)은 건드리지 않는다. ```sql 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=`으로 돌리고 drift query를 다시 돌린다. 쓰기를 다시 열기 전에 그 namespace가 결과에서 사라져야 한다.