208 lines
6.5 KiB
Markdown
208 lines
6.5 KiB
Markdown
# 🏠 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로 연결됩니다.
|
||
- **배포 방식**:
|
||
```bash
|
||
# 로컬 PC에서 실행
|
||
npm run build
|
||
npm run deploy:nas
|
||
```
|
||
|
||
---
|
||
|
||
### 🟩 Backend (lotto-backend)
|
||
|
||
- **역할**: 로또 데이터 수집, 분석, 추천 API를 제공하며 SQLite로 데이터를 관리합니다.
|
||
- **주요 기능**:
|
||
- 최신 및 특정 회차 조회
|
||
- 추천 번호 생성 및 히스토리 관리 (중복 제거)
|
||
- 즐겨찾기, 메모, 태그 관리
|
||
- 배치 추천 기능
|
||
- **기술 스택**: FastAPI, SQLite, APScheduler (정기 수집)
|
||
- **주요 엔드포인트**:
|
||
```http
|
||
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/
|
||
```
|
||
- **주요 엔드포인트**:
|
||
```http
|
||
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`
|