blog

Vault 타 서비스 적용기

NEXTREE.

• 10 min read
Vault 타 서비스 적용기

Vault 는 Vizend 내 파일관리 서비스 입니다.Vault에서 파일의 데이터 구조는 참조 파일과 물리파일로 나뉘어집니다.

참조 파일은 물리파일을 참조하는 구조이고, 실제 파일 하나를 여러 명이 가지게 되더라도 실제 사용되는 저장공간은 파일 하나의 용량만 차지하게 됩니다.

제가 Vault 기능을 유지보수 하면서 경험한 바로는 크게 세 가지로 나뉘는 것 같습니다.

vault는 크게 3가지 저장소로 나뉩니다.

저장소 종류

1) 개인 저장소: Stash

  • 폴더 구조를 가진 개인 저장소

2) 일반 저장소: Cabinet / Clip

공고, 게시물 첨부파일 등 “일반적인 첨부파일 저장소”로 쓰입니다.

  • Cabinet: Clip의 묶음(컨테이너) 개념

  • Clip: ClipFile(참조 파일)의 묶음 개념

  • 적용 범위/단위는 서비스(devlime, vizend, 반장노트 등) 비즈니스 로직에 따라 달라질 수 있음

  • “서비스 전체 저장소를 1 cabinet”으로 보기도 하고

  • “게시판마다 cabinet을 분리”하기도 함

3) 사진 저장소: MiniAlbum / Minipix

  • Minipix: 사진 저장소 “서비스 이름”

  • MiniAlbum: 실제 도메인(관리 단위)

공통 개념: “참조 파일 저장소”

세 저장소(Stash / Clip / Photo)는 공통적으로 reference file(참조 파일) 을 저장합니다.

  • 저장되는 파일

  • Stash: StashFile

  • Clip: ClipFile

  • MiniAlbum: PhotoFile

이들은 모두 실제 파일인 VaultFile 을 가리키는 참조입니다.따라서 참조 파일을 많이 복제해도 실제 저장 용량이 바로 증가하는 구조는 아닙니다.

타서비스에 적용을 할때 맞닥뜨린 도전

제가 Vault를 맡는 동안 Vault를 실제로 다른 서비스에 적용하는 업무를 맡게 되었습니다. 해당 서비스 이름은 “반장노트”입니다. 반장노트는 인력관리 앱이라고 말할 수 있으며, 2026년 상반기 기준으로 개발중에 있습니다. (자세한 서비스 설명은 보안상 설명하기에는 제한이 있어 양해 부탁드립니다.)

반장노트에서 Vault가 필요한 기능으로는 나의 서류, 공고에 서류 제출하기가 있었습니다.

여기서 처음에 Vault를 쉽게 적용할 것으로 생각했으나 몇가지 적용하는 데에 제약사항이 있었습니다.

먼저 내서류 는 Stash를 사용해 적용해야 했는데 Stash는 근본적으로 폴더 구조라는 것입니다.

반장노트는 내 서류에 저장해야하는 서류 종류가 딱 정해져 있었고 이는 폴더 구조에 들어맞지 않았습니다. 하지만 Vault는 MSA 서비스 중 하나로서, 범용 서비스로서 기능해야 하기 때문에 타 서비스 하나에 적용을 한다는 이유로 Vault Stash 도메인을 바꿀 수는 없었습니다. 따라서 Stash의 구조를 유지하면서 반장노트에 적용을 해야했습니다.

1. Vault의 범용성의 역설

그래서 고민 끝에 폴더를 고정적으로 미리 생성을 하고 폴더를 변경, 삭제하는 로직을 사용자에게 제공하지 않는 방식으로 적용을 하였습니다. 이 문제를 해결하고 나니 다른 문제가 기다리고 있었습니다. Vault가 저장, 업로드/다운로드 기능만 제공을 하고, 각 업로드한 파일에 대한 메타데이터는 반장노트 백엔드에서 vault 구조랑 비슷하게 서류 도메인을 만들어 메타데이터를 반장노트에 저장할 것인지를 결정해야 했습니다. Vault가 온전히 파일 관리 기능을 전문적으로 담당하려면 메타데이터 또한 저장하는 구조가 좋았고 이를 해결하기위해 대표님께서 json 형식의 string 컬럼을 각 clipfile,stashfile,photofile에 추가했습니다. 예를 들어 stashfile이 신분증 사진을 업로드할때, fileMetaData = “{ documentType: /“ID_CARD/” }” 이렇게 파일과 함께 메타데이터를 넣어 추가했습니다. 이를 통해 반장노트에서 내서류 도메인을 반장노트 백엔드에 따로 설계해 적용할 필요가 없어지게 되었습니다.

2. Backend to backend vs frontend to backend

타 서비스에서 vault 기능을 사용할 때에 2가지 방식이 있습니다:

  1. 타 서비스 백엔드에서 vault 백엔드를 client 형태로 직접 호출

  2. 타 서비스 프론트에서 vault 프론트의 api 상태관리 컴포넌트를 임포트 후 호출

처음에는 첫번째 방법으로 시도했으나 프로젝트를 진행하면서 이 방법은 서버에 부하를 주는 방식이라는 점을 파악하게 되었습니다. 예를 들어, 반장노트 프론트에서 업로드를 진행할때 먼저 반장노트 백엔드에 업로드 요청을 보내면서 파일을 백엔드에 보내고 다시 반장노트 백엔드에서 vault 백엔드로 전송하는 것은 반장노트, vault 서버 메모리를 불필요하게 많이 사용하기 때문입니다. 따라서 반장노트 프론트에서 vault 백엔드를 직접 호출하는 방식으로 가야했고 vault 프론트에 이미 api 별로 상태관리가 자동적으로 진행되는 커스텀 훅 컴포넌트가 만들어져 있기 때문에 해당 프론트 컴포넌트를 임포트하는 방식으로 하는것이 좋다는걸 알게 되었습니다.

3. Cabinet과 Clip의 범위

Cabinet은 Clip의 묶음이고 Clip은 ClipFiles의 묶음입니다. 이 문제는 Vault 담당이었던 제게 가장 큰 도전이었습니다. 타 서비스마다 Cabinet의 범위, Clip의 범위를 어떻게 정하면 좋을지 문의가 많이 들어왔었고

쉽게 답변을 드리기가 어려웠습니다. 각 게시판을 cabinet, 게시물을 clip으로 보기도하고 clip으로만 나누기도 했습니다. 아직까지 명확한 답을 하긴 어렵지만 제 경험으로는 cabinet을 한 서비스 전체가 하나를 공유하고 게시물에 사진, 첨부 파일을 넣을때 clip 생성 해당 게시물에다 서류를 제출할 때 전용 clip을 따로 생성하는 구조로 clip으로 대부분의 파일 묶음을 정의하는 것이 가장 유연한 구조였던 것 같습니다. 그리고 clip은 한 개인의 전체 파일을 담당하고 업로드 시 메타데이터도 같이 넘겨 업로드 하는 방식으로 하는 방식으로 진행했습니다. 다만 추후에는 메타데이터를 vault로 넘길지 반장노트로 넘길지 논의 과정에서 후자로 결정되었습니다. 메타데이터 관리를 반장노트에서 할 필요성이 있어서인 것 같습니다.

따라서 반장노트 적용시 다음과 같은 플로우로 적용했습니다.

구조

  • 반장노트는 공고용 clip 과 제출서류용 clip 을 분리

  • cabinet은 반장노트 전체가 1개를 공유

  • cabinetKey, cabinetId는 항상 같아야 함

흐름

1) 리더(팀장)이 공고 생성

  1. 반장노트 백엔드에서 registerJobPost(예시)

  2. 공고에 이미지 등록 시 registerClipFiles 호출

  3. 성공 시 반환된 clipId를 반장노트 백엔드의 해당 JobPost에 저장

2) 반장이 공고 클릭 → 제출

  1. 반장노트 백엔드에서 findJobPostDetail(예시)

  2. 제출하기 → 제출서류 리스트 → 신분증 클릭

  3. 파일 업로드 또는 “내서류로 불러오기”

  • 파일 업로드 시

- registerClipFiles 호출

- 반환된 clipId, clipFileIds를 jobApplication(예시)에 저장

- jobApplication에 해당 서류 타입이 없으면 registerClipFile, 있으면 addClipFile 사용

  • 내서류로 불러오기 시

- registerClipFilesFromstash 사용

-특정 서류의 stashFolderId를 조회 가능하면, 메타데이터 저장 없이 registerClipFilesFromstash로 처리 후 반장노트 백엔드에 저장

3) 팀장이 지원자 서류 조회

  1. 반장노트 백엔드에서 clipId 포함된 jobApplication 조회 → clipId 추출

  2. vault 백엔드에서 clipFileIds 조회 후 downloadFile(s)로 썸네일 미리보기

후기

반장노트에 vault 서비스를 적용하면서 많은 것을 배울 수 있었고, 아직 배워야 하는 것이 많다는 것을 알게 되었습니다. 범용성이 좋으면 희생해야 하는 부분이 있고 이를 보완하는 과정에서 성장을 했던 것 같습니다. 앞으로 또한 vault 담당자로서 반장노트 팀에게 어떻게 정해줄지 확실하게 정해주어야 개발 진척에 크게 도움이 될 것 같습니다. 만약 다른 서비스에서도 적용 업무를 맡게 된다면 vault에 대한 구조를 좀더 간결하게 설명하고 경험을 바탕으로 도메인 구조 설계에서 적극적으로 같이 설계하고 확신을 갖고 틀리면 수용하고 개선하는 방식으로 진행해야겠다고 다짐했습니다.

LEE DAVID

Site footer