docker-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docker Development

Docker 开发

Patterns for building, testing, and deploying Docker containers.

构建、测试和部署Docker容器的模式。

Core Principles

核心原则

Minimal images -- Alpine/distroless, multi-stage builds
Security first -- Non-root USER, no secrets in layers, pin versions
Testable -- Verifiable in CI with entrypoint bypass and DNS mocking
Cache-efficient -- Copy dependency files first, clean in same layer

最小化镜像 -- 使用Alpine/distroless基础镜像、多阶段构建
安全优先 -- 使用非root用户USER、不在镜像层中存储密钥、固定版本
可测试性 -- 在CI中通过绕过入口点和DNS模拟进行验证
缓存高效 -- 先复制依赖文件，在同一层中清理无用内容

Quick Reference

快速参考

Multi-Stage Build (Node.js)

多阶段构建（Node.js）

dockerfile

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

FROM node:20-alpine
RUN addgroup -g 1001 app && adduser -u 1001 -G app -D app
USER app
COPY --from=builder /app .
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "server.js"]

dockerfile

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

FROM node:20-alpine
RUN addgroup -g 1001 app && adduser -u 1001 -G app -D app
USER app
COPY --from=builder /app .
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "server.js"]

Multi-Stage Build (Go -- scratch/distroless)

多阶段构建（Go -- scratch/distroless）

dockerfile

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.* ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app/server .

FROM gcr.io/distroless/static:nonroot
COPY --from=builder /app/server /server
CMD ["/server"]

dockerfile

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.* ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app/server .

FROM gcr.io/distroless/static:nonroot
COPY --from=builder /app/server /server
CMD ["/server"]

Layer Optimization

镜像层优化

dockerfile

RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

dockerfile

RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

Build Cache: Copy Dependency Files First

构建缓存：先复制依赖文件

dockerfile

COPY package*.json ./
RUN npm ci
COPY . .

Dependency manifests before source so install layers stay cached on source-only changes.

dockerfile

COPY package*.json ./
RUN npm ci
COPY . .

先复制依赖清单再复制源码，这样当仅源码变化时，安装依赖的镜像层会保持缓存。

BuildKit Secrets

BuildKit 密钥管理

dockerfile

RUN --mount=type=secret,id=ssh_key,dst=/root/.ssh/id_rsa git clone git@github.com:org/repo.git

Secrets in

ENV

ARG

COPY

persist in layer history (

docker history

). Use

--mount=type=secret

dockerfile

RUN --mount=type=secret,id=ssh_key,dst=/root/.ssh/id_rsa git clone git@github.com:org/repo.git

通过

ENV

ARG

COPY

设置的密钥会保留在镜像层历史中（可通过

docker history

查看）。请使用

--mount=type=secret

方式。

Docker Bake (Multi-Platform)

Docker Bake（多平台构建）

hcl

target "app" {
  platforms = ["linux/amd64", "linux/arm64"]
  cache-from = ["type=gha"]
  cache-to = ["type=gha,mode=max"]
}

hcl

target "app" {
  platforms = ["linux/amd64", "linux/arm64"]
  cache-from = ["type=gha"]
  cache-to = ["type=gha,mode=max"]
}

Security Anti-Patterns

安全反模式

Anti-pattern	Fix
`FROM image:latest`	Pin version: `image:1.2.3-alpine`
No `USER` directive	`adduser` + `USER appuser`
`chmod 777`	Use specific permissions: `chmod 550`
`privileged: true` in compose	Remove or use specific `cap_add`
`volumes: [/:/host]`	Mount only needed paths
`ports: ["0.0.0.0:3000:3000"]`	Bind to `127.0.0.1:3000:3000`
`ENV DB_PASSWORD=secret`	Use `--mount=type=secret` or compose secrets

反模式	修复方案
`FROM image:latest`	固定版本： `image:1.2.3-alpine`
未设置 `USER` 指令	使用 `adduser` 创建用户并设置 `USER appuser`
`chmod 777`	使用特定权限： `chmod 550`
compose中设置 `privileged: true`	移除该配置或使用特定的 `cap_add`
`volumes: [/:/host]`	仅挂载所需路径
`ports: ["0.0.0.0:3000:3000"]`	绑定到 `127.0.0.1:3000:3000`
`ENV DB_PASSWORD=secret`	使用 `--mount=type=secret` 或compose密钥管理

CI Testing Gotchas

CI测试注意事项

Bypass entrypoint:

docker run --rm --entrypoint php myimage -v

Mock upstream DNS:

docker run --rm --add-host backend:127.0.0.1 nginx-image nginx -t

Compose validation:

cp .env.example .env

before

docker compose config

Secret scanning: Exclude
```
.env.example
```
, README, docs from scanners

绕过入口点：

docker run --rm --entrypoint php myimage -v

模拟上游DNS：

docker run --rm --add-host backend:127.0.0.1 nginx-image nginx -t

Compose验证：在执行
```
docker compose config
```
前复制
```
.env.example
```
为
```
.env
```
密钥扫描：将
```
.env.example
```
、README、文档排除在扫描范围外

.dockerignore

.dockerignore配置

Exclude:

.git

node_modules

vendor

.env*

*.pem

*.key

需排除的内容：

.git

、

node_modules

vendor

、

.env*

、

*.pem

、

*.key

Compose Essentials

Compose核心要点

depends_on

with

condition: service_healthy

healthcheck

with

start_period

for startup ordering

```
networks
```
with
```
internal: true
```
for database isolation from external access
```
profiles: [debug]
```
for optional services that only start with
```
--profile debug
```

使用
```
depends_on
```
搭配
```
condition: service_healthy
```
，并为依赖服务设置包含
```
start_period
```
的
```
healthcheck
```
来控制启动顺序
使用
```
networks
```
并设置
```
internal: true
```
实现数据库与外部访问隔离
使用
```
profiles: [debug]
```
定义可选服务，仅在添加
```
--profile debug
```
参数时启动

References

参考资料

```
references/ci-testing.md
```
-- Comprehensive CI testing patterns for Docker images

```
references/ci-testing.md
```
-- Docker镜像的CI测试完整模式指南