Streamlit + FastAPI + PostgreSQL 풀스택을
서브도메인으로 — air.sielain.com 구축기

각 단계를 클릭하거나 ▶ 순서대로 재생을 눌러 요청의 전체 여정을 따라가 보세요.

프로토타입은 데이터(JSON)와 분석 로직(JS)과 화면(HTML)이 한 파일 안에 있었습니다. 잘 돌아가는데 왜 쪼갰을까요? 아래 비교 탭을 눌러 보세요.

이 프로젝트의 결정적 설계 포인트는 compose 스택은 완전히 독립시키되, 프론트 컨테이너만 기존 터널의 네트워크에 추가로 연결한 것입니다.

# incheon_air_traffic_dashboard/docker-compose.yml (요약)
services:
  postgres:
    image: postgres:16-alpine
    healthcheck:                      # DB가 "진짜 준비될 때까지" 대기
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
    networks: [air_net]

  backend:
    build: ./backend
    depends_on:
      postgres: { condition: service_healthy }   # healthcheck 통과 후 기동
    volumes:
      - ./data:/data                  # 엑셀 원본 + 업로드 파일 보관 (rw)
    networks: [air_net]

  frontend:
    build: ./frontend
    container_name: air_traffic_frontend
    networks:
      - air_net                       # 내부 통신용 (backend, postgres)
      - sielain_net                   # ★ 기존 터널과의 공유 네트워크

networks:
  air_net: { driver: bridge }
  sielain_net:
    external: true                    # ★ 새로 만들지 않고 기존 것을 참조
    name: docker_sielain_net

cloudflared 터널은 설정 방식이 두 갈래이고, 어느 쪽인지에 따라 라우팅 추가 방법이 완전히 다릅니다. parts 배포 때 한 번 밟았던 함정을 이번에는 설계 단계에서 피했습니다.

cloudflared:
  image: cloudflare/cloudflared:latest
  command: tunnel --no-autoupdate --protocol http2 run
  environment:
    - TUNNEL_TOKEN=${CLOUDFLARE_TUNNEL_TOKEN}   # 이것만 있으면 끝

ingress:
  - hostname: air.sielain.com
    service: http://air_traffic_frontend:8501
  - hostname: parts.sielain.com
    service: http://parts-app:8000
  - service: http_status:404        # catch-all은 반드시 마지막

공공기관 원본 엑셀은 사람이 보기 좋은 양식(병합 셀, 합계 행)이라 그대로 DB에 넣을 수 없습니다. ETL이 하는 일과, "누적"이 어떻게 구현되는지를 봅니다.

# FastAPI 업로드 엔드포인트의 골격
@router.post("/upload/traffic")
def upload_traffic(period: str = Form(...), file: UploadFile = File(...)):
    # 1) 검증: YYYY-MM 형식, .xlsx 확장자
    # 2) 원본을 /data/uploads/ 에 보관 (재현 가능성)
    # 3) openpyxl로 '1호선 ' 시트 파싱 → {역명: {승차:[20], 하차:[20]}}
    # 4) 같은 period_label 레코드만 DELETE → INSERT  ← "월 단위 교체"의 핵심
    db.query(TrafficHourly).filter(
        TrafficHourly.period_label == period).delete()
    # 5) commit → 이후 모든 탭이 즉시 새 데이터 사용

UniqueConstraint("station_id", "direction",
                 "hour_index", "period_label")

탭5의 리포트는 그럴듯한 서술문이지만 언어 모델을 전혀 쓰지 않습니다. SQL/파이썬 집계값을 고정 템플릿 문자열에 대입할 뿐이라, 같은 데이터면 항상 같은 문장이 나오고 환각(hallucination)이 원천적으로 불가능합니다.

# 집계 (사실)
overall_avg = 28.8   # 전체 PM2.5 평균
top = {"station": "박촌", "avg": 47.9}

# 템플릿 (형식) — f-string에 값을 끼워 넣을 뿐
f"PM2.5 전체 평균은 {overall_avg}㎍/㎥이며, 역별 평균이 가장 높은 곳은 "
f"{top['station']}({top['avg']}㎍/㎥)입니다."