Khắc phục sự cố Docker

Trang này cung cấp hướng dẫn khắc phục sự cố cho các vấn đề bạn có thể gặp phải với Docker builds được tạo ra bởi các generators. Xem hướng dẫn Docker Bundling để hiểu về mẫu mà chúng tuân theo.

Cross-Platform Builds

Các generators như ts#agent, py#agent, ts#mcp-server, và py#mcp-server tạo ra các images cho linux/arm64 (Graviton), bất kể kiến trúc máy chủ. Việc xây dựng một image arm64 trên máy chủ x86_64 — hoặc một image amd64 trên Apple Silicon — yêu cầu hỗ trợ multi-platform build trong cài đặt Docker cục bộ của bạn.

Nếu multi-platform builds không được thiết lập, triệu chứng phụ thuộc vào Dockerfile:

Dockerfile có bước RUN (TypeScript generators RUN npm install cho các dependencies không thể bundle): quá trình build thất bại giữa chừng với
Terminal window
```
exec /bin/sh: exec format error
```
Dockerfile chỉ sử dụng COPY (Python generators): quá trình build thành công, nhưng docker run sau đó thất bại với
Terminal window
```
exec /usr/local/bin/python: exec format error
```
Base image không khả dụng cho nền tảng đích: quá trình build thất bại ở bước FROM với no match for platform in manifest.

Bật Multi-Platform Builds

Docker Desktop (Mac / Windows / Linux) đi kèm với mô phỏng QEMU được bật sẵn — thường không cần thiết lập thêm.

Máy chủ Linux (bao gồm CI runners) cần các QEMU binfmt handlers được đăng ký với kernel. Cài đặt chúng một lần cho mỗi máy:

docker run --privileged --rm tonistiigi/binfmt --install all

Xác minh các nền tảng được hỗ trợ khớp với những gì dự án của bạn nhắm đến:

docker buildx inspect --bootstrap

Dòng Platforms: nên bao gồm linux/arm64.

Builds Chậm trên Kiến trúc Được Mô phỏng

Việc xây dựng một image arm64 trên máy chủ x86_64 (hoặc ngược lại) sử dụng QEMU để mô phỏng từng lệnh, có thể chậm hơn nhiều lần so với một native build. Các generators giảm thiểu điều này bằng cách thực hiện dependency resolution bên ngoài Dockerfile — xem Docker Bundling. Nếu bạn vẫn thấy Docker builds chậm:

Đảm bảo bạn đang chạy các targets bundle / docker thông qua Nx (nx docker my-project) để bundle được cache giữa các lần chạy.
Trên CI, hãy xem xét một native ARM runner (ví dụ: ubuntu-24.04-arm của GitHub Actions) để tránh hoàn toàn QEMU.

Thiếu Build Context tại `cdk deploy` / `nx apply`

Target docker được tạo ra ghi build context của nó vào dist/packages/<project>/docker/... (Python) hoặc dist/packages/<project>/bundle/... (TypeScript), và infrastructure as code được tạo ra trỏ đến thư mục đó. Nếu thư mục đó không tồn tại khi bạn synth hoặc apply, bạn sẽ thấy các lỗi như ENOENT hoặc “directory does not exist”.

Các generators khai báo target docker là một dependency của build, vì vậy nx build (hoặc các targets nx deploy / nx apply được tạo ra) sẽ tạo ra build context trước khi CDK hoặc Terraform chạy. Nếu bạn gọi cdk hoặc terraform trực tiếp, hãy chạy bước docker trước:

nx run my-project:docker

Đọc thêm

Docker — Multi-platform builds
Hướng dẫn Docker Bundling — mẫu mà các generators tuân theo.