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
| Flag | Purpose | Example |
|------|---------|---------|
| -d | Detached (background) | -d |
| --name | Container name | --name my-nginx |
| -p | Port mapping (host:container) | -p 8080:80 |
| -v | Volume/bind mount | -v data:/var/lib/mysql |
| -e | Environment variable | -e DB_HOST=localhost |
| --env-file | Load env from file | --env-file .env |
| --restart | Restart policy | --restart unless-stopped |
| --rm | Auto-remove on stop | --rm (for temp containers) |
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
| Resource | Flag | Best Practice |
|----------|------|--------------|
| Memory | --memory=512m | Always set; container can exhaust host memory otherwise |
| Memory+Swap | --memory-swap=1g | Set equal to memory to disable swap |
| CPU | --cpus=2 | Hard limit; --cpu-shares for relative priority |
| PIDs | --pids-limit=100 | Prevent fork bombs |
| Ulimits | --ulimit nofile=65536 | File descriptor limits |
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
| Policy | Behavior | Use Case |
|--------|----------|----------|
| no | Never restart (default) | One-off tasks |
| on-failure[:N] | Restart on non-zero exit, max N times | Batch jobs |
| always | Always restart | Critical services (be careful — infinite loop risk) |
| unless-stopped | Restart unless explicitly stopped | Recommended for most services |
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
| Signal | docker command | Container effect |
|--------|---------------|------------------|
| SIGTERM | docker stop | Graceful shutdown (default) |
| SIGKILL | docker kill | Force kill (no cleanup) |
| SIGHUP | docker kill -s HUP | Reload config (app-specific) |
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 — 能力边界（适用与不适用场景）
| 分类 | 场景 | 说明 |
|------|------|------|
| ✅ 能做 | docker run 运行容器 | 所有参数、资源限制、重启策略 |
| ✅ 能做 | 健康检查配置 | HEALTHCHECK 指令 + 运行时覆盖 |
| ✅ 能做 | 日志管理 | 日志驱动选择 + 轮转配置 |
| ✅ 能做 | 进入容器调试 | docker exec / docker attach |
| ⚠️ 需条件 | --privileged 特权模式 | 仅调试用，生产禁止 |
| ⚠️ 需条件 | 修改运行中容器限制 | 需 docker update，部分参数不可动态改 |
| ❌ 超范围 | 编写 Dockerfile | 使用 docker-dockerfile |
| ❌ 超范围 | 多容器编排 | 使用 docker-compose |
| ❌ 超范围 | 镜像构建 | 使用 docker-build |
When NOT to Use This Skill
| ❌ Skip | ✅ Use Instead |
|---------|---------------|
| Docker basics / first-time setup | docker-basics |
| Writing Dockerfile | docker-build |
| Multi-container apps | docker-compose |
| Network configuration | docker-networking |
| Storage/Volume management | docker-storage |
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 引擎 | https://docs.docker.com/engine/ |
| docker run 参考 | https://docs.docker.com/reference/cli/docker/container/run/ |
| 容器管理 CLI | https://docs.docker.com/reference/cli/docker/container/ |
| 运行时选项 | https://docs.docker.com/engine/reference/run/ |
| 资源限制 | https://docs.docker.com/config/containers/resource_constraints/ |
| 日志驱动 | https://docs.docker.com/config/containers/logging/ |
🧭 Docker Skills Journey
📍 You are here: docker-run — Step 3: 容器管理与运维
← Previous: docker-build — Dockerfile & 镜像构建
→ Next: docker-networking / docker-storage / docker-compose