Docker hóa Ứng Dụng ASP.NET Core Của Bạn: Hướng Dẫn Từng Bước – Lộ Trình .NET

Ứng dụng ASP.NET Core chạy tốt trên máy bạn rồi chết trên server vì thiếu ICU, vì chuỗi kết nối trỏ vào localhost, hoặc vì runtime 9.0 còn sót lại. Docker không sửa được những lỗi đó, nhưng nó biến môi trường thành thứ lặp lại được. Bài này đi từ Dockerfile multi-stage cho .NET 10 tới Compose v2, kèm phần so sánh với cách đóng gói image trực tiếp từ SDK — chọn sai giữa hai cách này là nguồn gốc của phần lớn pipeline chậm.

Cập nhật 2026

  • Docker Engine 28/29 và Compose v2 (docker compose) là chuẩn. Key version: trong file compose đã bị bỏ; Compose in cảnh báo “the attribute version is obsolete” nếu bạn còn giữ.
  • Image .NET 8+ đã đổi cổng mặc định trong container sang 8080. EXPOSE 80 trong các bài cũ chỉ còn đúng với .NET 7 trở xuống.
  • Image chính thức có sẵn biến APP_UID (UID 1654); USER $APP_UID là cách chạy non-root mà không phải tạo user thủ công.
  • SDK .NET 10 publish được container image mà không cần Dockerfile: /t:PublishContainer với các property ContainerFamily, ContainerImageTags, ContainerRegistry.

Mô hình: image là layer, container là process

Một image là chồng layer chỉ-đọc, mỗi instruction trong Dockerfile tạo một layer. Container là image cộng thêm một lớp ghi được và một process. Hiểu điều này là hiểu luôn vì sao thứ tự instruction quyết định tốc độ build: layer nào không đổi thì BuildKit dùng lại cache, layer nào đổi thì mọi layer phía sau bị build lại.

Multi-stage là hệ quả trực tiếp: stage build cần SDK (vài trăm MB, có compiler, MSBuild, NuGet client), stage chạy chỉ cần aspnet runtime. Nếu bạn ship image chứa SDK, bạn ship cả một toolchain có thể biên dịch mã — không ai cần thứ đó trong production, và nó là bề mặt tấn công miễn phí.

Dockerfile .NET 10 dùng được cho production

Giả định project tên Shop.Api, có Central Package Management (Directory.Packages.props):

# syntax=docker/dockerfile:1
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src

COPY Directory.Build.props Directory.Packages.props ./
COPY Shop.Api/Shop.Api.csproj Shop.Api/
RUN --mount=type=cache,target=/root/.nuget/packages \
    dotnet restore Shop.Api/Shop.Api.csproj

COPY . .
RUN --mount=type=cache,target=/root/.nuget/packages \
    dotnet publish Shop.Api/Shop.Api.csproj \
      -c Release -o /app/publish --no-restore /p:UseAppHost=false

FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app
COPY --from=build /app/publish .
USER $APP_UID
EXPOSE 8080
ENTRYPOINT ["dotnet", "Shop.Api.dll"]

Bốn điểm đáng chú ý:

  • --mount=type=cache,target=/root/.nuget/packages giữ cache NuGet giữa các lần build, kể cả khi layer restore bị vô hiệu. Không có nó, mỗi lần đổi một dòng code là tải lại toàn bộ package.
  • Copy .csproj trước, copy source sau. Nhờ vậy sửa code không kéo theo restore. Nếu dùng CPM, phải copy cả Directory.Packages.props, nếu không restore sẽ đọc sai version.
  • /p:UseAppHost=false bỏ file apphost native — trong container ta chạy bằng dotnet Shop.Api.dll, nên file đó thừa.
  • USER $APP_UID đặt sau COPY để việc ghi file vào /app vẫn làm được lúc build, nhưng process chạy bằng user không phải root.

Đừng đặt ASPNETCORE_URLS=http://+:80 như các bài cũ. Image .NET 10 lắng nghe 8080 qua ASPNETCORE_HTTP_PORTS; chỉ khi thật sự cần cổng khác mới override, và khi đó sửa cả EXPOSE, mapping, probe.

.dockerignore quyết định tốc độ build

Build context được gửi nguyên thư mục cho daemon (hoặc BuildKit). Gửi kèm bin/, obj/, .git/ là tự làm chậm mọi lần build và có nguy cơ copy rác vào image.

**/bin/
**/obj/
.git/
.vs/
.vscode/
.idea/
*.user
**/appsettings.Development.json
**/*.Tests/
docs/
docker-compose*.yml
.env

Dòng appsettings.Development.json không chỉ để giảm size: file đó thường chứa connection string máy cá nhân, và nếu nó nằm trong image thì nó nằm trong registry, trong layer cache, trong bản backup registry. Xóa file khỏi image sau khi COPY cũng không xóa được layer chứa nó.

Build và chạy

docker build -t shop-api:1.0.0 .
docker run --rm -p 8080:8080 \
  -e ASPNETCORE_ENVIRONMENT=Development \
  shop-api:1.0.0
curl -i http://localhost:8080/health

Tag theo version (1.0.0) và chỉ dùng latest như bí danh phụ. Trong registry, tag bất biến (immutable) là điều kiện để rollback có nghĩa; nhiều registry cho phép bật chế độ cấm ghi đè tag, hãy bật.

Đóng gói bằng SDK thay vì Dockerfile

dotnet publish Shop.Api/Shop.Api.csproj -c Release \
  /t:PublishContainer \
  -p:ContainerFamily=noble-chiseled \
  -p:ContainerImageTags="1.0.0;latest" \
  -p:ContainerRegistry=ghcr.io \
  -p:ContainerRepository=evotek/shop-api

Target PublishContainer dựng image từ output publish, không cần Dockerfile và không cần Docker daemon — nó làm việc với registry API, hoặc ghi ra file tar bằng -p:ContainerArchiveOutputPath=./out/shop-api.tar để nơi khác load vào. Với CI chỉ có dotnet, đây là đường ngắn nhất.

Tiêu chí Dockerfile /t:PublishContainer
Kiểm soát layer, base image, apt package Toàn quyền Chỉ qua property
Multi-arch buildx, --platform Cần buildx hoặc build riêng từng arch
Cache NuGet Cache mount, kiểm soát được Dựa vào cache NuGet của máy/CI
Phù hợp khi Image cần tuỳ biến, nhiều project CI tối giản, app chuẩn

Lưu ý: publish container qua SDK không chạy docker build, nên các thứ như HEALTHCHECK, apt-get, hay một .dockerignore phức tạp đều không áp dụng. Nếu bạn cần chúng, quay lại Dockerfile.

Compose v2 cho dev, và bản prod khác ở đâu

Ứng dụng thật cần Postgres, Redis, có khi cả broker. Compose gom chúng vào một file, nhưng file dev và file prod không nên giống nhau.

name: shop

services:
  api:
    build:
      context: .
      target: final
    ports:
      - "8080:8080"
    environment:
      ASPNETCORE_ENVIRONMENT: Development
      ConnectionStrings__ShopDb: Host=db;Port=5432;Database=shop;Username=shop;Password=${POSTGRES_PASSWORD}
    depends_on:
      db:
        condition: service_healthy
    develop:
      watch:
        - action: rebuild
          path: ./Shop.Api

  db:
    image: postgres:17
    environment:
      POSTGRES_DB: shop
      POSTGRES_USER: shop
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U shop -d shop"]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  pgdata:

Ba thứ đã thay đổi so với bài viết kiểu 2024: không còn key version; depends_on với condition: service_healthy thay cho depends_on trần (bản trần chỉ đảm bảo thứ tự start, không đảm bảo DB sẵn sàng); và develop.watch thay cho bind-mount cả thư mục source — bind-mount source lên /app sẽ đè mất output publish và app chết với lỗi thiếu deps.json.

docker compose watch theo dõi thay đổi và rebuild (hoặc sync) container. Với vòng lặp trong ngày, nó rẻ hơn docker compose up --build và không cần mount source.

Bản prod thì khác về bản chất: không build, chỉ image: ghcr.io/evotek/shop-api@sha256:... (pin digest, không pin tag), không bind mount, read_only: true nếu app không ghi file, security_opt: ["no-new-privileges:true"], restart: unless-stopped, và giới hạn tài nguyên bằng mem_limit/cpus (các key deploy.resources chỉ có hiệu lực dưới Swarm).

Secret: đừng dùng ENV cho mật khẩu

Biến môi trường hiện trong docker inspect, trong docker compose config, và thường trong log của CI. Với Compose, dùng secrets dạng file — nó được mount vào /run/secrets/<name> và không xuất hiện trong metadata container:

services:
  api:
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

Phía ứng dụng, đọc thư mục đó như một nguồn cấu hình:

// File: Shop.Api/Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddKeyPerFile("/run/secrets", optional: true, reloadOnChange: false);

Key trong file db_password thành config key db_password, và bạn ghép connection string từ đó thay vì đặt cả chuỗi vào ENV. Trên Kubernetes hay cloud, thay bằng Secret/Key Vault — cùng một nguyên tắc: cấu hình nhạy cảm vào qua file hoặc volume, không qua ENV của image.

Healthcheck: cái bẫy của image tối giản

Ứng dụng cần một endpoint rẻ, không chạm database:

// File: Shop.Api/Program.cs
builder.Services.AddHealthChecks().AddCheck("self", () => HealthCheckResult.Healthy());
var app = builder.Build();
app.MapHealthChecks("/health");

Nhưng HEALTHCHECK trong Dockerfile cần một executable bên trong image. Image chiseled không có shell, không có curl, không có wget — CMD-SHELL sẽ fail ngay. Hai lựa chọn trung thực:

  • Image Debian + cài curl trong stage cuối, rồi HEALTHCHECK CMD curl -fsS http://localhost:8080/health || exit 1. Đơn giản, nhưng thêm package và tăng bề mặt tấn công.
  • Image chiseled và để orchestrator probe HTTP từ ngoài (Kubernetes readinessProbe, hoặc load balancer). Không cần binary nào trong image.

Đừng ngụy trang liveness bằng cách gọi endpoint có kiểm tra DB: khi DB sập, mọi container báo unhealthy và bị restart cùng lúc, biến một sự cố thành hai.

Kích thước image và image tối giản

Ba mức, chọn theo mức độ chấp nhận vận hành:

  • aspnet:10.0 — Debian, có shell, dễ debug, dễ cài thêm. Mặc định hợp lý.
  • aspnet:10.0-noble-chiseled — không shell, không package manager, chạy non-root, ít CVE hơn. Đổi lại: docker exec không vào được bằng shell, và app cần globalization đầy đủ phải dùng biến thể -extra hoặc bật InvariantGlobalization.
  • Image .NET của Chainguard — distroless, non-root, có SBOM và chữ ký. Tag thay đổi theo thời gian nên phải kiểm tra registry trước khi pin, đừng copy tag từ blog cũ.

Kiểm tra thay vì đoán: docker scout cves shop-api:1.0.0 và docker images shop-api. Nếu image vượt vài trăm MB, gần như chắc chắn bạn đang ship SDK hoặc copy cả bin/.

Cạm bẫy thường gặp

  • COPY . . trước restore: mọi thay đổi code đều làm mất cache NuGet. Đây là lỗi phổ biến nhất và cũng dễ sửa nhất.
  • Chạy root: mặc định của image aspnet là root. Thiếu USER $APP_UID nghĩa là container compromise = root trong container, và trên một số cấu hình là thoát ra host dễ hơn.
  • Secret trong image: ENV lúc build, appsettings.Production.json copy vào image, connection string trong docker-compose.yml commit lên git.
  • depends_on không kèm health condition: app start trước khi Postgres nhận kết nối, rồi migration ném lỗi. Sửa ở cả hai phía: health condition và retry khi mở kết nối.
  • Mount source trong dev: đã nói ở trên — dùng develop.watch.
  • Tag latest trong prod: hai lần deploy “cùng một tag” có thể là hai image khác nhau; rollback không xác định.

Debug bên trong container

Với image Debian, docker exec -it shop-api sh và docker logs -f shop-api là đủ cho phần lớn sự cố. Với image chiseled, không có shell: dùng docker debug (Docker Desktop) để gắn một toolbox tạm vào container đang chạy hoặc đã chết, hoặc chuyển sang image Debian ở nhánh debug. Với vòng lặp code, docker compose watch nhanh hơn attach debugger; chỉ attach khi cần breakpoint thật, và khi đó build cấu hình Debug có vsdbg trong một stage riêng.

Khi nào Compose là đủ, khi nào chưa

Tình huống Lựa chọn Lý do
Máy dev, 1–5 service Compose + watch Nhanh, không cần cluster
Prod 1 VM, tải ổn định Compose + digest + restart policy Không cần scheduler; chấp nhận downtime khi deploy
Nhiều replica, zero-downtime, autoscale Kubernetes + Helm Rolling update, probe, HPA
Dev cho hệ phân tán nhiều service .NET Aspire AppHost Orchestration + dashboard + OTel sẵn

Nhìn tới 2027

.NET 11 GA tháng 11/2026 (STS) sẽ có image 11.0; các tag 10.0 vẫn được vá đến 2028. Docker Engine 29 với containerd image store và build attestation (SBOM, provenance) đang thành mặc định, nên chữ ký image sẽ là bước tiếp theo sau multi-stage — không phải tính năng thêm, mà là yêu cầu của khách hàng enterprise.

Checklist trước khi push image đầu tiên

  • Dockerfile multi-stage, restore tách khỏi COPY . ., có cache mount.
  • USER $APP_UID, không port 80, tag theo version.
  • .dockerignore loại bin/, obj/, .git/, file cấu hình dev.
  • Không secret trong image, không secret trong compose commit.
  • Có /health rẻ, và biết ai sẽ probe nó.
  • Đã chạy docker scout cves và đọc kích thước image.

Đọc tiếp trong series: