kui-vault/01.Shelf/WORKBENCH/Gitea & Quartz 배포 자동화 트러블슈팅.md

id	created	tags
Gitea & Quartz 배포 자동화 트러블슈팅 20260401	2026-04-01 13:23

🛠️ Gitea & Quartz 배포 자동화 트러블슈팅 기록

1. 문제의 발단: Gitea 경로 변경 (/git/ 누락)

기존에 설정된 Gitea의 접속 주소가 /git/ 경로를 포함하고 있었으나, 서버 재설정 과정에서 이 경로가 빠지게 되었습니다. 이로 인해 연쇄적인 문제가 발생했습니다.

• 현상: Gitea 웹훅(Webhook)이 서버의 수신기(webhook 서비스)에 신호를 보내지 못함.

• 원인: Gitea 내부 리포지토리 설정과 외부 호출 URL이 일치하지 않아 404 에러 또는 연결 거부 발생.

---

2. 주요 장애 요인 및 해결 과정

📂 [Level 1] 서비스 실행 실패 (ConditionPathExists)

• 에러: webhook.service was skipped because of an unmet condition check.

• 원인: 기본 설치된 webhook 서비스가 /etc/webhook.conf 파일이 있어야만 작동하도록 설정됨.

• 해결: 서비스 파일(systemd)을 수정하여 해당 조건을 삭제하고, 우리가 직접 만든 hooks.json을 바라보도록 설정함.

🔑 [Level 2] 인증 에러 (no source for value retrieval)

• 에러: 500 | error evaluating hook: no source for value retrieval.

• 원인: hooks.json에는 비밀번호(Secret) 검사 로직이 있는데, Gitea 웹훅 설정에는 비밀번호가 비어 있거나 헤더 이름이 일치하지 않음.

• 해결: 보안을 위해 Gitea와 서버 양쪽에 동일한 비밀번호를 설정하거나, 테스트를 위해 trigger-rule을 삭제하여 문턱을 낮춤.

🚀 [Level 3] 스크립트 실행 환경 문제 (npx & node)

• 에러: npx: command not found 또는 node: No such file or directory.

• 원인: systemd 서비스는 사용자 터미널 환경변수(PATH)를 읽지 못해 NVM에 설치된 Node.js를 찾지 못함.

• 해결: deploy.sh 상단에 Node.js 실행 파일이 있는 절대 경로를 export PATH로 직접 주입함.

📉 [Level 4] 자원 부족 및 서버 경직 (kswapd0)

• 현상: 빌드 시작 시 서버가 급격히 느려지며 접속이 끊김.

• 원인: Quartz 빌드는 CPU와 메모리를 많이 사용하는데, 512MB~1GB 수준의 낮은 메모리로 인해 스왑(Swap) 현상이 심화됨.

• 해결: 1. Swap 확장: 기존 스왑 파일을 2GB로 대폭 확장하여 물리 메모리 부족에 대비함.

  2. 우선순위 조정: 빌드 명령어 앞에 **nice -n 19**를 붙여 다른 서비스(Nginx, Gitea)에 영향을 주지 않도록 최적화함.

---

3. 최종 자동화 아키텍처 (The "Tight" Setup)

구성 요소	역할	최적화 포인트
Gitea	소스 관리 및 트리거	/git/ 경로를 제외한 클린 URL 적용
Webhook	신호 수신기 (Port 29292)	전용 서비스 등록 및 자동 시작 설정
deploy.sh	배포 스크립트	절대 경로 사용, 로그 파일 기록, 우선순위 최저 설정
Swap File	가상 메모리 (2GB)	/etc/fstab 등록을 통한 영구 적용

---

📝 교훈

경로(Path)와 환경(Environment)은 언제나 명시적이어야 한다. > 공짜 서버일수록 수동으로 자원을 배분하고 우선순위를 관리하는 빡빡한 최적화가 시스템의 생명줄이 된다.