Ứ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.
Mục lục
Cập nhật 2026
- Docker Engine 28/29 và Compose v2 (
docker compose) là chuẩn. Keyversion:trong file compose đã bị bỏ; Compose in cảnh báo “the attributeversionis obsolete” nếu bạn còn giữ. - Image .NET 8+ đã đổi cổng mặc định trong container sang 8080.
EXPOSE 80trong 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_UIDlà 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:PublishContainervới các propertyContainerFamily,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/packagesgiữ cache NuGet giữa các lần build, kể cả khi layerrestorebị 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
.csprojtrướ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=falsebỏ file apphost native — trong container ta chạy bằngdotnet Shop.Api.dll, nên file đó thừa.USER $APP_UIDđặt sauCOPYđể việc ghi file vào/appvẫ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
curltrong stage cuối, rồiHEALTHCHECK 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 execkhông vào được bằng shell, và app cần globalization đầy đủ phải dùng biến thể-extrahoặc bậtInvariantGlobalization.- 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ướcrestore: 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
aspnetlà root. ThiếuUSER $APP_UIDnghĩ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:
ENVlúc build,appsettings.Production.jsoncopy vào image, connection string trongdocker-compose.ymlcommit lên git. depends_onkhô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
latesttrong 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,
restoretách khỏiCOPY . ., có cache mount. USER $APP_UID, không port 80, tag theo version..dockerignoreloạibin/,obj/,.git/, file cấu hình dev.- Không secret trong image, không secret trong compose commit.
- Có
/healthrẻ, và biết ai sẽ probe nó. - Đã chạy
docker scout cvesvà đọc kích thước image.
Đọc tiếp trong series:



