# task-932.4: Whisper GPU 서비스 인프라 완성 + InsuWiki 최종 연동

## SCQA

**S**: task-932.3에서 Whisper GPU HTTP 서비스(server.py)와 InsuWiki whisperStt.ts 통합 코드가 완성되었으며, GPU 모델 로딩 및 전사 기능이 정상 동작한다.

**C**: 두 가지 미해결 이슈가 남아 있었다: (1) GCP Cloud Functions → localhost:8200 접근 불가 (네트워크 격리), (2) systemd 서비스 미등록으로 서버 재부팅 시 자동 시작 불가. 이로 인해 InsuWiki의 2개 채널(보험명의정닥터, ins-king) 크롤링에서 Whisper GPU를 활용할 수 없었다.

**Q**: GCP Cloud Functions에서 로컬 Whisper GPU 서비스에 안전하게 접근 가능하도록 인프라를 완성할 수 있는가?

**A**: Cloudflare Tunnel + API 키 인증 미들웨어로 외부 접근 경로를 확보하고, systemd 사용자 서비스로 자동 시작을 구현했다. E2E 테스트에서 Tunnel을 통한 전사 요청이 HTTP 200으로 성공(응답시간 ~2초). 단, sudo 접근 불가로 방안 A(직접 포트 개방) 대신 방안 C(Cloudflare Tunnel)를 채택했으며, quick tunnel URL이 재시작 시 변경되는 제한이 있다.

## 작업 내용

### Step 1: Whisper GPU 서비스 시작 + 동작 확인
- `start-whisper-gpu.sh` 실행하여 서비스 기동
- health check: `curl http://localhost:8200/v1/health` → `{"status":"ok","model":"medium","device":"cuda","gpu_memory_used_mb":834}`
- GPU medium 모델 로딩: ~5초 (정상)

### Step 2: 네트워크 접근 방안 구현
- **방안 A(직접 포트 개방) 시도 → 실패**: `sudo ufw allow 8200/tcp` 불가 (sudo 패스워드 필요, 자동 실행 환경에서 입력 불가)
- **방안 C(Cloudflare Tunnel)로 전환**: cloudflared v2026.3.0 설치 → quick tunnel 생성
- 터널 URL: `https://alfred-suppliers-garcia-jam.trycloudflare.com`
- API 키 인증 미들웨어 추가 (server.py):
  - X-API-Key 헤더 검증 (hmac.compare_digest로 타이밍 공격 방지)
  - /v1/health: 인증 없이 접근 허용
  - localhost/127.0.0.1: 인증 건너뛰기
  - WHISPER_API_KEY 환경변수 미설정 시 인증 비활성화

### Step 3: systemd 서비스 등록
- sudo 없이 **사용자 레벨 systemd** (`systemctl --user`) 사용
- `whisper-gpu.service`: Whisper GPU 서비스 자동 시작
- `cloudflared-whisper.service`: Cloudflare Tunnel 자동 시작
- `loginctl enable-linger jay`: 부팅 시 로그인 없이도 서비스 시작

### Step 4: InsuWiki Firebase Functions 환경변수 설정
- `functions/.env` 파일 생성 (Firebase Functions 2세대, v5.1.1)
  - `LOCAL_WHISPER_URL=https://alfred-suppliers-garcia-jam.trycloudflare.com`
  - `WHISPER_API_KEY=<API_KEY>`
- whisperStt.ts의 `callLocalWhisper()`에 X-API-Key 헤더 조건부 추가

### Step 5: E2E 테스트 결과

| 테스트 | 결과 | 상세 |
|--------|------|------|
| Health check (localhost) | PASS | HTTP 200, GPU 메모리 834MB |
| Health check (tunnel) | PASS | HTTP 200, 응답시간 <1초 |
| 인증 없이 transcribe (tunnel) | PASS | HTTP 401 반환 |
| 올바른 API 키로 transcribe (tunnel) | PASS | HTTP 200, 전사 성공 |
| 잘못된 API 키로 transcribe (tunnel) | PASS | HTTP 401 반환 |
| localhost transcribe (키 없이) | PASS | HTTP 200, localhost 예외 정상 |

## 생성/수정 파일 목록

**수정:**
- `/home/jay/workspace/services/whisper-gpu/server.py` — API 키 인증 미들웨어 추가 (import hmac, 미들웨어 함수 42줄 추가)
- `/home/jay/workspace/scripts/start-whisper-gpu.sh` — .env.keys 자동 로드 추가
- `/home/jay/projects/insuwiki/functions/src/whisperStt.ts` — callLocalWhisper()에 X-API-Key 헤더 추가 (2줄 변경)
- `/home/jay/workspace/.env.keys` — WHISPER_API_KEY 항목 추가

**생성:**
- `/home/jay/.config/systemd/user/whisper-gpu.service` — Whisper GPU systemd 사용자 서비스
- `/home/jay/.config/systemd/user/cloudflared-whisper.service` — Cloudflare Tunnel systemd 사용자 서비스
- `/home/jay/workspace/scripts/start-cloudflared-whisper.sh` — Cloudflare Tunnel 시작 스크립트
- `/home/jay/projects/insuwiki/functions/.env` — Firebase Functions 환경변수
- `/home/jay/.local/bin/cloudflared` — Cloudflare Tunnel 바이너리

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **sudo 접근 불가로 방화벽 포트 개방 실패** — Cloudflare Tunnel(방안 C)로 전환하여 외부 접근 경로 확보. cloudflared v2026.3.0 설치, quick tunnel로 HTTPS 엔드포인트 제공.
2. **sudo 없이 시스템 레벨 systemd 등록 불가** — 사용자 레벨 systemd(`~/.config/systemd/user/`) 사용 + `loginctl enable-linger`로 부팅 시 자동 시작 보장.
3. **start-whisper-gpu.sh에서 WHISPER_API_KEY 미로드** — 스크립트에 `.env.keys` 자동 source 로직 추가 (환경변수 미설정 시에만).

### 범위 외 미해결 (2건)
1. **Cloudflare quick tunnel URL 변경 문제** — trycloudflare.com URL은 터널 재시작 시 변경됨. 영구 해결에는 Cloudflare 계정 생성 + named tunnel 설정 또는 sudo 접근 후 직접 포트 개방 필요. 범위 외 사유: 계정 생성/sudo 접근은 제이회장님 판단 필요.
2. **Firebase Functions 미배포** — firebase CLI 미인증 상태(`firebase login` 필요). functions/.env 파일은 생성 완료되었으나 실제 배포(deploy)는 미실행. 범위 외 사유: firebase 인증 토큰 부재.

## 셀프 QC

- [x] 1. 영향 파일: server.py(기존 엔드포인트 무변경 확인), whisperStt.ts(callLocalWhisper만 수정), .env.keys(추가만)
- [x] 2. 엣지 케이스: API 키 미설정 시 인증 비활성화, localhost 요청 시 인증 건너뛰기, 빈 API 키 전송 시 401
- [x] 3. 작업 지시 5개 Step 모두 수행 확인 (방안 A→C 전환은 인프라 제약으로 인한 합리적 대안)
- [x] 4. 보안: hmac.compare_digest 타이밍 공격 방지, API 키 하드코딩 없음, .env 파일 gitignore 확인
- [x] 5. E2E 테스트 6건 전체 통과
- [x] 6. 발견 이슈 3건 직접 해결, 범위 외 2건 사유 명시