Cloudflare Error Analysis and Improvement

📋 에러 분석

에러 1: KV Namespace 부재

KV namespace 'DOMAIN_KV' not found for staging environment

위치: verify-resources.sh 실행 중

원인 분석:

프로비저닝 실패: provision_kv_namespace 함수가 KV를 생성하지 못함
환경 불일치: wrangler kv namespace list --env staging이 올바른 환경을 확인하지 못함
생성 로직 문제: KV 생성 후 ID 추출 실패

에러 2: tmate Action 파라미터 오류

Unexpected input(s) 'limit-access-to-this-repository', 'timeout-minutes'

위치: deploy.yml의 tmate action 설정

원인: mxschmitt/action-tmate@v3에서 지원하지 않는 파라미터 사용

지원되는 파라미터:

sudo
install-dependencies
limit-access-to-actor (not limit-access-to-this-repository)
detached
connect-timeout-seconds (not timeout-minutes)
tmate-server-host
tmate-server-port
github-token

에러 3: 실행 시간 과다

증상: Provision 단계에서 시간이 너무 오래 걸림

원인 분석:

순차적 리소스 생성: D1 → KV → Queue를 순차적으로 생성
재시도 로직: 실패 시 재시도로 인한 지연
API 호출 과다: 각 리소스마다 여러 API 호출

🔍 현재 설정 확인

1. 로컬 환경 설정

wrangler.jsonc 확인

Dev 환경:

"kv_namespaces": [
  {
    "binding": "DOMAIN_KV",
    "id": "dev_kv_namespace_id",  // ❌ Placeholder
    "preview_id": "dev_kv_preview_id"
  }
]

Staging 환경 (확인 필요):

staging_kv_namespace_id placeholder일 가능성
실제 KV Namespace ID가 설정되지 않음

2. GitHub Actions 설정

provision-resources.sh 동작

현재 흐름:

D1 Database 프로비저닝
KV Namespace 프로비저닝
wrangler.jsonc 업데이트
Queue 프로비저닝
검증 단계에서 실패 ← 여기서 KV 부재 감지

문제점:

KV 생성은 시도하지만, 생성 후 ID 추출 실패
또는 생성 자체가 실패했지만 에러가 제대로 전파되지 않음

3. Cloudflare 가이드 준수 여부

✅ 준수 중

✅ Secrets 관리: GitHub Secrets 사용
✅ 커밋 컨벤션: 구조화된 메시지 사용

❌ 미준수

❌ 로컬 시뮬레이션: wrangler dev --remote 사용 안 함
❌ 실시간 로그: wrangler tail 통합 없음
❌ 단계적 롤아웃: 롤백 메커니즘 없음
❌ KISS 원칙: 복잡한 프로비저닝 로직

🎯 문제점 요약

Critical (배포 실패)

KV Namespace 부재
- Staging 환경에 DOMAIN_KV 네임스페이스가 없음
- 프로비저닝이 실패하거나 생성 후 ID 추출 실패
tmate Action 파라미터 오류
- 잘못된 파라미터로 인한 Action 실패
- 디버깅 세션 접근 불가

High (성능 및 안정성)

프로비저닝 시간 과다
- 순차적 리소스 생성으로 인한 지연
- 재시도 로직으로 인한 추가 지연
로컬-CI 환경 불일치
- 로컬에서는 dev 환경만 사용
- CI에서는 staging/production 환경 사용
- 환경별 리소스 상태 불일치

Medium (개선 필요)

Cloudflare 가이드 미준수
- 로컬 시뮬레이션 부재
- 실시간 로그 모니터링 부재
- 롤백 메커니즘 부재

🔧 개선 기획안

Phase 1: 즉시 수정 (Critical)

1.1 KV Namespace 생성 로직 개선

문제: KV 생성 후 ID 추출 실패 또는 생성 자체 실패

해결 방안:

방안 A: 생성 후 즉시 검증

# create_kv_namespace 함수 개선
create_kv_namespace() {
  local env="$1"
  local namespace="DOMAIN_KV"

  # 생성 시도
  local create_output
  create_output=$(npx wrangler kv namespace create "$namespace" --env "$env" 2>&1)

  # 생성 성공 확인
  if echo "$create_output" | grep -qi "created\|success"; then
    # 즉시 리스트하여 ID 추출
    sleep 2  # 생성 전파 대기
    local kv_list
    kv_list=$(npx wrangler kv namespace list --env "$env" 2>&1)
    kv_id=$(get_kv_id_from_list "$env" "$kv_list")

    if [[ -n "$kv_id" ]]; then
      echo "$kv_id"
      return 0
    fi
  fi

  # 생성 실패 또는 ID 추출 실패
  echo "❌ Failed to create or extract KV namespace ID" >&2
  echo "Output: $create_output" >&2
  return 1
}

방안 B: 사전 생성 스크립트

# 로컬에서 미리 리소스 생성
wrangler kv namespace create DOMAIN_KV --env staging
wrangler kv namespace create DOMAIN_KV --env production

권장: 방안 A (자동 생성) + 방안 B (수동 생성 옵션)

1.2 tmate Action 파라미터 수정

현재 (잘못됨):

- name: Setup tmate session (on failure)
  if: failure()
  uses: mxschmitt/action-tmate@v3
  with:
    limit-access-to-this-repository: true  # ❌ 지원 안 함
    timeout-minutes: 30  # ❌ 지원 안 함

수정 후:

- name: Setup tmate session (on failure)
  if: failure()
  uses: mxschmitt/action-tmate@v3
  with:
    limit-access-to-actor: true  # ✅ 올바른 파라미터
    connect-timeout-seconds: 1800  # ✅ 30분 = 1800초

Phase 2: 성능 개선 (High Priority)

2.1 병렬 리소스 프로비저닝

현재 (순차적):

D1 생성 (30초) → KV 생성 (30초) → Queue 생성 (60초) = 120초

개선 후 (병렬):

D1 생성 (30초) ┐
KV 생성 (30초) ├→ 동시 실행 = 60초
Queue 생성 (60초) ┘

구현:

# provision-resources.sh 개선
provision_resources_parallel() {
  local env="$1"

  # 백그라운드로 병렬 실행
  provision_d1_database "$env" > /tmp/d1-output.txt 2>&1 &
  D1_PID=$!

  provision_kv_namespace "$env" > /tmp/kv-output.txt 2>&1 &
  KV_PID=$!

  # 대기
  wait $D1_PID
  D1_EXIT=$?

  wait $KV_PID
  KV_EXIT=$?

  # 결과 확인
  if [[ $D1_EXIT -ne 0 ]] || [[ $KV_EXIT -ne 0 ]]; then
    echo "❌ Resource provisioning failed"
    return 1
  fi

  # Queue는 순차적으로 (의존성)
  provision_queues "$env"
}

2.2 리소스 존재 확인 최적화

현재: 각 리소스마다 개별 API 호출

개선: Bulk API 사용

# 한 번의 API 호출로 모든 리소스 확인
wrangler d1 list
wrangler kv namespace list --env staging
wrangler queues list

Phase 3: Cloudflare 가이드 준수 (Medium Priority)

3.1 로컬 시뮬레이션 강화

현재: wrangler dev --local만 사용

개선: wrangler dev --remote 추가

# package.json에 추가
"dev:remote:staging": "wrangler dev --remote --env staging",
"dev:remote:production": "wrangler dev --remote --env production"

사용법:

# Staging 환경과 동일한 리소스로 로컬 테스트
pnpm dev:remote:staging

3.2 실시간 로그 모니터링 통합

현재: 로그 확인이 수동

개선: 배포 후 자동 로그 스트림

- name: Start Log Monitoring
  if: success()
  run: |
    echo "📊 Starting log monitoring..."
    timeout 60 wrangler tail --env "${{ steps.env.outputs.environment }}" &
    LOG_PID=$!
    sleep 10  # 초기 요청 확인
    kill $LOG_PID 2>/dev/null || true

3.3 롤백 메커니즘 추가

현재: 롤백 기능 없음

개선: 배포 전 버전 백업 및 롤백 스크립트

#!/bin/bash
ENV="${1:-staging}"

echo "🔄 Rolling back to previous version..."

# 이전 배포 버전 확인
PREVIOUS_VERSION=$(wrangler deployments list --env "$ENV" | head -2 | tail -1 | awk '{print $1}')

if [[ -n "$PREVIOUS_VERSION" ]]; then
  wrangler rollback --env "$ENV" --message "Rollback to $PREVIOUS_VERSION"
  echo "✅ Rolled back to version: $PREVIOUS_VERSION"
else
  echo "❌ No previous version found"
  exit 1
fi

Phase 4: KISS 원칙 적용 (Simplification)

4.1 프로비저닝 로직 단순화

현재: 복잡한 재시도 및 에러 처리

개선: 단순한 “존재 확인 → 없으면 생성” 로직

# 단순화된 프로비저닝
provision_simple() {
  local env="$1"
  local resource_type="$2"
  local resource_name="$3"

  # 존재 확인
  if resource_exists "$resource_type" "$resource_name" "$env"; then
    echo "✅ $resource_name already exists"
    return 0
  fi

  # 생성
  if create_resource "$resource_type" "$resource_name" "$env"; then
    echo "✅ $resource_name created"
    return 0
  else
    echo "❌ Failed to create $resource_name"
    return 1
  fi
}

4.2 환경별 리소스 사전 생성

방안: 수동으로 한 번만 생성, 이후는 자동 검증만

#!/bin/bash
# 한 번만 실행하여 모든 환경의 리소스 생성

ENVIRONMENTS=("dev" "staging" "production")

for env in "${ENVIRONMENTS[@]}"; do
  echo "🔧 Setting up resources for $env..."

  # D1
  wrangler d1 create "newsfork-metadata-${env}" || echo "D1 may already exist"

  # KV
  wrangler kv namespace create DOMAIN_KV --env "$env" || echo "KV may already exist"

  # Queues
  for queue in research contract liveness seed domain; do
    wrangler queues create "newsfork-${queue}-${env}" || echo "Queue may already exist"
  done

  # DLQ
  wrangler queues create "newsfork-dlq-${env}" || echo "DLQ may already exist"
  wrangler queues create "newsfork-seed-dlq-${env}" || echo "Seed DLQ may already exist"
  wrangler queues create "newsfork-domain-dlq-${env}" || echo "Domain DLQ may already exist"
done

장점:

✅ 한 번만 실행
✅ CI에서는 검증만 수행 (빠름)
✅ KISS 원칙 준수

📊 개선 효과 예상

Before (현재)

❌ KV Namespace 부재 → 배포 실패
❌ tmate Action 오류 → 디버깅 불가
❌ 프로비저닝 시간: 120초+
❌ 로컬-CI 환경 불일치

After (개선 후)

✅ KV Namespace 자동 생성 또는 사전 생성
✅ tmate Action 정상 동작
✅ 프로비저닝 시간: 60초 (50% 단축)
✅ 로컬-CI 환경 일치 (wrangler dev --remote)
✅ 롤백 메커니즘 추가
✅ 실시간 로그 모니터링

🎯 구현 우선순위

Phase 1: 즉시 수정 (Critical) - 1시간

✅ tmate Action 파라미터 수정
✅ KV Namespace 생성 로직 개선
✅ 에러 메시지 명확화

Phase 2: 성능 개선 (High) - 2시간

✅ 병렬 리소스 프로비저닝
✅ 리소스 존재 확인 최적화

Phase 3: 가이드 준수 (Medium) - 3시간

✅ 로컬 시뮬레이션 강화 (wrangler dev --remote)
✅ 실시간 로그 모니터링 통합
✅ 롤백 메커니즘 추가

Phase 4: 단순화 (Low) - 2시간

✅ 프로비저닝 로직 단순화
✅ 환경별 리소스 사전 생성 스크립트

📝 체크리스트

즉시 수정 필요

tmate Action 파라미터 수정
KV Namespace 생성 로직 개선
에러 메시지 명확화

성능 개선

병렬 리소스 프로비저닝
리소스 존재 확인 최적화

Cloudflare 가이드 준수

wrangler dev --remote 스크립트 추가
실시간 로그 모니터링 통합
롤백 메커니즘 추가

단순화

프로비저닝 로직 단순화
환경별 리소스 사전 생성 스크립트

🔍 현재 설정 확인 결과

로컬 환경

✅ wrangler dev --local: 정상 작동
❌ wrangler dev --remote: 스크립트 없음
❌ 환경별 리소스 사전 생성: 없음

GitHub Actions

✅ Secrets 관리: GitHub Secrets 사용
❌ tmate Action: 잘못된 파라미터
❌ KV 프로비저닝: 생성 실패 또는 ID 추출 실패
❌ 병렬 처리: 순차적 실행

Cloudflare 가이드 준수

❌ 로컬 시뮬레이션: --remote 옵션 미사용
❌ 실시간 로그: 통합 없음
❌ 롤백 메커니즘: 없음
❌ KISS 원칙: 복잡한 프로비저닝 로직

작성 일시: 2026-01-28
우선순위: Critical
예상 소요 시간: 8시간 (단계별 구현)