Files

2026-01-25 17:42:19 +09:00

6.5 KiB

Raw Blame History

🏠 Home NAS Web Platform (webpage)

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

🖥️ NAS 환경 정보

항목	값
NAS	Synology NAS
OS	Synology DSM
CPU	(예: Intel / AMD / ARM – 필요 시 기입)
메모리	(예: 8GB / 16GB)
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로 연결됩니다.

배포 방식:

# 로컬 PC에서 실행
npm run build
npm run deploy:nas

🟩 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

6.5 KiB Raw Blame History Unescape Escape