Files
clean-architecture-backend-…/docs/fileserver/storage-certification.md
T
DongHyeonka 6583cc2e02 docs(fileserver): 파일서버 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: 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개가 번역 전과 같음).
2026-11-07 17:29:57 +09:00

3.7 KiB

저장소 인증

인증이 volume마다인 이유

원자적 rename, 같은 파일 저장소 보장, symlink 거부는 「Kubernetes」나 「PVC」의 성질이 아니라 특정 mount 뒤의 특정 파일 시스템의 성질이다. CSI driver, StorageClass, 접근 모드, backend, mount 옵션 중 하나만 바꿔도 그중 무엇이든 달라질 수 있다. 다섯을 모두 적지 않은 인증은 다른 곳으로 옮길 수 없다.

인증하는 것

성질 중요한 이유
staging과 content가 같은 파일 저장소 저장소를 넘는 rename은 복사라서 게시가 원자적이지 않게 된다.
원자적 rename 게시 경로의 기본 전략이다.
원자적 생성(O_EXCL) 게시를 조용한 덮어쓰기가 아니라 새로 만들기만 하게 한다.
symlink 거부 바뀐 부모 폴더가 쓰기를 root 밖으로 돌리는 것을 막는다.
범위 읽기 다운로드 계약이 기댄다.

인증 돌리기

이 repo는 인증 job 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 배포하는 쪽이 대상 volume을 저장 루트(/var/lib/backend/files)에 마운트한 일회성 pod에서 아래를 차례로 확인한다.

  1. staging과 content 폴더를 만들고, staging의 파일을 content로 mv해 원자적 rename이 되는지 본다.
  2. 두 폴더의 장치 번호(stat -c %d)가 같은지 본다. 다르면 rename이 복사가 된다.
  3. set -o noclobber 상태에서 같은 파일을 두 번 만들어 O_EXCL 생성이 막히는지 본다.
  4. 결과와 함께 묶음(Kubernetes 버전, CSI driver, StorageClass, 접근 모드, backend, mount 옵션)을 기록한다.

결과는 묶음 전체를 담은 기계가 읽는 형식으로 그 volume에 남긴다:

{
  "kubernetesVersion": "...",
  "csiDriver": "...",
  "storageClass": "...",
  "accessMode": "ReadWriteOnce",
  "backend": "ext2/ext3",
  "mountOptions": "rw,relatime",
  "atomicMove": true,
  "sameFileStore": true,
  "atomicCreate": true
}

2번이 실패하면 인증하지 않는다. staging과 content가 다른 저장소인 volume은 게시가 소리 없이 복사로 바뀐다.

네트워크 파일 시스템

docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d
FILESERVER_NFS_TESTS=true ./gradlew :adapter:outbound:fileserver:test

mount는 일부러 hard다. soft mount는 느린 서버를 짧게 끝난 쓰기로 바꾼다. 이 설계가 받아들이지 않는 바로 그 손상이다.

시작 때 강제

FileserverStartupValidator가 부팅 때 probe를 다시 돌리고, 필수 capability가 없으면 요청을 받지 않는다. 원자적 move를 증명하지 못하는 파일 시스템에 ATOMIC_MOVE_REQUIRED를 두면 조용히 기능을 줄이지 않고 닫힌 쪽으로 실패한다.

새 저장소 더하기

실행되는 계약 둘을 통과해야 한다. 글로 쓴 호환 주장은 받지 않는다.

  • UploadStoragePortContract — 애플리케이션 port의 계약이다. application-fileserver testFixtures에 있다 (testImplementation testFixtures(project(':application-fileserver'))). 애플리케이션의 FakeUploadStorageGateway도 이것을 상속한다. 그래서 use case 테스트와 실제 저장소가 같은 offset, chunk checksum, 크기 상한 규칙을 지킨다(0바이트로 선언한 업로드는 첫 바이트를 거부한다).
  • ContentStoreContract — 로컬 어댑터의 내부 BlockingContentStore SPI 계약이다. 이 어댑터의 테스트에 있다. 그 SPI는 일부러 어댑터 안에 둔다(리뷰 S1-#12: 애플리케이션은 그것을 부르지 않는다). 그래서 계약도 어댑터에 있다. 그 SPI를 다시 쓰는 저장소도 이것을 상속한다.