모든 것을 하나로 — Docker 패키징부터 클라우드 배포까지 완전 정복 [2026 실전 튜토리얼]

[Docker 없이]
개발자 Mac → "잘 돼요!"
CI 서버    → "패키지 없음 오류"
프로덕션   → "Python 버전 다름"
팀원 PC    → "의존성 충돌"
[Docker 있으면]
어디서 실행해도 → 동일한 결과 ✅

┌─────────────────────────────────────────────────────┐
│                   클라이언트 (브라우저/앱)               │
└──────────────────────────┬──────────────────────────┘
                           │ HTTPS
┌──────────────────────────▼──────────────────────────┐
│              Railway 클라우드 플랫폼                    │
│  ┌───────────────────────────────────────────────┐  │
│  │           FastAPI 컨테이너 (포트 8000)           │  │
│  │  ┌─────────────┐  ┌──────────────────────┐    │  │
│  │  │  RAG 파이프라인│  │ LangGraph 에이전트 팀 │    │  │
│  │  │  (2편)       │  │ + 메모리 (3~4편)     │    │  │
│  │  └──────┬──────┘  └──────────┬───────────┘    │  │
│  └─────────┼───────────────────┼────────────────┘  │
│            │                   │                    │
│  ┌─────────▼───────────────────▼────────────────┐  │
│  │        PostgreSQL 컨테이너 (체크포인터 + 벡터DB)  │  │
│  └──────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

ai-service/
├── .env                      # 로컬 개발용 (절대 커밋 금지!)
├── .env.example              # 팀원 공유용 예시 파일
├── .gitignore
├── Dockerfile                # 프로덕션 이미지 정의
├── docker-compose.yml        # 로컬 전체 스택 실행
├── requirements.txt
├── app/
│   ├── main.py               # FastAPI 진입점
│   ├── rag_pipeline.py       # 2편: RAG 로직
│   ├── agents/
│   │   ├── state.py          # 3편: 공유 상태
│   │   ├── agents.py         # 3편: 에이전트 3개
│   │   ├── supervisor.py     # 3편: 슈퍼바이저
│   │   └── graph.py          # 3편: 그래프 조립
│   └── memory/
│       └── checkpointer.py   # 4편: PostgreSQL 체크포인터
├── .github/
│   └── workflows/
│       └── deploy.yml        # CI/CD 파이프라인
└── scripts/
    └── healthcheck.sh        # 헬스체크 스크립트

# Dockerfile
# ─────────────────────────────────────
# Stage 1: 빌더 (빌드 도구 포함)
# ─────────────────────────────────────
FROM python:3.12-slim AS builder
# Python 최적화 환경변수
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1
WORKDIR /build
# 빌드 도구 설치 (최종 이미지에는 포함 안 됨)
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    gcc \
    && rm -rf /var/lib/apt/lists/*
# 가상환경 생성 & 의존성 설치
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --upgrade pip && \
    pip install -r requirements.txt
# ─────────────────────────────────────
# Stage 2: 프로덕션 (빌드 도구 제외)
# ─────────────────────────────────────
FROM python:3.12-slim AS production
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PATH="/opt/venv/bin:$PATH"
# 빌더에서 가상환경만 복사 (빌드 도구는 제외)
COPY --from=builder /opt/venv /opt/venv
# 보안: root가 아닌 전용 사용자로 실행
RUN useradd --create-home --shell /bin/bash appuser
WORKDIR /home/appuser/app
# 앱 코드 복사
COPY --chown=appuser:appuser app/ .
USER appuser
EXPOSE 8000
# 프로덕션 서버: gunicorn + uvicorn workers
CMD ["gunicorn", "main:app", \
     "--worker-class", "uvicorn.workers.UvicornWorker", \
     "--workers", "2", \
     "--bind", "0.0.0.0:8000", \
     "--timeout", "120", \
     "--access-logfile", "-"]

# docker-compose.yml
version: "3.9"
services:
  # ── 메인 앱 ─────────────────────────────────
  app:
    build:
      context: .
      target: production        # Dockerfile의 production 스테이지 사용
    ports:
      - "8000:8000"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - DATABASE_URL=postgresql://aiuser:aipass@db:5432/aidb
      - ENVIRONMENT=development
    depends_on:
      db:
        condition: service_healthy  # DB 준비될 때까지 대기
    volumes:
      - ./app:/home/appuser/app     # 개발 중 코드 변경 즉시 반영
      - uploads_data:/home/appuser/app/uploads
    restart: unless-stopped
  # ── PostgreSQL DB ────────────────────────────
  db:
    image: pgvector/pgvector:pg16  # pgvector 확장 포함 버전
    environment:
      POSTGRES_USER: aiuser
      POSTGRES_PASSWORD: aipass
      POSTGRES_DB: aidb
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U aiuser -d aidb"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped
volumes:
  postgres_data:
  uploads_data:

# 전체 스택 시작 (백그라운드)
docker-compose up -d
# 로그 확인
docker-compose logs -f app
# 종료
docker-compose down
# 완전 초기화 (볼륨까지 삭제)
docker-compose down -v

# .env.example — 팀원 공유용 (실제 값 없이 키 이름만)
ANTHROPIC_API_KEY=your-api-key-here
DATABASE_URL=postgresql://user:password@localhost:5432/aidb
ENVIRONMENT=development
SECRET_KEY=generate-a-random-32-char-string

# .gitignore — 반드시 포함
.env
.env.local
*.db
uploads/
vector_store/
__pycache__/
*.pyc
.DS_Store

# app/config.py — 설정 중앙 관리
from pydantic_settings import BaseSettings
from functools import lru_cache
class Settings(BaseSettings):
    # 필수 설정 (없으면 앱 시작 안 됨)
    anthropic_api_key: str
    database_url: str
    # 선택 설정 (기본값 있음)
    environment: str = "production"
    secret_key: str = "change-this-in-production"
    max_upload_size_mb: int = 10
    max_conversation_turns: int = 50
    class Config:
        env_file = ".env"
        case_sensitive = False
@lru_cache()  # 한 번만 로드, 이후 캐시 사용
def get_settings() -> Settings:
    return Settings()
# 사용법:
# from config import get_settings
# settings = get_settings()
# settings.anthropic_api_key

# .github/workflows/deploy.yml
name: Deploy AI Service
on:
  push:
    branches: [main]           # main 브랜치 push 시 실행
  pull_request:
    branches: [main]           # PR 시 테스트만 실행
jobs:
  # ── 1단계: 테스트 ────────────────────────────
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: "pip"
      - name: Install dependencies
        run: pip install -r requirements.txt pytest httpx
      - name: Run tests
        run: pytest app/tests/ -v --tb=short
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          DATABASE_URL: "sqlite:///./test.db"
  # ── 2단계: Docker 빌드 & 푸시 ──────────────────
  build:
    needs: test                 # 테스트 통과 후에만 실행
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Build Docker image
        run: docker build --target production -t ai-service:${{ github.sha }} .
      - name: Verify image starts
        run: |
          docker run --rm -d --name test-container \
            -e ANTHROPIC_API_KEY=dummy \
            -e DATABASE_URL=dummy \
            -p 8000:8000 \
            ai-service:${{ github.sha }}
          sleep 5
          curl -f http://localhost:8000/health || exit 1
          docker stop test-container
  # ── 3단계: Railway 배포 ──────────────────────
  deploy:
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Install Railway CLI
        run: npm install -g @railway/cli
      - name: Deploy to Railway
        run: railway up --service ai-service
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

# 1. Railway CLI 설치
npm install -g @railway/cli
# 2. 로그인
railway login
# 3. 새 프로젝트 생성
railway init
# 4. PostgreSQL 서비스 추가
railway add --plugin postgresql
# 5. 환경변수 설정 (한 번에 여러 개)
railway variables set \
  ANTHROPIC_API_KEY=your-key \
  ENVIRONMENT=production \
  SECRET_KEY=$(openssl rand -hex 32)
# 6. 배포!
railway up

# 배포된 URL 확인
railway open
# 실시간 로그 보기
railway logs --tail
# 환경변수 목록 확인
railway variables

# app/main.py에 추가
from fastapi import FastAPI
from datetime import datetime
import os
app = FastAPI()
@app.get("/health")
async def health_check():
    """
    로드밸런서, Railway, 모니터링 도구가 이 엔드포인트를 주기적으로 호출합니다.
    200 응답 = 정상, 5xx = 비정상 → 자동 재시작
    """
    return {
        "status": "healthy",
        "timestamp": datetime.utcnow().isoformat(),
        "environment": os.getenv("ENVIRONMENT", "unknown"),
        "version": "1.0.0"
    }
@app.get("/health/detailed")
async def detailed_health():
    """DB 연결까지 확인하는 상세 헬스체크"""
    checks = {}
    # DB 연결 확인
    try:
        from memory.checkpointer import get_db_connection
        conn = get_db_connection()
        conn.close()
        checks["database"] = "ok"
    except Exception as e:
        checks["database"] = f"error: {str(e)}"
    # 전체 상태 판단
    all_ok = all(v == "ok" for v in checks.values())
    status_code = 200 if all_ok else 503
    return JSONResponse(
        content={"status": "healthy" if all_ok else "degraded", "checks": checks},
        status_code=status_code
    )