gahusb/web-page-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
21a8173963175454aea042443e16923d4d4196d5
web-page-backend/README.md

263 lines
8.9 KiB
Markdown
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 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
│ ├── stock-lab/ # 🟪 stock-lab (Stock + AI)
│ ├── 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)
```
---
## 🧩 서비스 구성 개요
```mermaid
graph LR
User[User Browser] -->|HTTP| Nginx
subgraph NAS [Synology NAS]
Nginx -->|/api/lotto| Lotto[Lotto Backend]
Nginx -->|/api/travel| Travel[Travel Proxy]
Nginx -->|/api/stock| Stock[Stock Lab]
Stock -->|Trading/Balance| KIS[KIS API (Korea Inv.)]
Stock -->|Market News| News[News Sites]
end
subgraph Windows [High-Performance PC]
Stock -->|Analyze Request| WinServer[Windows AI Server]
WinServer -->|LLM Inference| Ollama[Ollama (Llama 3.1)]
WinServer -->|GPU| GPU[NVIDIA 3070 Ti]
end
```
---
## 🛠️ 개발 환경 설정 (Local Development)
이 프로젝트는 **Windows/Mac 로컬 환경**과 **Synology NAS 운영 환경**을 모두 지원하도록 구성되었습니다.
### 1. 환경 변수 설정
`docker-compose.yml`은 환경 변수에 의존합니다.
1. `.env.example` 파일을 복사하여 `.env` 파일을 생성하세요.
```bash
cp .env.example .env
```
2. `.env` 파일의 경로(`RUNTIME_PATH`, `PHOTO_PATH` 등)를 로컬 환경에 맞게 수정하세요.
- 기본값은 현재 디렉토리(`.`) 기준으로 설정되어 있어 바로 실행 가능합니다.
### 2. 로컬 실행
```bash
docker compose up -d
```
- Frontend: http://localhost:8080
- Backend API: http://localhost:18000
- Travel API: http://localhost:19000
- Stock Lab API: http://localhost:18500
---
### 🟦 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 연동 필요)
---
### 🟩 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}
```
---
### 🟪 Stock Lab (stock-lab)
- **역할**: 주식 시장 분석 및 AI 기반 투자 조언 제공. NAS의 편의성과 Windows PC의 고성능을 결합한 하이브리드 아키텍처입니다.
- **주요 기능**:
- **시장 뉴스 스크랩**: 네이버 증권, 해외 주요 뉴스 사이트 크롤링
- **자산 관리**: 한국투자증권(KIS) Open API 연동 (잔고 조회, 매수/매도)
- **AI 분석**: 고성능 PC의 로컬 LLM(Llama 3.1)을 활용하여 뉴스+포트폴리오 종합 분석
- **기술 스택**: Python, FastAPI, Ollama (Lava/Llama3), Docker
- **연동 구조**:
```
[NAS Stock-Lab] <--(HTTP)--> [Windows AI Server] <--(Localhost)--> [Ollama GPU]
```
- **주요 엔드포인트**:
```http
GET /api/stock/analyze # AI 시장 분석 요청
GET /api/stock/news # 최신 뉴스 데이터
GET /api/trade/balance # 계좌 잔고 조회
```
---
### 🟨 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`
Reference in New Issue View Git Blame Copy Permalink