sam-react-prod/docs/[REF] production-deployment-checklist.md

운영 배포 체크리스트

문서 목적: 로컬/개발 환경에서 운영 환경으로 전환 시 필요한 변경사항 정리 작성일: 2025-11-07 상태: 내부 개발용 → 추후 운영 배포 시 참고

---

🔴 필수 변경 사항 (운영 배포 전 필수)

1. Frontend URL 변경

현재 설정 (로컬 개발용):

# .env.local
NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000

운영 배포 시 변경:

# .env.production 또는 배포 플랫폼 환경 변수
NEXT_PUBLIC_FRONTEND_URL=https://your-production-domain.com
# 예시: https://5130.co.kr

영향 범위:

• src/lib/api/auth/auth-config.ts:8 - CORS 설정
• 백엔드 PHP API의 CORS 허용 도메인 추가 필요

---

2. API Key 보안 강화 ⚠️

현재 상태 (내부 개발용):

# .env.local
NEXT_PUBLIC_API_KEY=42Jfwc6EaRQ04GNRmLR5kzJp5UudSOzGGqjmdk1a

보안 위험:

• NEXT_PUBLIC_ 접두사로 인해 브라우저에서 API Key 노출
• 개발자 도구 → Network/Console에서 키 확인 가능
• 클라이언트 측 JavaScript에서 접근 가능

운영 배포 시 해결 방안 (택 1):

방안 A: 서버 전용 API Key로 전환

# .env.production (서버 사이드 전용)
API_KEY=your-production-secret-key

• NEXT_PUBLIC_ 접두사 제거
• Next.js API Routes에서만 사용
• 브라우저 접근 불가

방안 B: 운영용 별도 Public API Key 발급

# PHP 백엔드 팀에 운영용 Public API Key 요청
NEXT_PUBLIC_API_KEY=production-public-safe-key

• 제한된 권한으로 발급 (읽기 전용 등)
• IP 화이트리스트 적용
• Rate Limiting 설정

코드 수정 필요 위치:

• src/lib/api/client.ts:40 - API Key 사용 로직
• .env.example:32 - 문서 불일치 해결

---

🟡 권장 변경 사항

3. 백엔드 CORS 설정

PHP API 서버 설정 확인:

// Laravel sanctum config 예시
'allowed_origins' => [
    'http://localhost:3000',      // 개발
    'https://5130.co.kr',         // 운영 (추가 필요)
],

Sanctum 쿠키 도메인:

// config/sanctum.php
'stateful' => explode(',', env(
    'SANCTUM_STATEFUL_DOMAINS',
    'localhost,localhost:3000,127.0.0.1,5130.co.kr'
)),

---

4. Next.js 운영 최적화

next.config.ts 추가 권장:

const nextConfig: NextConfig = {
  turbopack: {},

  // 운영 환경 추가 설정
  reactStrictMode: true,
  poweredByHeader: false,        // 보안: X-Powered-By 헤더 제거
  output: 'standalone',          // Docker 배포용
  compress: true,                // Gzip 압축
};

---

5. 빌드 스크립트 추가

package.json 추가 권장:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint",

    // 추가 권장
    "build:prod": "NODE_ENV=production next build",
    "type-check": "tsc --noEmit",
    "lint:fix": "eslint --fix"
  }
}

---

🟢 배포 플랫폼별 설정

Vercel 배포

프로젝트 설정 → Environment Variables:

NEXT_PUBLIC_API_URL=https://api.5130.co.kr
NEXT_PUBLIC_FRONTEND_URL=https://your-app.vercel.app
NEXT_PUBLIC_AUTH_MODE=sanctum
API_KEY=<서버 전용 키>

Docker 배포

docker-compose.yml 예시:

version: '3.8'
services:
  nextjs-app:
    build: .
    environment:
      - NEXT_PUBLIC_API_URL=https://api.5130.co.kr
      - NEXT_PUBLIC_FRONTEND_URL=https://your-domain.com
      - API_KEY=${API_KEY}
    ports:
      - "3000:3000"

전통적인 서버 배포

.env.production 파일 생성:

NEXT_PUBLIC_API_URL=https://api.5130.co.kr
NEXT_PUBLIC_FRONTEND_URL=https://your-domain.com
NEXT_PUBLIC_AUTH_MODE=sanctum
API_KEY=<서버 전용 키>

---

📋 최종 배포 체크리스트

환경 변수

• NEXT_PUBLIC_FRONTEND_URL → 운영 도메인으로 변경
• NEXT_PUBLIC_API_KEY → 보안 방안 적용 (서버 전용 또는 제한된 Public Key)
• NEXT_PUBLIC_AUTH_MODE → sanctum 또는 bearer 확인
• .env.local Git 커밋 안 됨 확인 (.gitignore:100)

백엔드 연동

• PHP API CORS 설정에 운영 도메인 추가
• Sanctum 쿠키 도메인 설정 확인
• 운영용 API Key 발급 (필요 시)
• API 엔드포인트 테스트 (https://api.5130.co.kr)

빌드 & 테스트

• npm run build 로컬 테스트
• npm run lint 통과 확인
• tsc --noEmit TypeScript 타입 체크
• 브라우저 콘솔 에러 없는지 확인

보안

• API Key 브라우저 노출 문제 해결
• HTTPS 사용 확인
• 민감 정보 환경 변수로 분리
• X-Powered-By 헤더 제거 (poweredByHeader: false)

성능

• 이미지 최적화 (Next.js Image 컴포넌트 사용)
• 번들 사이즈 확인 (npm run build 출력 확인)
• Gzip/Brotli 압축 활성화
• CDN 설정 (필요 시)

---

🔧 현재 상태 (2025-11-07)

개발 환경:

• ✅ API URL: https://api.5130.co.kr (운영 API 사용 중)
• ⚠️ Frontend URL: http://localhost:3000 (로컬)
• ⚠️ API Key: NEXT_PUBLIC_API_KEY (브라우저 노출)
• ✅ Auth Mode: sanctum (쿠키 기반 인증)

내부 개발용 사용 중:

• 현재는 개발/테스트 목적으로 API Key 노출 허용
• 운영 배포 시 반드시 위 체크리스트 검토 필요

---

📌 참고 문서

• claudedocs/api-key-management.md - API Key 관리 가이드
• claudedocs/authentication-design.md - 인증 시스템 설계
• claudedocs/authentication-implementation-guide.md - 구현 가이드
• .env.example - 환경 변수 템플릿

---

📞 배포 전 확인 담당

• API Key 발급: PHP 백엔드 팀
• CORS 설정: PHP 백엔드 팀
• 인프라 설정: DevOps 팀
• 보안 검토: 보안 담당자

---

마지막 업데이트: 2025-11-07 다음 검토 예정: 운영 배포 1주 전