Serinew Archive

Archive는 이미지·동영상 등 파일을 Cloudflare R2에 저장하고, 메타데이터는 PostgreSQL(archive.file)에, 조회 가속은 Redis에 두는 Serinew용 마이크로서비스입니다. HTTP API는 Go / Gin으로 제공합니다.

주요 기능

• 파일 업로드 (POST /v1/file)
  • multipart/form-data: file / files / file[] 또는 임의 파일 파트
  • application/x-www-form-urlencoded 또는 multipart 텍스트 필드: file_base64(또는 fileBase64, data) + filename 등
• 파일 메타 조회 (GET /v1/file/:fileId) — UUID 기준, Redis 캐시 후 DB 폴백
• OpenAPI(Swagger) — GET /v1/docs (리다이렉트 포함)
• R2 업로드 시 Cache-Control 설정으로 CDN/브라우저 캐시 힌트 제공(환경변수로 조절)

스택

구분	기술
언어 / 런타임	Go 1.25+
HTTP	Gin
DB	PostgreSQL + GORM (archive 스키마)
객체 저장	Cloudflare R2 (AWS S3 호환 API)
캐시	Redis (선택, 파일 메타 TTL 캐시)
문서	swaggo/swag

요구 사항

• Go 1.25 이상 권장
• PostgreSQL (마이그레이션으로 archive.file 생성 가능)
• (선택) Redis
• (업로드 시) Cloudflare R2 버킷 및 API 토큰

빠른 시작

1. 저장소 클론 후 루트에서 환경 파일 준비:

   cp .env.example .env

   .env에 DB, Redis(선택), R2, PORT 등을 채웁니다. R2 업로드를 쓰려면 R2_*와 R2_PUBLIC_BASE_URL이 필요합니다.

2. 의존성 및 실행:

   go mod download
   go run ./cmd/server

3. 헬스·문서:

   • GET http://localhost:<PORT>/
   • GET http://localhost:<PORT>/v1/
   • Swagger UI: http://localhost:<PORT>/v1/docs

환경 변수 요약

자세한 설명과 예시는 .env.example을 참고하세요.

변수	설명
PORT	HTTP 포트 (기본 8080)
DB_*	PostgreSQL 연결
REDIS_URL	Redis URL (비우면 메타 캐시 없이 DB만 사용)
FILE_CACHE_TTL_SEC	Redis 메타 캐시 TTL(초), 기본 3600
R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET, R2_PUBLIC_BASE_URL	R2 업로드·publicUrl 생성
R2_REGION	보통 auto
R2_OBJECT_CACHE_CONTROL	객체 Cache-Control (미설정 시 장기 캐시 기본값, off면 생략)

API 요약

메서드	경로	설명
GET	/	서비스 인사용
GET	/v1/	v1 그룹 상태
POST	/v1/file	파일 업로드
GET	/v1/file/:fileId	메타데이터 조회 (UUID)
GET	/v1/docs/*	Swagger

데이터베이스

archive.file 테이블(스키마 archive)에 메타가 저장됩니다. 서버 기동 시 repository.Migrate에서 스키마·테이블 자동 생성을 시도합니다. 운영 DB는 별도 마이그레이션 정책에 맞게 조정할 수 있습니다.

Redis 캐시

• 키: archive:files:<uuid> (도구에 따라 archive → files 트리로 표시)
• 값: API data와 동일한 FileView JSON
• TTL: FILE_CACHE_TTL_SEC

Docker

루트에 Dockerfile이 있으면 이미지 빌드 후 컨테이너에 동일한 환경 변수를 주입하면 됩니다.

Swagger 재생성

주석 기반 스펙을 갱신할 때:

go run github.com/swaggo/swag/cmd/swag@v1.16.4 init -g cmd/server/main.go -o docs --parseDependency --parseInternal

라이선스

저장소 정책에 따릅니다.