---
kind: PROJECT_DECISION
slug: no-physical-paths-in-metadata
title: 물리 경로와 원본 파일명을 저장하지 않는다
topic: fileserver-state-and-fencing
project: clean-architecture-backend-template
status: 게시 전
sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
rootTreeNode: decision:no-physical-paths-in-metadata
decisionStatus: ADOPTED
decidedOn: 2026-08-30
source:
  - src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/jpa/fileserver/V1__create_fileserver_metadata.sql
  - final/document.md#a08
---

# 물리 경로와 원본 파일명을 저장하지 않는다

## 결정문

파일 메타데이터에 물리 경로도 마운트도 원본 물리 파일명도 저장하지 않는다. 콘텐츠 키는 서버가 만든 불투명 키이고 원본 이름은 표시용 텍스트일 뿐이다.

## 판단 이유

물리 경로를 저장하면 그 값이 언젠가 경로 조작에 쓰인다. 저장소에서 읽은 값이라는 이유로 신뢰되기 쉽고, 그것을 만든 것은 결국 업로드한 쪽이다.

원본 파일명도 같다. 사용자가 정하는 값이고, 그것으로 파일을 찾거나 열면 경로 순회와 확장자 기반 오판의 입구가 된다.

그래서 두 값의 역할을 분리한다. 서버가 만든 불투명 키가 자원을 지목하고, 원본 이름은 화면에 보여 줄 때만 쓴다.

마운트를 저장하지 않는 것도 같은 계열이다. 저장 위치가 메타데이터에 박히면 저장소를 옮길 때 레코드를 고쳐야 하고, 그 값이 코드 경로로 흘러들 수 있다.

## 영향

감수하는 것

원본 이름으로 파일을 찾을 수 없다. 검색이 필요하면 별도 색인이 필요하다.

저장 위치를 메타데이터에서 알 수 없으므로, 키에서 위치를 유도하는 규칙이 어딘가에 있어야 한다.

얻는 것

경로 순회와 확장자 기반 오판의 입구가 메타데이터에 없다.

저장소를 옮겨도 메타데이터를 고치지 않는다.

## 근거

- **파일 상태 기계와 READY가 뜻하는 것**
  이 결정이 속한 메타데이터 설계다.
- **sanitize가 아니라 reject가 기본이다**
  신뢰할 수 없는 값을 다루는 같은 계열의 규칙이다.
- **이름은 값이 아니라 registry key다**
  식별자와 표시용 값을 구별하는 같은 원칙이다.