🚇 Seoul Metro Data Pipeline

서울 지하철 실시간 도착 정보를 수집하여 Kafka 기반 스트리밍 파이프라인으로 처리하고, Spark로 배치/스트리밍 분석 후 S3 Data Lake에 적재하는 데이터 파이프라인 프로젝트입니다.

본 프로젝트는 팀 단위 데이터 엔지니어링 실습용 파이프라인 예제로, 수집 → 메시징 → 처리 → 저장 → 자동화 전 과정을 경험하는 것을 목표로 합니다.

---

📌 프로젝트 개요

• 데이터 소스: Seoul Metro Open API (실시간 도착 정보)
• 수집: Python 기반 Collector
• 메시징: Apache Kafka
• 처리: Apache Spark (Batch / Structured Streaming)
• 저장: AWS S3 (Data Lake)
• 자동화: GitHub Actions (스케줄링 및 파이프라인 실행)

---

🏗 아키텍처

[Seoul Metro API]
       ↓
[Collector (Python, Docker)]
       ↓
[Kafka]
       ↓
[Spark (Batch / Streaming)]
       ↓
[GitHub Actions]
       ↓
[S3 Data Lake]
       ↓
[Athena (선택)]

구성 요소 역할

구성 요소	역할
Collector	API 호출 및 표준 JSON 생성
Kafka	데이터 버퍼링 및 스트리밍 전달
Spark	배치/스트리밍 처리, 집계 및 정제
GitHub Actions	파이프라인 자동 실행 (cron)
S3	원본/처리 데이터 영구 저장
Athena	S3 기반 SQL 분석 (선택)

---

👥 역할 분담

이름	담당
민흥기	기본파이프라인 구현,Kafka 메시지 큐 도입,GitHub Actions
이재원	Docker 컨테이너화,Spark 분산 처리,AWS 클라우드 연계

📂 디렉토리 구조

seoul_train/
├─ .github/workflows/
│  └─ metro-data-pipeline.yml
├─ data/
│  └─ raw/
├─ docker/
│  ├─ compose.yml
│  ├─ Dockerfile.python
│  └─ Dockerfile.spark
├─ output/
│  ├─ line_stats/
│  └─ station_stats/
├─ src/
│  ├─ collector.py
│  ├─ api_client.py
│  ├─ producer.py
│  ├─ consumer.py
│  ├─ processor.py
│  ├─ analyzer.py
│  ├─ spark_batch.py
│  ├─ spark_streaming.py
│  └─ s3_uploader.py
├─ .env
├─ Dockerfile
├─ pyproject.toml
└─ README.md

---

⚙️ 실행 방법 (로컬 환경)

1. 환경 변수 설정

.env 파일 생성:

SEOUL_API_KEY=YOUR_API_KEY
KAFKA_BOOTSTRAP_SERVERS=kafka:9092
S3_BUCKET=your-bucket-name
AWS_REGION=ap-northeast-2

---

2. Kafka 및 Spark 실행

docker compose -f docker/compose.yml up -d kafka kafka-ui spark-master spark-worker

Kafka UI 접속:

http://localhost:8080

---

3. Producer / Consumer 실행

docker compose -f docker/compose.yml up producer consumer

---

4. Spark 배치 처리

docker compose -f docker/compose.yml run --rm spark-batch

---

5. Spark 스트리밍 처리

docker compose -f docker/compose.yml run --rm spark-streaming

---

☁️ GitHub Actions 파이프라인

실행 트리거

• push (src 변경 시)
• schedule (매 시간 정각 실행)
• workflow_dispatch (수동 실행 가능)

파이프라인 단계

1. collect: API 데이터 수집
2. process: 데이터 정제 및 변환
3. upload: S3 업로드 (스케줄 실행 시)
4. notify: 결과 로그 출력

---

🗄 데이터 레이아웃 (S3)

s3://<bucket>/metro/processed/YYYY/MM/DD/HH/

샘플 데이터:

{
  "station": "서울",
  "line": "1호선",
  "collected_at": "2026-01-26T13:38:52",
  "arrivals": [
    {"direction": "인천", "arrival_time": "3분"}
  ]
}

---

🛠 트러블슈팅

• Kafka 연결 실패: KAFKA_BOOTSTRAP_SERVERS 확인
• NoSuchBucket 에러: S3 버킷명 및 리전 확인
• Spark 체크포인트 경고: 로컬 테스트 환경에서는 무시 가능

---

📈 향후 개선 사항 (Roadmap)

• GitHub Actions → Airflow (워크플로우 오케스트레이션)
• S3 + Athena → Elasticsearch + Kibana (실시간 시각화)
• Spark Batch → Spark ML (머신러닝 파이프라인)

---

📚 참고

• Seoul Metro Open API
• Apache Kafka
• Apache Spark
• AWS S3 & Athena
• GitHub Actions

---

👥 팀 프로젝트 목적

본 프로젝트는 팀 단위로 다음 역량을 학습하기 위해 제작되었습니다.

• 데이터 수집 파이프라인 설계
• 메시징 시스템(Kafka) 운용
• 분산 처리(Spark) 경험
• 자동화(CI/CD) 구성
• Data Lake 구조 이해

---