홈 k3s 클러스터 구축기 (5) — Next.js Redis 캐시 연동
Next.js 16 캐시 아키텍처, @fortedigital/nextjs-cache-handler 연동, 빌드 ID 기반 캐시 격리까지
읽는 데 90분연재 5 / 8편
- #k3s
- #kubernetes
- #nextjs
- #redis
- #cache-handler
- #isr
- #revalidate
- #docker
이 문서의 목차
환경: Next.js 16.1.4,
@fortedigital/nextjs-cache-handlerv3.0.0-next16-beta.1, k3s v1.31+ (작성 당시 기준. 현재 사이트는@mirunamu/next-redis-cache2.0.0)
4편에서 k3s 클러스터에 Redis를 배포하고 RedisInsight로 모니터링 환경을 구축했습니다. Redis가 준비되었으니, 이제 Next.js 앱의 캐시를 연동할 차례입니다.
그런데 왜 굳이 커스텀 캐시 핸들러가 필요할까요? Next.js는 기본적으로 캐시를 파일시스템과 인메모리에 저장합니다. 단일 서버라면 이것으로 충분하지만, k8s처럼 Pod이 여러 개인 환경에서는 근본적인 한계에 부딪힙니다. Pod A에서 ISR로 재생성한 페이지를 Pod B는 알 수 없고, 사용자는 어느 Pod에 요청이 라우팅되느냐에 따라 최신 페이지를 보기도 하고 stale 페이지를 보기도 합니다. revalidateTag()로 캐시를 무효화해도 해당 Pod의 로컬 캐시만 날아가고 나머지 Pod에는 반영되지 않습니다. Pod이 재시작되면 인메모리 캐시는 당연히 사라지고, 컨테이너 환경에서는 파일시스템 캐시마저 유실됩니다.
결국 Pod 간 캐시를 공유할 수 있는 외부 저장소가 필요하며, 이것이 Redis를 캐시 백엔드로 연동하는 이유입니다. 이 편에서는 캐시 아키텍처를 먼저 이해하고, 라이브러리 연동과 빌드 ID 기반 캐시 격리까지 한 편에 담았습니다.
이 편 이후의 변경 (현재: @mirunamu/next-redis-cache 2.0)
이 편은 @fortedigital/nextjs-cache-handler로 cacheHandler(단수)만 Redis에 연동한 시점의 기록입니다. 이후 cacheHandlers(복수)까지 Redis로 다루기 위해 캐시 핸들러를 직접 구현하여 @mirunamu/next-redis-cache로 교체했고(Next.js Redis 캐시 핸들러 직접 만들기), 그 패키지를 테스트로 감사해 1.1.0 핫픽스와 2.0.0으로 다시 설계했습니다(next-redis-cache 2.0 — 버그를 테스트로 먼저 재현하고 다시 설계하기).
지금 이 사이트는 2.0.0으로 운영되며, 이 편의 설정 코드(onCreation 훅, instrumentation.ts의 KEYS 정리, registerInitialCache 프리워밍)는 더 이상 쓰지 않습니다. 빌드 ID로 캐시 키를 격리한다는 원칙은 그대로이고, 현재 구성은 현재 구성 요약에 정리했습니다.
Redis에 무엇을 저장할지 결정하려면, 먼저 Next.js가 캐시를 어떻게 관리하는지 정확히 이해해야 합니다.
Next.js에서 "정적 페이지"와 "캐시"는 분리된 개념이 아닙니다. 프리렌더된 HTML/RSC payload 자체가 Incremental Cache의 엔트리입니다. 단, 저장 위치는 생성 시점에 따라 다릅니다.
| 시점 | 저장 위치 | 경로 |
|---|---|---|
빌드 타임 (next build) | 파일시스템 | .next/server/app/docs/[slug].html |
| 런타임 ISR 재생성 | cacheHandler (Redis) | Redis 키 (docs: prefix) |
빌드 타임 페이지는 cacheHandler.set()을 거치지 않고 파일시스템에 직접 저장됩니다. 런타임에 ISR 재생성이 일어나면 그때 cacheHandler.set()을 통해 Redis에 저장됩니다.
주의할 점은 런타임 조회 경로입니다. 커스텀 cacheHandler를 지정하면 Next.js 기본 FileSystemCache가 통째로 대체되므로, 핸들러의 get()이 null을 돌려줄 때 Next.js가 파일시스템으로 알아서 폴백하지 않습니다. 그 요청은 캐시 미스로 처리되고, dynamicParams = false인 라우트라면 404가 됩니다. 이 편 당시에는 registerInitialCache()로 빌드 산출물을 미리 채우고 LRU 폴백도 두어 이 문제가 드러나지 않았지만, 이후 Pod 로컬 메모리 층 없이 운영하면서 Redis가 비거나 끊기면 문서 페이지가 404를 내는 원인이 되었습니다. 지금 쓰는 @mirunamu/next-redis-cache 2.0은 Redis에 항목이 없거나 Redis를 쓸 수 없을 때 핸들러 안에서 .next/server/app의 빌드 산출물을 읽어 응답합니다.
Next.js 16에는 캐시 핸들러 설정이 두 가지 있습니다. 이름이 비슷해서 리네이밍처럼 보이지만, 완전히 별개의 시스템이며 공존합니다.
| 설정 | 용도 | 인터페이스 | 상태 |
|---|---|---|---|
cacheHandler (단수) | ISR, fetch 캐시 (revalidate), 라우트 핸들러 | 클래스 생성자 | v14.1.0~ 현역 |
cacheHandlers (복수) | 'use cache' 디렉티브 전용 | 객체 | v16.0.0~ 신규 |
단수는 클래스 생성자를 요구하고, get/set/revalidateTag 메서드로 캐시를 관리합니다.
class CacheHandler {
constructor(ctx)
get(key, ctx): Promise<{ lastModified, value } | null>
set(key, data, ctx): Promise<void>
revalidateTag(tags): Promise<void>
resetRequestCache(): void
}반면 복수는 'use cache' 디렉티브 전용으로, 태그 기반 만료(getExpiration, updateTags)를 중심으로 한 다른 형태의 인터페이스를 사용합니다.
interface DataCacheHandler {
get(cacheKey, softTags): Promise<DataCacheEntry | undefined>
set(cacheKey, pendingEntry): Promise<void>
refreshTags(): Promise<void>
getExpiration(tags): Promise<Timestamp>
updateTags(tags, durations?): Promise<void>
}인터페이스가 완전히 다르므로 하나의 핸들러로 양쪽을 커버할 수 없습니다. cacheHandlers(복수)를 설정하지 않으면 Next.js 16이 내장 인메모리 LRU 캐시를 기본값으로 사용하며, 이 편에서는 단수만 Redis로 연동합니다.
cacheMaxMemorySize와 'use cache'
cacheMaxMemorySize는 cacheHandler(단수)뿐 아니라 cacheHandlers(복수)의 'use cache' 인메모리 LRU에도 동시에 적용됩니다(소스 코드 (새 창)). 따라서 이 값을 0으로 두면 두 계층의 Pod-로컬 메모리 캐시가 함께 꺼집니다.
이 편처럼 복수를 Redis로 연동하지 않은 구성에서는 내장 인메모리 LRU가 'use cache'의 유일한 저장소이므로, 0으로 끄면 해당 캐시가 통째로 사라집니다. 그래서 이 시점에서는 기본값(50 MB)을 유지했습니다. 단수 쪽에 Pod-로컬 레이어가 함께 생기지만, Redis가 source of truth이므로 ISR revalidate 시점에 갱신됩니다.
복수까지 Redis에 연결한 뒤에는 판단이 뒤집힙니다. 저장소가 Redis로 통일되면 Pod-로컬 메모리 레이어는 Pod마다 다른 값을 들고 있을 여지만 남기므로, 멀티 Pod 캐시 일관성이라는 목적에 비추어 꺼 두는 편이 맞습니다.
Next.js 16에서는 기본적으로 캐시가 비활성화되어 있습니다. 아래와 같이 명시적으로 옵트인한 경우에만 cacheHandler를 통해 Redis에 캐시가 쌓입니다.
| 캐시 대상 | 옵트인 방법 |
|---|---|
| ISR 페이지 | export const revalidate = 60 |
| fetch 캐시 | fetch(url, { next: { revalidate: 3600 } }) |
| force-cache | fetch(url, { cache: 'force-cache' }) |
| on-demand 정적 생성 | generateStaticParams에 없는 경로의 첫 요청 |
옵트인 설정이 없는 코드에서는 Redis에 아무것도 쌓이지 않으므로, 캐시 핸들러를 연동했다고 해서 모든 요청이 Redis를 거치는 것은 아닙니다.
ISR과 fetch revalidate는 캐싱 레벨이 다릅니다. ISR은 페이지 전체를 재생성하는 반면, fetch revalidate는 개별 API 응답을 캐싱합니다. 둘 다 cacheHandler를 통해 Redis에 저장되지만, 캐시 키와 갱신 주기는 독립적입니다.
const data = await fetch("https://api.github.com/users/...", {
next: { revalidate: 3600 } // 1시간
});이 코드의 동작은 stale-while-revalidate 패턴을 따릅니다. 서버(Next.js)가 GitHub API를 호출하고 응답을 Redis에 캐싱하면, 이후 1시간 동안은 동일한 fetch 요청에 대해 Redis의 캐싱된 응답을 반환합니다. 1시간이 지난 뒤에는 캐싱된 응답을 즉시 반환하면서 백그라운드에서 API를 다시 호출하여 캐시를 갱신합니다. 브라우저는 이 과정을 전혀 인지하지 못하고, 렌더링된 HTML만 받게 됩니다.
// src/lib/github-stats.ts — 5개 fetch
const CACHE_CONFIG = {
profile: { next: { revalidate: 3600 } }, // 1시간
repos: { next: { revalidate: 3600 } }, // 1시간
events: { next: { revalidate: 1800 } }, // 30분
languages: { next: { revalidate: 86400 } }, // 24시간
contributions: { next: { revalidate: 3600 } }, // 1시간
};
// src/lib/npm-stats.ts — 2개 fetch
const CACHE_CONFIG = {
packages: { next: { revalidate: 86400 } }, // 24시간
downloads: { next: { revalidate: 3600 } }, // 1시간
};당시에는 이 7개의 fetch가 revalidate를 쓰고 있어서 런타임에 Redis로 캐시가 쌓였습니다. 나머지 문서 페이지들은 빌드타임에 전부 정적 생성되고 revalidate를 쓰지 않았지만, 파일시스템에서 직접 서빙된 것은 아닙니다. 앞서 설명한 대로 커스텀 cacheHandler가 파일시스템 캐시를 대체하므로, 이 페이지들도 registerInitialCache()가 캐시 핸들러에 밀어넣은 항목을 통해 서빙되었습니다.
지금 Redis에 들어가는 것
GitHub·npm 통계를 가져오던 두 모듈은 이후 GitHub 활동 섹션과 함께 삭제되어, 현재 앱 코드에는 revalidate를 쓰는 fetch가 없습니다. 사이트의 모든 문서 페이지는 generateStaticParams()와 dynamicParams = false로 빌드타임에 생성되고 ISR을 쓰지 않습니다.
그래도 Redis는 비어 있지 않습니다. 프리렌더된 페이지(APP_PAGE)와 빌드 때 만든 OG 이미지 같은 정적 Route Handler(APP_ROUTE)가 cacheHandler를 거치기 때문입니다. 2.0 핸들러는 첫 요청에서 빌드 산출물로 응답한 뒤 그 항목을 Redis에 다시 채우고, 이후 요청은 Redis에서 읽습니다. cacheHandlers('use cache')도 Redis에 연결되어 있지만, 앱 코드에 'use cache'가 없어 아직 쓰이지 않는 경로입니다.
cacheHandler 인터페이스는 get/set/revalidateTag 세 메서드를 구현하면 되므로 커스텀 핸들러로도 충분히 만들 수 있습니다. Next.js 14까지는 @neshca/cache-handler가 사실상 표준으로 쓰였지만 16을 지원하지 않고, 그 외에 검증된 대안도 많지 않은 상황입니다. 그중 @fortedigital/nextjs-cache-handler가 주간 59K 다운로드로 가장 활발하게 유지보수되고 있어 이 라이브러리를 사용했습니다.
베타 리스크
Next.js 16용은 v3.0.0-next16-beta.1입니다. 활발하게 유지보수되고 있지만 프로덕션 도입 시 주의가 필요합니다.
라이브러리와 Redis 클라이언트를 설치합니다. @next 태그는 Next.js 16 대응 베타 버전을 가리킵니다.
cd docs/
npm install @fortedigital/nextjs-cache-handler@next @redis/client설정 파일은 세 곳을 수정합니다. 캐시 핸들러 정의(cache-handler.mjs), 서버 시작 시 훅(instrumentation.ts), 그리고 Next.js 설정(next.config.ts)입니다. 이 절의 코드는 @fortedigital 시절의 기록이므로, 지금 따라 설정한다면 현재 구성 요약의 2.0 구성을 쓰는 편이 맞습니다.
// docs/cache-handler.mjs
import { CacheHandler } from "@fortedigital/nextjs-cache-handler";
import createRedisHandler from "@fortedigital/nextjs-cache-handler/redis-strings";
import createLruHandler from "@fortedigital/nextjs-cache-handler/local-lru";
import { createClient } from "@redis/client";
import { PHASE_PRODUCTION_BUILD } from "next/constants.js";
const buildId = process.env.BUILD_ID || "default";
CacheHandler.onCreation(async (context) => {
// 빌드타임: Redis 없이 LRU 메모리 캐시만 사용
if (context.serverOptions?.phase === PHASE_PRODUCTION_BUILD) {
return { handlers: [createLruHandler()] };
}
// 런타임: Redis + LRU 폴백
const client = createClient({ url: process.env.REDIS_URL });
client.on("error", (err) => {
console.error("[Redis]", err.message);
});
await client.connect();
const redisHandler = await createRedisHandler({
client,
keyPrefix: `docs:${buildId}:`,
sharedTagsKey: `docsTags:${buildId}`,
sharedTagsTtlKey: `docsTagTtls:${buildId}`,
});
return {
handlers: [redisHandler, createLruHandler()],
};
});
export default CacheHandler;PHASE_PRODUCTION_BUILD 분기가 핵심입니다. Docker 빌드 시에는 Redis가 없으므로 LRU 메모리 캐시만 사용하고, 런타임에는 Redis를 우선으로 쓰되 장애 시 LRU로 폴백합니다. keyPrefix에 빌드 ID를 포함시키는 이유는 빌드 ID 기반 캐시 격리 섹션에서 다룹니다.
| 시점 | handlers | 결과 |
|---|---|---|
next build (Docker) | [lruHandler] | Redis 연결 안 함 |
node server.js (k8s) | [redisHandler, lruHandler] | Redis 우선, 실패 시 LRU 폴백 |
Next.js는 src/instrumentation.ts의 register() 함수를 서버 시작 시 자동으로 한 번 호출합니다. 이 hook에서 두 가지 작업을 수행합니다.
- 이전 빌드 캐시 정리: KEYS로 현재 빌드 ID가 아닌 키를 찾아 삭제
- 빌드타임 캐시 프리로딩: 파일시스템의 정적 페이지를 Redis에 밀어넣기
// docs/src/instrumentation.ts
export async function register() {
if (process.env.NEXT_RUNTIME === "nodejs") {
const { createClient } = await import("@redis/client");
const client = createClient({ url: process.env.REDIS_URL });
await client.connect();
const buildId = process.env.BUILD_ID || "default";
const currentPrefix = `docs:${buildId}:`;
const currentTagsKey = `docsTags:${buildId}`;
const currentTtlKey = `docsTagTtls:${buildId}`;
const [cacheKeys, tagsKeys, ttlKeys] = await Promise.all([
client.keys("docs:*"),
client.keys("docsTags:*"),
client.keys("docsTagTtls:*"),
]);
const oldKeys = [
...cacheKeys.filter((key) => !key.startsWith(currentPrefix)),
...tagsKeys.filter((key) => key !== currentTagsKey),
...ttlKeys.filter((key) => key !== currentTtlKey),
];
if (oldKeys.length > 0) {
console.log(`[cache-cleanup] Deleting ${oldKeys.length} old keys`);
await client.del(oldKeys);
}
const remaining =
cacheKeys.length + tagsKeys.length + ttlKeys.length - oldKeys.length;
console.log(`[cache-cleanup] Done. Remaining: ${remaining} current keys`);
await client.disconnect();
const { registerInitialCache } = await import(
"@fortedigital/nextjs-cache-handler/instrumentation"
);
const CacheHandler = (await import("../cache-handler.mjs")).default;
await registerInitialCache(CacheHandler, { setOnlyIfNotExists: true });
}
}docs:*, docsTags:*, docsTagTtls:* 세 패턴을 병렬로 조회하여 현재 빌드 ID에 해당하지 않는 키를 일괄 삭제합니다. 이 사이트의 Redis 키 수는 수십 개 수준이므로 KEYS 명령으로도 블로킹 우려 없이 충분합니다. [cache-cleanup] 로그로 정리 과정을 추적할 수 있어, kubectl logs에서 각 배포마다 몇 개의 dead 키가 삭제되었는지 확인할 수 있습니다.
이 정리 로직은 이후 자체 패키지의 cleanupOldBuildKeys()로 옮기면서 SCAN 기반으로 바뀌었고, 2.0에서는 빌드 레지스트리를 쓰는 startCacheMaintenance()로 다시 바뀌었습니다. "현재 빌드가 아닌 키는 전부 지운다"는 이 편의 규칙이 롤링 업데이트 중인 옛 Pod의 키까지 지운다는 문제가 드러났기 때문이며, 자세한 내용은 아래 롤링 업데이트와 잔여 키에서 다룹니다.
setOnlyIfNotExists: true — Redis에 이미 해당 키가 있으면 덮어쓰지 않습니다. 앱이 재시작되어도 런타임에 갱신된 더 최신 캐시를 보존합니다.
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
output: "standalone",
reactStrictMode: false,
images: {
unoptimized: true,
},
cacheHandler: require.resolve("./cache-handler.mjs"),
generateBuildId: async () => process.env.BUILD_ID || "default",
};
export default nextConfig;cacheMaxMemorySize를 별도로 설정하지 않아 기본값(50 MB)이 적용되는데, 이는 'use cache' 디렉티브의 내장 인메모리 LRU를 살려 두기 위한 선택입니다. 복수 핸들러가 Redis에 연결되지 않은 이 시점에서는 그 LRU가 유일한 저장소이기 때문입니다. 단수 쪽에도 Pod-로컬 레이어가 함께 생기지만, Redis가 source of truth 역할을 하고 ISR revalidate 주기에 맞춰 갱신되므로 실질적인 불일치는 제한적입니다. generateBuildId는 빌드마다 고정된 ID를 부여하여 캐시 키를 빌드별로 격리합니다.
현재 저장소의 설정은 다릅니다
복수 핸들러까지 Redis로 옮긴 뒤 이 값은 cacheMaxMemorySize: 0으로 바뀌었습니다. 캐시 저장소가 Redis 하나로 통일된 이상 Pod-로컬 메모리 레이어를 유지할 이유가 없기 때문입니다. 현재 next.config.ts 전문은 현재 구성 요약에 있습니다.
cache-handler.mjs가 Redis에 접속하려면 REDIS_URL 환경변수가 필요합니다. 4편에서 생성한 docs-secret.yaml에 추가합니다.
stringData:
REDIS_URL: "redis://default:비밀번호@redis-master.mirunamu.svc.cluster.local:6379"kubectl apply -f secrets/docs-secret.yaml -n mirunamu기존 Dockerfile에 BUILD_ID ARG와 cache-handler.mjs COPY를 추가합니다. BUILD_ID는 빌드 스테이지와 런타임 스테이지 양쪽에 필요한데, 빌드 스테이지에서는 next build가 generateBuildId를 통해 읽고, 런타임 스테이지에서는 cache-handler.mjs가 Redis 키 접두어로 사용합니다.
# 2. 빌드
FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ARG BUILD_ID
ENV BUILD_ID=${BUILD_ID}
RUN npm run build
# 3. 실행
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ARG BUILD_ID
ENV BUILD_ID=${BUILD_ID}
# ...
COPY --from=builder --chown=nextjs:1001 /app/cache-handler.mjs ./cache-handler.mjsCI/CD에서 --build-arg BUILD_ID=${{ github.sha }}로 전달하면 빌드 ID가 git commit SHA와 일치합니다. 런타임 시작 시 instrumentation.ts의 registerInitialCache()가 빌드 출력물(.next/server/app/)을 읽어서 Redis에 밀어넣었고, 이 디렉토리는 standalone 출력에 이미 들어 있으므로 따로 COPY하지 않았습니다.
현재 Dockerfile은 여기에 use-cache-handler.mjs와 두 핸들러가 함께 import하는 cache/ 디렉토리(cache/config.mjs)를 추가로 복사합니다. 2.0의 빌드 산출물 폴백도 이미지 안의 같은 .next/server/app/을 읽으므로, 폴백을 위해 따로 챙길 파일은 없습니다.
커밋 및 푸시
bash cd docs/ && git add . && git commit -m "Redis 캐시 핸들러 연동" && git pushPod 및 환경변수 확인
bash kubectl get pods -n mirunamu kubectl exec -n mirunamu deploy/docs -- env | grep REDIS_URL캐시 키 확인
페이지를 몇 개 연 뒤 Redis Pod에서
docs:프리픽스 키를 조회합니다. Bitnami Redis 컨테이너에는 비밀번호 파일이$REDIS_PASSWORD_FILE로 마운트되어 있어, 이를REDISCLI_AUTH로 넘기면 비밀번호가 명령줄에 드러나지 않습니다.bash kubectl exec -n mirunamu redis-master-0 -- sh -c \ 'REDISCLI_AUTH="$(cat "$REDIS_PASSWORD_FILE")" redis-cli --scan --pattern "docs:*" | head'이 편 당시에는
registerInitialCache()가 동작했다면docs:<빌드ID>:/robots.txt,docs:<빌드ID>:/docs같은 정적 페이지 키가 보였습니다. 2.0에서는 현재 빌드와 직전 빌드의docs:<빌드ID>:e:<경로>항목 키, 그리고 빌드 레지스트리docs:_builds가 보입니다. 태그 상태 해시docs:_tagstate는 첫 무효화가 기록될 때 생기므로, 태그 무효화를 쓰지 않는 이 사이트에는 없습니다.
RedisInsight는 삭제했습니다
이 편을 쓸 때는 4편에서 띄운 RedisInsight 웹 GUI로 키를 확인했지만, 공개 노출 문제로 이후 클러스터에서 삭제했습니다. 지금은 위처럼 kubectl exec로 redis-cli를 쓰거나 kubectl port-forward로 로컬 도구를 붙여 확인합니다.
이 편 당시 라이브러리에서는 키마다 TTL이 이렇게 달랐습니다.
| 키 종류 | TTL | 이유 |
|---|---|---|
fetch 캐시 (revalidate 있음) | revalidate × 1.5 | stale window 확보 |
정적 페이지 (revalidate 없음) | ~1.5년 | 라이브러리 기본값 365일 × 1.5 |
"1yr"로 보이던 키들은 registerInitialCache()가 밀어넣은 정적 페이지입니다. 라이브러리 내부에 defaultStaleAge = 60 * 60 * 24 * 365(365일)가 하드코딩되어 있었고, 실제 Redis TTL은 이 값의 1.5배로 설정되었습니다. 사실상 영구 캐시에 가까웠지만, 빌드 ID 기반 격리 덕분에 재배포 시 이전 빌드의 키가 정리되므로 무한히 쌓이지는 않았습니다.
@mirunamu/next-redis-cache 2.0에서는 TTL을 쓰기 시점부터 계산하며, 숫자 revalidate는 1.5배, revalidate가 없는 정적 항목은 30일, 어떤 항목도 최대 365일입니다. 직전 빌드처럼 정리 대상에서 잠시 보존되는 빌드의 키는 TTL이 1일로 줄어듭니다.
Redis 캐시 연동 후 배포하면 정상적으로 동작하는 것처럼 보이지만, 두 번째 배포부터 문제가 발생합니다. 페이지 HTML은 렌더링되는데 사이드바, 클라이언트 컴포넌트, 인터랙션이 전부 동작하지 않는 증상이 나타납니다. 브라우저 콘솔에는 JS 청크에 대한 404 에러가 쏟아집니다.
Next.js는 빌드마다 고유한 빌드 ID를 생성하고, 클라이언트 JS 청크 경로에 이 ID를 포함시킵니다. 문제는 registerInitialCache()가 빌드타임 HTML을 Redis에 밀어넣을 때 발생합니다. 이 HTML 안에는 해당 빌드의 JS 청크 경로가 하드코딩되어 있습니다.
재배포 시 흐름은 이렇습니다.
- 새 빌드가 배포되면서
.next/static/디렉토리에 새로운 빌드 ID의 JS 청크가 생성됩니다 - 그런데 Redis에는 이전 빌드의 HTML이 아직 남아있고,
setOnlyIfNotExists: true때문에 덮어쓰지 않습니다 - 사용자가 페이지에 접속하면 Redis에서 이전 빌드의 HTML을 서빙합니다
- 이 HTML이 참조하는 JS 청크 경로는
/_next/static/<이전-빌드-ID>/...인데, 서버에는 새 빌드 ID의 청크만 존재합니다 - 브라우저가 JS 청크를 요청하면 404가 반환되고, React 하이드레이션이 실패합니다
결과적으로 서버 렌더링된 HTML은 보이지만 클라이언트 사이드 코드가 전혀 로드되지 않아, 사이드바 토글, 검색, GitHub 활동 섹션 등 모든 인터랙티브 요소가 죽습니다.
cache-handler.mjs의 keyPrefix에 빌드 ID를 포함시키면 빌드마다 완전히 다른 Redis 키 네임스페이스를 사용하게 됩니다. 이전 빌드의 캐시는 새 빌드에서 애초에 조회되지 않습니다.
const buildId = process.env.BUILD_ID || "default";
const redisHandler = await createRedisHandler({
client,
keyPrefix: `docs:${buildId}:`, // docs:abc123: 형태
sharedTagsKey: `docsTags:${buildId}`,
sharedTagsTtlKey: `docsTagTtls:${buildId}`,
});next.config.ts에서도 같은 BUILD_ID를 빌드 ID로 사용하여 양쪽이 일치하도록 합니다.
generateBuildId: async () => process.env.BUILD_ID || "default",BUILD_ID는 CI/CD에서 git commit SHA로 주입합니다.
# .github/workflows/docker-publish.yml
- name: Build and push
uses: docker/build-push-action@v6
with:
build-args: |
BUILD_ID=${{ github.sha }}이 구조에서 배포 흐름은 다음과 같이 바뀝니다.
- 새 Pod가 시작되면
instrumentation.ts의register()가 실행됩니다 - KEYS로 이전 빌드의 캐시 키(
docs:<이전-SHA>:*,docsTags:<이전-SHA>,docsTagTtls:<이전-SHA>)를 찾아 삭제합니다 registerInitialCache()가 새 빌드의 HTML을docs:<새-SHA>:키에 밀어넣습니다
cleanup은 현재 빌드 ID가 아닌 모든 키를 삭제하므로, 이전 빌드의 키는 세대에 관계없이 전부 정리됩니다. 다만 k8s 롤링 업데이트 특성상, 배포마다 소수의 이전 빌드 키가 남을 수 있습니다.
Deployment의 RollingUpdate 전략은 새 Pod가 Ready 상태가 된 후에 Old Pod을 종료합니다. 이 전환 구간에서 Old Pod과 New Pod이 동시에 트래픽을 처리하게 되는데, New Pod의 cleanup이 이전 키를 삭제한 이후에도 Old Pod은 여전히 요청을 받고 있으므로, 캐시 핸들러가 Old 빌드 ID로 새 캐시 엔트리를 기록합니다.
이렇게 남은 키는 다음 배포의 cleanup에서 일괄 삭제됩니다. 현재 빌드 ID가 아닌 키를 전부 삭제하는 방식이기 때문에, 몇 세대 전 키든 한 번에 정리되며 누적되지 않습니다.
보이지 않던 반대 방향의 문제
롤링 업데이트로 남은 이전 빌드의 캐시 키는 현재 빌드의 keyPrefix와 일치하지 않으므로 새 Pod가 조회하지 않고, 다음 배포 때 정리됩니다. 이 점만 보면 잔여 키는 무해합니다.
문제는 반대 방향이었습니다. 새 Pod의 cleanup은 아직 트래픽을 받는 옛 Pod가 읽는 키까지 지웁니다. 이 편의 구성에는 LRU 폴백이 있었지만, 이후 자체 패키지로 바꾸고 Pod 로컬 메모리 층을 끈 뒤에는 옛 Pod가 지워진 키를 조회하면 그대로 캐시 미스가 됩니다. 패키지 레포의 롤링 업데이트 카오스 테스트에서 1.0.6은 이 구간에 옛 인스턴스가 dynamicParams = false 문서를 404로 응답했습니다. 2.0의 startCacheMaintenance()는 docs:_builds 레지스트리로 현재 빌드와 직전 빌드 하나를 남기고, 다른 빌드도 모든 키가 30분 이상 읽히지 않았을 때만 지웁니다. 보류한 빌드는 같은 인스턴스가 나중에 다시 확인해 정리하며, 설령 키가 없어도 빌드 산출물 폴백이 응답하므로 404로 이어지지 않습니다.
이 편에서 만든 구성과, 지금 이 사이트가 쓰는 @mirunamu/next-redis-cache 2.0.0 구성을 나란히 비교하면 다음과 같습니다.
| 항목 | 5편 시점 | 현재 (2.0.0) |
|---|---|---|
| 캐시 핸들러 패키지 | @fortedigital/nextjs-cache-handler | @mirunamu/next-redis-cache ^2.0.0 |
cacheHandler (단수) | Redis + LRU 폴백 | createCacheHandler(cacheConfig) — Redis + 빌드 산출물 폴백 |
cacheHandlers (복수) | 미설정 → 내장 인메모리 LRU | default에 createUseCacheHandler(cacheConfig) — Redis |
| Redis 연결 | onCreation에서 await client.connect() | connectRedis(REDIS_URL) — 첫 연결 최대 1초 대기, 이후 백그라운드 재연결 |
| Redis 장애 시 | LRU 폴백 | 빌드 산출물로 응답. 명령 타임아웃이 나면 10초간 Redis를 건너뛰는 서킷 브레이커 |
cacheMaxMemorySize | 기본값(50 MB) | 0 — Pod 로컬 메모리 레이어 비활성 |
generateBuildId | process.env.BUILD_ID — git SHA 기반 | 동일 |
| 빌드타임 동작 | LRU 메모리 캐시 (Redis 연결 안 함) | 핸들러 no-op (Redis 연결 안 함) |
| 캐시 키 | docs:<빌드ID>:<키>, docsTags:<빌드ID>, docsTagTtls:<빌드ID> | docs:<빌드ID>:e:<키>, docs:<빌드ID>:u:<키>, 공유 docs:_builds·docs:_tagstate |
| 항목 형식 | JSON 문자열 | brotli 압축 바이너리 봉투 |
| 이전 빌드 캐시 정리 | instrumentation.ts에서 KEYS + DEL | startCacheMaintenance() — 레지스트리 기반, 현재·직전 빌드 보존 |
| 빌드 캐시 → Redis 전파 | registerInitialCache() 프리워밍 | 프리워밍 끔. 첫 요청이 빌드 산출물로 응답하며 Redis에 재시드 |
이 편이 남긴 제약은 'use cache' 디렉티브가 사용하는 cacheHandlers(복수)였습니다. 복수를 Redis로 연동하지 못하면 Pod 로컬 인메모리 LRU에 캐시가 쌓이고, 같은 요청이라도 어느 Pod이 받느냐에 따라 캐시 히트 여부가 달라집니다. 당시 @fortedigital은 복수를 지원하지 않았고(Issue #152 (새 창)), 결국 두 인터페이스를 모두 구현한 캐시 핸들러를 직접 만들어 @mirunamu/next-redis-cache로 배포했습니다. 그 패키지는 이후 테스트로 드러난 결함을 고치며 2.0으로 다시 설계되었고, 그사이 앱 쪽에 덧대 두었던 자체 래퍼(빌드 산출물 폴백, 연결 대기 제한, 레지스트리 정리)는 모두 패키지로 흡수되었습니다.
그 결과 앱에 남은 캐시 코드는 설정 파일 하나와 세 줄짜리 핸들러 파일 두 개입니다. 두 핸들러와 인스트루멘테이션이 같은 설정 객체를 공유합니다.
// cache/config.mjs
import { connectRedis } from "@mirunamu/next-redis-cache/redis";
/** @type {import("@mirunamu/next-redis-cache").RedisCacheConfig} */
export const cacheConfig = {
client: () => connectRedis(process.env.REDIS_URL, { label: "docs" }), // REDIS_URL이 없으면 null: 빌드 산출물만으로 응답
namespace: process.env.CACHE_NAMESPACE || "docs", // 키 docs:<BUILD_ID>:*
buildId: process.env.BUILD_ID || undefined, // CI가 커밋 SHA를 주입, 없으면 .next/BUILD_ID
};// cache-handler.mjs
import { createCacheHandler } from "@mirunamu/next-redis-cache";
import { cacheConfig } from "./cache/config.mjs";
export default createCacheHandler(cacheConfig);// use-cache-handler.mjs
import { createUseCacheHandler } from "@mirunamu/next-redis-cache/use-cache";
import { cacheConfig } from "./cache/config.mjs";
export default createUseCacheHandler(cacheConfig);next.config.ts는 단수와 복수를 모두 Redis 핸들러에 연결하고, Pod 로컬 메모리 층을 끕니다.
const nextConfig: NextConfig = {
output: "standalone",
cacheHandler: require.resolve("./cache-handler.mjs"),
cacheHandlers: {
default: require.resolve("./use-cache-handler.mjs"),
},
cacheMaxMemorySize: 0,
generateBuildId: async () => process.env.BUILD_ID || "default",
// ...
};cacheMaxMemorySize: 0은 앞서 설명한 판단이 뒤집힌 결과입니다. 두 계층의 저장소가 모두 Redis가 된 이상, Pod 로컬 메모리 레이어는 Pod 간 캐시 일관성이라는 목표를 흐리는 요소일 뿐입니다. Redis 장애 때의 폴백도 메모리 캐시가 아니라 이미지에 들어 있는 빌드 산출물이므로 이 설정과 충돌하지 않습니다.
서버 시작 훅은 REDIS_URL이 없을 때 기동 로그에 큰 경고를 남기고, 있으면 옛 빌드 정리를 기다리지 않고 시작합니다. Redis가 죽어 있어도 서버 기동이 붙잡히지 않게 하려는 것입니다.
// src/instrumentation-node.ts (instrumentation.ts가 nodejs 런타임에서만 import, 경고 문구는 줄임)
import { startCacheMaintenance } from "@mirunamu/next-redis-cache/instrumentation";
import { cacheConfig } from "../cache/config.mjs";
export function startRedisCacheMaintenance() {
if (!process.env.REDIS_URL) {
console.warn("[cache] REDIS_URL is not set - starting without the Redis cache.");
return;
}
// await하지 않는다: 이 빌드를 등록하고, Redis가 준비되면 옛 빌드 키를 정리. 프리워밍은 끔
startCacheMaintenance({ config: cacheConfig });
}2.0으로 전환한 뒤 운영 사이트는 sitemap의 모든 경로를 200으로 응답하고 있습니다. Redis가 1초 안에 응답하지 않은 순간이 한 번 있었는데, 서킷 브레이커가 열려 그동안의 요청을 빌드 산출물로 응답했고 Redis가 다시 응답하자 스스로 닫혔습니다. 옛 빌드의 키도 레지스트리 규칙대로 정리되어, Redis에는 현재 빌드와 직전 빌드의 키만 남아 있습니다. 패키지 내부 구조와 테스트 과정은 Next.js Redis 캐시 핸들러 직접 만들기와 next-redis-cache 2.0 — 버그를 테스트로 먼저 재현하고 다시 설계하기에서 다룹니다.
5편 요약
- 캐시 아키텍처: 빌드타임 산출물은 파일시스템에 있지만, 커스텀
cacheHandler가 조회 경로를 통째로 대체하므로 핸들러가 빌드 산출물까지 책임져야 함. 단수와 복수는 별개 시스템 - fetch revalidate: 서버사이드 API 캐싱. 브라우저는 모름. ISR과는 다른 레벨
- 라이브러리 선택:
@fortedigital로 단수를 연동. 복수 미지원이라는 한계가 남아 자체 패키지로 교체했고, 현재는@mirunamu/next-redis-cache2.0 - 빌드 ID 격리: Redis 캐시 키에 빌드 ID를 포함시켜 재배포 시 이전 빌드 캐시와의 충돌 방지. 정리는 "현재 빌드만 남기기"가 아니라 "현재·직전 빌드를 남기고 아무도 읽지 않는 빌드만 지우기"여야 롤링 업데이트가 안전함
cacheMaxMemorySize의 맥락 의존성: 복수가 Redis에 연결되지 않았다면 기본값 유지, 연결된 뒤에는0. 단수/복수 어느 쪽이 어디에 저장되는지에 따라 정답이 달라짐
다음 편에서는 Redis PVC가 특정 노드에 묶이는 한계를 넘어, Longhorn 분산 스토리지를 도입하여 노드 장애에도 데이터가 유실되지 않는 구조를 만들어 봅니다.
- @fortedigital/nextjs-cache-handler GitHub (새 창) — 이 편에서 사용한 캐시 핸들러
- @mirunamu/next-redis-cache npm (새 창) — 이후 교체한 자체 패키지
- next-redis-cache GitHub (새 창) — README, MIGRATION.md (새 창)(1.x → 2.x)
- Next.js cacheHandler (단수) 공식 문서 (새 창)
- Next.js cacheHandlers (복수) 공식 문서 (새 창)
- Next.js
'use cache'디렉티브 (새 창) - @redis/client 공식 문서 (새 창)
관련 문서
글쓴이 mirunamu00

