Environment Health Checker

Environment Health Checker

당신이 Laravel 환경 설정, 캐시, 또는 데이터베이스 연결 문제를 진단해야 할 때 이 Skill을 사용하세요.

🎯 자동 실행 트리거

다음 상황에서 자동으로 실행:

• 사용자가 "설정이 반영 안돼" 또는 "configuration not applied" 언급
• "Database connection error" 또는 "SQLite connection attempt" 오류
• "Database hosts array is empty" 오류
• ".env 파일 수정했는데 변화 없음"
• "왜 Laravel이 [잘못된 DB]로 연결하려고 해?"

📋 진단 체크리스트

1. 현재 환경 상태 확인

# 현재 환경 정보 수집
php artisan tinker --execute="
echo 'APP_ENV: ' . config('app.env') . PHP_EOL;
echo 'APP_DEBUG: ' . (config('app.debug') ? 'true' : 'false') . PHP_EOL;
echo 'DB_CONNECTION: ' . config('database.default') . PHP_EOL;
echo 'DB_DATABASE: ' . DB::connection()->getDatabaseName() . PHP_EOL;
echo 'SESSION_DRIVER: ' . config('session.driver') . PHP_EOL;
echo 'CACHE_STORE: ' . config('cache.default') . PHP_EOL;
echo 'QUEUE_CONNECTION: ' . config('queue.default') . PHP_EOL;
"

기대값 (로컬 개발 환경):

• APP_ENV: local
• DB_CONNECTION: pgsql_local
• DB_DATABASE: ykp_dashboard_local
• SESSION_DRIVER: file
• CACHE_STORE: file
• QUEUE_CONNECTION: sync

2. .env 파일 검증

# .env 파일 읽기 (중요 변수만)
grep -E "^(APP_ENV|DB_CONNECTION|DB_HOST_LOCAL|DB_DATABASE_LOCAL|SESSION_DRIVER|CACHE_STORE|QUEUE_CONNECTION)=" .env

검증 항목:

• ✅ APP_ENV=local (프로덕션 아님)
• ✅ DB_CONNECTION=pgsql_local (로컬 PostgreSQL)
• ✅ SESSION_DRIVER=file (database 아님)
• ✅ CACHE_STORE=file (database 아님)
• ✅ QUEUE_CONNECTION=sync (database 아님)

3. 캐시 상태 진단

# 캐시된 설정 파일 존재 여부 확인
ls -la bootstrap/​cache/​*.php 2>/​dev/​null | grep -E "(config|routes|services)"

문제 감지:

• config.php 존재 → 캐시된 설정 사용 중 → .env 변경 무시됨!
• routes.php 존재 → 라우트 캐시 사용 중
• services.php 존재 → 서비스 캐시 사용 중

4. 데이터베이스 연결 테스트

# 실제 DB 연결 테스트
php artisan tinker --execute="
try {
    \$count = DB::table('users')->count();
    echo 'DB 연결 성공! Users: ' . \$count . PHP_EOL;
} catch (Exception \$e) {
    echo 'DB 연결 실패: ' . \$e->getMessage() . PHP_EOL;
}
"

🔧 자동 해결 절차

문제 1: 캐시 문제 (가장 흔함!)

증상: .env 변경했는데 반영 안됨, 구 설정 사용 중

해결:

# 모든 캐시 클리어
php artisan optimize:clear

# 개별 캐시 클리어 (필요 시)
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear

사용자에게 안내:

✅ 캐시 클리어 완료!

Laravel이 캐시된 설정을 사용하고 있었습니다. 다음 명령어로 모든 캐시를 삭제했습니다:

php artisan optimize:clear

다음 단계: 서버를 재시작하세요:

# 기존 서버 종료 (Ctrl+C)
# 새로 시작
php artisan serve

문제 2: 잘못된 DB 연결

증상: "SQLite connection attempt", "pgsql 대신 sqlite 사용", "Supabase 대신 로컬 DB 사용"

해결:

1. .env 파일에서 DB_CONNECTION 확인
2. 올바른 값으로 수정 제안:
   • 로컬: DB_CONNECTION=pgsql_local
   • 프로덕션: DB_CONNECTION=pgsql

사용자에게 안내:

⚠️ 잘못된 DB 연결 감지!

현재 설정: DB_CONNECTION=sqlite (또는 잘못된 값) 로컬 개발용 권장 설정:

DB_CONNECTION=pgsql_local
DB_HOST_LOCAL=localhost
DB_DATABASE_LOCAL=ykp_dashboard_local

.env 파일을 수정한 후 캐시를 클리어하세요:

php artisan optimize:clear

문제 3: Session/​Cache 드라이버 문제

증상: "Database hosts array is empty" (session/​cache가 DB 사용하려 함)

해결: .env 파일에서 다음 값 확인:

SESSION_DRIVER=file  # database 아님!
CACHE_STORE=file     # database 아님!
QUEUE_CONNECTION=sync # database 아님!

사용자에게 안내:

⚠️ Session/​Cache 드라이버 문제!

로컬 개발 환경에서는 파일 기반 드라이버를 사용하세요:

SESSION_DRIVER=file
CACHE_STORE=file
QUEUE_CONNECTION=sync

왜? 더 빠르고, DB 연결 문제 없고, 디버깅 쉬움!

.env 수정 후:

php artisan optimize:clear

문제 4: 서버 재시작 필요

증상: 캐시 클리어했는데도 변화 없음

해결:

# Windows에서 PHP 서버 프로세스 종료
taskkill /​F /​IM php.exe

# 또는 Ctrl+C로 종료 후 재시작
php artisan serve

사용자에게 안내:

🔄 서버 재시작 필요!

캐시를 클리어했지만, 실행 중인 PHP 서버가 이전 설정을 메모리에 유지하고 있을 수 있습니다.

해결: 서버 재시작

# 현재 서버 종료 (Ctrl+C)
# 새로 시작
php artisan serve

📊 최종 보고서 형식

진단 완료 후 다음 형식으로 보고:

🏥 환경 건강 진단 완료

✅ 정상 항목:
- APP_ENV: local
- DB_DATABASE: ykp_dashboard_local

⚠️ 문제 발견:
1. 캐시 문제: config.php 파일 존재 (캐시된 설정 사용 중)
   → 해결: php artisan optimize:clear 실행 완료

2. Session 드라이버 문제: SESSION_DRIVER=database
   → 권장: SESSION_DRIVER=file (로컬 개발용)

📋 권장 조치:
1. .env 파일에서 SESSION_DRIVER=file 설정
2. 서버 재시작: Ctrl+C 후 php artisan serve

💡 참고: CLAUDE.md "Environment Configuration" 섹션 참조

🚨 프로덕션 환경 감지 시

만약 APP_ENV=production 감지 시:

🚨 경고: 프로덕션 환경 감지!

현재 설정:
- APP_ENV: production
- DB_CONNECTION: pgsql (Supabase로 추정)

⚠️ 로컬 개발 중이라면 즉시 수정 필요:

.env 파일:
APP_ENV=local
DB_CONNECTION=pgsql_local

⚠️ 실제 프로덕션(Railway)이라면:
- Railway 환경변수에서 관리 (파일 수정 금지)
- DB 백업 확인 후 작업 진행

🎓 학습 포인트

이 Skill이 발견한 문제는 다음과 같이 요약:

1. Laravel 캐시 메커니즘: php artisan config:cache 실행 시 .env 무시됨
2. 환경 파일 로딩 순서: .env.local은 production 모드에서 로드 안됨
3. 파일 vs DB 드라이버: 로컬 개발은 파일 드라이버가 빠르고 안정적

다음에 비슷한 문제 발생 시:

1. 먼저 캐시 클리어: php artisan optimize:clear
2. 서버 재시작
3. 그래도 안되면 .env 파일 확인