Deploy: Vercel, Docker, Cloud Run, cache nhiều instance và observability
So sánh Vercel và self-host, Dockerfile tối ưu với output standalone, deploy Cloud Run (GCP), những thứ phải xử lý khi chạy nhiều instance (cache handler, khoá mã hoá Server Action, version skew), biến môi trường, CI/CD, instrumentation và log.
Chạy next start trên một máy thì đơn giản. Chạy 10 instance sau load balancer thì xuất hiện vấn đề mà local không bao giờ thấy:
revalidate ở instance này nhưng instance khác vẫn cũ, Server Action lỗi sau mỗi lần deploy, người dùng đang mở bản cũ tải chunk
không còn tồn tại. JD có GCP, Docker, CI/CD — module này nối các mảnh đó với Next.js.
🎯 Mục tiêu học tập
- So sánh Vercel và self-host theo chi phí, tính năng, vận hành
- Viết Dockerfile multi-stage với
output: 'standalone' - Deploy lên Cloud Run với Cloud SQL và Secret Manager
- Xử lý cache, khoá mã hoá và version skew khi nhiều instance
- Thiết lập instrumentation, log có cấu trúc, trace
Vercel hay self-host
| Vercel | Self-host (Docker trên Cloud Run/GKE/VM) | |
|---|---|---|
| Công sức vận hành | Gần như không | Bạn lo cache, scale, CDN, log |
| Tính năng Next.js | Đầy đủ ngay (PPR, ISR, image, cache toàn cục) | Đầy đủ nhưng phải cấu hình cache handler, CDN |
| Chi phí | Rẻ khi nhỏ; tăng nhanh theo băng thông/function | Dự đoán được khi lớn |
| Dữ liệu và tuân thủ | Theo region của Vercel | Toàn quyền (VPC, dữ liệu trong nước) |
Next.js có Build Adapters API để các nền tảng (Netlify, Cloudflare, AWS qua OpenNext) hỗ trợ đầy đủ hơn — kiểm tra adapter của nền tảng bạn chọn.
Dockerfile
// next.config.ts
const nextConfig = { output: 'standalone' }; // chỉ copy đúng file cần chạy vào .next/standalone
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
RUN npm run build
FROM node:22-alpine AS run
WORKDIR /app
ENV NODE_ENV=production PORT=8080 HOSTNAME=0.0.0.0
RUN addgroup -S app && adduser -S app -G app
COPY --from=build --chown=app:app /app/.next/standalone ./
COPY --from=build --chown=app:app /app/.next/static ./.next/static
COPY --from=build --chown=app:app /app/public ./public
USER app
EXPOSE 8080
CMD ["node", "server.js"]
Image cuối ~150-200MB thay vì >1GB. Biến NEXT_PUBLIC_* được nhúng lúc build → phải có lúc docker build
(build-arg) và mỗi môi trường cần build riêng, hoặc chuyển cấu hình client sang đọc runtime từ server.
Deploy Cloud Run (GCP)
# Build và đẩy image lên Artifact Registry
gcloud builds submit --tag asia-southeast1-docker.pkg.dev/$PROJECT/web/shop:$GIT_SHA
# Deploy
gcloud run deploy shop \
--image asia-southeast1-docker.pkg.dev/$PROJECT/web/shop:$GIT_SHA \
--region asia-southeast1 --port 8080 \
--min-instances 1 --max-instances 20 --concurrency 80 --cpu 1 --memory 1Gi \
--add-cloudsql-instances $PROJECT:asia-southeast1:shop-db \
--set-secrets DATABASE_URL=db-url:latest,SESSION_SECRET=session-secret:latest \
--service-account shop-runtime@$PROJECT.iam.gserviceaccount.com
--min-instances 1tránh cold start cho trang chính;--concurrencyhợp với Node (nhiều request trên một instance).- Secret từ Secret Manager, service account có quyền tối thiểu.
- Đặt Cloud CDN / Load Balancer phía trước cho
/_next/static/*(file có hash, cacheimmutable1 năm) và ảnh. - Region trùng với Cloud SQL; dùng connector hoặc private IP.
Chạy nhiều instance: ba vấn đề phải xử lý
| Vấn đề | Triệu chứng | Cách xử lý |
|---|---|---|
| Cache nằm trong bộ nhớ/đĩa của từng instance | Sửa giá, instance A thấy mới, instance B vẫn cũ | Cấu hình cacheHandler/cacheHandlers dùng Redis (Memorystore) chung; revalidate lan tới mọi instance |
| Khoá mã hoá Server Action khác nhau giữa các build/instance | Lỗi "Failed to find Server Action" hoặc giải mã lỗi sau deploy | Đặt cố định NEXT_SERVER_ACTIONS_ENCRYPTION_KEY cho mọi instance của một bản build |
| Version skew: trình duyệt mở bản cũ gọi tới server bản mới | Chunk 404, action không tồn tại | deploymentId trong config; giữ static asset cũ một thời gian (bucket); bắt lỗi chunk và reload |
// next.config.ts
const nextConfig = {
output: 'standalone',
deploymentId: process.env.GIT_SHA,
cacheComponents: true,
cacheHandlers: { default: require.resolve('./cache-handler-redis.mjs'), remote: require.resolve('./cache-handler-redis.mjs') },
};
(API cache handler có hai thế hệ: cacheHandler cho ISR/data cache cũ và cacheHandlers cho 'use cache' — đối chiếu tài liệu
"Self-hosting" của đúng phiên bản bạn dùng.)
CI/CD
# .github/workflows/deploy.yml (rút gọn)
on: { push: { branches: [main] } }
permissions: { id-token: write, contents: read } # Workload Identity Federation, không lưu key JSON
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: google-github-actions/auth@v2
with:
workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
service_account: deployer@${{ vars.PROJECT }}.iam.gserviceaccount.com
- uses: google-github-actions/setup-gcloud@v2
- run: gcloud builds submit --tag $IMAGE:${{ github.sha }}
- run: npm run db:migrate # migration tương thích ngược (expand/contract) trước khi đổi code
- run: gcloud run deploy shop --image $IMAGE:${{ github.sha }} --region asia-southeast1 --no-traffic --tag sha-${GITHUB_SHA::7}
- run: npx playwright test --grep @smoke # smoke test trên URL tag mới
env: { BASE_URL: https://sha-${{ github.sha }}---shop-xyz.a.run.app }
- run: gcloud run services update-traffic shop --to-latest --region asia-southeast1
Deploy bản mới không nhận traffic → smoke test → chuyển traffic (có thể từng phần, ví dụ 10%) → rollback bằng một lệnh chuyển traffic về revision cũ.
Observability
// instrumentation.ts (gốc dự án)
export async function register() {
if (process.env.NEXT_RUNTIME === 'nodejs') {
const { registerOTel } = await import('@vercel/otel');
registerOTel({ serviceName: 'shop-web' }); // trace tự động cho request, fetch, render
}
}
export async function onRequestError(err: unknown, request: { path: string; method: string }, context: { routerKind: string; routePath: string; routeType: string }) {
await logger.error({ err, path: request.path, route: context.routePath, type: context.routeType }, 'request_error');
}
- Log JSON một dòng (pino) ra stdout → Cloud Logging tự parse; gắn
traceđể nối log với Cloud Trace. - Theo dõi: tỷ lệ lỗi 5xx, p95 latency theo route, cold start, cache hit rate, Web Vitals từ RUM.
- Cảnh báo theo SLO (ví dụ 99.5% request < 1s) thay vì theo từng spike CPU.
🚩 Sai lầm hay gặp
- Nhiều instance mà không có cache handler chung.
- Không cố định khoá mã hoá Server Action.
- Migration phá vỡ tương thích chạy cùng lúc với deploy code mới.
- Lưu service account key JSON trong GitHub secrets thay vì Workload Identity Federation.
🏋️ Bài tập thực hành
Dockerfile standalone, Cloud Run 2+ instance, Cloud SQL, Memorystore làm cache handler, Secret Manager, GitHub Actions với WIF, deploy không traffic + smoke test + chuyển traffic. Chứng minh: sửa giá ở một request, gọi 20 lần (đi qua các instance khác nhau) đều thấy giá mới. Có dashboard p95 latency và log lỗi.
📚 Tài nguyên học tập
-
Next.js — Self-HostingCache handler, encryption key, skewDocs
-
Next.js — DeployingCác lựa chọn deployDocs
- Docs
- Docs
✅ Tự đánh giá hoàn thành
- Tôi viết được Dockerfile standalone chạy user không phải root
- Tôi deploy được lên Cloud Run với secret và Cloud SQL
- Tôi giải thích và xử lý được 3 vấn đề khi chạy nhiều instance
- Tôi có pipeline deploy có smoke test và rollback
- Tôi thiết lập được instrumentation và log có cấu trúc