일하는 ai

25. Quartz에서 글 옮기고 지운 뒤 ENOENT로 다시 죽을 때

9 min read

-

Quartz에서 문서를 여러 개 이동·삭제·리네임한 직후 사이트가 갑자기 죽고, 로그에 ENOENT가 보이면 대부분은 watcher가 이미 사라진 파일 경로를 다시 읽으려는 상태다.
이때는 단순 pm2 restart quartz만 반복하기보다, 출력 폴더를 비우고 안전 재빌드로 한 번 끊어주는 편이 훨씬 빠르다.

칠판 치트시트

  1. 최근에 글을 많이 옮기거나 지웠는지 먼저 본다
  2. 로그에 ENOENT / ENOTEMPTY / 삭제된 경로 재참조가 보이면 watcher 꼬임 가능성이 높다
  3. 일반 재시작보다 safe-rebuild.sh를 먼저 쓴다
  4. 127.0.0.1:8090 헬스체크가 200이면 복구 판단
flowchart LR
A[문서 이동/삭제/리네임] --> B[Quartz watcher가 옛 경로 추적]
B --> C[ENOENT 또는 ENOTEMPTY]
C --> D{일반 restart만 반복?}
D -- 예 --> E[같은 오류 재발 가능]
D -- 아니오 --> F[safe-rebuild.sh 실행]
F --> G[public 백업 후 빈 public 재생성]
G --> H[PM2 재시작 + 8090 헬스체크]
H --> I[정상 복구]

가장 빠른 복구 순서

실무에서는 아래 순서가 가장 덜 흔들린다.

  1. 최근 작업 확인
    대량 이동/삭제/리네임이 있었으면 Quartz watcher 꼬임을 먼저 의심한다.

  2. 증상 확인
    PM2 로그나 빌드 로그에서 아래 신호를 본다.

    • ENOENT: no such file or directory
    • 삭제한 문서 경로를 다시 읽으려는 흔적
    • public/tags 같은 출력 디렉터리에서 ENOTEMPTY

  3. 안전 재빌드 실행
    일반 재시작 대신 아래 스크립트를 먼저 실행한다.

/home/tw2/quartz/scripts/safe-rebuild.sh

  1. 정상 여부 확인
    스크립트는 내부적으로 아래를 처리한다.

    • pm2 stop quartz
    • 기존 public/을 .public-backups/로 이동
    • 빈 public/ 재생성
    • pm2 start quartz
    • http://127.0.0.1:8090 헬스체크

  2. 브라우저/공개 주소 재확인
    로컬 8090이 200이면, 그다음 공개 도메인 응답까지 확인하면 된다.

왜 이런 일이 생기나

Quartz 공식 소개에서도 content edits에 대해 incremental rebuild와 hot-reload를 강조한다. 이 구조는 평소엔 빠르지만, 대량 이동/삭제 직후에는 watcher가 직전 상태를 따라가다 이미 없는 파일을 다시 보려는 순간이 생길 수 있다.

쉽게 말하면,

  • 파일은 이미 치웠는데
  • 감시자는 “아까 거 다시 볼게” 하고
  • 그 파일이 없으니 ENOENT가 나는 흐름이다.

그래서 이런 상황에서는 “다시 켜기”보다 빌드 산출물과 watcher 흐름을 한 번 깨끗하게 리셋하는 게 더 잘 먹힌다.

현장 미니 사례

사례 A) 중복 글 정리 후 aiee.app가 갑자기 죽음

  • 상황: 영혼 시리즈 문서를 이동하면서 기존 파일을 정리함
  • 증상: Quartz가 삭제된 경로를 rebuild 중 다시 읽다가 ENOENT
  • 해결: safe-rebuild.sh로 public/을 비우고 재기동
  • 결과: 로컬 127.0.0.1:8090과 공개 도메인 응답 모두 정상 복귀

사례 B) pm2 restart quartz만 여러 번 했는데 그대로임

  • 상황: 프로세스는 다시 떴지만 출력 폴더 상태가 꼬여 있었음
  • 증상: public/tags 계열에서 ENOTEMPTY 또는 이전 빌드 잔재 충돌
  • 해결: 기존 public/ 전체를 백업 이동한 뒤 빈 폴더로 재시작
  • 결과: 단순 재시작 반복보다 훨씬 빨리 안정화

복붙용 실행 블록

# 1) 안전 재빌드
/home/tw2/quartz/scripts/safe-rebuild.sh
 
# 2) 그래도 이상하면 최근 로그 확인
pm2 logs quartz --lines 200
 
# 3) 로컬 헬스 직접 확인
curl -I http://127.0.0.1:8090/

재발 방지

1. 대량 이동/삭제 직후에는 일반 restart보다 safe rebuild 우선

조금 귀찮아 보여도, 이후 재장애 시간을 줄인다.

2. 여러 문서를 한 번에 옮겼다면 바로 헬스체크

특히 허브 문서, 시리즈 문서, 인덱스 문서를 함께 손댔으면 바로 8090 응답을 본다.

3. 옛 URL이 살아 있어야 하면 alias나 리다이렉트도 같이 처리

문서 이동 문제는 빌드 장애와 별개로 외부 링크 404를 남길 수 있다.

검색형 FAQ

Q1. ENOENT가 보이면 무조건 Quartz 버그인가요?

A. 꼭 그렇진 않다. 실제로는 최근 파일 이동/삭제 뒤 watcher가 옛 경로를 참조하는 운영 상황에서 자주 생긴다.

Q2. 왜 pm2 restart quartz만으로는 부족할 수 있나요?

A. 프로세스만 다시 뜨고, 이미 꼬인 public/ 산출물이나 rebuild 흐름은 그대로 남을 수 있기 때문이다.

Q3. safe rebuild는 정확히 뭘 다른가요?

A. 기존 public/을 통째로 백업 이동하고 빈 public/에서 다시 시작한다. 즉, 찌꺼기 상태를 들고 가지 않는다.

Q4. 언제 이 루틴을 써야 하나요?

A. 문서를 몇 개 수준이 아니라 대량 이동/삭제/리네임한 직후, 또는 삭제된 파일 경로가 로그에 반복될 때다.

상황별 다음 글 바로가기 (10개)

  1. 일단 명령만 빨리 보고 싶다 → 05. Quartz 치트
  2. 배포 직전 최종 점검까지 같이 하고 싶다 → 12. 배포 5분 체크
  3. 사이트가 느리거나 먹통처럼 보인다 → 40. OpenClaw 답변 지연 해결
  4. gateway까지 같이 의심된다 → 33. gateway 무응답 복구
  5. 크론/자동화 운영 전체를 다시 정리하고 싶다 → 25. 크론 서브에이전트 분산운영
  6. 파일 정리 규칙부터 다시 잡고 싶다 → 21. Archive PARA+Z 리팩터링 실행
  7. 배포 전에 정적 파일/SEO를 같이 보고 싶다 → 12. 배포 5분 체크
  8. Quartz 전체 흐름보다 OpenClaw 운영 허브로 돌아가고 싶다 → 🚀 OpenClaw 인덱스
  9. 증상별 다른 장애 문서도 같이 보고 싶다 → Troubleshooting 허브
  10. 설치/기본 운영부터 다시 확인하고 싶다 → 19. OpenClaw 설치오류복구

다음 읽기

내부링크 보강 (10개)

  1. Troubleshooting 허브
  2. 05. Quartz 치트
  3. 12. 배포 5분 체크
  4. 45. 채팅 URL 자동저장 안 될 때
  5. 46. DM 대화 섞일 때 dmScope 바꾸기
  6. 57. Quota 리셋 후 요청 막힘 복구
  7. 24. 핵 실전운영 가이드
  8. 33. gateway 무응답 복구
  9. 34. 세션툴 검수 자동화
  10. 🚀 OpenClaw 인덱스

다음 추천 읽기: 05. Quartz 치트

※ 이 문서는 생성형 AI를 활용해 작성되었습니다.

그래프 뷰

백링크