155 lines
6.0 KiB
Markdown
155 lines
6.0 KiB
Markdown
# stock-gateway
|
|
|
|
한국 주식 분석 마이크로서비스 플랫폼의 **API Gateway 및 Docker Compose 오케스트레이션** 프로젝트.
|
|
|
|
APISIX API Gateway를 통해 6개 백엔드 서비스를 단일 진입점(`/api/v1/...`)으로 통합하고, Docker Compose로 전체 인프라(Redis, PostgreSQL, MongoDB)와 서비스를 한 번에 구동합니다.
|
|
|
|
## 아키텍처
|
|
|
|
```
|
|
Browser (localhost:3000)
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ APISIX API Gateway (:9080) │
|
|
│ /api/v1/dart/... → stock-dart-collector (:8001) │
|
|
│ /api/v1/kis/... → stock-kis-collector (:8002) │
|
|
│ /api/v1/news/... → stock-news-crawler (:8003) │
|
|
│ /api/v1/screening/… → stock-screener (:8004) │
|
|
│ /api/v1/catalyst/… → stock-catalyst (:8005) │
|
|
│ /api/v1/analysis/… → stock-llm-analyzer (:8006) │
|
|
└─────────────────────────────────────────────────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
Redis 7 PostgreSQL MongoDB 7
|
|
(:6379) (TimescaleDB) (:27017)
|
|
(:5432)
|
|
```
|
|
|
|
## 컨테이너 구성 (11개)
|
|
|
|
| 카테고리 | 서비스 | 이미지 | 포트 |
|
|
|---------|--------|--------|------|
|
|
| **인프라** | Redis | `redis:7-alpine` | 6379 |
|
|
| | PostgreSQL | `timescale/timescaledb:latest-pg16` | 5432 |
|
|
| | MongoDB | `mongo:7` | 27017 |
|
|
| **게이트웨이** | APISIX | `apache/apisix:3.8.0-debian` | 9080, 9091 |
|
|
| **수집** | stock-dart-collector | Python 3.12 | 8001 |
|
|
| | stock-kis-collector | Python 3.12 | 8002 |
|
|
| | stock-news-crawler | Python 3.12 | 8003 |
|
|
| **분석** | stock-screener | Python 3.12 | 8004 |
|
|
| | stock-catalyst | Python 3.12 | 8005 |
|
|
| | stock-llm-analyzer | Python 3.12 | 8006 |
|
|
| **프론트엔드** | stock-frontend | Node.js 20 | 3000 |
|
|
|
|
## 빠른 시작
|
|
|
|
### 1. 환경변수 설정
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# .env 파일을 편집하여 API 키 설정
|
|
```
|
|
|
|
필수 API 키:
|
|
- `DART_API_KEY` - [DART OpenAPI](https://opendart.fss.or.kr/) 인증키
|
|
- `KIS_APP_KEY` / `KIS_APP_SECRET` - [한국투자증권 Open API](https://apiportal.koreainvestment.com/) 앱 키
|
|
- `ANTHROPIC_API_KEY` - [Anthropic API](https://console.anthropic.com/) 키 (LLM 분석용)
|
|
|
|
### 2. 전체 스택 실행
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
### 3. 상태 확인
|
|
|
|
```bash
|
|
# 게이트웨이 헬스체크
|
|
curl http://localhost:9080/api/health
|
|
|
|
# 개별 서비스 헬스체크 (게이트웨이 경유)
|
|
curl http://localhost:9080/api/v1/dart/health
|
|
curl http://localhost:9080/api/v1/kis/health
|
|
|
|
# 전체 컨테이너 상태
|
|
docker compose ps
|
|
```
|
|
|
|
## APISIX 게이트웨이 설정
|
|
|
|
### 동작 모드
|
|
|
|
- **Standalone (declarative)**: etcd 없이 `apisix.yaml` 파일로 라우팅 설정
|
|
- 설정 변경 시 APISIX 컨테이너 재시작 필요
|
|
|
|
### API 라우팅
|
|
|
|
모든 API 경로는 `/api/v1/{service}/{path}` 패턴을 따릅니다. `proxy-rewrite` 플러그인이 버전 프리픽스를 제거하여 백엔드 서비스에 전달합니다.
|
|
|
|
```
|
|
요청: GET /api/v1/kis/stocks?market=KOSPI
|
|
→ 변환: GET /stocks?market=KOSPI → stock-kis-collector:8002
|
|
```
|
|
|
|
### 글로벌 플러그인
|
|
|
|
| 플러그인 | 설정 |
|
|
|---------|------|
|
|
| **CORS** | `allow_origins: *`, 모든 메서드/헤더 허용 |
|
|
| **Rate Limiting** | 100 req/s, burst 50, IP 기반, 초과 시 429 |
|
|
| **Prometheus** | `:9091`에서 메트릭 노출 |
|
|
|
|
### 헬스체크
|
|
|
|
모든 업스트림에 Active Health Check 설정:
|
|
- 정상: 10초 간격, 2회 연속 성공 → healthy
|
|
- 비정상: 5초 간격, 3회 연속 실패 → unhealthy
|
|
|
|
## API 엔드포인트 목록
|
|
|
|
| 메서드 | 경로 | 설명 |
|
|
|--------|------|------|
|
|
| GET | `/api/health` | 게이트웨이 상태 (버전 정보 포함) |
|
|
| GET | `/api/v1/{svc}/health` | 개별 서비스 헬스체크 |
|
|
| GET | `/api/v1/{svc}/streams` | Redis Stream 큐 길이 |
|
|
| GET | `/api/v1/kis/stocks` | 종목 목록 (검색, 필터, 페이징) |
|
|
| GET | `/api/v1/kis/stocks/{code}` | 종목 상세 (가격, 밸류에이션) |
|
|
| GET | `/api/v1/screening/results/latest` | 최근 스크리닝 결과 |
|
|
| GET | `/api/v1/catalyst/results/{code}` | 종목별 공시/카탈리스트 |
|
|
| GET | `/api/v1/analysis/results/{code}` | 종목별 AI 분석 결과 |
|
|
| POST | `/api/v1/dart/collect/financials` | DART 재무제표 수집 트리거 |
|
|
| POST | `/api/v1/dart/collect/disclosures` | DART 공시 수집 트리거 |
|
|
| POST | `/api/v1/kis/collect/stocks` | KIS 종목 목록 수집 트리거 |
|
|
| POST | `/api/v1/kis/collect/prices` | KIS 가격 수집 트리거 |
|
|
| POST | `/api/v1/news/collect/news` | 뉴스 크롤링 트리거 |
|
|
| POST | `/api/v1/screening/screen` | 스크리닝 실행 트리거 |
|
|
| POST | `/api/v1/catalyst/detect` | 카탈리스트 탐지 트리거 |
|
|
| POST | `/api/v1/analysis/analyze` | LLM 분석 트리거 |
|
|
|
|
## 프로젝트 구조
|
|
|
|
```
|
|
stock-gateway/
|
|
├── docker-compose.yml # 전체 스택 오케스트레이션
|
|
├── .env.example # 환경변수 템플릿
|
|
└── apisix/
|
|
└── conf/
|
|
├── config.yaml # APISIX 서버 설정 (standalone mode)
|
|
└── apisix.yaml # 라우트, 업스트림, 글로벌 룰 정의
|
|
```
|
|
|
|
## 관련 프로젝트
|
|
|
|
| 프로젝트 | 설명 |
|
|
|---------|------|
|
|
| [stock-common](../stock-common) | 공유 라이브러리 (모델, DB, Redis, 설정) |
|
|
| [stock-dart-collector](../stock-dart-collector) | DART 공시/재무제표 수집 |
|
|
| [stock-kis-collector](../stock-kis-collector) | KIS 주가/종목 수집 |
|
|
| [stock-news-crawler](../stock-news-crawler) | 뉴스 크롤링 |
|
|
| [stock-screener](../stock-screener) | 정량 스크리닝 |
|
|
| [stock-catalyst](../stock-catalyst) | 카탈리스트 탐지 |
|
|
| [stock-llm-analyzer](../stock-llm-analyzer) | LLM 기반 AI 분석 |
|
|
| [stock-cli](../stock-cli) | CLI 파이프라인 관리 도구 |
|
|
| [stock-frontend](../stock-frontend) | Next.js 웹 대시보드 |
|