SuperAPI AI Directory

containerization

General & other

View repository

Updated 10-16 09:30

About this skill

Containerization

References: Docker official documentation, Google Distroless project, Trivy documentation, CNCF Container Security White Paper, Chainguard Images.

Use Cases

  • First-time application containerization (migration from bare metal / VM)
  • Image size optimization (>500MB needs slimming)
  • Multi-stage build design
  • Security baseline hardening (CVE scanning, non-root execution)
  • Local development environment orchestration (Docker Compose)
  • Image building and pushing in CI
  • Multi-architecture images (linux/amd64 + linux/arm64)

Core Principles

1. 最小化攻击面
   使用 Distroless / Alpine / scratch
   不安装调试工具到生产镜像

2. 多阶段构建
   编译阶段 → 运行阶段
   只复制产物,不复制源码

3. 层缓存优先
   依赖安装在前,源码复制在后
   利用 BuildKit 缓存挂载

4. 非 root 运行
   USER 指令指定非特权用户
   文件权限最小化

5. 可复现构建
   锁定基础镜像 digest
   锁定依赖版本

6. 扫描前置
   CI 中构建后立即扫描
   阻断 HIGH/CRITICAL 漏洞

7. 标签规范
   语义化版本 + git SHA
   不依赖 :latest

Workflow

1. 分析应用依赖
   - 运行时需要哪些系统库
   - 编译时需要哪些工具链
   - 区分 devDependencies vs dependencies

2. 选择基础镜像
   - 编译阶段:官方 SDK 镜像(node:20, golang:1.22, python:3.12)
   - 运行阶段:distroless / alpine / scratch
   - 锁定 digest(sha256:xxx)

3. 编写多阶段 Dockerfile
   - Stage 1: 安装依赖
   - Stage 2: 编译 / 构建
   - Stage 3: 仅复制产物到最小运行时

4. 优化层缓存
   - COPY package.json → RUN npm ci → COPY src/
   - 使用 --mount=type=cache 加速

5. 安全加固
   - 添加 .dockerignore
   - USER nonroot
   - HEALTHCHECK 指令
   - 不暴露不必要端口

6. 本地验证
   - docker build --target=production
   - docker compose up(集成测试)
   - dive 分析层

7. 安全扫描
   - trivy image <image>:<tag>
   - 阻断 HIGH/CRITICAL
   - 生成 SBOM

8. 推送与签名
   - docker push → registry
   - cosign sign(可选)
   - 记录 digest

Image Optimization Strategies

Strategy Effect Use Case
Multi-stage build 50-90% reduction All projects
Distroless 70%+ reduction Go / Java / Node
Alpine base 60% reduction Need shell debugging
.dockerignore Reduce build context All projects
--mount=type=cache Accelerate builds Projects with many dependencies
Merge RUN instructions Reduce layers Multiple apt-get scenarios
scratch Minimal (<10MB) Statically compiled Go

Docker Compose Orchestration

# docker-compose.yml 结构
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://db:5432/app
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 3

  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]

volumes:
  pgdata:

Quality Self-Check

□ 使用多阶段构建
□ 运行阶段基于 Distroless / Alpine / scratch
□ 基础镜像锁定 digest 或具体版本
□ 非 root 用户运行
□ .dockerignore 排除无关文件
□ 依赖安装层在源码复制层之前(缓存友好)
□ 无 secrets 硬编码在镜像中
□ HEALTHCHECK 已配置
□ Trivy 扫描无 HIGH/CRITICAL
□ 镜像大小合理(<200MB 应用层)
□ 多架构构建(如需)
□ docker compose 可一键启动本地环境
□ 标签使用语义化版本 + SHA

Common Pitfalls

  1. :latest tag——Not reproducible, production rollback is difficult
  2. Single-stage build——Image contains compilation toolchain, size 1GB+
  3. Running as root——Direct root privileges after container escape
  4. COPY . .——Packaging .git / node_modules / .env into the image
  5. Not pinning base image——Upstream updates cause build failures
  6. RUN apt-get without cleanup——Residual cache in each layer
  7. Secrets written into ENV——Visible via docker inspect
  8. Not using .dockerignore——Build context in GB
  9. Missing HEALTHCHECK——Orchestrator cannot determine readiness
  10. Wrong layer order——Changing one line of code reinstalls all dependencies
  11. Pushing without scanning——CVE-laden images go to production
  12. Hardcoded ports in compose——Team conflicts

Supporting Templates

  • templates/dockerfile-template.md — Multi-stage Dockerfile + .dockerignore + Compose template

Collaboration with Other Skills

上游:
  backend-engineer → 应用代码 + 依赖清单
  frontend-engineer → 静态产物构建

下游:
  ci-cd-pipeline → 镜像构建阶段
  kubernetes-orchestration → 镜像部署
  secrets-config → 运行时 secrets 注入
  monitoring-alerting → 健康检查端点