문제: 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개가 번역 전과 같음).
3.4 KiB
3.4 KiB
Fileserver 업그레이드 안내
Capability 켜기
Fileserver는 꺼진 채로 나온다. 명시적으로 켜기 전에는 아무것도 등록하지 않는다. endpoint도, 스레드 pool도, metric도 없다.
app:
fileserver-platform:
enabled: true
instance-id: ${HOSTNAME}
default-namespace: default
observability:
fingerprint-key: ${FILESERVER_FINGERPRINT_KEY}
instance-id는 인스턴스마다 달라야 한다. writer lease의 소유자이기 때문이다. 두 노드가 같은 값을 쓰면 둘 다
같은 lease를 가졌다고 믿는다.
fingerprint-key는 필수이고 기본값이 없다. 없으면 key 없는 digest로 물러서지 않고 시작이 실패한다. 셀 수
있는 식별자 공간에서 key 없는 digest는 되돌릴 수 있다.
선택 면
각각 따로 된 스위치이고, 모두 기본으로 꺼져 있다.
app:
fileserver-platform:
admin:
enabled: false # management plane. 관리 port에 둔다
tus:
enabled: false # tus 1.0, Stable
httpbis-draft12:
enabled: false # Experimental. 표준 미확정, 예고 없이 바뀔 수 있다
nginx:
enabled: false # 프런트 프록시 위임. 검증한 internal location이 필요하다
DB schema
metadata schema는 capability 마이그레이션으로 설치되고 비활성 상태로 시작한다.
V1__create_fileserver_metadata.sql → capability_schema_registry: jpa-fileserver-metadata-v1
의도해서 활성화한다. 활성화한 schema 없이 capability를 켜면 첫 업로드가 아니라 시작 때 실패한다.
게시 방식 고르기
| 방식 | 언제 |
|---|---|
atomic-move-preferred |
기본값. probe가 증명하면 원자적 rename을, 아니면 metadata pointer를 쓴다. |
atomic-move-required |
닫힌 쪽으로 실패한다. 원자적 move를 증명하지 못하는 저장소에서는 시작을 거부한다. |
metadata-pointer |
원자적 rename이 없는 저장소용. 게시가 곧 metadata 확정이다. |
저장소를 인증했고 잘못된 설정이 게시 때가 아니라 부팅 때 드러나기를 원하면 atomic-move-required를 고른다.
놀랄 만한 동작
- content가 아직 있으면 삭제는
204가 아니라202로 답한다. 파일은 이미 읽을 수 없고, 물리 회수는 미뤘다.202를 실패로 다루면 쓸데없이 재시도한다. - batch 업로드는 part가 실패해도
200으로 답한다. batch는 명시적으로 원자적이지 않고, 상태 코드 하나로는 부분 결과를 정직하게 알릴 수 없다.results[].error를 읽는다. - 결과를 모르는 실패는 재시도하면 안 된다. 실패 Envelope의
error.details에서"ambiguous": true를 본다. If-Match는 version 숫자가 아니라 strong ETag를 받는다. client는 실제로 받은 표현에 대해서만 주장할 수 있다.- 스크립트가 될 수 있는 형식은 호출자가 요청해도 inline으로 그리지 않는다.
업그레이드 확인
cd src
./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew :application-fileserver:check :adapter:inbound:web-fileserver:check \
:adapter:outbound:fileserver:check :adapter:outbound:persistence-fileserver:check \
:composition:fileserver-platform:check --console=plain
./gradlew :app-bootstrap:architectureTest --console=plain