캐시 무효화

나이트로쉽의 선택적 Edge 응답 캐시는 앱의 HTTP 헤더를 기준으로 공개 함수/SSR 응답을 저장합니다. 프리렌더/ISR 및 프레임워크 데이터 캐시와는 별개입니다. 운영자가 응답 캐시 기능을 활성화해야 하며, 비활성화 상태에서는 이 헤더만으로 캐시가 켜지지 않고 응답 캐시 상태 헤더도 추가하지 않습니다.

ISR·프리렌더 페이지에서는 ntro purge가 세대를 올려 다음 요청부터 새 결과를 사용하게 합니다. 응답 캐시 기능이 활성화되어 있으면 같은 명령으로 일치하는 응답 캐시 엔트리도 무효화합니다.

공개 SSR 응답 캐시제목 링크 복사

브라우저 정책과 별도로 Edge 정책을 지정합니다.

Cache-Control: public, max-age=0, must-revalidate
CDN-Cache-Control: public, s-maxage=60, stale-while-revalidate=120, stale-if-error=300
Nitroship-Cache-Tag: articles, article:42

정책은 Nitroship-CDN-Cache-Control, CDN-Cache-Control, Cache-Control 순서로 처음 존재하는 헤더 하나를 선택합니다. 여러 정책을 합치거나 높은 우선순위 정책이 캐시 불가일 때 낮은 헤더로 대체하지 않습니다. CDN 전용 헤더는 s-maxage, 없으면 max-age를 인정합니다. Cache-Control만 사용하면 s-maxage가 필요하며 브라우저용 max-age만으로는 Edge 캐시를 켤 수 없습니다. 선택한 헤더의 private, no-store, no-cache 또는 0 이하 TTL은 저장을 막습니다.

예제는 60초 동안 신선한 응답을 사용합니다. 그 뒤 stale-while-revalidate는 120초 동안 기존 응답을 제공하며 백그라운드에서 갱신할 수 있습니다. stale-if-error는 백그라운드 갱신의 5xx/timeout 실패가 기록된 경우 신선도 종료 후 300초 이내에 기존 응답을 제공할 수 있게 합니다. 각 기간은 최대 31,536,000초지만 실제 보관에는 아래의 30일 상한이 우선합니다.

기능이 켜져 있으면 CDN 전용 정책 헤더와 Nitroship-Cache-Tag는 방문자 응답에서 제거합니다. Cache-Control을 정책으로 선택했다면 방문자 값의 s-maxage, stale-while-revalidate, stale-if-error를 제거합니다. CDN 전용 헤더로 정책을 지정하면 원래 브라우저용 Cache-Control은 유지합니다.

Next.js제목 링크 복사

공개 SSR 경로는 next.config의 headers() 또는 middleware로 **CDN-Cache-Control**을 설정합니다. Next.js가 생성하는 Cache-Control에 Edge 정책이 그대로 유지될 것이라고 가정하지 않습니다. next.config.mjs 예제:

export default {
  async headers() {
    return [{
      source: '/cached/:path*',
      headers: [
        {
          key: 'CDN-Cache-Control',
          value: 'public, s-maxage=60, stale-while-revalidate=120, stale-if-error=300',
        },
        { key: 'Nitroship-Cache-Tag', value: 'articles' },
      ],
    }];
  },
};

middleware에서 대상 경로의 응답에 CDN-Cache-Control과 Nitroship-Cache-Tag를 설정해도 됩니다. 다른 방문자와 공유해도 안전한 응답만 대상으로 지정합니다. 저장소의 examples/hello-ssr-cache는 동적 렌더 시각, 호스트별 응답과 태그를 보여줍니다. Next.js를 참고합니다.

대상과 한도제목 링크 복사

• 요청은 GET/HEAD이며 Authorization과 Range가 없어야 합니다. HEAD는 GET 캐시를 사용합니다.
• 응답 상태는 200, 301, 302, 307, 308, 404, 410을 지원합니다. Set-Cookie가 있으면 저장하지 않습니다.
• Content-Length가 있으면 본문은 최대 10,000,000바이트(십진 10 MB)입니다. 길이가 없는 chunked/스트리밍 응답은 최대 20,000,000바이트(십진 20 MB)입니다.
• 본문 크기나 Compute 노드의 메모리 캡처 예산을 초과하면 캡처를 중단하고 저장하지 않습니다. 방문자 응답 스트림은 계속 전달하며 본문을 서버 디스크에 캡처하지 않습니다.
• Vary: *와 Vary: Cookie는 캐시하지 않습니다. 다른 Vary 헤더는 별도 변형으로 저장합니다. 키에는 scheme, 호스트(대소문자 무관·포트 제외), 경로, 전체 query, Accept, 정규화 Accept-Encoding도 포함합니다. 서로 다른 호스트의 같은 경로는 캐시를 공유하지 않습니다.
• 요청에 Cookie가 있다는 사실만으로 캐시 우회를 보장하지 않습니다. 개인화 응답은 공개 캐시에 넣지 않고 private 또는 no-store를 사용합니다.
• Nitroship-Cache-Tag는 쉼표로 나누고 앞뒤 공백·빈 값·중복을 정리합니다. 대소문자를 구분하며 응답당 최대 128개, 태그당 최대 256 UTF-8 바이트입니다. NUL/CR/LF는 금지합니다. 태그가 잘못되면 저장하지 않으며 일부만 잘라 저장하지 않습니다.

보관은 생성 후 최대 30일의 best-effort이며 저장 보증이 아닙니다. 더 일찍 사라질 수 있습니다. TTL/SWR/SIE를 더 길게 지정해도 생성 후 30일을 넘은 엔트리는 사용하지 않습니다.

캐시 상태 확인제목 링크 복사

기능이 켜져 있으면 x-nitroship-cache를 확인합니다.

이는 SSR 캐시 상태이며 저장된 파일의 CDN 캐시 상태와 다릅니다. MISS라고 해서 반환된 응답의 저장을 보장하지 않습니다.

무효화와 삭제제목 링크 복사

ntro purge는 정확한 URL 또는 경로, 접두사, glob 패턴, 태그, 호스트, 앱 전체 중 한 종류만 선택합니다. --tag는 반복할 수 있고 purge 요청당 최대 16개입니다. purge 태그에도 태그당 최대 256 UTF-8 바이트가 적용됩니다.

사용법제목 링크 복사

대상을 고르는 방법은 여섯 가지이며, 한 번에 한 종류만 쓸 수 있습니다.

ntro purge /docs/page --app my-app --wait
ntro purge --prefix /docs/ --app my-app
ntro purge --glob '/assets/**' --app my-app
ntro purge --all --app my-app --yes
ntro purge --tag articles --tag article:42 --app my-app --wait
ntro purge --host www.example.com --app my-app --wait
ntro purge --tag article:42 --delete --app my-app --wait

/로 시작하는 경로는 앱의 프로덕션 별칭을 기준으로 처리합니다. 절대 URL 또는 --host 호스트명은 해당 앱의 호스트여야 합니다. host selector는 해당 호스트의 응답 캐시를 대상으로 합니다. 앱 전체 무효화는 확인을 요구합니다. --wait는 활성 엣지의 무효화 적용 결과를 기다리며 백그라운드 렌더 완료를 기다리지는 않습니다. CLI는 --wait가 없으면 기다리지 않습니다.

앱 연결이 없는 폴더에서는 --app <앱 이름>을 붙이세요. 위 예제에서는 앱을 명시했습니다.

무엇이 지워지고, 무엇이 안 지워지나요제목 링크 복사

기본 모드는 **invalidate(무효화)**입니다. 일치한 응답 캐시 엔트리를 stale로 처리해, SWR을 지정하지 않았어도 방문자는 기존 내용을 받고 백그라운드에서 새 내용을 생성할 수 있습니다. **--delete**를 추가하면 이전 엔트리를 제공하지 않고 다음 요청에서 동기 렌더가 필요합니다. delete는 invalidate보다 우선하며 두 모드 모두 생성 후 30일 상한을 넘은 엔트리는 제공하지 않습니다.

기존 프리렌더/ISR purge는 두 모드 모두 현재 세대 변경 동작을 유지합니다. --delete는 프레임워크 데이터 캐시 계약을 바꾸지 않습니다. 두 모드 모두 저장된 파일이나 CDN 캐시의 물리 삭제 명령이 아니며 --wait도 CDN 파일 삭제 완료를 보증하지 않습니다. 앱 영구 삭제에는 별도의 스토리지/CDN 정리 절차가 있습니다. 불변 정적 파일을 변경할 때는 새 배포를 생성합니다. 배포와 승격을 참고합니다.