웹훅 추가했는데 잘되려나?

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

@@ -0,0 +1,69 @@
+## 🛠️ 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)은 언제나 명시적이어야 한다.** > 공짜 서버일수록 수동으로 자원을 배분하고 우선순위를 관리하는 **빡빡한 최적화**가 시스템의 생명줄이 된다.