docker

Docker 核心知识

深入了解：使用 mcp__documentation__fetch_docs，并将技术设为：docker，以获取全面的文档。

Dockerfile（Node.js）

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./

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

Dockerfile（Python）

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

USER nobody
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

常用命令

# Build
docker build -t myapp:latest .
docker build -f Dockerfile.prod -t myapp:prod .

# Run
docker run -d -p 3000:3000 --name myapp myapp:latest
docker run --env-file .env myapp:latest

# Manage
docker ps                    # List running
docker logs myapp           # View logs
docker exec -it myapp sh    # Shell access
docker stop myapp           # Stop container
docker rm myapp             # Remove container

# Images
docker images               # List images
docker rmi myapp:latest     # Remove image
docker system prune         # Clean up

最佳实践

应做	不应做
使用多阶段构建	以 root 身份运行
使用 .dockerignore	复制 node_modules
使用明确指定版本的基础镜像标签	在生产环境使用 latest
每个容器只运行一个进程	安装不必要的软件包
利用层缓存（先 COPY package.json）	将密钥硬编码

.dockerignore

node_modules
.git
.env*
dist
*.log

不适用此技能的情况

以下情况请跳过此技能：

• 使用 docker-compose.yml 管理多容器应用——请使用 docker-compose 技能
• 在 Kubernetes 中编排容器——请使用 kubernetes 技能
• 自动化 CI/CD 流水线——请使用 github-actions 技能
• 仅运行第三方镜像，不创建 Dockerfile
• 使用抽象了 Docker 的容器平台（例如 Heroku、Google Cloud Run 配置）

反模式

反模式	问题	解决方案
在生产环境使用 :latest	部署结果不可预测	固定具体版本，如 node:20.10.0-alpine
以 root 身份运行	安全漏洞	使用 USER node 或创建非 root 用户
复制 node_modules/	构建速度慢、平台兼容性问题	将其添加到 .dockerignore，并在容器中运行 npm ci
安装开发依赖	镜像臃肿	使用 npm ci --only=production
不使用多阶段构建	生产镜像体积过大	分离构建阶段和运行阶段
在 ENV 中硬编码密钥	密钥暴露在镜像层中	使用 Docker secrets 或在运行时挂载
每条命令单独使用 RUN	产生过多镜像层	使用 && 链接相关命令
不使用 .dockerignore	上下文传输速度慢	排除不必要的文件
安装不必要的软件包	扩大攻击面、增加镜像体积	仅安装必需的软件包
不设置健康检查	不健康的容器仍会持续运行	添加 HEALTHCHECK 指令

快速故障排查

问题	诊断	修复方法
构建速度慢	构建上下文过大	添加 .dockerignore，优化层缓存
镜像体积过大	包含开发依赖、使用多个阶段	使用多阶段构建和 --only=production
容器中出现“Permission denied”	以 root 身份运行、文件所有权错误	使用 USER 指令和 COPY --chown
构建缓存未生效	在安装依赖前执行 COPY	先复制 package.json，再安装依赖，最后复制代码
容器立即崩溃	CMD/ENTRYPOINT 错误、缺少依赖	检查日志：docker logs <container>
无法连接数据库	网络错误、主机错误	使用服务名称作为主机名，并检查网络
出现“Exec format error”	平台错误（ARM 与 x86 不匹配）	为正确的平台构建：--platform linux/amd64
端口无法访问	未暴露或发布端口	使用 EXPOSE 和 docker run -p
文件未更新	使用了缓存层	清除缓存：docker build --no-cache
删除后卷数据仍然存在	未移除命名卷	使用 docker volume rm 或 docker-compose down -v

生产环境就绪

安全配置

# Security-hardened Dockerfile
FROM node:20-alpine AS builder

# Create non-root user
RUN addgroup -g 1001 appgroup && \
    adduser -u 1001 -G appgroup -s /bin/sh -D appuser

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

# Production image
FROM node:20-alpine

# Security: install security updates
RUN apk update && apk upgrade && rm -rf /var/cache/apk/*

# Create non-root user
RUN addgroup -g 1001 appgroup && \
    adduser -u 1001 -G appgroup -s /bin/sh -D appuser

WORKDIR /app

# Copy with correct ownership
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appgroup /app/package.json ./

# Drop privileges
USER appuser

# Security: read-only filesystem (use with docker run --read-only)
# Make /tmp writable if needed
VOLUME ["/tmp"]

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

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

镜像扫描

# Scan for vulnerabilities
docker scout cves myapp:latest
docker scout recommendations myapp:latest

# Alternative: Trivy scanner
trivy image myapp:latest

# Scan during CI/CD
docker build -t myapp:latest .
trivy image --exit-code 1 --severity HIGH,CRITICAL myapp:latest

资源限制

# docker-compose.yml with limits
services:
  app:
    image: myapp:latest
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M
    # Security options
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE

# Run with limits
docker run -d \
  --memory=512m \
  --memory-swap=512m \
  --cpus=1.0 \
  --read-only \
  --tmpfs /tmp \
  --security-opt=no-new-privileges:true \
  --cap-drop=ALL \
  myapp:latest

密钥管理

# docker-compose.yml with secrets
services:
  app:
    image: myapp:latest
    secrets:
      - db_password
      - api_key
    environment:
      - DB_PASSWORD_FILE=/run/secrets/db_password

secrets:
  db_password:
    external: true  # Or use file: ./secrets/db_password.txt
  api_key:
    external: true

// Read secrets in application
import { readFileSync } from 'fs';

const dbPassword = process.env.DB_PASSWORD_FILE
  ? readFileSync(process.env.DB_PASSWORD_FILE, 'utf8').trim()
  : process.env.DB_PASSWORD;

健康检查

# Dockerfile health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

# docker-compose.yml health check
services:
  app:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 10s

日志记录最佳实践

# docker-compose.yml logging
services:
  app:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
        labels: "service,environment"
        tag: "{{.Name}}/{{.ID}}"

# View logs with timestamps
docker logs --timestamps --tail 100 myapp

# Follow logs
docker logs -f myapp

# Logs from all containers
docker-compose logs -f --tail=100

网络安全

# docker-compose.yml network isolation
services:
  app:
    networks:
      - frontend
      - backend

  db:
    networks:
      - backend  # Not accessible from frontend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true  # No external access

监控指标

指标	告警阈值
容器 CPU 使用率	> 80%
容器内存使用率	> 80%
容器重启次数	5 分钟内 > 3 次
健康检查失败次数	> 0
镜像漏洞（严重）	> 0

生产环境命令

# Cleanup unused resources
docker system prune -af --volumes

# Monitor resources
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

# Check container health
docker inspect --format='{{.State.Health.Status}}' myapp

# Update without downtime (with docker-compose)
docker-compose pull
docker-compose up -d --no-deps --build app

检查清单

• 容器中使用非 root 用户
• 多阶段构建（最终镜像尽可能精简）
• 已配置 .dockerignore
• 指定基础镜像标签（而非 :latest）
• 已安装安全更新
• 已扫描镜像漏洞
• 已设置资源限制（CPU/内存）
• 根文件系统为只读
• 已移除不需要的功能
• 通过 Docker secrets 管理密钥（而非 ENV）
• 已配置运行状况检查
• 已配置日志轮换
• 网络隔离
• 镜像中不包含敏感数据

参考文档

• 多阶段构建
• 安全性