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

74 lines
3.7 KiB
Markdown

# 저장소 인증
## 인증이 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에 남긴다:
```json
{
"kubernetesVersion": "...",
"csiDriver": "...",
"storageClass": "...",
"accessMode": "ReadWriteOnce",
"backend": "ext2/ext3",
"mountOptions": "rw,relatime",
"atomicMove": true,
"sameFileStore": true,
"atomicCreate": true
}
```
2번이 실패하면 인증하지 않는다. staging과 content가 다른 저장소인 volume은 게시가 소리 없이 복사로 바뀐다.
## 네트워크 파일 시스템
```bash
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를 다시 쓰는 저장소도 이것을 상속한다.