Docker Run

Docker Run — Container Lifecycle Management

Complete guidance for running, monitoring, and managing Docker containers.

When to Use

ALWAYS use this skill when the user mentions:

• "docker run", "运行容器", "启动容器"
• "docker ps", "docker stop", "docker restart"
• "容器资源限制", "memory limit", "CPU limit"
• "健康检查", "healthcheck"
• "docker logs", "查看日志"
• "docker exec", "进入容器"
• "restart policy", "容器重启策略"

Container Lifecycle

docker pull → docker create → docker start → docker run (create+start)
                                                │
                          ┌─────────────────────┼─────────────────────┐
                          ▼                     ▼                     ▼
                      Running              Paused/Stopped         Killed
                          │                     │
                          ▼                     ▼
                      docker stop          docker start
                      docker kill          docker restart
                      docker rm            docker rm -f

docker run — Complete Reference

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

# Most common form
docker run -d --name myapp \
  -p 8080:8080 \
  -v /host/path:/container/path \
  -e ENV_VAR=value \
  --restart unless-stopped \
  myimage:tag

Resource Constraints

# Memory: limit + reservation
docker run --memory=512m --memory-reservation=256m myapp

# CPU: shares (relative) + cpus (absolute)
docker run --cpus=2 --cpu-shares=1024 myapp

# Combined: production-grade limits
docker run -d \
  --memory=1g --memory-swap=1g \
  --cpus=2 \
  --pids-limit=100 \
  myapp

Health Checks

Dockerfile HEALTHCHECK

HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

Health Check States

starting → healthy (passes)
         → unhealthy (fails 3 consecutive checks)

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

# Health check in compose
# services.app.healthcheck.test: ["CMD", "curl", "-f", "http://localhost:8080/health"]

Restart Policies

docker run --restart unless-stopped myapp
docker update --restart always myapp  # Change policy on running container

Logging & Debugging

# View logs
docker logs myapp                # All logs
docker logs -f myapp             # Follow (tail -f)
docker logs --tail 50 myapp      # Last 50 lines
docker logs --since 10m myapp    # Last 10 minutes

# Execute commands in container
docker exec -it myapp sh         # Interactive shell
docker exec myapp cat /etc/hosts # Run single command

# Inspect state
docker inspect myapp             # Full JSON metadata
docker stats myapp               # Live resource usage
docker top myapp                 # Running processes
docker port myapp                # Port mappings

Signal Handling

docker stop myapp    → SIGTERM → wait 10s → SIGKILL
docker kill myapp    → SIGKILL immediately
docker kill -s HUP myapp → Send custom signal

Workflow — 推荐操作流程

Step 1: 拉取或构建镜像: docker pull 或 docker build 准备好镜像 Step 2: 运行容器: docker run -d --name myapp -p 8080:8080 -v data:/data --memory 512m myapp Step 3: 验证启动: docker ps + docker logs myapp 确认运行正常 Step 4: 配置健康检查: 确保 HEALTHCHECK 在 Dockerfile 中定义或运行时指定 Step 5: 监控运行: docker stats + docker logs -f 持续观察

Gotchas — Common Pitfalls

• Default `--memory=0` (unlimited): Container can consume all host memory. → Recovery: docker run --memory=512m --cpus=1 app; check usage with docker stats.
• `docker stop` timeout: Default 10s grace period. → Recovery: docker stop -t 30 myapp; ensure app handles SIGTERM properly.
• `docker run` creates new container: Running docker run nginx twice creates two containers. → Recovery: docker start <existing-name> to restart; docker ps -a to find stopped containers.
• Logs filling disk: JSON-file driver has no rotation by default. → Recovery: docker run --log-opt max-size=10m --log-opt max-file=3 app; existing containers: edit /etc/docker/daemon.json + restart dockerd.
• `docker exec` exit codes: Returns the command's exit code. → Recovery: Use for scripting: docker exec myapp healthcheck.sh || exit 1.

Boundary — 能力边界（适用与不适用场景）

When NOT to Use This Skill

Security & Stability

• Always set --memory and --cpus limits in production to prevent noisy-neighbor issues.
• Avoid --privileged flag. Use specific --cap-add instead.
• Never run containers as root. Use --user flag or USER in Dockerfile.
• Use --read-only for stateless containers where possible.
• No executable scripts bundled. Guidance only.

📚 官方文档参考

🧭 Docker Skills Journey

📍 You are here: `docker-run` — Step 3: 容器管理与运维

← Previous: docker-build — Dockerfile & 镜像构建 → Next: docker-networking / docker-storage / docker-compose

docker run 基础使用

# 基本运行
docker run nginx:alpine                        # 前台运行

# 后台运行 + 命名
docker run -d --name web nginx:alpine          # -d 后台, --name 命名

# 端口映射
docker run -d -p 8080:80 nginx:alpine          # host:container
docker run -d -p 127.0.0.1:8080:80 nginx:alpine # 仅 localhost
docker run -d -p 8080:80/udp nginx:alpine       # UDP

# 卷挂载
docker run -d -v /data:/var/lib/mysql mysql:8.4        # bind mount
docker run -d -v myvolume:/data alpine                  # named volume
docker run -d -v /var/run/docker.sock:/var/run/docker.sock ...

# 环境变量
docker run -d -e NODE_ENV=production -e PORT=3000 node:22-alpine
docker run -d --env-file .env myapp

# 重启策略
docker run -d --restart always nginx:alpine
docker run -d --restart on-failure:5 myapp
docker run -d --restart unless-stopped myapp

# 资源限制
docker run -d --memory 512m --cpus 1.0 myapp
docker run -d --memory 256m --memory-swap 512m myapp

# 常用组合
docker run -d \
  --name myapp \
  --restart unless-stopped \
  -p 8080:8080 \
  -v app_data:/data \
  -e NODE_ENV=production \
  --memory 512m --cpus 0.5 \
  myapp:latest

# 容器管理
docker ps                     # 运行中
docker ps -a                  # 全部
docker logs -f myapp          # 跟踪日志
docker logs --tail 50 myapp   # 最后 50 行
docker exec -it myapp sh      # 进入容器
docker stop myapp             # 停止
docker start myapp            # 启动已停止的
docker restart myapp          # 重启
docker rm myapp               # 删除
docker rm -f myapp            # 强制删除

Container with health check

FROM nginx:alpine
COPY default.conf /etc/nginx/conf.d/
HEALTHCHECK --interval=30s --timeout=3s --retries=3   CMD wget -qO- http://localhost/health || exit 1

docker build -t nginx-health .
docker run -d --name web nginx-health

# Watch health status change: starting → healthy
watch docker inspect --format='{{.State.Health.Status}}' web

# Simulate unhealthy: kill nginx inside
docker exec web nginx -s stop
# After 3 failed checks → unhealthy

Production-grade resource limits

docker run -d --name app   --memory=512m --memory-swap=512m \   # Hard limit, no swap
  --memory-reservation=256m \          # Soft limit for scheduler
  --cpus=2 \                           # Max 2 CPU cores
  --cpu-shares=1024 \                  # Relative weight (default 1024)
  --pids-limit=100 \                   # Prevent fork bombs
  --ulimit nofile=65536:65536 \        # Max open files
  --read-only \                        # Read-only root filesystem
  --tmpfs /tmp:rw,noexec,nosuid \      # Writable /tmp in RAM
  myapp:1.0.0

Restart Policies

# Set at run time
docker run --restart unless-stopped myapp

# Change on running container
docker update --restart always myapp

docker run 完整参数速查

容器生命周期

docker run 完整参数

重启策略

Logging Drivers

# Production log rotation (json-file)
docker run --log-opt max-size=10m --log-opt max-file=3 myapp

# Daemon-level: /etc/docker/daemon.json
{ "log-driver": "json-file", "log-opts": { "max-size": "10m", "max-file": "3" } }

健康检查模式库

内置 HEALTHCHECK

# HTTP 检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1

# TCP 检查
HEALTHCHECK --interval=10s --timeout=3s \
    CMD nc -z localhost 3306 || exit 1

# 进程检查
HEALTHCHECK --interval=30s --timeout=3s \
    CMD pgrep nginx || exit 1

# 自定义脚本
HEALTHCHECK --interval=30s --timeout=3s \
    CMD /app/health-check.sh || exit 1

运行时覆盖

docker run -d \
  --health-cmd="curl -f http://localhost:8080/health || exit 1" \
  --health-interval=10s \
  --health-timeout=3s \
  --health-start-period=30s \
  --health-retries=3 \
  myapp

参数说明

状态查看

docker inspect --format='{{.State.Health.Status}}' myapp
# healthy / unhealthy / starting

docker inspect --format='{{json .State.Health}}' myapp | jq .

按场景的推荐配置

Compose 中依赖健康检查

services:
  api:
    depends_on:
      db:
        condition: service_healthy     # 等待 db 健康再启动
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 15s
      timeout: 3s
      retries: 3