설정 검증기 (Configuration Validator)
설정 파일과 환경 변수의 유효성을 검증하여 런타임 오류와 누락된 설정을 방지합니다.
사용 시기
- 환경 변수나 설정 파일을 다룰 때
- 배포 또는 설정 문제가 발생했을 때
- 사용자가 ".env", "config", "environment variables", "settings" 등을 언급할 때
지침
1. 설정 파일 찾기
다음 파일들을 검색하세요:
.env,.env.example,.env.localconfig/,config.js,config.jsonsettings.py,application.ymlappsettings.json,.env.production
2. 누락된 변수 감지
.env.example와 .env 비교:
# 예제에는 있지만 .env에는 없는 변수
comm -23 <(grep -o '^[A-Z_]*' .env.example | sort) <(grep -o '^[A-Z_]*' .env | sort)
일반적인 필수 변수:
DATABASE_URL
API_KEY
SECRET_KEY
NODE_ENV
PORT
3. 변수 형식 검증
일반적인 문제 확인:
// 공백이 있는 값에 따옴표 누락
DATABASE_URL=postgres://localhost/db name // 나쁨
DATABASE_URL="postgres://localhost/db name" // 좋음
// 프로토콜 누락
API_URL=example.com // 나쁨
API_URL=https://example.com // 좋음
// 문자열로 해석될 불리언
DEBUG=true // 문자열로 해석될 수 있음
DEBUG=1 // 더 명확함
4. 런타임에 필수 변수 검증
Node.js 예제:
const requiredEnvVars = [
'DATABASE_URL',
'API_KEY',
'JWT_SECRET'
];
const missing = requiredEnvVars.filter(v => !process.env[v]);
if (missing.length > 0) {
throw new Error(`Missing required env vars: ${missing.join(', ')}`);
}
Python 예제:
import os
REQUIRED_ENV_VARS = [
'DATABASE_URL',
'SECRET_KEY',
'ALLOWED_HOSTS'
]
missing = [var for var in REQUIRED_ENV_VARS if not os.getenv(var)]
if missing:
raise EnvironmentError(f"Missing env vars: {', '.join(missing)}")
5. 타입 검증
타입 검증:
const config = {
port: parseInt(process.env.PORT || '3000', 10),
debug: process.env.DEBUG === 'true',
apiUrl: new URL(process.env.API_URL), // 유효하지 않으면 오류 발생
maxConnections: Number(process.env.MAX_CONNECTIONS),
};
// 검증
if (isNaN(config.port) || config.port < 1 || config.port > 65535) {
throw new Error('PORT must be a valid port number');
}
6. .env.example 생성
실제 .env에서 템플릿 생성:
# 값 제거, 키는 유지
sed 's/=.*/=/' .env > .env.example
또는 자리 표시자 사용:
DATABASE_URL=postgres://user:password@localhost:5432/dbname
API_KEY=your_api_key_here
SECRET_KEY=generate_random_secret
PORT=3000
NODE_ENV=development
7. 설정 스키마
스키마 정의 (Joi 예제):
const Joi = require('joi');
const envSchema = Joi.object({
NODE_ENV: Joi.string()
.valid('development', 'production', 'test')
.required(),
PORT: Joi.number()
.port()
.default(3000),
DATABASE_URL: Joi.string()
.uri()
.required(),
API_KEY: Joi.string()
.min(32)
.required(),
DEBUG: Joi.boolean()
.default(false),
}).unknown();
const { error, value } = envSchema.validate(process.env);
if (error) {
throw new Error(`Config validation error: ${error.message}`);
}
module.exports = value;
8. 보안 검사
시크릿을 커밋하지 마세요:
# .env가 gitignore에 있는지 확인
if ! grep -q "^\.env$" .gitignore; then
echo "Warning: .env not in .gitignore"
fi
# 코드 내 하드코딩된 시크릿 확인
grep -r "api_key.*=.*['\"]" --exclude-dir=node_modules
일반적인 보안 문제:
- 하드코딩된 비밀번호/키
- 프로덕션에서 기본 시크릿 사용
- 민감한 설정 노출
- 암호화되지 않은 시크릿
9. 환경별 설정
환경별로 구성:
.env.development
.env.staging
.env.production
.env.test
적절히 로드:
require('dotenv').config({
path: `.env.${process.env.NODE_ENV || 'development'}`
});
10. 모든 변수 문서화
CONFIG.md 생성:
# 설정 (Configuration)
## 환경 변수
### 필수
- `DATABASE_URL`: PostgreSQL 연결 문자열
- 형식: `postgres://user:pass@host:port/db`
- 예제: `postgres://app:secret@localhost:5432/myapp`
- `API_KEY`: 서드파티 API 키
- 획득처: https://dashboard.example.com
- 필요한 권한: read, write
### 선택 사항
- `PORT`: 서버 포트 (기본값: 3000)
- `DEBUG`: 디버그 로깅 활성화 (기본값: false)
- `MAX_CONNECTIONS`: 데이터베이스 풀 크기 (기본값: 10)
## 설정 방법
1. `.env.example`을 `.env`로 복사
2. 모든 필수 값 입력
3. `npm run validate-config` 실행하여 확인
11. 검증 스크립트
scripts/validate-config.js 생성:
const fs = require('fs');
function validateConfig() {
const required = ['DATABASE_URL', 'API_KEY'];
const missing = required.filter(v => !process.env[v]);
if (missing.length > 0) {
console.error(`❌ Missing: ${missing.join(', ')}`);
process.exit(1);
}
console.log('✓ All required config variables present');
}
validateConfig();
12. 모범 사례
- 절대 .env를 커밋하지 마세요: 항상 gitignore에 추가
- .env.example 유지 관리: 계속 업데이트
- 시작 시 검증: 잘못 설정되면 빠르게 실패
- 강력한 기본값 사용: 합리적인 대체값 사용
- 모든 항목 문서화: 각 변수 설명
- 시크릿 교체: 키를 정기적으로 업데이트
- 시크릿 관리자 사용: 프로덕션에서는 Vault, AWS Secrets Manager 사용
- 타입 검사: 존재 여부뿐만 아니라 타입도 검증
지원 파일
templates/config-validator.jstemplates/.env.examplescripts/generate-env-example.sh