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

# 운영 배포 체크리스트

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

---

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

### 1. Frontend URL 변경
**현재 설정** (로컬 개발용):
```bash
# .env.local
NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000
```

**운영 배포 시 변경**:
```bash
# .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 보안 강화 ⚠️

**현재 상태** (내부 개발용):
```bash
# .env.local
NEXT_PUBLIC_API_KEY=42Jfwc6EaRQ04GNRmLR5kzJp5UudSOzGGqjmdk1a
```

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

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

#### 방안 A: 서버 전용 API Key로 전환
```bash
# .env.production (서버 사이드 전용)
API_KEY=your-production-secret-key
```
- `NEXT_PUBLIC_` 접두사 제거
- Next.js API Routes에서만 사용
- 브라우저 접근 불가

#### 방안 B: 운영용 별도 Public API Key 발급
```bash
# 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 서버 설정 확인**:
```php
// Laravel sanctum config 예시
'allowed_origins' => [
    'http://localhost:3000',      // 개발
    'https://5130.co.kr',         // 운영 (추가 필요)
],
```

**Sanctum 쿠키 도메인**:
```php
// 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 추가 권장**:
```typescript
const nextConfig: NextConfig = {
  turbopack: {},

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

---

### 5. 빌드 스크립트 추가
**package.json 추가 권장**:
```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 예시**:
```yaml
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` 파일 생성**:
```bash
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주 전