Next.js từ cơ bản đến nâng cao
Trang chủ / Module 17
☁️ Module 17 / 18 · 5 ngày 📅 Tuần 10 ●●●○ Khó

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.

output: standaloneCloud RunCache handlerOpenTelemetry
📌 Vì sao module này quan trọng

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

VercelSelf-host (Docker trên Cloud Run/GKE/VM)
Công sức vận hànhGần như khôngBạ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/functionDự đoán được khi lớn
Dữ liệu và tuân thủTheo region của VercelToà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 1 tránh cold start cho trang chính; --concurrency hợ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, cache immutable 1 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ứngCách xử lý
Cache nằm trong bộ nhớ/đĩa của từng instanceSử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/instanceLỗ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ớiChunk 404, action không tồn tạideploymentId 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

Đưa capstone lên GCP

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

✅ 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