xiaowei-system/skills/devops/docker/SKILL.md

tags	name	description	triggers	version
devops	docker	Docker container management — build, run, inspect, debug, compose, and troubleshoot containers/images/volumes/networks.	docker 容器 docker-compose container dockerfile image	1.0.0

Docker

Common Operations

Containers

# List running containers
docker ps

# List all containers (including stopped)
docker ps -a

# Run a container
docker run -d --name myapp -p 8080:80 nginx:latest
docker run -d --name db -e POSTGRES_PASSWORD=secret postgres:16

# Run interactively
docker run -it ubuntu:24.04 bash

# Start / stop / restart
docker stop myapp
docker start myapp
docker restart myapp

# Remove
docker rm myapp
docker rm -f myapp   # force remove running container

# View logs
docker logs myapp
docker logs -f myapp        # follow
docker logs --tail 100 myapp

# Inspect
docker inspect myapp
docker stats myapp            # live resource usage

Images

# List images
docker images

# Pull
docker pull nginx:latest

# Build
docker build -t myapp:latest .
docker build -t myapp:latest --build-arg ENV=prod .

# Tag
docker tag myapp:latest myregistry.com/myapp:v1.0

# Push
docker push myregistry.com/myapp:v1.0

# Remove unused
docker image prune -f

# Inspect layers
docker history myapp:latest

Volumes

docker volume create mydata
docker volume ls
docker volume inspect mydata
docker run -v mydata:/data nginx
docker volume rm mydata
docker volume prune -f

Networks

docker network ls
docker network create mynet
docker network connect mynet myapp
docker run --network mynet myapp

docker-compose

# Start (detached)
docker compose up -d

# Start with rebuild
docker compose up -d --build

# Stop
docker compose down

# Stop and remove volumes
docker compose down -v

# View logs
docker compose logs -f

# Restart a service
docker compose restart api

# Scale
docker compose up -d --scale api=3

# Run one-off command
docker compose run --rm api python manage.py migrate

Dockerfile Essentials

FROM python:3.12-slim

WORKDIR /app

# Copy only dependency files first (layer cache optimization)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Then copy app code
COPY . .

# Non-root user for security
RUN useradd -m appuser && chown -R appuser:appuser /app
USER appuser

EXPOSE 8080
CMD ["python", "main.py"]

Multi-stage Build

# Stage 1: Build
FROM golang:1.23 AS builder
WORKDIR /build
COPY . .
RUN go build -o myapp

# Stage 2: Run
FROM ubuntu:24.04
COPY --from=builder /build/myapp /usr/local/bin/
CMD ["myapp"]

hermes-agent 实际构建模式（参考）

• uv 作为 Python 包管理：COPY --from=ghcr.io/astral-sh/uv /uv /usr/local/bin/
• tini 回收僵尸进程：apt-get install tini && ENTRYPOINT ["/usr/bin/tini", "-g", "--"]
• 动态 UID 映射：通过 HERMES_UID/HERMES_GID 环境变量在运行时用 usermod 映射

Debugging

Shell into running container

docker exec -it myapp bash
docker exec -it myapp sh        # for alpine

Copy files in/out

docker cp config.json myapp:/app/config.json
docker cp myapp:/app/logs/output.log ./

Check resource usage

docker stats
docker stats --no-stream

Network debugging

docker exec -it myapp curl localhost:8080/health
docker exec -it myapp nslookup db          # DNS lookup
docker exec -it myapp netstat -tlnp        # listening ports

Inspect with dive (layer inspection)

# Install
curl -sL https://raw.githubusercontent.com/wagoodman/dive/master/scripts/get | bash

# Use
dive myapp:latest

Troubleshooting

Problem	Fix
Cannot connect to Docker daemon	sudo systemctl start docker or add user to docker group
Port already allocated	docker ps check, docker rm conflicting container
No space left on device	docker system prune -a --volumes
Image pull failure	Check registry auth, try docker login
Container exits immediately	docker logs — usually missing env var or entrypoint error
Docker not available in cron	cron 环境无 TTY，无法 sudo。手动安装：sudo apt-get install docker.io && sudo usermod -aG docker $USER

Pitfalls

• cron 环境无 Docker：cron 任务没有 TTY，无法输入 sudo 密码。Docker 安装需要在有 TTY 的环境中手动执行 sudo apt-get install docker.io，然后 sudo usermod -aG docker $USER 并重新登录。
• 层缓存失效：每次 COPY . . 后跟 RUN 会让 RUN 步骤在代码变化时重新执行。把依赖文件（requirements.txt、go.mod）单独提前复制，再用 RUN 安装，最后才 COPY 源码。
• 容器内 root 默认：容器默认以 root 运行，生产环境应创建非 root 用户（RUN useradd -m appuser && USER appuser）。
• hermes-agent 需要 tini：Gateway 进程中可能有 MCP stdio 子进程等，需要 tini 作为 PID 1 回收僵尸进程。

学习计划

学习进度追踪见 references/docker-learning-plan.md。

Cleanup

# Remove stopped containers, unused networks, dangling images, build cache
docker system prune -af

# Remove all volumes (DATA LOSS)
docker system prune -af --volumes

---

模板与参考文件

文件	用途
templates/newapi.Dockerfile	Go 静态二进制生产级 Dockerfile 模板
templates/newapi.docker-compose.yml	newapi 服务 docker-compose 示例
templates/dockerignore	标准 .dockerignore 模板
references/hermes-agent-docker.md	hermes-agent 实际 Dockerfile 设计分析 + newapi 容器化要点
references/docker-china-mirror.md	Docker Hub 国内加速（DaoCloud 镜像），解决 GFW 阻断