ServBay 웹 서버 장애 처리 가이드
ServBay는 기본 웹 서버로 Caddy, NGINX, Apache를 지원하며, 유연한 로컬 개발 환경을 제공합니다. 활용 도중 웹사이트가 접속되지 않거나, 느리게 로딩되거나, 500 내부 서버 오류와 같은 에러가 발생할 수 있습니다. 본 가이드는 ServBay 환경에서 자주 발생하는 웹 서버 관련 장애의 진단과 해결 방법을 안내합니다.
ServBay 내장 장애 진단 도구 활용하기
ServBay에서는 자동으로 일반적인 설정 및 서비스 문제를 점검할 수 있는 강력한 장애 진단 도구를 제공합니다. 문제 발생 시, 이 도구로 먼저 자가진단하시는 것을 적극 추천합니다.
ServBay 앱을 열고, 좌측 내비게이션 바에서 장애 진단을 클릭하면 ServBay의 내장 장애 진단 화면으로 진입할 수 있습니다.
이 도구는 ServBay의 핵심 컴포넌트 상태, 포트 점유 상황, 설정 파일 문법 등을 점검한 후, 필요한 안내와 조치를 제공합니다. 문제 원인을 빠르게 찾는 데에 도움이 됩니다.
MAMP나 Laravel Herd에서 마이그레이션 후 최초 접속이 느린 경우
MAMP 또는 Laravel Herd에서 ServBay로 전환한 후 웹사이트를 한동안 사용하지 않았다가 다시 최초로 접속하면 5초 이상 대기 후에야 사이트가 열리는 현상이 있을 수 있습니다. 이후 일정 시간 동안은 정상적으로 빠른 접속이 가능하지만, 또 다시 일정 시간 휴지기 이후 최초 접속 시에는 느려집니다.
증상
Chrome 브라우저에서 개발자 도구(F12 또는 Cmd+Option+I), 네트워크(Network) 탭으로 이동 후 페이지를 새로고침하고 요청의 Timing 정보를 확인하면, DNS Lookup 부분에 약 5초의 대기 시간이 표시됩니다.
(이미지 설명: Chrome 개발자 도구 Network 탭에서 DNS Lookup 시간 확인)
원인
MAMP와 Laravel Herd는 설치 시 macOS DNS 설정을 강제 변경하며, 특정 도메인(*.test, *.local 등)의 해석을 가로채기 위해 /etc/resolver/ 디렉터리에 특별한 DNS 해석기 설정 파일을 추가합니다.
MAMP나 Herd를 완전히 삭제했더라도, 이러한 DNS 해석기 설정 파일이 시스템에 남아 있을 수 있습니다. 해당 도메인(예: .test)을 접속할 때, macOS가 먼저 남아있는 구 설정을 사용해 DNS 질의를 시도하지만 서비스가 없으므로 5초간 타임아웃이 발생합니다. 이후에야 정상적인 시스템 DNS로 해석이 완료되어 접속이 가능합니다.
해결 방법
아래 단계에 따라 MAMP 또는 Laravel Herd 잔여 DNS 설정을 완전히 정리하세요.
1. MAMP 또는 Laravel Herd 완전 제거
아직 완전히 삭제하지 않았다면 공식 제거 프로그램 또는 제공되는 스크립트로 완전히 삭제합니다.
MAMP 제거:
- MAMP 앱에서 제공하는 제거 기능 사용
- 직접
/Applications/MAMP폴더와 관련 설정 파일 삭제
Laravel Herd 제거:
bash
# Herd 공식 uninstall 명령어 사용
herd uninstall
# 위 명령이 동작하지 않으면, Herd 앱 및 설정 파일 수동 삭제
rm -rf ~/Library/Application\ Support/Herd
rm -rf ~/.config/herd2. /etc/resolver 디렉터리 내 잔여 파일 삭제
정상적으로 앱을 삭제해도 /etc/resolver/ 폴더 내 DNS 해석기 파일이 남아있을 수 있습니다. 아래 명령어로 직접 삭제하세요:
bash
# /etc/resolver 폴더 파일 목록 확인
ls -la /etc/resolver
# 특정 해석기 설정 파일(test, local 등) 삭제
sudo rm /etc/resolver/test
sudo rm /etc/resolver/local
# 추가적으로 MAMP/Herd에서 생성한 파일이 있다면 모두 삭제
# 예: sudo rm /etc/resolver/herdMAMP/Herd가 생성하는 대표적인 해석기 파일:
test-*.test도메인용local-*.local도메인용herd- Laravel Herd 전용
참고: 파일 삭제 시 관리자 권한(sudo)이 필요합니다.
3. *.local 도메인 사용 주의
macOS에서는 *.local을 로컬 네트워크(LAN)의 mDNS(Bonjour) 서비스 용도로 예약합니다. 개발 목적의 도메인으로 .local을 사용하면 다음과 같은 문제를 유발할 수 있습니다:
- DNS 해석 충돌
- 접속 속도 저하
- 예기치 않은 네트워크 동작
추천: 개발 시 다음과 같은 다른 도메인 후위를 사용하세요:
.test- 테스트 목적으로 예약된 TLD.localhost- 로컬 시스템 루프백 주소.dev- 실제 TLD지만, 로컬 개발에서 자주 사용됨- 또는 ServBay가 추천하는 커스텀 후위
4. DNS 캐시 초기화 (선택)
위 작업 후 DNS 캐시를 초기화해 변경 사항이 즉시 반영되도록 권장합니다:
bash
# macOS Big Sur (11) 이상
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
# macOS Catalina (10.15) 이하
sudo killall -HUP mDNSResponder5. 정상 동작 확인
삭제 후 ServBay 웹사이트를 다시 접속해봅니다.
- 브라우저에서 로컬 사이트 접근
- Chrome 개발자 도구 → 네트워크(Network) 탭
- 새로고침 후 Timing 정보 확인
- DNS Lookup 시간이 정상(50ms 미만)으로 줄었는지 확인
위 단계로 마이그레이션 후 최초 접속 속도 저하 문제를 대부분 해결할 수 있습니다. 문제가 계속된다면 VPN, 프록시 등 제3자 소프트웨어로 인한 DNS 장애가 있는지 확인하세요.
웹 서버 설정 파일 점검
웹 서버 설정 파일 오류는 사이트 접속 장애의 주요 원인입니다. ServBay는 각 웹 서버별로 문법 체크 도구를 제공합니다.
Caddyfile 검증
Caddy 내장 validate 명령어로 Caddyfile 설정이 올바른지 확인하세요.
bash
# macOS
/Applications/ServBay/bin/caddy validate -c /Applications/ServBay/etc/caddy/Caddyfile
# Windows
C:\ServBay\bin\caddy.exe validate -c C:\ServBay\etc\caddy\Caddyfile문법이 정확하다면 Valid configuration이 출력됩니다. 오류가 있으면 원인에 맞는 안내 메시지가 표시됩니다.
참고: caddy validate 명령은 많은 양의 INFO 및 WARN 메시지를 출력할 수 있으나, 이는 내부 로딩 정보이며, 마지막에 Valid configuration만 확인하면 됩니다.
Caddyfile 자주 발생하는 오류 예시
인증서 파일 없음 오류:
bash# macOS 예시 2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"} ... (기타 INFO/WARN 메시지) ... Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open /Applications/ServBay/ssl/private/tls-certs/mail.servbay.host/mail.servbay.host.1crt: no such file or directory # Windows 예시 2024/12/09 17:24:16.970 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"} ... (기타 INFO/WARN 메시지) ... Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open C:\\ServBay\\ssl\\private\\tls-certs\\mail.servbay.host\\mail.servbay.host.1crt: no such file or directoryloading certificates: open xxxxx: no such file or directory오류는 Caddyfile에서 지정한 SSL 인증서 파일 경로가 잘못되었거나, 해당 파일이 존재하지 않을 때 나타납니다. 사이트 설정의 인증서(.crt/.cer/.pem)와 개인키(.key) 파일 경로를 정확히 확인하고 실제 존재하는지 검증하세요. ServBay는 직접 인증서 가져오기, ACME 자동 발급 기능을 모두 지원합니다.웹사이트 루트 경로 오류 (공백 포함):
bash# macOS 예시 2024/12/09 17:26:37.371 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"} Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at /Applications/ServBay/etc/caddy/Caddyfile:1388 # Windows 예시 2024/12/09 17:26:37.371 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"} Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at C:\\ServBay\\etc\\caddy\\Caddyfile:1388parsing caddyfile tokens for 'root': too many arguments오류는 웹사이트 루트 경로에 공백이 들어갈 때 나타납니다. 예를 들어:- macOS:
root * /Applications/ServBay/www/public web의public web은 Caddy가 두 개의 인자로 해석 - Windows:
root * C:\ServBay\www\public web또한 동일
올바른 방식은 경로 전체를 쌍따옴표
"로 감싸는 것입니다:- macOS:
root * "/Applications/ServBay/www/public web" - Windows:
root * "C:\ServBay\www\public web"
팁: 폴더 및 파일명에 공백과 특수문자 사용을 피하고, 대신 하이픈(
-)이나 언더스코어(_)로 단어를 구분하세요(예:public-folder,public_dir).- macOS:
Rewrite 규칙 오류:
Caddyfile에서 NGINX 규칙을 그대로 복사하거나, Caddy 문법에 맞지 않는 규칙을 사용하면 검증에 실패합니다. Caddy Rewrite 모듈 문서 또는 ServBay의 NGINX에서 ServBay로 마이그레이션 가이드를 참고해 올바른 문법으로 작성하세요.
NGINX 설정 점검
NGINX 내장 -t 파라미터로 설정 및 문법 검사를 실행합니다.
bash
# macOS
/Applications/ServBay/bin/nginx -t
# Windows
C:\ServBay\bin\nginx.exe -t설정이 올바르면 다음과 같이 표시됩니다:
# macOS
nginx: the configuration file /Applications/ServBay/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /Applications/ServBay/etc/nginx/nginx.conf test is successful
# Windows
nginx: the configuration file C:\ServBay\etc\nginx\nginx.conf syntax is ok
nginx: configuration file C:\ServBay\etc\nginx\nginx.conf test is successful오류가 있을 경우, NGINX가 파일 경로와 라인 번호까지 상세 안내합니다. 주요 오류 유형:
- 문법 오류: 세미콜론
;누락, 중괄호}불일치 등. - 파일 경로 오류:
include또는 기타 지시문에 존재하지 않는 파일 또는 폴더 경로 지정. - 포트 충돌: 이미 다른 앱에서 사용중인 포트를 청취하도록 설정했을 때.
Apache 설정 점검
Apache의 apachectl configtest로 설정 파일 문법 확인을 합니다.
bash
# macOS
/Applications/ServBay/bin/apachectl configtest
# Windows
C:\ServBay\bin\httpd.exe -t문법이 올바르면 Syntax OK가 출력됩니다. 오류가 있으면 상세 메시지가 나옵니다. 대표적 Apache 오류:
- 모듈 로드 실패: 설정 파일에서 활성화한 모듈(
LoadModule)이 실제로 없거나 경로가 잘못됨. - .htaccess 파일 오류:
.htaccess내 문법 오류로 전체 설정 체크 실패, 또는 특정 폴더 접근 장애 발생. - 권한 설정 오류:
Directory,Files등 지시문에서 권한(Require,Allow,Deny)이 잘못되어 파일 접근이 제한됨.
500 내부 서버 오류 처리
500 Internal Server Error는 서버가 요청 실행 도중 예기치 못한 장애를 만나 요청을 처리할 수 없을 때 나타나는 HTTP 코드입니다. 보통 PHP, Python, Node.js 등 백엔드 스크립트 실행 실패와 연관됩니다.
기본 점검 방법
500 오류 발생 시 다음 단계로 점검하세요:
웹 서버 오류 로그 확인: 가장 먼저 체크할 부분입니다. 오류 로그에 파일 미존재, 스크립트 에러, 권한 문제 등 상세 내용이 기록됩니다.
macOS:
- Caddy:
/Applications/ServBay/var/logs/caddy/error.log - NGINX:
/Applications/ServBay/var/logs/nginx/error.log - Apache:
/Applications/ServBay/var/logs/apache/error.log
Windows:
- Caddy:
C:\ServBay\var\logs\caddy\error.log - NGINX:
C:\ServBay\var\logs\nginx\error.log - Apache:
C:\ServBay\var\logs\apache\error.log
가장 최근 로그를 확인하며,
error또는critical키워드를 찾아봅니다.- Caddy:
백엔드 서비스(PHP-FPM 등) 정상 실행 체크: PHP 의존 사이트라면 PHP-FPM 프로세스가 실행 중인지 확인하세요.
bashps aux | grep php-fpmphp-fpm: master process,php-fpm: pool www가 보이면 정상입니다. 없으면 PHP-FPM이 종료됐거나 실행되지 않은 상태입니다. ServBay UI 또는servbayctl로 PHP 서비스 재시작이 가능합니다.PHP 등 백엔드 스크립트 에러 로그 확인: 웹 서버 로그에서 FastCGI 또는 스크립트 실행 에러라면, 각각의 언어별 에러 로그를 추가로 확인해야합니다.
PHP 에러 로그 경로:
- macOS:
/Applications/ServBay/var/logs/php/php_error.log - Windows:
C:\ServBay\var\logs\php\php_error.log
PHP 에러 로그 내의
Fatal error,Parse error,Warning,Notice등과 현재 요청 중인 스크립트에 관련된 항목을 확인하세요. 운영 환경에서는display_errors를 꺼두는 것이 좋으나, 개발 환경에서는 일시적으로 켜서 상세 에러를 볼 수 있습니다(php.ini에서 설정).- macOS:
파일 및 폴더 권한 확인: 웹 서버 프로세스는 특정 사용자로 실행되므로, 웹사이트 파일과 폴더를 읽고 쓸 수 있는 권한이 필요합니다.
macOS:
bashls -la /Applications/ServBay/www/your-site/웹 서버 사용자(
_www등)가 루트 폴더 및 하위 파일, 폴더를 읽을 수 있어야 하며, 업로드 또는 로그 작성을 위해서는 쓰기 권한도 필요합니다.chmod,chown으로 권한과 소유자 설정이 가능합니다.Windows:
cmddir C:\ServBay\www\your-siteWindows에서는 ServBay 실행 계정에 폴더 접근/수정 권한이 있어야 하며, 속성 → 보안 탭에서 조정 가능합니다.
웹 서버별 500 오류 주요 점검 포인트
Caddy:
- FastCGI 설정: Caddyfile에서
php_fastcgi또는reverse_proxy의 PHP-FPM 주소(127.0.0.1:9000또는unix:/path/to/php-fpm.sock)가 올바른지 확인. - PHP-FPM 상태: 선택한 PHP 버전 및 PHP-FPM 서비스가 정상 동작 중인지 ServBay에서 점검.
- 리버스 프록시 설정:
reverse_proxy사용 시, 대상 서비스(Node.js 등)가 정상 실행 중인지, 포트 번호 등 경로가 올바른지 확인.
- FastCGI 설정: Caddyfile에서
NGINX:
fastcgi_pass설정:nginx.conf또는 사이트별 설정에서 PHP-FPM 주소가 올바른지 확인.client_max_body_size: 업로드 시 500 에러가 발생한다면 요청 크기 제한 설정이 너무 작을 수 있음.try_files지시문: 인덱스 파일 찾기 또는 FastCGI로 요청 넘기기 규칙이 올바르게 설정되어야 함.
Apache:
mod_rewrite모듈:.htaccess로 URL 재작성 시,mod_rewrite가 활성화되어야 함.- .htaccess 파일 내용: 잘못된 규칙(특히
RewriteRule)로 인해 500 에러가 발생할 수 있으니 문법 확인. AllowOverride설정: 해당 폴더의AllowOverride값이.htaccess적용을 허가하는지(All또는 최소한FileInfo,Limit포함) 확인.
서비스 관리
설정 파일을 변경하거나 백엔드 문제를 해결 후에는 웹 서버 또는 관련 서비스를 반드시 재시작해 변경사항을 반영하세요.
서비스 재시작
servbayctl restart 명령어로 원하는 웹 서버 서비스만 재시작할 수 있습니다.
bash
# Caddy 서비스 재시작
servbayctl restart caddy -all
# NGINX 서비스 재시작
servbayctl restart nginx -all
# Apache 서비스 재시작
servbayctl restart apache -all-all은 해당 웹 서버에 연관된 서비스(FastCGI 등)도 함께 재시도합니다.
서비스 상태 확인
servbayctl status 명령어로 서비스 현재 상태를 점검합니다.
bash
# Caddy 서비스 상태 확인
servbayctl status caddy -all
# NGINX 서비스 상태 확인
servbayctl status nginx -all
# Apache 서비스 상태 확인
servbayctl status apache -all실행 결과로 running(실행 중), stopped(중지됨) 등 상태가 표시되며, 서비스 구동 여부를 즉시 확인할 수 있습니다.
고급 장애 진단 방법
기본 단계 이외에 추가적인 심층 진단이 필요하다면 아래 방법을 활용해보세요.
- 브라우저 개발자 도구 활용: F12로 호출,
콘솔(Console)및네트워크(Network)탭에서 JS 에러, 요청 상태 코드, 응답 헤더/본문 등을 체크하여 프론트엔드와 백엔드 장애 요인을 구분. curl -v명령어 사용: 터미널에서curl -v your-website.servbay.demo로 웹사이트 요청, 상세 요청/응답 정보(헤더, SSL/TLS 연결 등) 분석.your-website.servbay.demo를 실제 ServBay 도메인으로 변경해 사용.- 방화벽 임시 차단 해제 테스트: macOS 내장 또는 써드파티 방화벽·보안앱이 외부 접속을 제한할 수 있으니, 일시적으로 해제 후 정상 동작 확인. 문제가 해결된다면 ServBay 사용 포트(80, 443 등)를 허용하세요.
- 다른 브라우저/기기에서 테스트: 브라우저 캐시, 설정 문제 또는 특정 기기에 한정된 장애를 확인하기 위해 다른 환경에서 접근해봅니다.
- 로컬 DNS 해석 및 hosts 파일 설정 확인: 커스텀 도메인 사용 시, 주소가
127.0.0.1또는::1로 정상적으로 지정되어 있는지 hosts 파일, 로컬 DNS 설정을 검사.- macOS:
/etc/hosts - Windows:
C:\Windows\System32\drivers\etc\hosts
- macOS:
마무리
웹 서버 장애는 로컬 개발에서 흔히 접하는 이슈입니다. 설정 파일 문법 점검, 오류 로그 분석, 서비스 구동 상태 확인, 파일 권한 확인 등 단계별 점검으로 대부분 해결할 수 있습니다. ServBay의 내장 장애 진단 도구와 servbayctl 커맨드 라인 툴을 적극 활용하세요. 보다 복잡한 장애 발생 시, ServBay 공식 문서 또는 기술 지원팀에 문의하여 도움받으실 수 있습니다.
