BurningTimesAi/공유/조직공지/2026-04-15_Phase3_NAS_post_receive_설치가이드.md

---
from: 총괄PM
to: PD님
type: 설치가이드
subject: Phase 3 — Gitea 저장소 웹훅 + Discord 실시간 알림 (가동 확정)
status: 완료
priority: normal
created: 2026-04-15
completed: 2026-04-15
ref_phase: Phase 3
actual_route: Gitea 저장소 웹훅(Discord 템플릿)
target_channel: "#클로드ai (단일 채널, 전 조직 공용 알림)"
verified_commit: f71ed75
---

## 🎉 Phase 3 가동 확정 (2026-04-15)

PD님이 다음 절차로 실제 설치·검증 완료:
1. 저장소 Settings → 웹훅 → Webhook 추가 → Discord 선택
2. Target URL 에 Discord webhook 등록
3. Branch filter `main` 지정
4. 테스트 커밋 `f71ed75` push → Discord `#클로드ai` 채널 정상 수신 스크린샷 확인

본 설치 가이드는 **완료** 상태. 아래 본문의 NAS Git Hooks 기반 원안은 Gitea 환경 제약(Git Hooks 메뉴 미노출)으로 **채택 안 됨**. 실제 가동 경로는 **Gitea 저장소 웹훅 + 단일 채널 알림**이며, 채널별 분기는 필요 시 후속 안건(Phase 5+)으로 검토.

---

# Phase 3 설치 가이드 — NAS post-receive + Discord 실시간 알림

## 목적

git push가 NAS 저장소에 도달하는 **그 순간**에 Discord webhook으로 알림을 발송하여, 부서 세션이 열려있지 않은 상태에서도 PD님·PM·부서가 이벤트를 즉시 인지한다. Claude 세션 간 통신의 근본 한계(세션 간 직접 통신 불가, 5분 throttle 지연)를 우회하는 **실시간 계층**.

## 동작 개요

```
어느 세션이든 push 발생
    ↓
NAS bare repo의 hooks/post-receive 실행 (bash)
    ↓
변경 파일 경로 패턴 분석
    ↓
채널별 Discord webhook 호출
    ├─ 공유/소통/PM↔개발실/* → #pm-inbox + #dev-inbox
    ├─ 공유/소통/PM↔기획실/* → #pm-inbox + #plan-inbox
    ├─ 공유/소통/개발실↔기획실/* → #dev-inbox 또는 #plan-inbox
    └─ 공유/조직공지/* 또는 공유/공통_업무_규칙.md → #core-rules
    ↓
PD님·PM·부서 담당자 Discord 알림 즉시 수신 (모바일 포함)
```

---

## 준비물 (PD님 수작업 필요)

### 1. Discord 서버·채널·webhook 준비

**추천 채널 구조:**
```
BurningTimes 서버
├── #pm-inbox        ← PM 수신 알림
├── #dev-inbox       ← 개발실 수신 알림
├── #plan-inbox      ← 기획실 수신 알림
└── #core-rules      ← 조직공지·코어룰 변경 전 조직 알림
```

**각 채널의 webhook URL 발급 방법:**
1. Discord 채널 우클릭 → 채널 편집 → 연동(Integrations)
2. Webhook 만들기 → 이름 지정 (예: "BurningTimes-git") → 복사 URL
3. 4개 채널 각각 반복, 총 4개 URL 수집

### 2. NAS 저장소 접근

SSH 또는 NAS 관리 콘솔로 bare repo 경로 접근 가능해야 함.
- Gitea 기본 경로 예시: `/volume1/gitea-repos/BurningTimes/BurningTimesAi.git/`
- 또는 `/var/lib/gitea/repositories/BurningTimes/BurningTimesAi.git/`

정확한 경로는 NAS Gitea 관리자 페이지의 저장소 설정에서 확인.

---

## 설치 절차 (PD님 실행)

### STEP 1 — 스크립트 배치
레포 루트에 이미 커밋된 `scripts/nas_post_receive.sh` 를 NAS로 복사:

```bash
# 옵션 A: NAS에 SSH 접속해서 git pull
ssh admin@burning.i234.me
cd /path/to/local-clone
git pull origin main
cp scripts/nas_post_receive.sh /volume1/gitea-repos/BurningTimes/BurningTimesAi.git/hooks/post-receive
chmod +x /volume1/gitea-repos/BurningTimes/BurningTimesAi.git/hooks/post-receive

# 옵션 B: Gitea 관리 UI에 git hook 직접 붙여넣기
# 관리자 → Site Administration → Repositories → BurningTimesAi → Git Hooks → post-receive
# → scripts/nas_post_receive.sh 내용 전체 붙여넣기 → Update
```

### STEP 2 — 환경변수 파일 생성
webhook URL 보관 파일 생성. **본 파일은 절대 commit 금지** (C6 데이터 보호):

```bash
cat > /volume1/gitea-repos/BurningTimes/BurningTimesAi.git/hooks/post-receive-env <<'EOF'
PM_WEBHOOK_URL="https://discord.com/api/webhooks/..."
DEV_WEBHOOK_URL="https://discord.com/api/webhooks/..."
PLAN_WEBHOOK_URL="https://discord.com/api/webhooks/..."
ALL_WEBHOOK_URL="https://discord.com/api/webhooks/..."
EOF

chmod 600 /volume1/gitea-repos/BurningTimes/BurningTimesAi.git/hooks/post-receive-env
```

※ Gitea 관리 UI만 허용되는 환경이면 nas_post_receive.sh 내부 `source "$ENV_FILE"` 대신 직접 상단에 4개 URL을 변수로 하드코딩. 단 이 경우 script 파일 자체의 권한을 600으로 제한 필수.

### STEP 3 — 테스트
BurningTimesAi 저장소에 **의미 없는 테스트 커밋** push:
```bash
cd E:\BurningTimesAi
echo "" >> 공유/조직공지/.test_phase3.md
git add 공유/조직공지/.test_phase3.md
git commit -m "test(phase3): post-receive webhook 검증"
git push origin main

# 기대 결과: Discord #core-rules 채널에 즉시 알림 도착 ✅

# 테스트 커밋 원복
git rm 공유/조직공지/.test_phase3.md
git commit -m "revert: phase3 테스트 커밋"
git push origin main
```

### STEP 4 — 설치 완료 보고
PD님이 다음 경로로 완료 보고 파일을 작성·커밋:
- `공유/소통/PD→PM/2026-MM-DD_Phase3_설치완료.md` (또는 기존 PD 로그)
- 제가 fetch 확인 후 Phase 3 가동 확정.

---

## 트러블슈팅

| 증상 | 원인 | 해결 |
|------|------|------|
| Discord에 메시지 안 옴 | webhook URL 잘못 | hooks/post-receive.log 확인, curl 수동 테스트 |
| 한글 파일명 깨짐 | NAS locale 설정 | `LC_ALL=ko_KR.UTF-8` 를 post-receive 상단 추가 |
| 모든 변경에 알림 안 감 | 경로 패턴 미매치 | nas_post_receive.sh 의 case 절 경로를 실제 변경 파일로 조정 |
| curl 명령 없음 | NAS busybox 환경 | wget 또는 nc(netcat) 기반으로 변환 필요. 별도 안건 |

---

## 보안·C6 준수

- `post-receive-env` 파일은 **절대 commit 금지**. `.gitignore` 무관 (NAS bare repo 파일)
- webhook URL 유출 시 즉시 Discord 채널 편집 → Webhook 삭제·재발급
- Discord 서버 자체의 사용자 초대·역할 관리는 PD님 전적 관리

---

## 연관
- **Phase 1** (a556d6a): 공유/소통/ 허브 6축 — 본 알림의 입력
- **Phase 2** (9a6ef2f): SessionStart inbox_scan — 세션 내 알림
- **Phase 3** (본 문서): NAS 서버측 실시간 알림 — 세션 외 알림
- **C21**(초안): C21-1 즉시 push 의무 → Phase 3 알림 실효성의 전제
- **C22**: 본 가이드의 용어(Phase 3, inbox, webhook)는 이후 변경 금지

## 상태

- [x] scripts/nas_post_receive.sh 커밋 완료
- [x] 본 설치 가이드 커밋 완료
- [ ] PD님: Discord 서버·채널·webhook URL 4개 준비
- [ ] PD님: NAS에 hook 스크립트 배치 + env 파일 생성
- [ ] PD님: 테스트 커밋 1건 push → Discord 수신 확인
- [ ] 총괄PM: 수신 확인 보고 수령 후 Phase 3 가동 확정

**준비 완료 시 본 문서의 status 를 `완료` 로 갱신 후 commit·push 부탁드립니다.**