Docker 常见问题与解决方案 #

容器运行问题 #

1. 容器无法启动 #

问题：容器立即退出 #

症状：容器启动后立即停止

docker run -d my-app:latest
# 容器很快变为 Exited 状态

解决方案：

1. 检查容器日志：

docker logs container-name

2. 以交互模式运行容器：

docker run -it my-app:latest /bin/sh

3. 检查 Dockerfile 中的 CMD/ENTRYPOINT 指令是否正确

问题：端口无法访问 #

症状：容器运行正常，但无法通过端口访问服务

解决方案：

1. 检查端口映射是否正确：

docker run -p 8080:80 my-app:latest  # 正确
docker run -p 80 my-app:latest       # 错误，未映射到主机端口

2. 检查应用是否绑定到正确的接口：

# 应用应绑定到 0.0.0.0 而不是 localhost
CMD ["node", "server.js", "--host", "0.0.0.0"]

3. 检查防火墙设置

2. 权限问题 #

问题：权限不足错误 #

症状：

permission denied
dial unix /var/run/docker.sock: connect: permission denied

解决方案：

1. 将用户添加到 docker 组：

sudo usermod -aG docker $USER
# 注销并重新登录

2. 或使用 sudo 运行 Docker 命令

问题：文件权限错误 #

症状：容器内无法访问挂载的文件

解决方案：

1. 检查用户 ID：

# 在 Dockerfile 中使用与主机匹配的用户 ID
RUN adduser -u 1000 -D appuser
USER appuser

2. 设置正确的文件权限：

sudo chown -R 1000:1000 /host/path

镜像构建问题 #

1. 构建失败 #

问题：Dockerfile 构建失败 #

症状：

Step 5/10 : RUN npm install
 ---> Running in abc123
npm WARN deprecated ...
npm ERR! code ELIFECYCLE
The command '/bin/sh -c npm install' returned a non-zero code: 1

解决方案：

1. 检查语法错误
2. 验证命令是否正确
3. 确保依赖项可用
4. 使用多阶段构建减少错误：

FROM node:16-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:16-alpine AS production
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY --from=builder /app/dist ./dist

2. 构建缓慢 #

问题：Docker 构建时间过长 #

解决方案：

1. 优化 Dockerfile 指令顺序以利用缓存：

# 好的做法：先复制依赖文件
COPY package*.json ./
RUN npm ci
COPY . .  # 应用代码后复制

2. 使用 .dockerignore 排除不必要的文件

3. 使用 BuildKit 加速构建：

export DOCKER_BUILDKIT=1
docker build -t my-app:latest .

网络问题 #

1. 容器间通信 #

问题：容器无法相互通信 #

症状：使用容器名无法访问其他容器

解决方案：

1. 使用自定义网络：

# 创建自定义网络
docker network create mynetwork

# 在同一网络中运行容器
docker run --network mynetwork --name db postgres
docker run --network mynetwork --name web my-app

2. 或使用 Docker Compose：

version: '3.8'
services:
  web:
    image: my-app:latest
    depends_on:
      - db
  db:
    image: postgres:13

2. 外部访问问题 #

问题：无法从主机访问容器服务 #

解决方案：

1. 确保端口正确映射：

docker run -p 8080:80 my-app:latest

2. 检查应用是否绑定到正确的接口：

# 应用需要绑定到 0.0.0.0
EXPOSE 80

存储问题 #

1. 数据持久化 #

问题：容器重启后数据丢失 #

解决方案：

1. 使用命名卷：

docker volume create mydata
docker run -v mydata:/app/data my-app:latest

2. 使用绑定挂载：

docker run -v /host/path:/container/path my-app:latest

2. 磁盘空间不足 #

题：磁盘空间不足 #

解决方案：

1. 清理未使用的 Docker 对象：

# 清理构建缓存
docker builder prune

# 清理所有未使用的对象
docker system prune -a

# 清理未使用的卷
docker volume prune

# 清理未使用的镜像
docker image prune -a

2. 查找占用空间大的容器：

docker system df

Docker Compose 问题 #

1. 服务依赖 #

问题：服务启动顺序问题 #

症状：应用服务在数据库服务准备好之前启动

解决方案：

1. 使用 healthcheck 确保依赖服务就绪：

version: '3.8'
services:
  app:
    image: my-app:latest
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:13
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d myapp"]
      interval: 10s
      timeout: 5s
      retries: 5

2. 环境变量问题 #

问题：环境变量未生效 #

解决方案：

1. 检查 .env 文件格式：

# .env 文件应为 KEY=VALUE 格式
DB_HOST=localhost
DB_PORT=5432

2. 在 docker-compose.yml 中正确引用：

version: '3.8'
services:
  app:
    image: my-app:latest
    environment:
      - DB_HOST=${DB_HOST}
      - DB_PORT=${DB_PORT}
    env_file:
      - .env

性能问题 #

1. 容器运行缓慢 #

问题：容器响应慢 #

解决方案：

1. 检查资源限制：

docker stats  # 查看资源使用情况

2. 增加容器资源：

docker run -m 1g --cpus="2.0" my-app:latest

3. 在 docker-compose.yml 中设置资源：

version: '3.8'
services:
  app:
    image: my-app:latest
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

2. 镜像过大 #

问题：Docker 镜像文件过大 #

解决方案：

1. 使用多阶段构建：

FROM node:16-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:16-alpine AS production
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY --from=builder /app/dist ./dist

2. 使用 Alpine 基础镜像：

FROM node:16-alpine  # 比 node:16 小很多

3. 删除不必要的文件：

RUN npm ci --only=production && npm cache clean --force

安全问题 #

1. 权限提升 #

问题：容器以 root 权限运行 #

解决方案：

1. 在 Dockerfile 中创建并使用非 root 用户：

FROM node:16-alpine

RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001 -G nodejs

WORKDIR /app
COPY --chown=nodejs:nodejs package*.json ./
RUN npm ci --only=production
COPY --chown=nodejs:nodejs . .

USER nodejs
EXPOSE 3000
CMD ["npm", "start"]

2. 敏感信息泄露 #

问题：敏感信息存储在镜像中 #

解决方案：

1. 使用构建参数：

ARG API_KEY
ENV API_KEY=$API_KEY

2. 运行时通过环境变量或卷挂载：

docker run -e API_KEY=secret my-app:latest

系统问题 #

1. Docker 服务问题 #

问题：Docker 服务无法启动 #

解决方案：

1. 重启 Docker 服务：

# Linux
sudo systemctl restart docker

# macOS/Windows
# 通过 Docker Desktop 重启

2. 检查 Docker 服务状态：

sudo systemctl status docker

2. Docker 守护进程错误 #

问题：Docker 守护进程错误 #

解决方案：

1. 检查 Docker 日志：

sudo journalctl -u docker.service

2. 重置 Docker 配置：

# 备份重要数据后
docker system prune -a --volumes

调试技巧 #

1. 容器调试 #

进入运行中的容器： #

docker exec -it container-name /bin/sh

运行调试容器： #

docker run -it --rm --volumes-from main-container alpine /bin/sh

2. 日志分析 #

实时查看日志： #

docker logs -f container-name

查看特定时间范围的日志： #

docker logs --since "2023-01-01T00:00:00" container-name

3. 网络调试 #

检查网络配置： #

docker network ls
docker network inspect network-name

测试网络连接： #

docker run --rm -it busybox ping hostname

故障排除流程 #

1. 系统性故障排除 #

当遇到 Docker 问题时，按照以下步骤进行：

1. 检查错误信息：仔细阅读错误消息
2. 查看日志：使用 docker logs 检查容器日志
3. 检查状态：使用 docker ps -a 查看容器状态
4. 验证配置：检查 Dockerfile 和 docker-compose.yml
5. 测试网络：验证端口映射和网络连接
6. 资源检查：检查磁盘空间和内存使用情况

2. 常用诊断命令 #

# 检查 Docker 系统信息
docker info
docker version

# 检查容器详细信息
docker inspect container-name

# 查看容器进程
docker top container-name

# 检查系统资源使用
docker stats

# 查看系统磁盘使用情况
docker system df

预防措施 #

1. 最佳实践遵循 #

• 使用 .dockerignore 排除不必要的文件
• 实施多阶段构建
• 使用非 root 用户运行容器
• 定期清理未使用的 Docker 对象
• 使用健康检查确保服务状态

2. 监控设置 #

• 设置日志轮转避免磁盘空间耗尽
• 监控容器资源使用情况
• 实施适当的健康检查

小结 #

Docker 常见问题通常涉及容器运行、镜像构建、网络连接、存储管理和安全配置等方面。通过系统性的故障排除方法和预防措施，可以有效解决和避免这些问题。重要的是要熟悉常用的诊断命令和调试技巧，以便快速定位和解决问题。