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. 환경변수 설정

cp .env.example .env
# .env 파일을 편집하여 API 키 설정

필수 API 키:

• DART_API_KEY - DART OpenAPI 인증키
• KIS_APP_KEY / KIS_APP_SECRET - 한국투자증권 Open API 앱 키
• ANTHROPIC_API_KEY - Anthropic API 키 (LLM 분석용)

2. 전체 스택 실행

docker compose up -d --build

3. 상태 확인

# 게이트웨이 헬스체크
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	공유 라이브러리 (모델, DB, Redis, 설정)
stock-dart-collector	DART 공시/재무제표 수집
stock-kis-collector	KIS 주가/종목 수집
stock-news-crawler	뉴스 크롤링
stock-screener	정량 스크리닝
stock-catalyst	카탈리스트 탐지
stock-llm-analyzer	LLM 기반 AI 분석
stock-cli	CLI 파이프라인 관리 도구
stock-frontend	Next.js 웹 대시보드