[WordPress] LocalWP "Briefly unavailable for scheduled maintenance" 발생시 대처법

문제 해결 방법 안내

사용자가 LocalWP에서 "Briefly unavailable for scheduled maintenance" 메시지를 보고 있다고 하네요. 이 문제는 WordPress 업데이트나 플러그인/theme 업데이트 실패 후 .maintenance 파일이 남아 발생합니다. 해결하려면, 이 파일을 삭제하거나 업데이트가 완료될 때까지 기다리면 됩니다. 만약 문제가 계속된다면, WordPress 루트 디렉토리에서 .maintenance 파일을 수동으로 삭제하고 파일 권한, 디스크 용량, PHP 오류 등을 확인해 보세요. LocalWP 로그를 체크하고 여러 가지 접근 방식을 시도해 보세요.

8초 동안 생각함

문제 원인 ― “Briefly unavailable for scheduled maintenance”가 나타나는 이유

WordPress는 플러그인‧테마‧코어 업데이트를 수행할 때, 루트 디렉터리에 .maintenance 파일을 만들어 트래픽을 일시적으로 차단합니다.
업데이트 스크립트가 **완료되거나 종료 코드 0**로 끝나면 이 파일을 즉시 삭제하지만, 다음과 같은 상황에서 제거되지 않고 남을 수 있습니다.

대표 원인 세부 설명

PHP 실행 시간 초과	max_execution_time 한도를 초과해 스크립트가 중단됨
메모리 부족	memory_limit 미만의 남은 메모리, WP 업데이트 압축 해제 중 OOM 발생
디스크 공간 부족	LocalWP 가상 디스크에 남은 용량이 부족하여 파일 쓰기 실패
파일 권한 오류	웹 서버(php-fpm) 사용자와 OS 사용자(예: Windows의 LOCALUSER) 간 권한 불일치
FTP/네트워크 끊김	업데이트 파일 다운로드 중 연결 단절 → 압축이 미완료 상태로 남음

.maintenance 파일이 존재하는 한, WordPress는 모든 프론트·백엔드 요청을 503 화면으로 리다이렉트합니다.

---

즉시 복구 절차 (30초 해결)

전제: LocalWP 기본 경로는
C:\Users\<USER>\Local Sites\<사이트명>\app\public

1. 사이트 셸 열기
   LocalWP → 해당 사이트 우측 “>_ Open Site Shell” 클릭
   (Windows PowerShell 세션이 열림)
2. .maintenance 제거Linux/macOS라면 rm -f .maintenance
3. # 파일명: PowerShell 세션 (경로: 사이트 루트) Remove-Item .maintenance -Force
4. 캐시 무효화 후 확인
   • 브라우저 새로고침 Ctrl + F5
   • WordPress 관리자 화면 정상 접속되는지 체크

---

근본 원인별 영구 대책 (선택 적용)

원인 해결 방법

PHP 실행 시간	wp-config.php에 지정 set_time_limit(300); 또는 @ini_set('max_execution_time','300');
메모리 부족	php.ini 수정 또는 wp-config.php에 define('WP_MEMORY_LIMIT', '256M');
디스크 부족	LocalWP “⚙ Preferences → Advanced → Disk” 에서 사이트별 디스크 경로 확인 후 용량 확보
권한 오류	PowerShell icacls . /grant "Everyone:F" (개발 환경 한정)
네트워크 문제	LocalWP > “Tools → Restart” 로 로컬 서버 재시작 후 다시 업데이트 시도

---

업데이트 안정성 향상을 위한 권장 워크플로

# 파일명: Update-WordPress.ps1  (경로: <프로젝트>\scripts)
# 목적: WP‑CLI로 무중단·안전 업데이트 자동화
# 실행:  PowerShell -ExecutionPolicy Bypass -File .\scripts\Update-WordPress.ps1
wp cli update --yes            # WP‑CLI 자체 업데이트
wp plugin update --all --quiet # 모든 플러그인
wp theme  update --all --quiet # 모든 테마
wp core  update --quiet        # 코어 업데이트

• WP‑CLI는 내부적으로 .maintenance 관리 로직이 견고하여, GUI보다 실패 확률이 낮습니다.
• 업데이트 전 wp maintenance-mode activate → 완료 후 wp maintenance-mode deactivate 패턴으로 롤백 대비 가능.

---

정리 & 체크리스트

1. 현재는 .maintenance 삭제로 즉시 복구
2. 추후 재발 방지를 위해
   • PHP 시간·메모리·디스크 리소스 한도 점검
   • 업데이트 전후 백업 → WP‑CLI 자동화 도입
3. LocalWP 내 Tools → Logs에서 php-fpm.log·nginx.log 를 주기적으로 확인해 이상 징후 모니터링

궁금한 점이나 로그 분석이 더 필요하면 덤프 파일을 첨부해 주세요. 추가로 살펴드리겠습니다!