🏠 Home NAS Web Platform (webpage)

Synology NAS 기반의 개인 웹 플랫폼으로, 로또 분석/추천 서비스와 여행 사진 지도 서비스를 포함합니다. Frontend, Backend, Travel Proxy, Auto Deployer를 Docker Compose로 통합하여 운영합니다.

---

🖥️ NAS 환경 정보

항목	값
NAS	Synology NAS
OS	Synology DSM
CPU	Intel Celeron J4025 (2 Core, 2.0GHz)
메모리	18 GB
Docker	Synology Container Manager
Reverse Proxy	Nginx (컨테이너)
Git Server	Gitea (self-hosted)

---

📁 디렉토리 구조

/volume1
├── docker/
│   └── webpage/                # 🚀 운영 런타임 (Docker Compose 기준점)
│       ├── backend/             # lotto-backend
│       ├── travel-proxy/        # travel API + thumbnail generator
│       ├── deployer/            # webhook 기반 자동 배포 컨테이너
│       ├── frontend/            # 정적 파일 (Vite build 결과)
│       ├── nginx/
│       │   └── default.conf
│       ├── scripts/
│       │   └── deploy.sh        # webhook이 호출하는 실행기
│       ├── docker-compose.yml
│       └── data/
│           └── lotto.db
│
├── workspace/
│   └── web-page-backend/        # 🧠 Git 레포 (backend + infra)
│       ├── backend/
│       ├── travel-proxy/
│       ├── deployer/
│       ├── nginx/
│       ├── scripts/
│       │   └── deploy-nas.sh    # 실제 운영 반영 로직
│       ├── docker-compose.yml
│       ├── .env.example
│       └── README.md
│
└── web/
    └── images/
        └── webPage/
            └── travel/          # 📷 원본 여행 사진 (RO)

---

🧩 서비스 구성 개요

Internet
  ↓
Nginx (frontend container)
  ├── /            → SPA (React/Vite)
  ├── /api/        → lotto-backend
  ├── /api/travel/ → travel-proxy
  ├── /media/...   → Nginx 직접 파일 서빙
  └── /webhook/    → deployer

---

🟦 Frontend (lotto-frontend)

• 역할: React + Vite 기반 SPA로, 로또 추천 및 여행 지도 UI를 제공합니다.
• 특징:
  • 정적 파일만 운영 서버에 배포합니다.
  • 장기 캐시(assets/)와 index.html 캐시 무효화 전략을 사용합니다.
  • Backend / Travel API는 Nginx에서 Reverse Proxy로 연결됩니다.
• 배포 방식:
  1. 로컬 개발:
     • .env 파일 설정 후 docker compose up으로 전체 스택 실행 가능
  2. 운영 배포:
     • Code를 Git에 Push
     • Webhook이 트리거되어 NAS가 자동 Pull & Deploy
     • (Frontend 빌드 산출물은 별도 업로드 혹은 CI 연동 필요)

---

🛠️ 개발 환경 설정 (Local Development)

이 프로젝트는 Windows/Mac 로컬 환경과 Synology NAS 운영 환경을 모두 지원하도록 구성되었습니다.

1. 환경 변수 설정

docker-compose.yml은 환경 변수에 의존합니다.

1. .env.example 파일을 복사하여 .env 파일을 생성하세요.

   cp .env.example .env
   

2. .env 파일의 경로(RUNTIME_PATH, PHOTO_PATH 등)를 로컬 환경에 맞게 수정하세요.
   • 기본값은 현재 디렉토리(.) 기준으로 설정되어 있어 바로 실행 가능합니다.

2. 로컬 실행

docker compose up -d

• Frontend: http://localhost:8080
• Backend API: http://localhost:18000
• Travel API: http://localhost:19000

---

---

🟩 Backend (lotto-backend)

• 역할: 로또 데이터 수집, 분석, 추천 API를 제공하며 SQLite로 데이터를 관리합니다.
• 주요 기능:
  • 최신 및 특정 회차 조회
  • 추천 번호 생성 및 히스토리 관리 (중복 제거)
  • 즐겨찾기, 메모, 태그 관리
  • 배치 추천 기능
• 기술 스택: FastAPI, SQLite, APScheduler (정기 수집)
• 주요 엔드포인트:

  GET  /api/lotto/latest
  GET  /api/lotto/{drw_no}
  GET  /api/lotto/recommend
  GET  /api/lotto/recommend/batch
  GET  /api/history
  PATCH /api/history/{id}
  DELETE /api/history/{id}
  

---

🟨 Travel Proxy (travel-proxy)

• 역할: 여행 사진 API, 지역별 사진 매칭, 썸네일 자동 생성 및 캐시를 담당합니다.
• 설계 포인트:
  • 원본 사진은 읽기 전용(RO)으로 마운트합니다.
  • 썸네일은 쓰기/읽기(RW) 전용 캐시 디렉토리를 사용합니다.
  • 사진 메타데이터 변경 시 캐시가 자동으로 무효화됩니다.
• 데이터 구조:

  /data/travel/           # 원본 사진 (RO)
    ├── 24.09.jeju/
    ├── 25.07.maldives/
    └── _meta/
        ├── region_map.json
        └── regions.geojson
  
  /data/thumbs/           # 썸네일 캐시 (RW)
    ├── 24.09.jeju/
    └── 25.07.maldives/
  

• 주요 엔드포인트:

  GET /api/travel/regions
  GET /api/travel/photos?region=jeju
  GET /media/travel/.thumb/{album}/{file}
  

---

🟥 Deployer (webpage-deployer)

• 역할: Gitea Webhook을 수신하여 Git pull 및 Docker 재기동을 자동화합니다.
• 흐름: Gitea Push → Webhook → deployer → /scripts/deploy.sh → docker compose up -d --build
• 보안: HMAC SHA256 서명(X-Gitea-Signature)을 WEBHOOK_SECRET 환경변수로 검증합니다.
• 특징:
  • Docker socket을 마운트하여 사용합니다.
  • 롤백을 위해 .releases/ 디렉토리에 자동 백업을 수행합니다.

---

🔁 배포 플로우 요약

• Backend / Travel / Infra 변경: git push를 통해 Gitea로 푸시하면 Webhook이 트리거되어 자동으로 배포됩니다.
• Frontend 변경: 로컬에서 빌드 후, 생성된 정적 파일만 NAS로 업로드합니다.

---

🧪 운영 체크 포인트

• /health: Backend 서비스 상태 확인
• /api/travel/photos: 응답 속도 확인
• /media/travel/.thumb: 썸네일 생성 여부 확인
• deployer 컨테이너 로그 확인

---

📝 TODO

🔥 로또 서비스 고도화

• 추천 결과 통계 시각화 (분포, 합계, 홀짝)
• 추천 히스토리 필터 및 검색 기능
• 추천 결과 즐겨찾기 UI
• 회차 대비 추천 성능 분석

🗺️ 여행 지도 UI

• 지도 영역 클릭 시 해당 지역 사진 로딩
• 사진 지연 로딩 (Lazy Load)
• 앨범 및 연도별 필터 기능
• 모바일 UX 개선

⚙️ 운영/인프라

• Docker 이미지 버전 태깅 자동화
• 배포 실패 시 자동 롤백 기능
• Health check 기반 배포 성공 판단 로직
• 로그 수집 및 관리 체계 개선

---

✨ 철학

“NAS는 서버가 아니라 집이다.”

그래서 안전하고, 단순하며, 복구 가능한 구조를 최우선으로 합니다.

---

Makefile 설정 사용 예시

• 배포: make deploy
• 백엔드 로그: make logs S=backend
• 전체 로그: make logs
• 상태: make status