개발자 디버그 게이트 (is_dev_ip / DEBUG_ALLOWED_IPS)

운영에서 APP_DEBUG=false(상세 에러 비노출)를 안전하게 유지하면서, 허용된 개발자 IP에서만 상세 에러·디버그 출력을 보고 싶을 때 사용하는 Core 공통 기능입니다.

전역은 APP_DEBUG=false → 실제 사용자에게는 일반 에러 페이지(경로·설정 비노출).
허용 IP 요청에 한해 그 요청 동안만 app.debug=true → 개발자만 상세 스택트레이스 확인.
코드/Blade 어디서나 is_dev_ip() 로 "개발자 전용 분기" 작성 가능.

설정

허용 IP는 루트 .env 의 DEBUG_ALLOWED_IPS 에 둡니다(전 프로젝트 공통 적용).

# 쉼표구분: 단일 IP / CIDR / IPv6 모두 지원. 비우면 비활성(안전 기본값).
DEBUG_ALLOWED_IPS=203.0.113.5,10.0.0.0/8

값	의미
비어 있음	비활성 — 동작 변화 없음(기본값)
`203.0.113.5`	단일 IP
`203.0.113.0/24`	CIDR 대역
여러 개(쉼표)	개발 IP가 바뀌거나 여러 명일 때 복수 등록

.env 변경 후에는 컨테이너 재시작이 필요합니다(env_file 은 시작 시 로드).

동작 원리

Core DebugGate 미들웨어가 web 그룹 최우선으로 실행되어, 요청 IP가 허용 목록이면 app.debug=true 로 승격합니다.
요청 IP는 리버스 프록시 뒤에서도 실제 방문자 IP(trustProxies/real_ip 복원값)로 판정되므로, CDN/프록시 뒤에서도 개발자 IP가 정확히 매칭됩니다.

`is_dev_ip()` 헬퍼

// 현재 요청 IP가 허용 개발자 IP인지
if (is_dev_ip()) {
    logger()->debug('dev-only detail', ['payload' => $payload]);
}

// 특정 IP를 직접 검사
is_dev_ip('203.0.113.5'); // bool

@if (is_dev_ip())
    <pre>{{ json_encode($debugData, JSON_PRETTY_PRINT) }}</pre>
@endif

활용 예:

개발자에게만 디버그 패널·쿼리 로그·상세 메시지 노출
운영 도메인에서 점검 시, 일반 사용자엔 영향 없이 개발자만 상세 확인

주의사항

허용 목록은 좁게 유지하세요(특정 IP/대역만). 광범위 대역은 상세 에러 노출 위험.
개발 환경 IP가 동적이면 바뀔 때마다 갱신하거나, 안정적인 대역/식별자를 사용하세요.
is_dev_ip()/디버그 게이트는 프록시 신뢰 설정이 올바라야 실 IP로 동작합니다(프록시 뒤 운영 시 trustProxies 점검).
보안 게이트이므로 변경 시 동작을 검증하세요(Core 단위 테스트 포함).

설정​

동작 원리​

is_dev_ip() 헬퍼​

주의사항​

설정

동작 원리

`is_dev_ip()` 헬퍼

주의사항