Files
obsidian/services/bunnycdn.md

21 KiB

title, updated, tags
title updated tags
BunnyCDN Reference 2026-03-23
cdn
bunnycdn
infrastructure
reference

BunnyCDN Reference

Bunny.net CDN 공식 문서 기반 종합 레퍼런스. API, 설정, 보안, 가격 등 실무 참조용.

1. Pull Zone Configuration

Origin 설정

필드 타입 설명
OriginUrl string 파일을 가져올 원본 서버 URL
OriginType enum OriginUrl, DnsAccelerate, StorageZone, LoadBalancer, EdgeScript, MagicContainers, PushZone
OriginHostHeader string Origin으로 전송할 Host 헤더
AddHostHeader boolean 요청된 Host 헤더를 origin에 전달
DnsOriginPort int32 Origin 포트
DnsOriginScheme string Origin 프로토콜 (http/https)
StorageZoneId int64 Storage Zone을 origin으로 사용 시 ID
VerifyOriginSSL boolean Origin SSL 인증서 검증

캐싱 설정

필드 타입 설명
CacheControlMaxAgeOverride int64 캐시 제어 override (초)
CacheControlPublicMaxAgeOverride int64 브라우저 캐시 override (초)
IgnoreQueryStrings boolean 캐시 키에서 쿼리스트링 무시
QueryStringVaryParameters array 캐시 키에 사용할 특정 쿼리 파라미터
EnableCacheSlice boolean 비디오 최적화용 cache slicing
CacheErrorResponses boolean Origin 에러 응답도 캐시
UseStaleWhileUpdating boolean 업데이트 중 stale 캐시 제공
UseStaleWhileOffline boolean Origin 다운 시 stale 캐시 제공
UseBackgroundUpdate boolean 백그라운드 캐시 갱신
EnableSmartCache boolean 스마트 캐싱
EnableRequestCoalescing boolean 동일 요청 병합
RequestCoalescingTimeout int32 병합 락 시간
EnableQueryStringOrdering boolean 쿼리스트링 정렬로 캐시 히트율 향상

Cache Vary 설정

필드 설명
EnableWebpVary WebP 포맷별 캐시 분리
EnableAvifVary AVIF 포맷별 캐시 분리
EnableMobileVary 모바일 디바이스별 캐시 분리
EnableCountryCodeVary 국가별 캐시 분리
EnableHostnameVary 호스트네임별 캐시 분리
EnableCookieVary 쿠키별 캐시 분리
CookieVaryParameters Vary에 사용할 쿠키 목록

Origin Reliability

필드 설명
OriginRetries Origin 재시도 횟수
OriginConnectTimeout Origin 연결 타임아웃 (초)
OriginResponseTimeout Origin 응답 타임아웃 (초)
OriginRetry5XXResponses 5XX 에러 시 재시도
OriginRetryConnectionTimeout 연결 타임아웃 시 재시도
OriginRetryResponseTimeout 응답 타임아웃 시 재시도
OriginRetryDelay 재시도 전 대기 (ms)
FollowRedirects Origin 리다이렉트 시 캐시

Geo Zone (지역별 활성화)

  • EnableGeoZoneUS - 북미
  • EnableGeoZoneEU - 유럽
  • EnableGeoZoneASIA - 아시아/오세아니아
  • EnableGeoZoneSA - 남미
  • EnableGeoZoneAF - 아프리카

Pull Zone 타입

  • Type: Premium (Standard) 또는 Volume (High Volume)
  • Standard: 119 PoPs, 글로벌 최적 레이턴시
  • Volume: 10 PoPs, 대용량/비디오에 적합, 저렴

2. Custom Hostnames

설정 프로세스

  1. Pull Zone 생성 시 기본 호스트네임: {zonename}.b-cdn.net
  2. DNS에 CNAME 레코드 추가: cdn.example.com -> {zonename}.b-cdn.net
    • TTL: 3600 이하 권장
    • Proxy 옵션 비활성화 필수 (Cloudflare 등에서)
  3. Bunny 대시보드에서 Custom Hostname 추가
  4. SSL 인증서 설정

SSL 인증서 옵션

옵션 설명
Free Let's Encrypt 자동 발급/갱신. CNAME 설정 후 사용 가능
Custom Certificate Base64 인코딩된 인증서+키 업로드
Wildcard SSL Bunny DNS 사용 시만 자동 발급 가능, 아니면 커스텀 인증서 업로드 필요

ForceSSL

  • HTTP -> HTTPS 자동 리다이렉트
  • 호스트네임별 개별 설정 가능

SSL/TLS 프로토콜 설정

필드 설명
EnableTLS1 TLS 1.0 지원 (레거시, 비권장)
EnableTLS1_1 TLS 1.1 지원 (레거시, 비권장)
EnableAutoSSL 호스트네임 추가 시 자동 SSL
DisableLetsEncrypt Let's Encrypt 자동 발급 비활성화

SSL 인증서 유효성 검사

  • HTTP-01: 기본 방식 (useOnlyHttp01=true)
  • DNS-01: Bunny DNS Zone 존재 시 사용 가능 (useOnlyHttp01=false). 와일드카드 도메인은 DNS-01만 지원

3. Edge Rules

Action 타입 (11종)

Action 설명
Force SSL HTTP를 HTTPS로 리다이렉트
Redirect to URL 다른 URL로 리다이렉트
Change Origin URL 다른 origin 서버로 라우팅
Override Cache Time 커스텀 캐시 시간 설정
Block Request 조건 매칭 요청 차단
Set Response Header 응답 헤더 추가/수정
Set Request Header Origin으로 보내는 요청 헤더 추가/수정
Force Download 브라우저에서 파일 다운로드 강제
Disable/Enable Token Auth 요청별 토큰 인증 제어
Override Browser Cache Time 브라우저 캐시 시간 커스텀
Set Network Rate Limit 매칭 요청의 대역폭 제한

Trigger 타입

Trigger 설명
Request URL URL 경로 매칭
Request Header 특정 HTTP 헤더 매칭
Response Header 응답 헤더 매칭
Country Code GeoIP 국가 코드 매칭
Remote IP 클라이언트 IP 매칭
File Extension 파일 확장자 매칭

Match 조건

  • Match Any: 하나라도 매칭되면 실행
  • Match All: 모든 조건 매칭 시 실행
  • Match None: 어떤 것도 매칭되지 않을 때 실행
  • 하나의 룰에 여러 트리거 + 여러 액션 설정 가능

Variable Expansion

Edge Rules에서 %{Collection.Key} 문법으로 동적 변수 사용 가능.

지원 액션: Change Origin URL, Redirect to URL, Set Request Header, Set Response Header

Collection 변수 설명
RequestHeaders %{RequestHeaders.Host} 요청 Host 헤더
RequestHeaders %{RequestHeaders.User-Agent} User-Agent
RequestHeaders %{RequestHeaders.Accept-Language} 언어
Query %{Query.paramname} 쿼리 파라미터 값
Request %{Request.Method} HTTP 메서드
Request %{Request.Path} 전체 경로 (쿼리 포함)
Request %{Request.QueryString} 쿼리스트링만
Path %{Path.0}, %{Path.0-2}, %{Path.3-} URL 경로 세그먼트 (인덱스/범위)
Url %{Url.FileName} 파일명
Url %{Url.Extension} 확장자
Url %{Url.Directory} 디렉토리
Url %{Url.Hostname} 호스트네임
User %{User.IP} 클라이언트 IP
User %{User.CountryCode} 2자리 국가 코드
Server %{Server.ZoneCode} 서버 존 코드
Server %{Server.ID} 서버 ID

4. API Reference

기본 정보

  • Base URL: https://api.bunny.net
  • 인증: AccessKey 헤더에 API 키
  • API 키 위치: 대시보드 > Account > API Keys

API 카테고리

카테고리 설명
Pull Zones CDN 존 관리
Storage Zones 엣지 스토리지
DNS Zones DNS 관리
Stream Video Libraries 비디오 콘텐츠
Statistics 대역폭/성능 통계
Billing 과금/소비 데이터
Purge 캐시 무효화
API Keys 자격증명 관리
Countries 지역 차단 참조
Regions 엣지 서버 위치

주요 Pull Zone 엔드포인트

List Pull Zones

GET /pullzone
Query: page, perPage (5-1000), search, includeCertificate
Response: { Items[], CurrentPage, TotalItems, HasMoreItems }

Add Pull Zone

POST /pullzone
Body: { Name, OriginUrl, Type, ... }

Update Pull Zone

POST /pullzone/{id}
Body: (전체 설정 필드 - 섹션 1 참조)

Delete Pull Zone

DELETE /pullzone/{id}

Hostname 관리 엔드포인트

Add Custom Hostname

POST /pullzone/{id}/addHostname
Body: { "Hostname": "cdn.example.com" }
Response: 204

Remove Custom Hostname

DELETE /pullzone/{id}/removeHostname
Body: { "Hostname": "cdn.example.com" }
Response: 204

Set Force SSL

POST /pullzone/{id}/setForceSSL
Body: { "Hostname": "cdn.example.com", "ForceSSL": true }
Response: 204

Load Free Certificate (Let's Encrypt)

GET /pullzone/loadFreeCertificate?hostname=cdn.example.com&useOnlyHttp01=true
- useOnlyHttp01=false: Bunny DNS Zone 존재 시 DNS-01 검증 시도
- 와일드카드 도메인: DNS-01만 지원
Response: 200

Add Custom Certificate

POST /pullzone/{id}/addCertificate
Body: {
  "Hostname": "cdn.example.com",
  "Certificate": "<base64-encoded-cert>",
  "CertificateKey": "<base64-encoded-key>"
}
Response: 204

Cache Purge 엔드포인트

Purge Pull Zone Cache (전체 또는 태그별)

POST /pullzone/{id}/purgeCache
Body: { "CacheTag": "optional-tag" }  // CacheTag 생략 시 전체 퍼지
Response: 204

Purge URL (개별 URL)

POST /purge?url=https://cdn.example.com/path/file.js
Response: 204

5. Bunny Shield (DDoS Protection)

개요

Bunny Shield는 통합 보안 스택. 200+ Tbps 네트워크, 119개 글로벌 스크러빙 센터.

주요 기능 6가지

기능 설명
WAF OWASP Top 10, zero-day 익스플로잇 차단
DDoS Protection 대규모 공격 완화, stateful mitigation
Rate Limiting IP/사용자/경로별 요청 제한
Bot Detection 악성 봇 실시간 탐지/차단
Access Lists VPN, Tor 노드 등 차단
Upload Scanning 파일 바이러스/악성코드/CSAM 스캔

DDoS Protection 설정

Pull Zone 필드:

  • ShieldDDosProtectionEnabled: boolean
  • ShieldDDosProtectionType: DetectOnly, ActiveStandard, ActiveAggressive

DDoS 보호 메커니즘

  1. Stateful Request Tracking: 요청 정당성 검증
  2. JavaScript Proof-of-Work Challenge: 브라우저에 연산 과제 부여, 봇 차별화
  3. Behavioral Analysis: 실시간 트래픽 패턴 분석

DDoS Sensitivity 레벨

레벨 설명
Low 1 최소 보호
Medium 2 권장 시작점
High 3 강화 보호
Extreme 4 항시 활성화 (Always-On)

6. WAF (Web Application Firewall)

보호 범위

  • SQL Injection: 쿼리 파라미터/폼의 SQL 인젝션 탐지/차단
  • XSS Protection: 악성 스크립트 실행 시도 차단
  • Remote File Inclusion (RFI): 원격 서버 파일 포함 시도 차단
  • OWASP Top 10: 전체 커버리지

기능

  • AI 기반 자동 위협 탐지
  • 커스텀 보안 규칙 설정 가능
  • 실시간 트래픽 모니터링
  • 저레이턴시 처리
  • 정기적 위협 정의 업데이트

WAF 로그 API

GET https://api.bunny.net/shield/event-logs/{shieldZoneId}

차단/허용 트래픽의 상세 로그 조회.


7. Optimizer (Image Optimization)

가격

  • $9.50/월 per Pull Zone
  • 무제한 요청, 무제한 최적화, 무제한 이미지
  • 대역폭은 별도 과금

설정 필드

필드 설명
OptimizerEnabled Optimizer 활성화
OptimizerEnableWebP WebP 포맷 변환
OptimizerEnableManipulationEngine 이미지 조작 엔진
OptimizerImageQuality 데스크톱 이미지 품질 (1-100)
OptimizerMobileImageQuality 모바일 이미지 품질 (1-100)
OptimizerDesktopMaxWidth 데스크톱 최대 이미지 폭 (0-5000)
OptimizerMobileMaxWidth 모바일 최대 이미지 폭 (0-5000)
OptimizerMinifyCSS CSS 미니파이
OptimizerMinifyJavaScript JavaScript 미니파이
OptimizerPrerenderHtml SEO HTML 프리렌더
OptimizerAutomaticOptimizationEnabled 자동 최적화
OptimizerEnableUpscaling 이미지 업스케일링
OptimizerTunnelEnabled Origin 터널 최적화

Watermark 설정

필드 설명
OptimizerWatermarkEnabled 워터마크 활성화
OptimizerWatermarkUrl 워터마크 이미지 URL
OptimizerWatermarkPosition BottomLeft, BottomRight, TopLeft, TopRight, Center, CenterStretch
OptimizerWatermarkOffset 오프셋 거리
OptimizerWatermarkMinImageSize 워터마크 적용 최소 이미지 크기

Static HTML Optimization

  • OptimizerStaticHtmlEnabled: 정적 HTML 최적화
  • OptimizerStaticHtmlWordPressPath: WordPress 경로
  • OptimizerStaticHtmlWordPressBypassCookie: WordPress 바이패스 쿠키

8. DNS Integration

Bunny DNS 지원 레코드 타입

Enum 타입 설명
0 A IPv4
1 AAAA IPv6
2 CNAME Canonical Name
3 TXT 텍스트
4 MX 메일
5 Redirect (RDR) 리다이렉트 레코드
6 Flatten CNAME Flattening
7 PullZone Pull Zone 직접 매핑
8 SRV Service
9 CAA Certificate Authority Authorization
10 PTR Pointer
11 Script DNS 스크립트 연결
12 NS Name Server
13 SVCB Service Binding
14 HTTPS HTTPS Service
15 TLSA TLS Authentication

특수 레코드

  • PullZone 레코드: DNS 레코드를 기존 Pull Zone에 직접 매핑
  • Flatten 레코드: 루트 도메인에서 CNAME 기능 (ANAME 역할)
  • Script 레코드: DNS 스크립트 연결
  • Accelerated 레코드: CDN 가속을 위한 Pull Zone 연결 (Accelerated: true, AcceleratedPullZoneId)

DNS API

PUT /dnszone/{zoneId}/records
Body: {
  "Type": 0,          // 레코드 타입 enum
  "Name": "cdn",
  "Value": "1.2.3.4",
  "Ttl": 3600,
  "Priority": 0,
  "Accelerated": true,
  "PullZoneId": 12345,
  "AutoSslIssuance": true,
  "MonitorType": 0,   // 0-3
  "SmartRoutingType": 0, // 0-2
  "Comment": "CDN record"
}
Response: 201

DNS 모니터링

Bunny DNS는 레코드 모니터링 기능 내장 (MonitorType 필드).


9. Origin Shield

개요

Origin Shield는 CDN 엣지 PoP와 Origin 사이의 2차 캐싱 레이어. 전 세계 여러 PoP에서 같은 파일 요청 시, Origin Shield가 단일 캐싱 포인트로 동작하여 Origin 트래픽을 대폭 감소.

설정 필드

필드 설명
EnableOriginShield Origin Shield 활성화
OriginShieldZoneCode Shield 위치 존 코드
OriginShieldEnableConcurrencyLimit 동시 요청 제한
OriginShieldMaxConcurrentRequests 최대 동시 요청 수
OriginShieldQueueMaxWaitTime 큐 최대 대기 시간 (ms)
OriginShieldMaxQueuedRequests 최대 큐 요청 수

동작 방식

사용자 -> 엣지 PoP (1차 캐시) -> Origin Shield (2차 캐시) -> Origin 서버
  • 엣지 PoP 캐시 미스 시, Origin 직접 요청 대신 Origin Shield에 요청
  • Origin Shield에 캐시가 있으면 바로 응답
  • Origin Shield도 캐시 미스면 Origin에 1회만 요청

10. WebSocket Support

설정

필드 타입 설명
EnableWebSockets boolean WebSocket 프로토콜 연결 허용
MaxWebSocketConnections int32 최대 동시 WebSocket 연결 (500-25,000)

11. Logging and Monitoring

로그 설정

필드 설명
EnableLogging 액세스 로깅 활성화
LogFormat Plain 또는 JSON
LoggingIPAnonymizationEnabled IP 익명화
LogAnonymizationType OneDigit 또는 Drop
LoggingSaveToStorage 로그를 Storage Zone에 저장
LoggingStorageZoneId 로그 저장 Storage Zone ID

Log Forwarding (실시간 로그 전송)

필드 설명
LogForwardingEnabled 로그 포워딩 활성화
LogForwardingHostname Syslog 엔드포인트 호스트
LogForwardingPort 포트
LogForwardingToken 인증 토큰
LogForwardingProtocol UDP, TCP, TCPEncrypted, DataDog
LogForwardingFormat Plain 또는 JSON

Log Forwarding 특성

  • Syslog RFC 5424 포맷
  • 10-30초 딜레이
  • UDP: 암호화 없음, 패킷 손실 가능
  • TCP/TCPEncrypted: 안정적 전송
  • DataDog 직접 연동 지원

보안/접근제어 관련 로깅

  • WAF 로그: GET /shield/event-logs/{shieldZoneId}
  • Pull Zone 통계: Statistics API

12. Pricing

Monthly Minimum

$1/월

Standard Network (119 PoPs)

지역 가격/GB
Europe & North America $0.01
Asia & Oceania $0.03
South America $0.045
Middle East & Africa $0.06

Volume Network (10 PoPs)

구간 가격/GB
0 - 500 TB $0.005
500 TB - 1 PB $0.004
1 PB - 2 PB $0.002
2 PB+ 커스텀 (영업 문의)

추가 서비스 가격

서비스 가격
Bunny Optimizer $9.50/월 per Pull Zone
Bunny Shield 별도 (보안 기능 통합)
Storage Zone 별도 과금
Stream 별도 과금

Pull Zone 설정으로 비용 제어

  • MonthlyBandwidthLimit: 월간 대역폭 한도 (bytes)
  • BudgetRedirectedCountries: 특정 국가를 저렴한 지역으로 리다이렉트
  • 지역별 Geo Zone 활성화/비활성화로 과금 지역 제어
  • 언제든 Standard <-> Volume 전환 가능

13. Security & Access Control (기타)

Referrer/IP 제어

필드 설명
AllowedReferrers 허용 Referrer 호스트 목록
BlockedReferrers 차단 Referrer 호스트 목록
BlockNoneReferrer Referrer 없는 직접 접근 차단
BlockedIps IP 차단 목록
BlockedCountries 국가 코드 차단 (2자리)
BlockRootPathAccess 루트 경로 접근 차단
BlockPostRequests POST 요청 차단

Rate Limiting (Pull Zone 레벨)

필드 설명
ConnectionLimitPerIPCount IP당 최대 연결 수
RequestLimit 초당 최대 요청
LimitRatePerSecond IP별 초당 속도 제한
LimitRateAfter 속도 제한 전 전송량
BurstSize IP 차단 전 최대 버스트

Token Authentication

  • ZoneSecurityEnabled: URL 토큰 인증 활성화
  • ZoneSecurityIncludeHashRemoteIP: 토큰에 원격 IP 포함

CORS

  • EnableAccessControlOriginHeader: CORS 헤더 활성화
  • AccessControlOriginHeaderExtensions: CORS 적용 파일 확장자

AWS S3 Origin 연동

  • AWSSigningEnabled: AWS 요청 서명
  • AWSSigningKey, AWSSigningSecret, AWSSigningRegionName

14. 기타 기능

Perma-Cache

  • PermaCacheStorageZoneId: 영구 캐시용 Storage Zone
  • PermaCacheType: Automatic 또는 Manual

Custom Error Pages

  • ErrorPageEnableCustomCode: 커스텀 에러 페이지 HTML
  • ErrorPageCustomCode: HTML 코드
  • ErrorPageWhitelabel: 브랜딩 제거

Preloading Screen

  • PreloadingScreenEnabled: 로딩 화면 표시
  • PreloadingScreenTheme: Light / Dark
  • PreloadingScreenDelay: 표시 전 딜레이 (0-10,000ms)
  • DDoS Challenge 등에서 사용

Sticky Sessions

  • StickySessionType: Off / On
  • StickySessionCookieName: 세션 쿠키 이름
  • StickySessionClientHeaders: 클라이언트 식별 헤더

AI 기능

  • EnableBunnyImageAi: AI 이미지 생성
  • BunnyAiImageBlueprints: AI 이미지 블루프린트

15. 엣지 스크립트 보안 (CrowdSec + 국가 차단)

구성

  • 스크립트: crowdsec-bouncer-middleware (ID: 64811)
  • 연결된 Pull Zone: inouter (5316471), actions (5330178)
  • 관리: cfb-manager (K3s tools ns)

동작 순서

요청 → BunnyCDN 엣지
  1. 국가 차단 (Cdn-RequestCountryCode 헤더)
     - 차단: US,CA,GB,DE,FR,IT,ES,NL,BE,AT,CH,SE,NO,DK,FI,PL,CZ,PT,IE,RO,HU,BG,HR,SK,SI,LT,LV,EE,LU,MT,CY,GR,IS,UA,RU,BY
     - 차단 시 403 반환
  2. CrowdSec bloom filter (악성 IP 판별)
     - bloom filter에 hit → 캡차 또는 403
     - cfb-manager가 주기적으로 bloom filter 업데이트
  3. 캡차 (Cloudflare Turnstile)
     - bloom hit된 IP에게 캡차 제시
     - 통과 시 4시간 허용 (DB + 쿠키)
  4. 정상 → Origin으로 전달

주의사항

  • BunnyCDN Traffic Manager 국가 차단은 사용하지 않음 (Let's Encrypt/Origin Shield 문제 유발)
  • 엣지 스크립트의 국가 차단은 Cdn-RequestCountryCode 헤더 기반이라 내부 요청에 영향 없음
  • Free SSL 발급: 국가 차단이 엣지 스크립트에 있으므로 Let's Encrypt 검증 통과 가능

Pull Zone 설정

  • Origin: HTTPS (서울 220.120.65.245, 오사카 172.233.93.180)
  • VerifyOriginSSL: false
  • 국가 차단(BlockedCountries): 비어있음 (엣지 스크립트에서 처리)
  • Origin Shield: 비활성화

참고 링크