Docker Commands

验证：未记录

适用版本: 未记录
验证范围: 尚未登记验证记录。

本文缩写（英文全称与中文含义）

缩写	英文全称／名称	中文含义
CI	Continuous Integration	持续集成
DNS	Domain Name System	域名系统

1. Important Points#

docker 管理单个 image/container；docker compose 管理一组服务的期望状态。排障顺序固定为 ps → logs → inspect → exec，不要一开始就进容器修改文件。

image:      immutable build artifact; tag is a movable reference
container:  image 的运行实例；删 container 不等于删 image/volume
volume:     persistent data; docker compose down -v 会删除该项目的 named volume
compose:    service name 是同一 Compose 网络内的 DNS name

生产和共享环境：使用 immutable image tag，先审查 compose config，不要盲目 prune、down -v 或 rm -f。密钥不写入 image、命令历史或 Git。

2. Daily Debug#

Need	Command
Running / all containers	`docker ps` / `docker ps -a`
Status with ports	`docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'`
Follow recent logs	`docker logs --tail 100 -f <container>`
Inspect configuration	`docker inspect <container>`
Shell / process / env	`docker exec -it <container> sh` / `docker top <container>`
Resource usage	`docker stats`
Copy a diagnostic file	`docker cp <container>:/path/file ./file`

docker ps -a
docker logs --tail 100 -f order-api
docker inspect order-api
docker exec -it order-api sh

3. Run a Container#

# Disposable command.
docker run --rm alpine:3.20 echo hello

# Local service: config stays outside the image; named volume persists data.
docker volume create --label keep=true pgdata
docker run -d --name postgres-dev --restart unless-stopped -e POSTGRES_PASSWORD=postgres -v pgdata:/var/lib/postgresql/data -p 5432:5432 postgres:16

# Read runtime settings from a local file; do not COPY this file into the image.
docker run --rm --env-file .env.local -p 3000:3000 order-api:local

--restart unless-stopped 会在 Docker daemon/主机重启后恢复容器；手动 docker stop 后不会自动恢复。更新已有容器的策略：

docker update --restart unless-stopped order-api
docker inspect order-api --format '{{.HostConfig.RestartPolicy.Name}}'

4. Image and Registry#

# Local build; --pull checks for a newer base image.
docker build --pull -t order-api:local .
docker build -f docker/Dockerfile -t order-api:local .

# Release: retain the immutable Git SHA tag for rollback.
docker tag order-api:local registry.example.com/order-api:git-a1b2c3d
docker push registry.example.com/order-api:git-a1b2c3d
docker pull registry.example.com/order-api:git-a1b2c3d

local:       order-api:local
release:     registry.example.com/order-api:1.0.0
rollback:    registry.example.com/order-api:git-a1b2c3d
prod alias:  mutable pointer only; never the sole rollback reference

CI multi-architecture build:

docker buildx build --platform linux/amd64,linux/arm64 -t registry.example.com/order-api:git-a1b2c3d --push .

5. Compose Workflow#

先渲染配置，确认变量和最终 service 定义；--env-file 只提供 Compose 变量替换，不会自动成为容器环境变量。容器环境需要在 Compose 的 environment: 或 env_file: 中显式声明。

docker compose -f infra/docker-compose.yml --env-file api/.env.dev config
docker compose -f infra/docker-compose.yml --env-file api/.env.dev up -d
docker compose ps
docker compose logs --tail 100 -f worker

Build and start one service#

docker compose -f infra/docker-compose.yml --env-file api/.env.dev up --build worker

up --build 在启动前构建 worker 的 build: 镜像，再启动该服务及其 depends_on 依赖。它仍使用 Docker layer cache，适合 Dockerfile、构建上下文源代码或 build.args 变更后的日常开发。

# Detached development workflow.
docker compose -f infra/docker-compose.yml --env-file api/.env.dev up -d --build worker
docker compose -f infra/docker-compose.yml logs -f worker

# Must invalidate every build layer.
docker compose -f infra/docker-compose.yml --env-file api/.env.dev build --no-cache worker
docker compose -f infra/docker-compose.yml --env-file api/.env.dev up worker

若服务只有 image: 而没有 build:，--build 没有可构建内容，改用 docker compose pull worker。docker compose restart worker 只重启现有 container：不会 build、pull 或读取新的环境变量。

Operate and reset#

docker compose restart worker
docker compose up -d --force-recreate worker    # Apply changed env/config without rebuilding.
docker compose down                             # Remove project containers and networks.
docker compose down -v                          # Also remove project named volumes: local reset only.

Compose 内部服务互访使用 service name，例如 http://postgres:5432；主机访问 published port，例如 localhost:5432。不必手工创建网络。

6. Network and Data#

docker network ls
docker network inspect REPLACE_NETWORK
docker volume ls
docker volume inspect pgdata

# Backup only after confirming the application has flushed/stopped writes.
docker run --rm -v pgdata:/data:ro -v "$PWD":/backup alpine:3.20 tar czf /backup/pgdata.tgz -C /data .

# Restore overwrites files in the target volume.
docker run --rm -v pgdata:/data -v "$PWD":/backup alpine:3.20 tar xzf /backup/pgdata.tgz -C /data

7. Cleanup#

先看占用，再清理无用资源；volume 默认不自动删，因为它可能是数据库数据。

docker system df
docker container prune --filter 'until=168h'
docker image prune -a --filter 'until=336h'
docker builder prune --filter 'until=168h'
docker volume prune --filter 'label!=keep'

Scope	Safe default
Dev laptop	每周或 Docker 占用超过 30 GB
CI builder	每日或构建后，按缓存价值调整
Shared host	维护窗口执行，先确认运行中服务与 volume

8. Troubleshooting#

Symptom	Check	Minimal fix
Port occupied	`docker ps --format 'table {{.Names}}\t{{.Ports}}'`; `lsof -i :3000`	停止占用者，或改 host port 为 `3001:3000`
Container exits	`docker ps -a`; `docker logs --tail 200 <container>`	检查 command、必需 env、依赖连接、volume 权限
Service name unresolved	`docker network inspect <network>`	放入同一 Compose/user-defined network，并用 service name
Disk full	`docker system df`; `docker volume ls`; `df -h`	先 prune container/image/cache，人工确认 volume
OOM	`docker inspect <container> --format '{{.State.OOMKilled}}'`; `docker stats`	调整 memory limit、heap 或 worker concurrency；检查泄漏