첨부파일 저장 아키텍처 단계별 계획
1. 목적
이 문서는 포탈의 첨부파일 기능을 FileStore와 PortalConsole로 확장하는 단계별 운영 계획을 정의한다. 현재 시스템은 개발 단계이므로 기존 운영 데이터의 마이그레이션은 수행하지 않는다. 정책과 API 계약은 신규 구조에 맞춰 바로 정리한다.
핵심 원칙은 저장소 기술 설정과 파일 lifecycle은 FileStore가 담당하고, 사용자·조직·포탈 업무 권한은 2단계에서 PortalConsole가 담당하는 것이다.
2. 최종 책임 분리
| 영역 | 1단계 | 2단계 목표 |
|---|---|---|
| R2·S3·로컬 저장소 등록 | FileStore | FileStore |
| Backend 자격증명 namespace | FileStore 서버 환경변수와 관리자 UI | FileStore 서버 환경변수와 관리자 UI |
consumerId별 Backend 라우팅 | FileStore | FileStore |
| 저장 prefix | FileStore | FileStore |
| 파일 크기·MIME·보존 검증 | FileStore | FileStore의 최종 검증 |
| 파일 메타데이터와 lifecycle | FileStore | FileStore |
| 포탈·사용자·조직 인증 | 포탈 또는 기존 인증 흐름 | PortalConsole |
| 업무 객체 접근 권한 | 포탈 | PortalConsole |
| 첨부파일 사용 가능 여부 | FileStore 정책과 포탈 설정 | PortalConsole의 포탈 권한 |
| 포탈의 호출 대상 | FileStore 직접 호출 가능 | PortalConsole 경유 |
FileStore의 포탈별 정책은 1단계에서 저장 검증과 라우팅을 함께 담당한다. 2단계에서도 FileStore는 최종 보안 경계로서 파일 크기, MIME type, 활성 상태, Backend 연결을 검증한다.
3. 1단계: FileStore 중심 운영
3.1 목표
1단계의 목표는 PortalConsole에 의존하지 않고 FileStore만으로 첨부파일 저장 기능을 검증하는 것이다. 개발 단계이므로 기존 설정을 다른 시스템으로 이전하거나 변환하지 않는다.
3.2 관리 범위
FileStore 관리자 UI에서 다음 항목을 관리한다.
- Cloudflare R2, Amazon S3, 로컬 디스크 Backend
- Backend의 ID, 표시 이름, 저장 유형, Bucket, Endpoint, Region
- 서버 환경변수의 secret namespace 참조
- Backend 활성화 상태
- 포탈별
consumerId - 포탈별 Backend 연결과 저장 prefix
- 최대 파일 크기
- 허용 MIME type
- 보존 기간
- 암호화 필요 여부
- 읽기·쓰기 활성화 여부
- RAG publish 허용 여부
실제 Access Key와 Secret Key는 관리자 UI 또는 설정 파일에 저장하지 않는다. R2와 S3 자격증명은 해당 Backend를 사용할 때만 서버의 비밀 환경변수 또는 비밀관리 시스템에 등록한다.
3.3 1단계 작업 순서
| 순서 | 작업 | 완료 기준 |
|---|---|---|
| 1 | R2 Backend 등록 | Backend 상세 화면에서 설정을 확인할 수 있다. |
| 2 | 포탈 저장 정책 등록 | consumerId가 Backend와 저장 prefix에 연결된다. |
| 3 | 업로드 API 검증 | 허용 MIME, 최대 크기, write 권한이 적용된다. |
| 4 | 다운로드 API 검증 | read 권한과 만료된 locator 정책이 적용된다. |
| 5 | 삭제 API 검증 | 메타데이터를 soft delete하고 감사 로그를 남기며, 원본 객체는 별도 cleanup 전까지 보존한다. |
| 6 | 포탈 연동 계약 확정 | 포탈이 사용할 API 요청 필드와 인증 방식을 문서화한다. |
3.4 1단계 완료 상태
현재 코드에는 다음 기능이 구현되어 있다.
- R2·S3·로컬 디스크 Backend 등록 UI
- Backend 상세 조회와 삭제
- 포탈별 저장 정책 등록·수정·삭제
- Backend와 정책의 서버 측 schema 검증
- FileStore 관리자 세션 인증
- 파일 업로드·다운로드 locator·metadata-only soft delete API
- 파일 lifecycle 감사 로그
1단계의 남은 확인 작업은 실제 R2 연결과 실제 업로드·다운로드·삭제의 통합 검증이다. 이 작업은 데이터 마이그레이션이 아니라 신규 개발 환경 검증이다.
4. 2단계: PortalConsole 연계
4.1 목표
2단계에서는 포탈이 사용자와 조직 권한을 직접 판단하지 않고 PortalConsole를 통해 첨부파일 요청을 처리한다. PortalConsole는 FileStore의 저장 정책을 복제하지 않는다.
4.2 PortalConsole의 책임
PortalConsole는 다음 정보를 관리한다.
{
"portalId": "document-library",
"fileStoreEnabled": true,
"fileStoreConsumerId": "document-library"
}관리 범위는 포탈 활성화 여부, 사용자·조직 인증, 업무 객체 접근 권한, 업로드·다운로드·삭제 권한이다. FileStore의 maxBytes, allowedContentTypes, backendId, Bucket, Endpoint를 다시 저장하지 않는다.
4.3 FileStore의 책임
FileStore는 다음을 계속 관리한다.
consumerId와 Backend의 연결- R2·S3·로컬 저장소 연결
- 저장 prefix
- 최대 파일 크기와 MIME type의 최종 검증
- 파일 메타데이터와 lifecycle
- metadata-only soft delete와 보존 처리
- 보존 기간·legal hold 종료 후 별도 cleanup job을 통한 원본 객체 삭제
- 저장 관련 감사 로그
PortalConsole가 잘못 구성되거나 우회되더라도 FileStore는 자체 정책을 통과하지 못한 요청을 거부한다.
4.4 2단계 요청 흐름
포탈
→ PortalConsole
→ 사용자·조직·업무 객체 권한 확인
→ 포탈의 첨부파일 사용 여부 확인
→ FileStore
→ consumerId 정책 확인
→ MIME·용량·read/write 검증
→ Backend 선택
→ Cloudflare R2, Amazon S3 또는 로컬 디스크PortalConsole는 FileStore 서비스 토큰을 브라우저에 전달하지 않는다. 포탈과 PortalConsole 간의 인증 정보도 서버 측에서만 보관한다.
4.5 2단계 작업 순서
| 순서 | 작업 | 완료 기준 |
|---|---|---|
| 1 | PortalConsole에 포탈의 FileStore 사용 여부 추가 | 포탈별 활성 상태를 조회할 수 있다. |
| 2 | PortalConsole와 FileStore 간 서버 인증 구성 | 서버 간 요청이 인증된다. |
| 3 | 권한 검증용 upload-session API 추가 | 사용자와 포탈 권한을 확인한 뒤 FileStore를 호출한다. |
| 4 | 업로드 완료 API 연결 | 업로드 세션이 멱등적으로 완료된다. |
| 5 | 다운로드와 삭제 API 연결 | 권한 확인 후 FileStore lifecycle API를 호출한다. |
| 6 | requestId 감사 추적 추가 | 두 서비스의 이벤트를 하나의 요청으로 추적할 수 있다. |
| 7 | 포탈 호출 대상 변경 | 포탈은 PortalConsole만 호출한다. |
| 8 | 장애·재시도·만료 처리 추가 | URL 만료와 일시적 네트워크 오류가 안전하게 처리된다. |
5. 정책 중복 방지 규칙
정책의 원본은 1단계와 2단계 모두 FileStore에 둔다. PortalConsole는 정책 내용을 복사하지 않고 포탈과 consumerId의 연결 및 사용자 권한만 관리한다.
다음 값은 PortalConsole에 저장하지 않는다.
backendId- Bucket
- Endpoint
secretRef- Access Key
- Secret Key
- FileStore의 세부 저장 정책 전체
PortalConsole 관리자 화면에서 저장 정책을 보여줄 필요가 있으면 FileStore의 읽기 전용 정책 조회 API를 사용한다. PortalConsole에서 정책을 수정하지 않는다.
6. 개발 단계 운영 원칙
현재 개발 상태에서는 마이그레이션 작업을 만들지 않는다. 새로운 포탈과 정책은 현재 schema와 관리자 UI를 기준으로 등록한다. PortalConsole 연계가 시작되면 새 API 계약을 먼저 확정하고, 기존 개발용 포탈 호출부를 해당 계약에 맞춰 수정한다.
변경 전후의 데이터 변환보다 다음 검증을 우선한다.
- R2 연결과 자격증명 namespace 검증
- 포탈 정책과 Backend 연결 검증
- 파일 업로드·다운로드·삭제 검증
- 애플리케이션 재시작 후 설정 저장소와 데이터 저장소 유지 검증
- 권한 실패와 감사 로그 검증
7. 현재 실행 계획
현재는 1단계를 진행한다.
- R2 환경변수와 관리자 UI의
secretRef를 일치시킨다. - 포탈별 정책을 FileStore에서 등록한다.
- 실제 포탈 연동 전에 FileStore의 업로드·다운로드·삭제를 검증한다.
- 검증이 끝난 뒤 PortalConsole 연계 API를 설계한다.
8. 완료 기준
1단계는 다음 조건을 모두 만족하면 완료로 본다.
- R2 Backend 연결 설정이 상세 화면에서 확인된다.
- 잘못된 MIME type과 파일 크기가 거부된다.
- 비활성 정책과 write 불가 정책이 업로드를 거부한다.
- 활성 파일만 다운로드할 수 있다.
- 삭제 이벤트가 metadata-only soft delete와 감사 로그로 남고, DELETED 파일의 원본 객체는 cleanup 전까지 보존된다.
- Access Key와 Secret Key가 브라우저, 설정 파일, API 응답에 노출되지 않는다.
- 포탈이 사용할 최소 API 계약이 문서화된다.