← Lecture Note
M13실습30분 · ~10 슬라이드

배포 · 운영 · 확장

본인 도메인으로 production 배포

학습 목표

Vercel CLI 로 배포하고, 도메인·로그·게이트웨이·드레인까지 운영 체계를 세운다.

코드를 로컬에서 완벽하게 동작시켰다면, 이제 그것을 세상에 내보내야 합니다. M13은 Vercel CLI를 중심으로 배포 파이프라인 전체—환경 변수 동기, 커스텀 도메인, 로그 관측, AI Gateway 폴백, 드레인 연동—를 한 흐름으로 익히는 모듈입니다.

Vercel CLI 설치 및 프로젝트 연결

npm i -g vercel@latest
vercel login          # GitHub/GitLab OAuth 또는 이메일
vercel link           # 현재 디렉터리를 Vercel 프로젝트에 연결

vercel link를 실행하면 .vercel/project.json이 생성됩니다. 팀 프로젝트라면 --scope <team-slug> 옵션을 함께 넘기세요. 이 파일은 .gitignore에 추가하지 않아도 되지만, 민감 정보는 없으니 커밋해도 무방합니다.

환경 변수 동기: vercel env pull

Vercel 대시보드에 등록된 환경 변수를 로컬 .env.local로 내려받습니다.

vercel env pull .env.local

이 명령은 Development 환경의 변수를 가져옵니다. CI/CD에서 Preview·Production 변수가 필요하다면 --environment preview 또는 --environment production 플래그를 사용하세요.

중요: ANTHROPIC_API_KEY, OPENAI_API_KEY, ELEVENLABS_API_KEY 같은 시크릿은 반드시 Vercel 대시보드에서 Encrypted 타입으로 등록하고, .env.local은 .gitignore에 추가해 두세요. vercel env pull 결과물을 커밋하는 실수가 가장 흔한 보안 사고입니다.

강의의 callLLM() 통합 함수는 VERCEL_AI_GATEWAY_URL 같은 게이트웨이 엔드포인트도 환경 변수로 관리합니다.

// lib/llm.ts — callLLM() 핵심 발췌
export async function callLLM(
  model: string,        // "anthropic/claude-sonnet-4-5" | "openai/gpt-4o" 형식
  messages: CoreMessage[],
  options?: { temperature?: number }
) {
  const baseURL = process.env.VERCEL_AI_GATEWAY_URL;   // 게이트웨이 엔드포인트
  const apiKey  = process.env.AI_GATEWAY_TOKEN;

  const response = await fetch(`${baseURL}/${model}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      messages,
      temperature: options?.temperature ?? 0.7,
    }),
  });

  if (!response.ok) throw new Error(`LLM call failed: ${response.statusText}`);
  return response.json();
}

"provider/model" 문자열 한 줄만 바꾸면 Anthropic ↔ OpenAI를 전환할 수 있는 구조입니다.

Production 배포: vercel --prod

vercel --prod

Git을 통한 자동 배포(Vercel ↔ GitHub 연동)도 가능하지만, 첫 실습에서는 CLI 흐름을 직접 체험하는 것이 좋습니다. 배포 URL은 https://<project>.vercel.app 형식으로 즉시 발급됩니다.

Preview 배포(vercel 명령만 실행)는 PR 단위 검토에, --prod는 실제 트래픽에 붙는 슬롯입니다. 두 환경의 환경 변수가 다를 수 있으므로 대시보드에서 반드시 확인하세요.

커스텀 도메인 연결

대시보드 Settings → Domains에서 도메인을 추가하면 Vercel이 CNAME/A 레코드를 안내합니다. DNS TTL이 전파될 때까지(보통 수 분~1시간) 기다린 뒤 vercel domains inspect <yourdomain.com>으로 상태를 확인합니다.

레코드 타입호스트값
CNAMEwwwcname.vercel-dns.com
A@76.76.21.21

HTTPS 인증서는 Vercel이 자동으로 발급·갱신합니다. 별도 설정은 불필요합니다.

Functions Logs와 AI Gateway 관측

배포 후 런타임 오류나 LLM 응답을 추적하려면 Functions Logs를 활용합니다.

vercel logs <deployment-url> --follow

AI Gateway를 경유한 요청은 대시보드 AI Gateway → Observability 탭에서 모델별 토큰 사용량, 레이턴시, 오류율을 확인할 수 있습니다. Fallback 설정은 대시보드 또는 vercel.json에서 지정합니다.

// vercel.json — AI Gateway fallback 예시
{
  "aiGateway": {
    "routes": [
      {
        "path": "anthropic/claude-sonnet-4-5",
        "fallback": ["openai/gpt-4o"]
      }
    ]
  }
}

Claude가 429(Rate Limit)나 5xx를 반환하면 자동으로 GPT-4o로 폴백됩니다. callLLM()은 동일 인터페이스이므로 애플리케이션 코드 변경 없이 이 혜택을 누립니다.

Drains: Sentry / Datadog 연동

Vercel Log Drains는 Functions·Edge의 모든 로그를 외부 서비스로 스트리밍합니다.

  • Sentry: 대시보드 Integrations → Sentry 설치 후 SENTRY_DSN 환경 변수 등록. 오류는 자동으로 이슈화됩니다.
  • Datadog: Integrations → Datadog 설치 또는 HTTP Drain(Endpoint URL + API Key)으로 수동 연결.

Log Drain은 Settings → Log Drains에서 추가하며, JSON 또는 NDJSON 포맷을 선택할 수 있습니다.

실습 (Lab)

이 Lab의 목표는 본인 도메인으로 AI Agent 서비스를 Production 배포하고, URL과 화면을 팀에 공유하는 것입니다.

Step 1. CLI 설치 및 프로젝트 연결

npm i -g vercel@latest && vercel login && vercel link

Step 2. 환경 변수 확인

vercel env pull .env.local
# ANTHROPIC_API_KEY, OPENAI_API_KEY, AI_GATEWAY_TOKEN 등 누락 없는지 확인

Step 3. Production 배포

vercel --prod
# 출력된 배포 URL을 메모

Step 4. 커스텀 도메인 연결

  • Vercel 대시보드 → Settings → Domains → 본인 도메인 입력
  • DNS 레코드를 도메인 레지스트라에 적용
  • vercel domains inspect <yourdomain.com>으로 연결 확인

Step 5. 로그 확인 및 AI Gateway 관측

vercel logs https://<yourdomain.com> --follow
  • 대시보드 AI Gateway 탭에서 토큰 사용량 스크린샷 촬영

Step 6. URL 공유 및 시연

  • Slack/채널에 https://<yourdomain.com> 공유
  • 에이전트 기능(RAG 질의, 음성 입력, 보고서 생성 중 택 1) 실시간 시연

시연 중 에러가 발생하면 vercel logs --follow를 열어두고 함께 디버깅하세요. 배포 환경에서만 재현되는 버그는 환경 변수 누락이 원인인 경우가 80%입니다.

핵심 정리

  • vercel link → vercel env pull → vercel --prod 세 단계가 기본 배포 흐름이다.
  • 시크릿은 Vercel 대시보드에 Encrypted로 등록하고 절대 커밋하지 않는다.
  • AI Gateway의 "provider/model" 라우팅과 Fallback 설정으로 callLLM()은 코드 변경 없이 멀티 모델 폴백을 지원한다.
  • Functions Logs(vercel logs --follow)와 AI Gateway Observability로 프로덕션 트래픽을 실시간 추적한다.
  • Log Drains(Sentry/Datadog)을 연결해 오류 알림과 장기 메트릭을 외부 관측 도구로 분리한다.
  • 운영 체크리스트: 환경 변수 암호화, Rate Limit 모니터링, 월별 AI 비용 상한선(Vercel Spend Management) 설정.
LAB · 실습

본인 도메인으로 production 배포 + URL 공유 + 시연