LinuxUnity LinuxUnity

Bài viết / Docker

Docker: Multi-stage build

28/08/2026 7 phút đọc 9 lượt xem

PP Peter Parker

Trong bài này

Multi-stage build là gì và giải quyết vấn đề gì?

Một application hiện đại thường cần nhiều thứ để build hơn là để chạy: TypeScript compiler, test runner, bundler, native compiler, package manager cache và toàn bộ source code. Nếu đem tất cả vào production image, runtime image sẽ lớn hơn, có nhiều dependency hơn cần scan và nhiều tool hơn mức process thực sự cần.

Multi-stage build tách build environment khỏi runtime environment trong cùng một Dockerfile. Build stage tạo ra artifact. Final stage chỉ copy artifact và runtime dependency thật sự cần thiết.

Nó không phải phép thuật làm image luôn nhỏ hơn. Nếu copy nhầm node_modules chứa dev dependency, giữ lại compiler/library mà runtime không cần, hoặc base image vốn đã rất lớn, final image vẫn phình to. Multi-stage chỉ cho tôi ranh giới để làm đúng — làm đúng hay không vẫn tùy vào cách viết Dockerfile.

App demo: có dev dependency và build artifact

Tạo một app demo TypeScript nhỏ.

package.json:

text
{
  "name": "multi-stage-demo",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "start": "node dist/server.js"
  },
  "dependencies": {
    "express": "5.1.0"
  },
  "devDependencies": {
    "@types/express": "5.0.3",
    "@types/node": "22.15.3",
    "typescript": "5.8.3"
  }
}

src/server.ts:

typescript
import express from "express";

const app = express();
const port = Number(process.env.PORT || 3000);

app.get("/health", (_request, response) => {
  response.json({ ok: true });
});

app.listen(port, "0.0.0.0", () => {
  console.log(`listening on ${port}`);
});

tsconfig.json:

text
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"]
}

Cách đầu tiên: single-stage build

Dockerfile single-stage dễ viết:

text
FROM node:24-bookworm-slim
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build

ENV NODE_ENV=production
EXPOSE 3000
CMD ["npm", "start"]

Build và kiểm tra:

text
docker build -f Dockerfile.single --tag multi-stage-demo:single .
docker image ls multi-stage-demo:single
docker run --rm -p 3000:3000 multi-stage-demo:single

Image này chạy được. Nhưng nó giữ lại TypeScript, @types/*, source .ts, tsconfig và toàn bộ dev dependency. Runtime server thật ra chỉ cần JavaScript build artifact, Express runtime dependency và Node runtime — phần còn lại chỉ chiếm chỗ và tăng attack surface.

single-stage-layers

Cách thứ hai: multi-stage build

multi-stage-pipeline

Dockerfile multi-stage:

text
FROM node:24-bookworm-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM deps AS builder
COPY tsconfig.json ./
COPY src ./src
RUN npm run build

FROM node:24-bookworm-slim AS runner
WORKDIR /app
ENV NODE_ENV=production

COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY --from=builder /app/dist ./dist

USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

Build final stage:

text
docker build --tag multi-stage-demo:multi .
docker image ls multi-stage-demo:single multi-stage-demo:multi
docker run --rm -p 3000:3000 multi-stage-demo:multi

Final stage không copy src, tsconfig.json, TypeScript compiler hay @types. Nó cài lại production dependencies từ lockfile, sau đó chỉ copy dist từ builder sang.

Vì sao không copy nguyên node_modules từ builder

Cách dưới có thể hoạt động trong vài app:

text
COPY --from=builder /app/node_modules ./node_modules

Nhưng node_modules của builder thường chứa cả dev dependency. Nếu dùng cách này, final image vô tình giữ lại TypeScript, test library, type definitions. Có thể tách bằng một deps-prod stage riêng để prune, hoặc cài npm ci --omit=dev riêng ở runner như demo phía trên — cách thứ hai đơn giản và dễ audit hơn.

Với native dependency, vấn đề còn sâu hơn. Builder và runner phải tương thích OS, architecture và shared library. Copy node_modules từ Debian builder sang Alpine runner có thể fail lúc runtime vì khác libc (glibc vs musl). Đừng đổi base image ở final stage chỉ vì nó nhỏ hơn, nếu native artifact được build cho một base khác.

So sánh phải đo, không đoán

Sau khi build, lấy số đo thực tế trên máy local:

text
docker image ls multi-stage-demo:single multi-stage-demo:multi

docker run --rm multi-stage-demo:single sh -lc \
  'test -d node_modules/typescript && echo "typescript exists"'

docker run --rm multi-stage-demo:multi sh -lc \
  'test ! -d node_modules/typescript && echo "typescript absent"'

Kết quả size phụ thuộc base image, lockfile, cache và architecture. Bài viết không nên nêu một con số MB cố định như kết quả phổ quát — mỗi máy, mỗi thời điểm build lại cho một con số hơi khác nhau. Chụp số liệu thật từ máy chạy lab và ghi rõ environment (OS, kiến trúc CPU, phiên bản Docker) đi kèm.

Image Size local Có TypeScript runtime? /health pass?
multi-stage-demo:single 97.9MB Có Có
multi-stage-demo:multi 81.7MB Không Có
text
root@unity:/home/docker-multibuild# docker image ls multi-stage-demo:single
                                                                                              
IMAGE                     ID             DISK USAGE   CONTENT SIZE   EXTRA
multi-stage-demo:single   df1f43025c01        419MB         97.9MB        
root@unity:/home/docker-multibuild# docker image ls multi-stage-demo:multi
                                                                                              
IMAGE                    ID             DISK USAGE   CONTENT SIZE   EXTRA
multi-stage-demo:multi   d57c625695c7        337MB         81.7MB

Multi-stage giúp gì ngoài image size

  • Final image có ít build tool hơn, giảm dependency surface và scan noise.
  • Dockerfile diễn đạt rõ artifact nào đi từ build sang runtime.
  • CI cache có thể tách dependency install với source build.
  • Runtime container dễ chạy non-root hơn vì chỉ cần writable path cụ thể.
  • Review release dễ hơn: final stage copy gì chính là runtime contract.

Multi-stage không tự giải quyết:

  • Secret bị truyền vào build hoặc hardcode trong source.
  • CVE trong base image/runtime dependency.
  • Health check không phản ánh database readiness.
  • Database migration chạy đồng thời khi nhiều replica boot.
  • Persistent upload/data bị đặt trong local container filesystem.

Khi nào multi-stage không đáng phức tạp

Một static config image rất nhỏ, không có build artifact, có thể chỉ cần một stage. Một image tool/debug cũng có thể chủ ý giữ lại CLI utility. Nhưng application production có compile/bundle/native build thường nên có build/runtime boundary rõ ràng.

Đừng ép multi-stage nếu final stage cuối cùng vẫn copy lại toàn bộ source, full node_modules, compiler và package manager cache. Khi đó Dockerfile dài hơn nhưng boundary vẫn không tồn tại.

LinuxUnity sẽ áp dụng gì từ đây

LinuxUnity đã dùng multi-stage Dockerfile phức tạp hơn demo: build libvips native, build Sharp theo ràng buộc compatibility, prune production dependency, build Next.js standalone rồi copy artifact cần cho runtime. Điều đáng học không phải chỉ là số stage. Điều đáng học là mỗi stage có trách nhiệm rõ ràng:

text
native library build -> dependency build -> Next.js build -> minimal runner

Kết Luận

Multi-stage build không phải chiếc đũa thần tự động làm nhỏ Docker image, mà là công cụ giúp bạn thiết lập ranh giới kiến trúc rõ ràng giữa môi trường build và môi trường runtime. Việc giảm dung lượng từ 97.9MB xuống 81.7MB ở bài demo trên chỉ là kết quả bề nổi; giá trị cốt lõi nằm ở việc loại bỏ triệt để các dev dependency, thu hẹp diện tích tấn công (attack surface) và làm cho runtime contract của ứng dụng trở nên minh bạch.

Những điểm then chốt cần đóng gói lại:

  • Tự tạo ranh giới đúng: Multi-stage chỉ cung cấp cơ chế, còn việc chọn lọc những artifact nào được đi tiếp vào final stage hoàn toàn phụ thuộc vào kỷ luật viết Dockerfile. Copy nguyên khối node_modules hay giữ lại compiler thừa sẽ triệt tiêu toàn bộ lợi ích của việc chia stage.
  • Đo lường thực tế, không đoán mò: Đừng chọn base image chỉ vì một con số MB trên mạng. Mỗi môi trường build, kiến trúc CPU và phiên bản Docker sẽ cho ra kết quả khác nhau. Hãy luôn đo đạc số liệu thực tế trên máy local/CI trước khi đưa ra quyết định.
  • Cẩn trọng với Native Dependencies: Tốc độ hay dung lượng nhỏ của Alpine/musl không bao giờ đáng đánh đổi bằng sự bất ổn định của hệ thống runtime. Việc đổi base image ở final stage mà không kiểm tra khả năng tương thích của shared library (glibc vs musl) là nguyên nhân hàng đầu gây ra lỗi runtime ẩn.

Nắm vững tư duy phân tách ranh giới này là tiền đề quan trọng trước khi xử lý các bài toán containerization phức tạp hơn trong thực tế.