Adminer.php 파일이 비어있는 이유는 무엇일까요? 파일 이름을 바꾸면 정상적으로 작동합니다. 원인 분석 및 3단계 해결 방법을 알려드립니다.

어제 오후, 저는 서버에 Adminer 데이터베이스 관리 도구를 설치하고 있었습니다. Adminer는 가볍고 사용하기 쉽습니다. phpMyAdmin 처럼 여러 종속성이 필요한 것과는 달리, 단 하나의 PHP 파일만으로 모든 기능을 수행할 수 있습니다. 공식 웹사이트에서 최신 버전을 다운로드하여 서버에 업로드하고 권한을 설정한 후, 브라우저를 열어 확인해 볼 준비를 했습니다.

그러자 모든 것이 암흑으로 변했습니다.

페이지를 세 번이나 새로고침했는데, F5 키를 너무 많이 눌러서 손가락이 욱신거렸다. 그래도 아무 반응이 없었다. 브라우저 개발자 도구를 열어보니 200 OK 오류는 표시되었지만 응답 본문은 비어 있었다. 완전히 어이가 없었다. 도대체 무슨 일이 벌어지고 있는 걸까?

잠시 생각해 봤습니다. 파일 권한 문제일까요? 확인해 보니 755였습니다. PHP 버전 호환성 문제일까요? 확인해 보니 PHP 8.2라서 문제없습니다. 파일 자체에 문제가 있는 걸까요? 새 파일을 다운로드해서 덮어썼는데도 여전히 빈 화면입니다.

이유는 알 수 없지만, 문득 이름을 바꿔보는 것도 괜찮겠다 싶은 생각이 들었습니다.

adminer.php 파일 이름을 adminer1.php로 변경하고 페이지를 새로고침했습니다.

접속에 성공했습니다.

정말 어이가 없었어요. 똑같은 파일, 똑같은 코드, 똑같은 서버인데 이름만 바꾸면 접근이 가능하다니? 이게 대체 무슨 신비로운 논리죠?

adminer.php 파일이 비어있는 문제

나중에 알고 보니 이건 미신이 아니라 PHP 캐싱 때문에 발생한 문제였습니다.

OPcache는 Opcode Cache의 줄임말로, PHP의 성능 최적화 확장 기능입니다. 원리는 간단합니다. PHP는 인터프리터 언어이기 때문에 각 요청은 실행 전에 PHP 코드를 오퍼레이션 코드로 컴파일해야 합니다. OPcache는 컴파일된 결과를 메모리에 캐시하여, 이후 요청에서 재컴파일 없이 캐시된 버전을 직접 사용할 수 있도록 함으로써 성능을 크게 향상시킵니다.

하지만 바로 거기에 문제가 있습니다.

이전에는 adminer.php에서 "파일을 찾을 수 없습니다"라는 메시지가 표시되었습니다(잘못된 파일을 업로드했기 때문입니다). OPcache는 잘못된 콘텐츠의 컴파일된 결과를 캐시했습니다. 이후 adminer.php를 올바른 코드로 교체했지만, OPcache는 이를 무시하고 메모리에서 이전 캐시를 계속 읽어 빈 페이지가 표시되거나 이전 오류 메시지가 나타났습니다.

파일 이름을 adminer1.php로 변경하면 OPcache에서 완전히 새로운 파일 경로로 인식되어 다시 로드되고 올바르게 해석됩니다.

마치 새 책을 이미 빌렸는데 도서관 색인 카드에는 여전히 예전 책의 청구기호가 적혀 있는 것과 같습니다. 책꽂이에서 그 책을 찾아보면 당연히 비어 있겠죠. 하지만 책 제목을 바꾸면 도서관에서 새 색인 카드를 만들어 주고, 그러면 새 책을 찾을 수 있게 됩니다.

이유 1: OPcache 캐시로 인해 공백이 발생합니다.

어떻게 처리할까요?

PHP-FPM 서비스를 재시작하고 OPcache 캐시를 지우십시오.

# 查看正在运行的PHP版本
php -v

# 重启对应的PHP-FPM（例如PHP 8.5）
sudo systemctl restart php8.5-fpm

# 或者重启所有PHP-FPM服务
sudo systemctl restart php*-fpm

재시작 후 파일 이름을 다시 adminer.php로 변경하고 웹페이지를 새로고침하세요(브라우저를 강제로 새로고침하려면 Ctrl+F5를 누르는 것이 좋습니다). 그러면 문제가 해결될 것입니다.

하지만 이야기는 아직 끝나지 않았습니다.

PHP-FPM을 재시작한 후 adminer.php 파일을 원래대로 되돌리고 페이지를 새로고침했지만 여전히 빈 화면이었습니다. 정말 어이가 없었습니다.

이유 2: Nginx 설정 규칙 제한

이것이 두 번째 가능한 이유로 이어집니다.

Nginx 설정 파일에 adminer.php에 대한 접근을 제한하는 특별 규칙이 있을 수 있습니다.

이전에 HestiaCP 패널에서 Fail2Ban을 설정 하고 무차별 대입 공격을 방지하기 위해 adminer.php에 대한 정확한 일치 규칙을 작성했습니다 . 이 규칙은 파일 이름을 adminer.php로 하드코딩했기 때문에 파일 이름을 adminer1.php로 변경하면 이 Nginx 규칙을 우회하여 정상적으로 접근할 수 있었습니다.

문제 해결 방법은 간단합니다. Nginx 설정 파일에서 하드코딩된 항목을 찾아보세요.

sudo grep -rn "adminer.php" /etc/nginx/

`location = /adminer.php { … }`와 같은 규칙을 발견했다면, Nginx가 해당 특정 파일명을 특별하게 처리하고 있다는 의미입니다. 해당 부분을 삭제하거나 수정하면 됩니다.

이유 3: PHP 오류 표시 설정

세 번째 이유는 좀 더 미묘합니다.

PHP 스크립트가 가로채지거나 오류가 발생했지만 페이지에서 오류 표시가 비활성화된 경우(display_errors = Off)가 있습니다. 실제 운영 환경에서 PHP는 기본적으로 오류를 숨기고 빈 페이지를 표시합니다. 예를 들어, 진입 파일(index.php)이 "./adminer.php"를 포함하려고 시도하는 동안 어떤 이유로든 충돌하면 페이지가 빈 화면으로 바뀝니다.

이러한 상황에서는 오류 로그를 확인하는 것이 가장 확실한 방법입니다.

# 查看Nginx错误日志
sudo tail -n 20 /var/log/nginx/error.log

# 或者查看HestiaCP对应域名的error日志
sudo tail -n 20 /var/log/nginx/domains/adminer.domain.com.error.log

로그를 확인하시면 화면이 하얗게 나오는 진짜 이유를 알 수 있습니다.

솔직히 말씀드리면, 결국 error.log 파일을 확인하고 나서야 문제를 찾았습니다. adminer.php 파일이 존재하지 않는 PHP 확장 프로그램을 호출하고 있었고, display_errors 설정이 꺼져 있어서 페이지는 비어 있었지만 오류 로그에는 그 내용이 명확하게 기록되어 있었던 것입니다.

해결 방법 및 문제 해결 단계

이 사건은 제게 깊은 인상을 남겼습니다.

기술적인 문제는 겉으로 보이는 것만큼 간단하지 않은 경우가 많습니다. 예를 들어, adminer.php 파일이 비어 있는 것은 처음에는 파일 자체의 문제처럼 보일 수 있지만, 자세히 살펴보면 캐싱 문제일 수도 있고, 더 나아가서는 설정 문제일 수도 있으며, 심지어 코드 자체의 문제일 수도 있습니다.

프로그래머가 아니라면 이런 것들이 자신과는 무관하다고 생각할 수도 있습니다. 하지만 한번 생각해 보세요. 여러분이 사용하는 모든 앱, 방문하는 모든 웹페이지는 백그라운드에서 비슷한 시스템을 작동시키고 있습니다. 캐싱, 설정, 오류 처리 등 이러한 개념들은 사실 어디에나 존재합니다.

우리 인간과 마찬가지로, 미루는 습관, 불안감, 짜증과 같은 "증상"은 표면적으로는 게으름처럼 보일 수 있지만, 더 깊이 파고들면 불분명한 목표, 더 나아가 파고드는 것에 대한 두려움, 그리고 더 근본적으로는 어린 시절의 경험으로 형성된 사고방식 때문일 수 있습니다.

진정한 근본 원인을 찾아야만 올바른 해결책을 제시할 수 있습니다.

마지막으로, adminer.php 파일이 비어 있는 문제가 발생하는 경우 다음 순서대로 확인해 보세요.

먼저 PHP-FPM을 재시작하고 캐시를 지운 다음, Nginx 설정을 확인하고 마지막으로 error.log 파일을 확인하십시오.

대부분의 경우, 처음 두 단계만으로도 문제를 해결하기에 충분합니다.

물론, 그래도 문제가 해결되지 않으면 error.log 파일을 확인해 보세요.

그것이 답을 알려줄 것입니다.

여기까지 읽어주셔서 감사합니다. 도움이 되셨다면 좋아요와 공유 부탁드립니다. 최신 소식을 가장 먼저 받아보고 싶으시다면 팔로우도 해주세요!

제 글을 읽어주셔서 감사합니다. 다음에 또 뵙겠습니다.