--- name: env-manager description: | 트리거: "환경변수 관리", "env 정리해줘", ".env 만들어줘", "환경변수 설정", "env 파일 생성", "시크릿 관리", "secrets manager", "vault", "doppler", "환경변수 검증", "env diff" 수행: .env, .env.example, 환경변수 문서 일관 관리. 타입 검증 스크립트(Zod/pydantic), 시크릿 관리 도구 연동, Git hooks로 .env 커밋 방지, 환경별 diff 비교까지 포함한다. 출력: .env.example, 검증 스크립트(TS/Python), .gitignore, pre-commit hook, 시크릿 관리 가이드 --- # Environment Variable Manager ## 목적 프로젝트의 환경변수를 체계적으로 관리한다. `.env.example`을 단일 진실 원천으로 유지하고, 환경별 파일 분리, 런타임 타입 검증, Git hook 기반 누출 방지, 시크릿 관리 도구 연동까지 제공한다. --- ## 실행 절차 1. **환경변수 목록 수집**: 코드베이스에서 `process.env.*` / `os.environ` / `getenv` 패턴 스캔 2. **카테고리 분류**: 앱 설정 / 데이터베이스 / 외부 API / 인증 / 인프라 그룹화 3. **민감도 분류**: PUBLIC (빌드 타임 노출 가능) / SECRET (런타임 전용) 구분 4. **`.env.example` 생성**: 주석 포함, 실제 값 없이 예시/설명만 기재 5. **환경별 `.env` 템플릿 생성**: development / staging / production 분리 6. **검증 스크립트 생성**: 앱 시작 전 필수 변수 존재 여부 + 타입 검사 7. **`.gitignore` 및 Git hook 설정**: `.env*` 커밋 방지 자동화 8. **시크릿 관리 도구 연동 가이드 제공** (필요 시) --- ## 출력 형식 ### .env.example ```bash # .env.example # ============================================================ # 이 파일을 .env.local (개발) 또는 .env (프로덕션)으로 복사하세요. # 실제 비밀값은 절대 이 파일에 커밋하지 마세요. # 마지막 업데이트: 2024-01-15 | 담당: @devteam # ============================================================ # ────────────────────────────────────────────────────────────── # 앱 기본 설정 # ────────────────────────────────────────────────────────────── NODE_ENV=development # development | staging | production APP_NAME=MyApp # 앱 이름 (로그, 이메일 제목 등에 사용) APP_URL=http://localhost:3000 # 외부 접근 URL (트레일링 슬래시 없음) APP_PORT=3000 # 서버 리스닝 포트 LOG_LEVEL=debug # error | warn | info | debug | trace # ────────────────────────────────────────────────────────────── # 데이터베이스 (PostgreSQL) # ────────────────────────────────────────────────────────────── DATABASE_URL=postgresql://user:password@localhost:5432/myapp_dev DATABASE_POOL_MIN=2 DATABASE_POOL_MAX=10 DATABASE_POOL_IDLE_TIMEOUT=30000 # ────────────────────────────────────────────────────────────── # Redis (캐시 / 세션) # ────────────────────────────────────────────────────────────── REDIS_URL=redis://localhost:6379 # REDIS_PASSWORD= # [SECRET] 프로덕션에서 필수 REDIS_TLS=false # 프로덕션에서는 true # ────────────────────────────────────────────────────────────── # 인증 / 보안 # ────────────────────────────────────────────────────────────── JWT_SECRET= # [SECRET] 최소 32자 랜덤 문자열 필수 JWT_EXPIRES_IN=7d SESSION_SECRET= # [SECRET] 최소 32자 랜덤 문자열 필수 BCRYPT_ROUNDS=12 ALLOWED_ORIGINS=http://localhost:3000 # CORS 허용 출처 (쉼표 구분) # ────────────────────────────────────────────────────────────── # 외부 서비스 # ────────────────────────────────────────────────────────────── STRIPE_PUBLIC_KEY=pk_test_ # [PUBLIC] 클라이언트 노출 가능 STRIPE_SECRET_KEY=sk_test_ # [SECRET] 서버 전용 STRIPE_WEBHOOK_SECRET=whsec_ # [SECRET] GOOGLE_CLIENT_ID= # [PUBLIC] GOOGLE_CLIENT_SECRET= # [SECRET] SENTRY_DSN= # 오류 추적 ``` --- ### 환경변수 검증 스크립트 #### TypeScript — Zod 기반 ```ts // src/lib/env.ts import { z } from 'zod'; const envSchema = z.object({ NODE_ENV: z.enum(['development', 'staging', 'production']).default('development'), APP_URL: z.string().url(), APP_PORT: z.coerce.number().int().min(1).max(65535).default(3000), LOG_LEVEL: z.enum(['error', 'warn', 'info', 'debug', 'trace']).default('info'), DATABASE_URL: z.string().min(1, 'DATABASE_URL is required'), DATABASE_POOL_MIN: z.coerce.number().default(2), DATABASE_POOL_MAX: z.coerce.number().default(10), REDIS_URL: z.string().default('redis://localhost:6379'), JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 characters'), JWT_EXPIRES_IN: z.string().default('7d'), SESSION_SECRET: z.string().min(32, 'SESSION_SECRET must be at least 32 characters'), BCRYPT_ROUNDS: z.coerce.number().min(10).max(14).default(12), STRIPE_SECRET_KEY: z.string().startsWith('sk_').optional(), GOOGLE_CLIENT_SECRET: z.string().optional(), SENTRY_DSN: z.string().url().optional(), }); function validateEnv() { const result = envSchema.safeParse(process.env); if (!result.success) { const errors = result.error.issues .map((issue) => ` - ${issue.path.join('.')}: ${issue.message}`) .join('\n'); console.error(`\n[ENV ERROR] 환경변수 검증 실패:\n${errors}\n`); process.exit(1); } return result.data; } export const env = validateEnv(); export type Env = typeof env; ``` #### Python — pydantic-settings 기반 ```python # src/config.py from pydantic import AnyHttpUrl, Field, SecretStr, field_validator from pydantic_settings import BaseSettings, SettingsConfigDict class Settings(BaseSettings): model_config = SettingsConfigDict( env_file='.env', env_file_encoding='utf-8', case_sensitive=True, ) APP_ENV: str = Field(default='development', pattern='^(development|staging|production)$') APP_URL: AnyHttpUrl = 'http://localhost:8000' APP_PORT: int = Field(default=8000, ge=1, le=65535) DATABASE_URL: str = Field(..., description='PostgreSQL connection string') REDIS_URL: str = 'redis://localhost:6379' JWT_SECRET: SecretStr = Field(..., min_length=32) JWT_EXPIRES_MINUTES: int = Field(default=10080) # 7일 STRIPE_SECRET_KEY: SecretStr | None = None SENTRY_DSN: AnyHttpUrl | None = None @field_validator('DATABASE_URL') @classmethod def validate_db_url(cls, v: str) -> str: if not v.startswith(('postgresql://', 'postgres://')): raise ValueError('DATABASE_URL must be a PostgreSQL URL') return v settings = Settings() ``` --- ### .gitignore 설정 ```gitignore # 환경변수 파일 (모든 .env 변형 제외) .env .env.local .env.development .env.development.local .env.staging .env.staging.local .env.production .env.production.local .env.*.local # .env.example은 커밋 대상 (실제 값 없음) !.env.example ``` --- ### Git Hook — .env 커밋 방지 ```bash # .git/hooks/pre-commit (또는 husky 설정) #!/bin/sh # .env 파일 커밋 방지 훅 FORBIDDEN_FILES=$(git diff --cached --name-only | grep -E '^\.env(\.[^e]|$)') if [ -n "$FORBIDDEN_FILES" ]; then echo "" echo "❌ [보안 경고] .env 파일을 커밋하려 했습니다:" echo "$FORBIDDEN_FILES" echo "" echo ".env 파일에는 실제 시크릿이 포함될 수 있습니다." echo "커밋을 중단합니다. .env.example만 커밋하세요." echo "" exit 1 fi ``` **husky 설정 (package.json):** ```json { "husky": { "hooks": { "pre-commit": "sh .git/hooks/pre-commit" } } } ``` **lint-staged와 통합 (`.husky/pre-commit`):** ```bash #!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh" # .env 커밋 방지 if git diff --cached --name-only | grep -qE '^\.env(\.[^e]|$)'; then echo "❌ .env 파일은 커밋할 수 없습니다. .env.example을 사용하세요." exit 1 fi npx lint-staged ``` --- ### 환경별 diff 비교 두 환경의 환경변수 키를 비교하여 누락된 변수를 탐지한다. ```bash #!/bin/bash # scripts/env-diff.sh # 사용법: ./scripts/env-diff.sh .env.example .env.production FILE_A=${1:-.env.example} FILE_B=${2:-.env.local} # 키만 추출 (값 제외, 주석 제외) keys_a=$(grep -E '^[A-Z_]+=?' "$FILE_A" | cut -d= -f1 | sort) keys_b=$(grep -E '^[A-Z_]+=?' "$FILE_B" | cut -d= -f1 | sort) echo "=== $FILE_A에 있지만 $FILE_B에 없는 키 (누락) ===" comm -23 <(echo "$keys_a") <(echo "$keys_b") echo "" echo "=== $FILE_B에 있지만 $FILE_A에 없는 키 (추가됨) ===" comm -13 <(echo "$keys_a") <(echo "$keys_b") echo "" echo "=== 빈 값인 필수 변수 ($FILE_B) ===" grep -E '^[A-Z_]+=$' "$FILE_B" | cut -d= -f1 ``` --- ### 시크릿 관리 도구 연동 가이드 #### AWS Secrets Manager ```bash # 시크릿 저장 aws secretsmanager create-secret \ --name "myapp/production/jwt-secret" \ --secret-string "$(openssl rand -hex 32)" # 앱에서 읽기 (Node.js) import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager"; const client = new SecretsManagerClient({ region: "ap-northeast-2" }); const response = await client.send(new GetSecretValueCommand({ SecretId: "myapp/production/jwt-secret", })); const secret = response.SecretString; ``` #### HashiCorp Vault ```bash # 시크릿 저장 vault kv put secret/myapp/production \ jwt_secret=$(openssl rand -hex 32) \ db_password=mypassword # 앱에서 읽기 vault kv get -field=jwt_secret secret/myapp/production ``` #### Doppler (권장 — 가장 간단) ```bash # CLI 설치 및 연동 brew install dopplerhq/cli/doppler doppler login doppler setup # 프로젝트 선택 # 환경변수 주입하여 실행 doppler run -- npm start doppler run -- python manage.py runserver # .env 파일로 내보내기 doppler secrets download --no-file --format env > .env.production ``` #### GitHub Actions Secrets 연동 ```yaml # .github/workflows/deploy.yml env: DATABASE_URL: ${{ secrets.DATABASE_URL }} JWT_SECRET: ${{ secrets.JWT_SECRET }} STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }} ``` --- ### 비밀 생성 명령어 ```bash # 32자 랜덤 시크릿 (JWT, Session 등) node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" python -c "import secrets; print(secrets.token_hex(32))" openssl rand -hex 32 # UUID 형식 node -e "console.log(require('crypto').randomUUID())" python -c "import uuid; print(uuid.uuid4())" ``` --- ### 배포 전 환경변수 보안 체크리스트 ```markdown ## 배포 전 체크리스트 ### 필수 확인 - [ ] .env 파일이 .gitignore에 포함 - [ ] pre-commit hook 또는 git-secrets 설치됨 - [ ] JWT_SECRET, SESSION_SECRET이 32자 이상 랜덤값 - [ ] 데이터베이스 비밀번호가 강력한 값으로 변경됨 - [ ] Stripe/결제 키가 라이브(live) 키로 교체됨 - [ ] BCRYPT_ROUNDS가 12 이상 - [ ] DB_SSL=true (프로덕션) - [ ] ALLOWED_ORIGINS에 실제 도메인만 포함 - [ ] LOG_LEVEL이 error 또는 warn (프로덕션) - [ ] NEXT_PUBLIC_* / VITE_* 변수에 시크릿 미포함 ### 시크릿 관리 도구 - [ ] AWS Secrets Manager / Vault / Doppler 중 하나 사용 - [ ] GitHub Actions Secrets에 프로덕션 값 등록됨 - [ ] 팀원 전원이 시크릿 접근 방법 공유됨 ``` --- ## 사용 예시 **입력:** > "Next.js + PostgreSQL + Redis + Stripe + Google OAuth 프로젝트 환경변수 파일 만들어줘." **출력:** - `.env.example` — 모든 변수 주석 포함 - `src/lib/env.ts` — Zod 검증 스키마 - `scripts/env-diff.sh` — 환경별 diff 스크립트 - `.git/hooks/pre-commit` — 커밋 방지 훅 - `.gitignore` 스니펫 - 보안 체크리스트 --- ## 주의사항 - `.env.example`에는 실제 비밀값 절대 포함 금지 — 형식/예시 값만 기재 - `[SECRET]` 주석으로 민감 변수 명시적 표시 - `NEXT_PUBLIC_*` / `VITE_*` 접두사 변수는 클라이언트 번들에 포함됨 — 시크릿 사용 금지 - `DATABASE_URL`은 개별 변수보다 단일 연결 문자열 선호 (ORM 호환성) - 프로덕션 환경에서는 반드시 AWS Secrets Manager / Vault / Doppler 중 하나를 사용한다 - `git-secrets` 또는 `truffleHog`를 CI 파이프라인에 추가하여 자동 탐지 권장