← 프로젝트

StockPulse — 주식 이상 탐지 · AI 분석 파이프라인

  • 개인 프로젝트 · 설계부터 운영까지
  • Kafka · MSA
  • Kubernetes · ArgoCD
  • TimescaleDB

개요

장이 열려 있는 동안 주가가 갑자기 튀면, 투자자가 가장 먼저 궁금한 건 “왜?“입니다. StockPulse는 미국 68종목과 한국 40종목의 시세를 지켜보다가 급등락이 나오면, 그 움직임이 종목 하나의 일인지, 업종 전체인지, 시장 전체인지 먼저 나눕니다. 그다음 관련 뉴스를 모아 LLM이 원인을 한국어 · 영어로 정리하고, 대시보드와 Slack으로 보냅니다.

수집부터 알림까지 서비스 7개가 Kafka 토픽 7개(DLQ 2개 포함)로 이어지고 Next.js 대시보드가 붙은 이벤트 기반 구조입니다. 온프레미스 쿠버네티스 클러스터에 ArgoCD GitOps로 배포해 운영했고, 혼자 설계하고 만들고 운영한 개인 프로젝트입니다.

아키텍처

스크롤을 내리면 설명을 따라 다이어그램이 움직입니다. 노드를 가리키거나 선택하면 사양이 보입니다.

한눈에 보기

StockPulse는 외부 데이터(시세 · 뉴스 · LLM)를 받아 온프레미스 쿠버네티스 안의 서비스들이 Kafka로 주고받으며 처리하고, 결과를 브라우저와 Slack으로 보냅니다. 배포는 아래쪽 GitOps 흐름이 맡습니다.

services ×8topics ×7Kafka ×3

1시세가 들어오는 길

미국 68종목은 stock-collector가 NYSE 장중에만 60초마다 yfinance에서 1분봉을 가져와 stock.raw.us로 보냅니다. 장이 닫히면 개장까지 잠듭니다.

stock.raw.usNYSE calendar

한국 40종목은 kis-bridge가 한국투자증권 WebSocket으로 실시간 체결을 받아 1분봉으로 묶어 stock.raw.kr로 보냅니다. 토큰은 만료 전에 갱신하고, 끊기면 5→60초 백오프로 다시 붙습니다.

stock.raw.krKIS H0STCNT0

2급등락 탐지와 분류

anomaly-detector는 두 토픽을 함께 읽어, 등락률이나 Z-score가 임계값을 넘는 최근 5분 이내의 bar만 골라냅니다. 한국은 상하한 ±30%를 고려해 임계값을 더 높게 둡니다.

% OR Z-scorelast 5 min

ETF를 섹터 체온계로 씁니다. 같은 방향으로 움직인 섹터 ETF가 3개 섹터 이상이거나 같은 방향으로 움직인 섹터가 3개 이상이면 MARKET, 섹터 ETF 자신이거나 해당 섹터 ETF · 같은 섹터 종목이 함께 움직이면 SECTOR, 아니면 INDIVIDUAL. 결과는 anomaly.detected로 나갑니다.

INDIVIDUALSECTORMARKET

3원인 분석

news-fetcher가 anomaly.detected를 받아, 영문은 티커와 섹터 키워드로 NewsAPI(최근 3일) · Google News에서, 한글은 섹터 키워드로 Naver · Google News RSS에서 언어별로 최대 4건을 모아 news.fetched로 보냅니다.

anomaly.detectednews.fetched

ai-analyzer가 Groq LLM으로 한국어 · 영어 분석을 씁니다. 분류에 따라 프롬프트 초점을 기업 이슈 · 섹터 이슈 · 매크로로 바꾸고, 429가 오면 안내된 시간만큼 기다렸다 다시 부릅니다. 실패가 이어져 서킷브레이커가 열리면 news.fetched.dlq로 보냅니다.

llama-3.3-70bcircuit breaker 5×/60snews.fetched.dlq

4사람에게 닿기까지

api가 analysis.completed를 받아 TimescaleDB에 저장하고, WebSocket /ws/live로 열려 있는 대시보드에 바로 밀어줍니다. 브라우저는 nginx Ingress를 거쳐 들어옵니다.

analysis.completed/ws/live

notifier는 같은 결과를 섹터 · 이벤트 유형 필터로 거른 뒤 Slack으로 보냅니다. 3번 시도해도 실패하면 analysis.completed.dlq로 옮깁니다.

3 attemptsanalysis.completed.dlq

재시작했을 때의 동작은 단계마다 다릅니다. 탐지 · 뉴스 수집 · 알림은 earliest로 놓친 메시지를 다시 처리하고, LLM 분석과 api는 latest로 두어 밀린 메시지에 LLM 비용이 한꺼번에 나가거나 같은 신호가 다시 뜨지 않게 했습니다.

earliestlatest

5매일 다시 배우는 모델

ml-trainer CronJob이 한국 25종목의 다음 날 방향을 예측합니다. 매일 전날 예측을 채점하고, 30일 정확도가 52% 아래거나 모델이 7일을 넘으면 다시 학습합니다. 매주 한 번은 Optuna로 튜닝하고 walk-forward로 검증합니다.

LGB 0.4 · XGB 0.35 · Cat 0.25Purged CV

6Git 푸시에서 배포까지

main에 푸시하면 self-hosted runner의 GitHub Actions가 바뀐 경로를 서비스에 매핑해 변경된 서비스만 빌드하고, Harbor에 stock/<svc>:<sha7>로 올립니다.

path → service mapimages ×9

Actions가 매니페스트의 이미지 태그를 바꿔 커밋하면([skip ci]로 루프 방지), ArgoCD가 60초마다 저장소를 확인해 selfHeal · prune으로 클러스터를 Git과 똑같이 맞춥니다. 이미지는 Harbor에서 받아 오고, 비밀값은 Sealed Secrets로 암호화해 Git에 둡니다.

selfHeal · pruneServerSideApply

7지켜보는 눈 — 관측

Prometheus가 15초마다 api와 anomaly-detector의 지표, 쿠버네티스 · 노드 지표를 모으고, Grafana 대시보드 하나에서 Kafka lag · API p95 지연 · 탐지 건수 · ML 정확도를 봅니다.

anomaly_detected_totalml_prediction_accuracy
한눈에 보기1 / 14
외부 데이터온프레미스 쿠버네티스 · namespace stock사용자CI/CD · GitOpsKAFKA ×3yfinance미국 1분봉 · 60초KIS OpenAPI한국 실시간 체결NewsAPI · RSS영문 · 한국어 뉴스Groq LLMllama-3.3-70bSlack이상 신호 알림브라우저실시간 대시보드stock-collectoryfinance · 장중만kis-bridge틱 → 1분봉 집계news-fetcher언어별 최대 4건ai-analyzer한/영 원인 분석notifier필터 · 재시도anomaly-detector% · Z · ETF 분류apiFastAPI · WebSocketTimescaleDB이상값 · 분석 저장frontendNext.js 14Ingressnginx · MetalLBml-trainerCronJob ×3PrometheusGrafana · 15초 수집Sealed Secrets시크릿 복호화GitHubmain 브랜치Actionsself-hosted · 변경분Harbor사설 레지스트리ArgoCDselfHeal · prune

직접 해보기

미국 장 1분봉이 들어오고 있습니다

기준 3.0% 또는 Z 2.0누적 탐지 0

실제 서비스의 종목 구성과 탐지 · 분류 규칙을 브라우저에서 재현했습니다. 시세, 뉴스, AI 분석 문장은 예시입니다.

운영 기록

ArgoCD가 영원히 OutOfSync

증상
배포가 끝나도 StatefulSet들이 계속 OutOfSync로 표시됐습니다.
원인
StatefulSet의 volumeClaimTemplates처럼 클러스터가 채워 넣는 필드가 Git과 계속 달랐습니다.
조치
해당 필드를 ignoreDifferences로 비교에서 뺐고, 같은 이유로 CronJob의 status도 뺐습니다. ServerSideApply=true는 큰 리소스가 last-applied annotation 한도(262KB)에 걸리지 않도록 미리 켜 두었습니다.

ArgoCD는 selfHeal과 prune이 켜져 있어서, 차이가 남아 있으면 계속 동기화를 시도합니다. 클러스터가 채워 넣는 필드 때문에 생긴 차이는 아무리 동기화해도 사라지지 않아 대시보드가 늘 OutOfSync였고, 진짜 차이가 생겨도 알아보기 어려웠습니다. 그래서 비교에서 뺄 필드를 명시했습니다. 재시도 5회(5초부터 최대 3분)와 삭제를 마지막에 하는 PruneLast는 처음부터 설정해 두었습니다.

배운 점 GitOps에서 "Git과 같다"의 기준에서 클러스터가 관리하는 필드는 빼야 합니다. 비교 대상과 적용 방식을 함께 설계합니다.

브로커 3대가 작은 노드의 메모리를 넘본다

증상
힙을 지정하지 않으면 브로커마다 메모리 limit(2Gi) 기준으로 잡혀 세 대가 최대 6Gi를 쓸 수 있었고, 2코어 8GB 노드에서는 OOMKill 위험이 있었습니다.
원인
스테이트풀 워크로드의 기본 JVM 설정이 작은 노드 기준으로는 컸고, 기동 · 종료 시간도 고려돼 있지 않았습니다.
조치
브로커 · ZooKeeper 힙을 -Xmx256m으로 제한하고, 재시작 때 __consumer_offsets 로딩을 기다리도록 startupProbe를 최대 630초로, 정상 종료를 위해 terminationGracePeriodSeconds를 90초로 늘렸습니다.

Kafka는 브로커 3대로 운영합니다. 복제 계수 3은 컨슈머 오프셋 · 트랜잭션 로그 토픽에만 지정했고, 애플리케이션 토픽은 자동 생성에 맡겨 브로커 기본값을 따릅니다. 메모리와 함께 기동 · 종료 시간도 맞췄습니다. 브로커가 뜰 때는 __consumer_offsets를 읽는 시간이 필요한데, 파티션 54개를 읽는 동안 liveness probe(60초)가 먼저 실패해 파드가 CrashLoopBackOff에 빠졌습니다. 내려갈 때도 기본 30초 유예로는 controlled shutdown이 끝나지 않아 파드를 강제 삭제(force delete)해야 하는 일이 반복됐습니다. 그래서 startupProbe로 충분한 시간을 주고, 종료 때도 controlled shutdown이 끝날 때까지 기다리게 했습니다.

배운 점 스테이트풀 워크로드는 "뜨는 시간"과 "내려가는 시간"까지가 리소스 설계입니다.

1분봉 배치가 Kafka 메시지 한도를 넘었다

증상
미국 68종목의 1분봉을 한 메시지로 묶어 보내자 메시지 크기 한도에 걸렸습니다.
원인
수집기가 조회 기간 전체(기본 5일치)의 분봉을 배치 메시지 하나에 담았습니다.
조치
쿠버네티스 배포에서는 조회 기간을 5일에서 1일로 줄여, 처음부터 10MB로 잡아 둔 메시지 한도 안에 들어오게 했습니다.

수집기는 60초마다 전 종목의 분봉을 key batch로 한 번에 보냅니다. 기본 조회 기간인 5일치는 종목당 봉이 2,000개 가까이 돼 10MB를 넘기 쉬워서, 클러스터 설정에서는 1일치만 보내도록 줄였습니다.

배운 점 "배치 하나 = 메시지 하나" 설계는 데이터가 늘면 한도에 부딪힙니다. 커질 수 있는 메시지는 쪼갤 단위를 먼저 정합니다.

설계 결정

단계마다 다른 consumer offset 전략

배경
파이프라인 단계마다 바라는 시작 위치가 다릅니다. 토픽에 남은 메시지를 처음부터 처리해야 하는 단계도, 지난 메시지를 처리하면 곤란한 단계도 있습니다.
검토한 대안
  • 모든 consumer를 earliest로
  • 모든 consumer를 latest로
선택 이유
컨슈머 그룹은 커밋한 오프셋부터 다시 읽으므로, 이 설정은 커밋된 오프셋이 없을 때(처음 배포하거나 그룹 오프셋이 만료됐을 때) 어디서 시작할지를 정합니다. 탐지 · 뉴스 수집 · 알림은 earliest로 두어 토픽에 남은 메시지부터 처리하고, LLM 분석과 api는 latest로 두어 그때 쌓여 있던 메시지에 LLM 비용이 한꺼번에 나가거나 지난 신호가 대시보드에 다시 뜨지 않게 했습니다.
트레이드오프
latest 단계는 처음 붙을 때 그 전에 쌓인 메시지를 건너뛰고, 건너뛴 신호는 DB에 남지 않습니다. 대시보드의 "과거 재분석"은 이미 저장된 최근 7일 신호 중 분석이 없거나 실패한 것(최대 30건)만 다시 분석합니다.

ETF를 섹터 체온계로 쓰는 이상 신호 분류

배경
종목 하나가 급등했을 때, 그게 그 회사만의 일인지 업종 전체의 움직임인지에 따라 원인도, 찾아볼 뉴스도 다릅니다.
검토한 대안
  • 종목 단위로만 판정하고 원인 추론은 LLM에 맡기기
선택 이유
섹터마다 ETF를 체온계로 둡니다. 같은 방향으로 움직인 섹터 ETF가 3개 섹터 이상에 걸쳐 있거나 같은 방향으로 움직인 섹터가 3개 이상이면 MARKET, 움직인 종목이 섹터 ETF 자신이거나 해당 섹터 ETF · 같은 섹터 종목이 함께 움직이면 SECTOR, 아니면 INDIVIDUAL로 나눕니다. 분류에 따라 LLM 프롬프트의 초점도 기업 이슈 · 섹터 이슈 · 매크로로 바꿉니다.
트레이드오프
분류 품질이 ETF 구성과 임계값에 달려 있습니다. 임계값은 시장마다 따로 조정해야 합니다(한국은 상하한 ±30%를 고려해 더 높게).

외부 API 실패는 기다리고, 끊고, DLQ로 격리

배경
LLM과 Slack 같은 외부 API는 언제든 느려지거나 429를 돌려줍니다. 메시지 하나의 실패가 파이프라인 전체를 막으면 안 됩니다.
검토한 대안
  • 실패한 메시지를 성공할 때까지 계속 재시도
  • 실패한 메시지 버리기
선택 이유
ai-analyzer는 429 응답에 적힌 대기 시간을 읽어 기다렸다 다시 부르고(최대 3번), 연속 5번 실패하면 60초 동안 호출을 끊습니다(서킷브레이커). 서킷이 열린 동안 들어온 메시지는 원래 토픽 · 에러 · 시각을 담아 news.fetched.dlq로 보냅니다. 그 밖의 실패는 "분석 실패" 문구로 analysis.completed에 흘려보내고, 대시보드의 "과거 재분석"으로 다시 분석할 수 있습니다. notifier도 Slack 전송을 5초 간격으로 최대 3번 시도한 뒤 analysis.completed.dlq로 보냅니다.
트레이드오프
DLQ에 쌓인 메시지를 다시 흘려보내는 도구는 아직 없습니다.

Kafka가 없어도 도는 일봉 경로

배경
Kafka · 수집기 · 탐지기가 모두 떠 있어야만 동작하면, 인프라 일부가 내려갔을 때 서비스 전체가 멈춥니다. 로컬에서 기능을 확인할 때도 전체 스택이 필요해집니다.
검토한 대안
  • Kafka 없이는 기동하지 않기
선택 이유
api는 Kafka 설정과 상관없이 APScheduler로 한 시간마다(그리고 기동 직후) 일봉 기반 파이프라인(탐지 → 뉴스 → 분석 → 저장)을 직접 돌리고, KAFKA_BOOTSTRAP_SERVERS가 있으면 analysis.completed 컨슈머를 함께 띄웁니다. 그래서 Kafka · 수집기 · 탐지기가 없어도 일봉 기준 결과는 계속 쌓입니다. 두 경로는 같은 탐지 · 분석 모듈(core/)을 써서 로직이 갈라지지 않습니다.
트레이드오프
일봉 경로는 실시간성이 없고, 운영에서도 스트리밍 경로와 함께 매시간 돌며 아직 분석되지 않은 일봉 신호마다 LLM을 호출합니다.

이미지 태그 커밋 + ArgoCD로 배포하는 GitOps

배경
서비스 8개와 ml-trainer, 이미지 9개를 빌드해 클러스터에 반영하는 과정을 손으로 하면, 지금 무엇이 어느 버전으로 떠 있는지 추적하기 어렵습니다.
검토한 대안
  • CI에서 kubectl apply로 직접 배포
선택 이유
CI는 변경된 서비스만 빌드해 Harbor에 올리고, 매니페스트의 이미지 태그를 커밋 SHA로 바꿔 커밋합니다([skip ci]로 루프 방지). ArgoCD가 그 커밋을 보고 selfHeal · prune으로 클러스터를 Git과 같게 맞춥니다. 무엇이 배포돼 있는지는 Git 기록이 답해 줍니다.
트레이드오프
태그 커밋이 저장소 기록에 쌓이고, ArgoCD 쪽에서는 클러스터가 채우는 필드를 비교에서 빼고 annotation 한도(262KB)에 대비해 ServerSideApply를 미리 켜는 등 따로 다룰 것이 생겼습니다(운영 기록 참고).

비밀값도 Git에 — Sealed Secrets

배경
GitOps로 모든 매니페스트를 Git에 두면, 비밀값을 어디에 둘지가 문제입니다.
검토한 대안
  • kubectl로 Secret을 손으로 생성
  • 외부 시크릿 저장소(Vault 등)
선택 이유
수동 실행 워크플로가 GitHub Secrets로 .env를 만들고, kubeseal로 암호화한 SealedSecret 6개를 커밋합니다. 클러스터 안의 컨트롤러만 복호화할 수 있어서 Git에 올려도 안전합니다. 컨트롤러도 ArgoCD Application으로 관리합니다.
트레이드오프
컨트롤러 키를 잃으면 모든 SealedSecret을 다시 만들어야 해서, 키 백업이 운영 절차에 들어가야 합니다.

인프라 · 비용

git pushmainActionsself-hosted · 변경분Harborstock/<svc>:<sha>태그 커밋[skip ci]ArgoCDselfHeal · prune클러스터namespace stock

온프레미스 쿠버네티스

  • 네임스페이스 stock 하나에 Deployment 12개, StatefulSet 3개(Kafka ×3 · ZooKeeper · TimescaleDB), DaemonSet 2개, CronJob 6개, Job 3개를 올렸습니다.
  • 외부 노출은 MetalLB(L2)가 준 IP 하나에 nginx Ingress로 경로를 나눕니다. /api · /ws · /auth · /metrics는 FastAPI로, /grafana · /prometheus는 모니터링으로, 나머지는 Next.js로 갑니다. WebSocket은 타임아웃을 1시간으로 늘렸습니다.
  • 저장소는 NFS 정적 PV(Retain)와 nfs-subdir-external-provisioner를 함께 쓰고, 무거운 워크로드(Kafka · DB · API · ML)는 node-tier=heavy 노드에 우선 배치합니다.
  • 이미지는 사설 Harbor에 두고, 자체 서명 인증서는 DaemonSet이 각 노드의 containerd에 배포합니다.

Git 푸시에서 배포까지

self-hosted runner의 GitHub Actions가 바뀐 경로를 서비스에 매핑해 변경된 서비스만 빌드합니다. Harbor에 stock/<svc>:<sha7>로 올린 뒤 매니페스트 태그를 바꿔 커밋하면, ArgoCD가 그 커밋을 60초 주기로 확인해 클러스터에 반영합니다. 비밀값은 Sealed Secrets로 암호화해 Git에 둡니다.

데이터 보존과 비용

  • 매주 도는 CronJob 두 개가 각각 NFS 사용률(80% 경고)과 Redis AOF 재작성을 맡습니다.
  • Kafka는 7일 또는 파티션당 15GiB까지만 보관합니다.

내 기여

StockPulse는 혼자 진행한 개인 프로젝트라 기획 · 개발 · 인프라 · 운영을 모두 직접 했습니다. 만든 순서대로 정리하면 다음과 같습니다.

클러스터 위에 파이프라인 세우기

  • 온프레미스 쿠버네티스에 ArgoCD(GitOps)와 self-hosted runner CI를 붙이고, FastAPI 백엔드 · 프런트엔드 · Kafka 파이프라인을 올렸습니다.
  • Sealed Secrets로 비밀값을 암호화해 Git에 올리고, NFS PV, MetalLB · Ingress(WebSocket), Harbor 인증서 배포를 설정했습니다.
  • Kafka · Zookeeper · TimescaleDB가 자원과 프로브 문제로 넘어지는 것을 메모리 한도, TCP 프로브, 서비스 링크 끄기로 하나씩 잡았습니다(운영 기록, 운영 기록).

기능과 관측

  • 한국 주식 1분봉(KIS)과 일봉 조회, 로그인, 관심 종목과 포트폴리오 손익(실시간 반영), 반응형 화면을 만들었습니다.
  • LLM 분석 리포트 파이프라인을 붙이고, 분석이 실패하면 다시 분석하게 했습니다. 탐지는 장 시간에만 하고, 주말 · 공휴일에는 요청을 줄였습니다.
  • Prometheus · Grafana(Helm), kube-state-metrics, node-exporter로 클러스터와 이상 탐지기 지표를 보이게 했습니다.

안정화와 예측

  • ArgoCD가 StatefulSet의 volumeClaimTemplates 때문에 계속 OutOfSync로 보이던 문제를 고쳤습니다(운영 기록).
  • 무료로 쓸 수 있는 토큰 양 때문에 LLM을 Gemini에서 Groq(llama-3.3-70b)로 바꿨습니다.
  • 섹터 ETF 피처, 상대강도, Purged Walk-Forward 교차검증을 쓴 주가 예측 모델을 학습해 화면에 보여 주고, 차트에 이상값 마커와 감지 뒤 결과(방향 유지 / 소멸)를 표시했습니다.

한계 · 회고

알고 있는 한계와, 다시 한다면 바꿀 부분입니다.

  • 분봉 스트리밍 탐지가 실제로는 신호를 내지 못합니다. 한국 분봉은 kis-bridge가 메시지마다 종목별 봉 하나만 보내는데, 탐지기는 메시지 하나만 보고 봉이 두 개 미만이면 건너뜁니다. 미국 분봉은 시간대를 떼어 낸 뉴욕 시각을 UTC 컨테이너 시계와 비교해 “최근 5분” 필터에서 걸러집니다. 그래서 쌓인 신호는 사실상 api가 매시간 돌리는 일봉 경로에서 나온 것입니다. 탐지기가 종목별 최근 봉을 상태로 쌓아 두고, 시각을 UTC로 통일하는 게 먼저 고칠 부분입니다.
  • API가 사실상 단일 인스턴스입니다. WebSocket 연결 관리가 프로세스 메모리에 있어서, API를 여러 대로 늘리면 일부 브라우저에 알림이 가지 않습니다. HPA는 최대 3대로 잡혀 있지만, Redis pub/sub로 브로드캐스트를 옮기기 전까지는 1대로 운영해야 합니다.
  • CI에 테스트가 없습니다. 변경된 서비스만 빌드하는 파이프라인은 갖췄지만, 빌드 전에 도는 테스트 단계가 없어서 회귀를 사람이 잡아야 합니다.
  • 파티션 수와 복제 계수를 정하지 않았습니다. 토픽을 자동 생성에 맡겨서 consumer를 늘려도 병렬 처리 효과가 제한적이고, 브로커가 3대인데도 애플리케이션 토픽은 기본 복제 계수(1)를 따릅니다.
  • 데이터 보존 정책이 실제 테이블에 적용되지 않습니다. 1일 뒤 압축, 시세 30일 · 분석 90일 보존 정책과 정리 CronJob을 만들었지만, 정책이 가리키는 테이블 이름이 앱이 만드는 테이블과 달라 실제로는 아무것도 압축 · 삭제하지 않습니다. 앱 테이블에 맞춰 정책을 다시 거는 게 먼저입니다.
  • 관측의 빈칸. ai-analyzer는 스크레이프 대상에 있지만 메트릭 서버가 없고, kafka-exporter가 배포되지 않아 대시보드의 Kafka lag 패널이 비어 있을 수 있습니다. Redis도 배포만 돼 있고 쓰이지 않습니다.
  • CronJob 시간대. timeZone: Asia/Seoul을 지정해 놓고 스케줄은 UTC로 환산해 적어서, 학습 · 정리 CronJob 6개가 모두 의도보다 9시간 이르게 돕니다.