docker-platform-guide

Docker 平台特定指南

本技能针对 Windows、Linux 和 macOS 平台，详细介绍 Docker 的差异、注意事项和优化方法。

本技能使用的 Shell 和路径约定

Docker 命令在各个平台上大多相同，但外围 Shell 工具并不相同。本指南采用以下约定：

• 在 docker exec / docker run 容器内 — 无论主机操作系统是什么，命令都针对 Linux Shell（容器运行 Linux）。
• 在主机上（Linux / macOS / WSL2） — 示例使用 bash，以及 /dev/null、grep、sed、awk 和包管理器（apt-get、brew）。
• 在主机上（Windows 原生 PowerShell） — 替换为：/dev/null -> $null，grep pattern -> Select-String pattern，sed -i 's/a/b/' f -> (Get-Content f) -replace 'a','b' | Set-Content f。请通过管道传递对象输出，而不是文本。
• Windows 上的 Docker Desktop 使用 WSL2 Linux 虚拟机 — bash 示例可在 WSL 发行版中运行。PowerShell 用户仍可直接运行 docker CLI；只需转换辅助 Unix 工具。

路径引号：将 Windows 路径绑定挂载到 Docker Desktop 时，请使用正斜杠或转义后的反斜杠（-v C:/Users/me/code:/app 或 -v "C:\Users\me\code:/app"）。PowerShell 主机路径使用 Windows 分隔符；容器路径始终使用 Linux 风格。

Linux

优势

• 原生容器： 没有虚拟化层开销
• 性能最佳： 直接使用内核功能（cgroups、命名空间）
• 功能完整： 可使用所有 Docker 功能
• 生产环境标准： 大多数生产部署都运行在 Linux 上
• 灵活性： 支持多种发行版

平台功能

容器技术：

• 命名空间：PID、网络、IPC、挂载、UTS、用户
• 用于资源控制的 cgroups v1 和 v2
• Overlay2 存储驱动程序（推荐）
• 用于强制访问控制的 SELinux 和 AppArmor

存储驱动程序：

# Check current driver
docker info | grep "Storage Driver"

# Recommended: overlay2
# /etc/docker/daemon.json
{
  "storage-driver": "overlay2"
}

Linux 专属配置

守护进程配置（/etc/docker/daemon.json）：

{
  "storage-driver": "overlay2",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "live-restore": true,
  "userland-proxy": false,
  "userns-remap": "default",
  "icc": false,
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 64000,
      "Soft": 64000
    }
  }
}

用户命名空间重映射：

# Enable in daemon.json
{
  "userns-remap": "default"
}

# Restart Docker
sudo systemctl restart docker

# Result: root in container = unprivileged user on host

SELinux 集成

# Check SELinux status
sestatus

# Run container with SELinux enabled
docker run --security-opt label=type:svirt_sandbox_file_t myimage

# Volume labels
docker run -v /host/path:/container/path:z myimage  # Private label
docker run -v /host/path:/container/path:Z myimage  # Shared label

AppArmor 集成

# Check AppArmor status
sudo aa-status

# Run with default Docker profile
docker run --security-opt apparmor=docker-default myimage

# Create custom profile
sudo aa-genprof docker run myimage

Systemd 集成

# Check Docker service status
sudo systemctl status docker

# Enable on boot
sudo systemctl enable docker

# Restart Docker
sudo systemctl restart docker

# View logs
sudo journalctl -u docker -f

# Configure service
sudo systemctl edit docker

cgroup v1 与 v2

# Check cgroup version
stat -fc %T /sys/fs/cgroup/

# If using cgroup v2, ensure Docker version >= 20.10

# /etc/docker/daemon.json
{
  "exec-opts": ["native.cgroupdriver=systemd"]
}

Linux 发行版特定说明

Ubuntu/Debian：

# Install Docker
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

# Non-root user
sudo usermod -aG docker $USER

RHEL/CentOS/Fedora：

# Install Docker
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io

# Start Docker
sudo systemctl start docker
sudo systemctl enable docker

# Non-root user
sudo usermod -aG docker $USER

Alpine：

# Install Docker
apk add docker docker-compose

# Start Docker
rc-update add docker boot
service docker start

macOS

架构

• Docker Desktop： 必须使用（macOS 不支持原生 Docker）
• 虚拟化： 使用 HyperKit（Intel）或 Virtualization.framework（Apple Silicon）
• Linux 虚拟机： 容器在轻量级 Linux 虚拟机中运行
• 文件共享： 绑定挂载使用 osxfs 或 VirtioFS

macOS 专属注意事项

资源分配：

Docker Desktop → Preferences → Resources → Advanced
- CPUs: Allocate based on workload (default: half available)
- Memory: Allocate generously (default: 2GB, recommend 4-8GB)
- Swap: 1GB minimum
- Disk image size: 60GB+ for development

文件共享性能：

传统的 osxfs 速度较慢。改进方法：

1. VirtioFS： 在 Docker Desktop 设置中启用（速度更快）
2. 委派/缓存挂载：

volumes:
  # Host writes delayed (best for source code)
  - ./src:/app/src:delegated

  # Container writes cached (best for build outputs)
  - ./build:/app/build:cached

  # Default consistency (slowest but safest)
  - ./data:/app/data:consistent

网络访问：

# Access host from container
host.docker.internal

# Example: Connect to host PostgreSQL
docker run -e DATABASE_URL=postgresql://host.docker.internal:5432/db myapp

Apple Silicon（M1/M2/M3）专属说明

架构注意事项：

# Check image architecture
docker image inspect node:20-alpine | grep Architecture

# M-series Macs are ARM64
# Some images only available for AMD64

# Build multi-platform
docker buildx build --platform linux/amd64,linux/arm64 -t myapp .

# Run AMD64 image on ARM (via emulation)
docker run --platform linux/amd64 myimage  # Slower

Rosetta 2 集成：

Docker Desktop → Features in development → Use Rosetta for x86/amd64 emulation

在 Apple Silicon 上更快地模拟 AMD64。

macOS Docker Desktop 设置

常规：

• ✅ 登录时启动 Docker Desktop
• ✅ 使用 VirtioFS（性能更好）
• ✅ 使用 Virtualization framework（Apple Silicon）

资源：

CPUs: 4-6 (for development)
Memory: 6-8 GB (for development)
Swap: 1-2 GB
Disk image size: 100+ GB (grows dynamically)

Docker Engine：

{
  "builder": {
    "gc": {
      "enabled": true,
      "defaultKeepStorage": "20GB"
    }
  },
  "experimental": false,
  "features": {
    "buildkit": true
  }
}

macOS 文件权限

# macOS user ID and group ID
id -u  # Usually 501
id -g  # Usually 20

# Match in container
docker run --user 501:20 myimage

# Or in Dockerfile
RUN adduser -u 501 -g 20 appuser
USER appuser

macOS 开发工作流

# docker-compose.yml for development
version: '3.8'

services:
  app:
    build: .
    volumes:
      # Source code with delegated (better performance)
      - ./src:/app/src:delegated
      # node_modules in volume (much faster than bind mount)
      - node_modules:/app/node_modules
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development

volumes:
  node_modules:

macOS 常见问题

问题： 文件同步缓慢 解决方案：

• 使用 VirtioFS
• 使用委派/缓存挂载
• 将依赖项存储在卷中（而非绑定挂载）

问题： CPU 使用率高 解决方案：

• 减少文件监视
• 将大型目录排除在文件共享之外
• 分配更多资源

问题： 端口已被占用 解决方案：

# Find process using port
lsof -i :PORT
kill -9 PID

Windows

有关 Windows Docker 的具体信息（容器类型、WSL2、镜像变体 nanoserver / windowsservercore、许可、网络、挂载语义、Visual Studio 集成），请参阅 references/windows-platform-detail.md。要点：

• 容器类型： Windows Server 容器（进程隔离）与 Hyper-V 容器（内核隔离）。
• WSL2 后端： Docker Desktop 的默认后端；可提供接近原生的 Linux 性能。
• 镜像变体： mcr.microsoft.com/windows/nanoserver（体积最小）与 windowsservercore（完整 API）。
• 挂载： 在 Git Bash 中将 S:\repos\x 转换为 /s/repos/x，或设置 MSYS_NO_PATHCONV=1。

平台比较

功能	Linux	macOS	Windows
性能	出色（原生）	良好（有虚拟机开销）	良好（WSL2）至一般（Hyper-V）
文件共享	原生	较慢（VirtioFS 正在改善）	较慢（WSL2 中更好）
资源效率	最佳	良好	良好（WSL2）
功能集	完整	完整	完整（LCOW）
生产环境	标准	仅开发	仅开发（LCOW）
易用性	适中	简单（Docker Desktop）	简单（Docker Desktop）
成本	免费	免费（Docker Desktop Personal）	免费（Docker Desktop Personal）

跨平台最佳实践

多平台镜像

# Create buildx builder
docker buildx create --name multiplatform --driver docker-container --use

# Build for multiple platforms
docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  -t myimage:latest \
  --push \
  .

平台无关的 Dockerfile

# Works on all platforms
FROM node:20-alpine

# Use COPY with --chmod (not RUN chmod, which is slower)
COPY --chmod=755 script.sh /usr/local/bin/

# Use environment variables for paths
ENV APP_HOME=/app
WORKDIR ${APP_HOME}

# Use exec form for CMD/ENTRYPOINT (works on Windows containers too)
CMD ["node", "server.js"]

跨平台 Compose 文件

version: '3.8'

services:
  app:
    build: .
    volumes:
      # Relative paths work everywhere
      - ./src:/app/src
      # Named volumes (platform-agnostic)
      - data:/app/data
    environment:
      # Use environment variables
      - NODE_ENV=${NODE_ENV:-development}

volumes:
  data:

跨平台测试

# Test on different platforms with buildx
docker buildx build --platform linux/amd64 -t myapp:amd64 --load .
docker run --rm myapp:amd64

docker buildx build --platform linux/arm64 -t myapp:arm64 --load .
docker run --rm myapp:arm64

平台选择指南

选择 Linux 的情况：

• 生产部署
• 追求最高性能
• 需要完整的 Docker 功能集
• 希望尽可能减少开销
• CI/CD 流水线

选择 macOS 的情况：

• 在 Mac 硬件上开发
• 需要 macOS 工具
• 希望轻松使用 Docker Desktop
• M1/M2/M3 开发

选择 Windows 的情况：

• 在 Windows 硬件上开发
• 使用特定于 Windows 的应用程序
• 团队使用 Windows
• 借助 WSL2 获得更好的 Linux 容器支持

本平台指南介绍了主要差异。投入生产前，务必在目标部署平台上进行测试。