핵심 기능
- Markdown 기반 게시글 작성 및 조회 기능 구현
- MinIO(S3 호환) 기반 이미지 업로드 시스템 구축
- GitHub Actions + Docker 기반 CI/CD 자동 배포 환경 구축
프로젝트 개요
개인 Linux 서버 환경에서 운영하는 마크다운 기반 기술 블로그 서비스를 개발했습니다.
Spring Boot 기반 REST API를 구현하고 MinIO(S3 호환)를 활용한 이미지 업로드 기능을 구축했습니다.
또한 GitHub Actions와 Docker를 활용하여 CI/CD 자동 배포 파이프라인을 구성하고
개인 서버에서 블로그 서비스를 직접 운영했습니다.
사용 기술
Backend
Spring Boot, Spring Security, JPA, QueryDSL
Infrastructure
MariaDB, MinIO (S3 compatible storage), Docker, Linux Server
CI/CD
- GitHub Actions
시스템 구조
블로그 서비스는 다음과 같은 구조로 동작합니다.
- Markdown 기반 게시글 작성
- 이미지 업로드 시 MinIO Object Storage 저장
- 게시글 조회 시 이미지 URL 반환
- GitHub Actions 기반 자동 빌드 및 Docker 배포
시스템 아키텍처
ERD
주요 구현
게시글 시스템
- Markdown 기반 게시글 작성 및 조회 API 구현
- 게시글 수정 및 삭제 기능 구현
- 카테고리 기반 게시글 관리
이미지 업로드 시스템
- MinIO 기반 이미지 업로드 기능 구현
- 게시글 이미지 URL 관리
- Object Storage 기반 파일 저장 구조 설계
CI/CD 자동 배포
- GitHub Actions 기반 빌드 자동화
- Docker 이미지 빌드 및 서버 배포
- Git push 시 자동 배포 파이프라인 구축
문제 해결 및 개선 경험
Orphan File 문제
게시글 수정 시 본문에서 제거된 이미지가
MinIO 스토리지에 남는 Orphan File 문제가 발생했습니다.
→ UploadFile 상태(TEMP / ATTACHED / DELETED)를 도입하여
파일 상태 기반 관리 구조를 설계했습니다.
결과
- 사용되지 않는 파일 식별 가능
- 스토리지 관리 안정성 개선
TEMP 파일 누적 문제
게시글 작성 취소 시 업로드된 이미지가
TEMP 상태로 스토리지에 누적되는 문제가 발생했습니다.
→ Spring Batch 기반 파일 정리 배치 작업을 구현하여
미사용 파일을 주기적으로 삭제하도록 개선했습니다.
GitHub Actions 환경 변수 문제
GitHub Actions 배포 과정에서
환경 변수가 전달되지 않아 애플리케이션 실행이 실패하는 문제가 발생했습니다.
→ GitHub Secrets와 .env 파일 전달 방식을 적용하여
CI/CD 환경에서 환경 변수 관리 문제를 해결했습니다.
CI/CD 배포 실패 문제 (SSH 인증 오류)
GitHub Actions에서 Docker 이미지를 빌드한 뒤
Ubuntu Linux 서버로 배포하는 과정에서 SSH 인증 오류가 발생했습니다.
Permission denied (publickey)
GitHub Actions 환경에서 서버 접속을 위한 SSH Key가 설정되지 않아 인증이 실패한 것이 원인이었습니다.
GitHub Actions 전용 SSH Key를 생성하고
Public Key를 서버 authorized_keys에 등록하고
Private Key를 GitHub Repository Secrets에 설정하여
Workflow에서 해당 Key를 사용하도록 구성했습니다.
이를 통해 GitHub Actions → Ubuntu 서버로 자동 배포가 정상적으로 동작하도록 개선했습니다.
프로젝트 결과
- MinIO 기반 이미지 업로드 시스템 구축
- GitHub Actions + Docker 기반 CI/CD 자동 배포 환경 구축
- 개인 Linux 서버에서 블로그 서비스 직접 운영
프로젝트 회고
개인 서버 환경에서 서비스를 직접 배포하고 운영하면서
애플리케이션 개발뿐만 아니라 배포와 인프라 관리까지 경험할 수 있었습니다.
특히 파일 업로드 시스템을 구현하면서
Object Storage 기반 파일 관리 구조와 배치 기반 파일 정리 방식의 필요성을 이해할 수 있었습니다.