본문으로 바로가기 본문 바로가기
WIKI 기술 지식 베이스

캐시 키

원문 보기 위키 갱신

캐시 키 (Cache keys)

캐시 키(Cache Key)는 Cloudflare가 캐시의 파일에 사용하는 식별자이고, 캐시 키 템플릿(Cache Key Template)은 주어진 HTTP 요청에 대한 식별자를 정의해요.

출처: 문서

본문

기본 캐시 키에는 다음이 포함돼요:

  1. 전체 URL:
    • scheme — HTTP 또는 HTTPS일 수 있어요.
    • host — 예: www.cloudflare.com
    • 쿼리 문자열이 있는 URI — 예: /logo.jpg?utm_source=newsletter
  2. 클라이언트가 보낸 Origin 헤더(CORS 지원용).
  3. x-http-method-override, x-http-method, x-method-override 헤더.
  4. x-forwarded-host, x-host, x-forwarded-scheme(http 또는 https가 아닌 경우), x-original-url, x-rewrite-url, forwarded 헤더.

커스텀 캐시 키 만들기

커스텀 캐시 키를 사용하면 어떤 리소스에 대해서도 캐시 가능 설정을 정밀하게 지정할 수 있어요. 더 많은 제어를 제공하지만 캐시 적중률을 낮추고 캐시 분할(sharding)을 초래할 수 있어요:

  1. Cloudflare 대시보드에서 Cache Rules 페이지로 이동해요. Cache Rules 열기 ↗
  2. Create rule을 선택해요.
  3. When incoming requests match 아래에서 규칙 표현식을 정의해요.
  4. Then 아래의 Cache eligibility 섹션에서 Eligible for cache를 선택해요.
  5. Cache Key 설정을 규칙에 추가하고 적절한 Query String 설정을 선택해요.
  6. Headers, Cookie, Host, User 설정도 선택할 수 있어요.
  7. 규칙을 저장하고 배포하려면 Deploy를 선택해요. 배포할 준비가 안 됐다면 Save as Draft를 선택해요.

참고 — URL 정규화가 활성화되면, 특히 커스텀 캐시 키를 설정하거나(캐시 키도 수정하는) 기기 유형별 캐시를 사용하는 경우 Normalize URLs to origin도 활성화하는 것을 권장해요. 이렇게 하면 캐시 키의 URL이 오리진으로 보내는 URL과 일치하도록 보장해 캐시 포이즈닝을 방지하고 일관된 동작을 보장해요.

캐시 키 템플릿

캐시 키 템플릿을 변경하는 일반적인 이유가 몇 가지 있어요. 캐시 키 템플릿을 변경하는 목적:

  • 캐시를 분할해 하나의 URL을 여러 파일에 저장하기. 예를 들어 URL의 특정 쿼리 문자열에 기반해 다른 파일을 저장하려는 경우.
  • 캐시를 통합해 서로 다른 HTTP 요청을 같은 파일에 저장하기. 예를 들어 기본적으로 Cloudflare 캐시 키에 추가되는 Origin 헤더를 제거하려는 경우.

SSL 설정이 캐시 동작에 미치는 영향

Cloudflare의 $scheme 변수는 캐싱 동작에서 핵심 역할을 하지만, 그 의미는 캐시 키 유형에 따라 달라져요:

  • 기본 캐시 키: $scheme은 오리진 scheme을 가리켜요. 즉 Cloudflare가 오리진 서버에 연결할 때 사용하는 프로토콜(HTTP 또는 HTTPS)이에요. 이 구성에서는 SSL 설정 변경(예: Flexible에서 Full로 전환)이 오리진 scheme을 바꿔요. 캐시 키가 오리진 scheme을 포함하므로, 이런 변경은 캐시 버스트(cache bust)를 트리거해 Cloudflare가 오리진에서 콘텐츠를 다시 가져와야 해요.
  • 커스텀 캐시 키: $scheme은 방문자 scheme을 가리켜요. 즉 Cloudflare에 요청하는 클라이언트가 사용하는 프로토콜이에요. 이 경우 커스텀 구성에 오리진 scheme이 명시적으로 포함되지 않는 한 SSL 설정 변경은 캐시 키에 영향을 주지 않아요.

예를 들어 Flexible SSL에서는 방문자가 HTTP를 사용하든 HTTPS를 사용하든 Cloudflare가 항상 HTTP로 오리진에 연결해요. 이로 인해 기본 구성 아래에서 두 프로토콜 모두 같은 캐시 키를 갖게 돼요.

기본 캐시 키를 사용할 때 SSL 설정 변경이 캐시 무효화로 이어질 수 있다는 점을 유의해요:

  • Off에서 Full, Full (strict), 또는 Strict로 전환하면 오리진 scheme이 HTTP에서 HTTPS로 바뀌어 캐시 버스트가 발생해요.
  • Flexible에서 Full, Full (strict), 또는 Strict로 이동하면 역시 오리진 scheme이 HTTPS로 바뀌고 캐시 버스트가 발생해요.

SSL 모드를 수정할 때 예상치 못한 캐시 동작을 피하려면 $scheme이 캐싱 구성과 어떻게 상호작용하는지 이해하는 것이 필수적이에요.

Cache Level: Ignore Query String

Cache Level이 Ignore Query String이면 기본 캐시 키의 모든 요소를 포함하되 URI의 쿼리 문자열은 더 이상 포함하지 않는 캐시 키를 만들어요. 예를 들어 http://example.com/file.jpg?something=123에 대한 요청과 http://example.com/file.jpg?something=789에 대한 요청은 이 경우 같은 캐시 키를 갖게 돼요.

캐시 키 설정

다음 필드가 캐시 키 템플릿을 제어해요.

Query String

쿼리 문자열은 어떤 URL 쿼리 문자열 매개변수가 캐시 키에 들어가는지 제어해요. 해당 필드를 사용해 특정 쿼리 문자열 매개변수를 include(포함)하거나 exclude(제외)할 수 있어요. 쿼리 문자열 매개변수를 포함하면 그 매개변수의 값이 캐시 키에 사용돼요.

예시

https://www.example.com/?foo=bar 같은 URL에서 쿼리 문자열 foo를 포함하면 bar가 캐시 키에 나타나요. include와 exclude 중 정확히 하나만 기대돼요.

사용 참고

  • 모든 쿼리 문자열 매개변수를 포함하려면(기본 동작) include: "*"를 사용해요.
  • 쿼리 문자열을 무시하려면 exclude: "*"를 사용해요.
  • 대부분의 쿼리 문자열 매개변수를 포함하되 일부만 제외하려면 exclude 필드를 사용해요. 그러면 다른 쿼리 문자열 매개변수는 포함된 것으로 간주돼요.

Headers

Headers는 어떤 헤더가 캐시 키에 들어가는지 제어해요. Query String과 유사하게 특정 헤더를 포함하거나 기본 헤더를 제외할 수 있어요.

헤더를 포함하면 그 헤더 값이 캐시 키에 포함돼요. 예를 들어 HTTP 요청에 X-Auth-API-Key: 12345 같은 HTTP 헤더가 있고 캐시 키 템플릿에 X-Auth-API-Key 헤더를 포함하면 12345가 캐시 키에 나타나요.

Include headers and selected values 섹션에서 헤더 이름과 값을 캐시 키에 추가할 수 있어요. 커스텀 헤더의 경우 값은 선택 사항이지만, 다음 제한된 헤더의 경우 1~10개의 특정 값을 포함해야 해요:

  • accept
  • accept-charset
  • accept-encoding
  • accept-datetime
  • accept-language
  • referer
  • user-agent

주의 — 커스텀 및 제한된 헤더의 경우 선택된 값은 대소문자를 구분하는 부분 문자열 일치(substring matching)를 사용해요. 예를 들어 text/plain은 Accept 헤더 값 text/plain, foo/bar와 일치해요. 의도하지 않은 값 text/plaintext와도 일치할 수 있지만 Text/Plain과는 일치하지 않아요.

헤더의 실제 값을 포함하지 않고 존재 여부만 확인하려면 Check presence of 옵션을 사용해요.

현재 Origin 헤더만 제외할 수 있어요. Origin 헤더는 명시적으로 제외하지 않는 한 항상 포함돼요. Origin 헤더 ↗︎를 캐시 키에 포함하는 것은 CORS ↗︎를 강제하는 데 중요해요.

또한 다음 헤더는 포함할 수 없어요:

  • 캐시나 프록시 기능을 재구현하는 헤더
    • connection
    • content-length
    • cache-control
    • if-match
    • if-modified-since
    • if-none-match
    • if-unmodified-since
    • range
    • upgrade
  • 다른 캐시 키 기능으로 다루어지는 헤더
    • cookie
    • host
  • Cloudflare 전용으로 cf- 접두사가 붙은 헤더, 예: cf-ray
  • 커스텀 캐시 키 템플릿에 이미 포함된 헤더, 예: origin

Host

Host는 어떤 host 헤더를 캐시 키에 포함할지 결정해요.

  • Use original host(API에서 resolved: false)이면 Cloudflare는 오리진으로 보내는 HTTP 요청에 Host 헤더를 포함해요.
  • Resolved host(API에서 resolved: true)이면 Cloudflare는 요청의 origin IP를 찾기 위해 해석된 Host 헤더를 포함해요. 이 Host 헤더는 Origin Rule로 변경된 경우 실제로 보내진 헤더와 다를 수 있어요.

query_string이나 header처럼 cookie는 어떤 쿠키가 캐시 키에 나타나는지 제어해요. 쿠키 값을 포함하거나 특정 쿠키의 존재를 확인할 수 있어요.

사용 참고

Cloudflare 전용 쿠키는 포함할 수 없어요. Cloudflare 쿠키는 __cf 접두사가 붙어요. 예: __cflb

사용자 기능

사용자 기능 필드는 최종 사용자(클라이언트)에 관한 기능을 캐시 키에 추가해요.

  • device_type — User Agent에 기반해 요청을 mobile, desktop, 또는 tablet으로 분류해요.
  • geo — IP 주소에서 파생된 클라이언트의 국가를 포함해요.
  • lang — 클라이언트가 보낸 Accept-Language 헤더에 포함된 첫 번째 언어 코드를 포함해요.

참고 — APO의 Cache by device type 설정과 Cache Rules의 Cache by device type 옵션은 같은 메커니즘을 사용해 기기 유형을 캐시 키에 추가해요. Cache Rules는 APO 없이 이를 수동으로 구성할 수 있게 해 줘요. 자세한 내용은 APO의 cache by device type을 참고해요.

제공 범위

캐시 키 옵션 제공 범위는 요금제에 따라 달라져요.

Free Pro Business Enterprise
Cache deception armor Yes Yes Yes Yes
Cache by device type Yes Yes Yes Yes
Ignore query string Yes Yes Yes Yes
Sort query string Yes Yes Yes Yes
Query string No No No Yes
Headers No No No Yes
Cookie No No No Yes
Host No No No Yes
User features No No No Yes

문제 해결

Cloudflare Trace를 사용해 요청에 어떤 캐시 키 설정이 적용되었는지 찾을 수 있어요. Trace 도구로 요청을 보낼 때 요청이 캐시에서 제공되었다면 Cache Parameters 섹션에 캐시 히트가 표시돼요. 그런 다음 View parameter detail을 선택해 정확히 어떤 캐시 키 속성이 사용되었는지 확인해요.

한계

Prefetch 기능은 Custom Cache Keys와 호환되지 않아요. Cache Rules에서는 커스텀 캐시 키를 사용해 모든 자산을 캐시해요. 하지만 Prefetch는 항상 기본 캐시 키를 사용해요. 결과적으로 키 불일치가 발생해요.

더 알아보기 (Learn more)

캐시 키는 Cloudflare가 캐시 항목을 식별하는 기준이에요. URL, Origin 헤더, 기타 요청 속성을 포함하며, 커스텀 캐시 키로 쿼리 문자열·헤더·쿠키·호스트·사용자 기능을 캐시 키에 반영해 콘텐츠 제공을 세밀하게 제어할 수 있어요.