1. 问题现象

当你执行 docker compose up 命令启动服务时，控制台可能会长时间停留在 Starting... 状态，服务无法正常进入 Up 状态。这种现象通常表现为：

• 控制台输出类似 Starting service_name... 后长时间无进展
• 服务状态一直显示为 starting 或 restarting
• 没有明显的错误信息，但服务就是无法正常启动
• 有时会伴随容器不断重启

2. 常见原因分析

2.1 容器启动命令执行时间过长

容器内的启动命令（如 CMD 或 ENTRYPOINT）执行时间过长，导致 Docker 认为容器仍在启动中。

典型场景：

• 应用需要初始化大量数据
• 等待外部服务（数据库、消息队列）连接
• 执行复杂的配置脚本

2.2 健康检查未通过

Docker Compose 配置中定义了 healthcheck，但健康检查一直失败，导致服务状态无法变为 healthy。

services:
  app:
    image: myapp:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

2.3 依赖服务未就绪

服务之间存在依赖关系，但被依赖的服务尚未完全启动。

services:
  app:
    depends_on:
      - db
      - redis
    # 如果 db 或 redis 未就绪，app 可能一直处于 starting 状态

2.4 资源限制问题

• 内存不足：容器申请的内存超过宿主机可用内存
• CPU 限制过严：启动过程需要更多 CPU 资源
• 磁盘空间不足：镜像拉取或容器运行时需要磁盘空间

2.5 端口冲突

容器试图绑定的端口已被其他进程占用。

services:
  web:
    ports:
      - "8080:8080"  # 如果宿主机 8080 端口已被占用

2.6 卷挂载问题

• 挂载的本地目录不存在或权限不足
• 使用命名卷但驱动配置有问题

2.7 镜像问题

• 镜像损坏或不完整
• 镜像标签错误（如使用了不存在的标签）

2.8 网络配置问题

• 自定义网络配置错误
• DNS 解析失败
• 防火墙规则阻止容器间通信

3. 诊断步骤

3.1 查看容器日志

# 查看所有服务的日志
docker compose logs

# 查看特定服务的日志
docker compose logs service_name

# 实时查看日志（类似 tail -f）
docker compose logs -f service_name

3.2 检查容器状态

# 查看所有容器状态
docker compose ps

# 查看详细状态信息
docker compose ps -a

# 查看单个容器的详细信息
docker inspect $(docker compose ps -q service_name)

3.3 进入容器调试

# 如果容器能启动但卡住，可以尝试进入容器
docker compose exec service_name sh

# 或者直接使用 docker exec
docker exec -it container_name sh

3.4 检查资源使用情况

# 查看系统资源使用
docker stats

# 查看特定容器的资源限制
docker inspect container_name | grep -A 10 "HostConfig"

4. 解决方案

4.1 优化启动命令

如果启动命令执行时间过长，可以考虑：

方案1：拆分初始化过程

# Dockerfile
# 将耗时的初始化移到构建阶段
RUN ./init_data.sh

# 启动命令只启动应用
CMD ["./start_app.sh"]

方案2：使用后台进程和就绪检查

services:
  app:
    image: myapp:latest
    command: >
      sh -c "
        ./init_background.sh &
        ./start_app.sh
      "

4.2 调整健康检查配置

services:
  app:
    healthcheck:
      # 增加重试次数和超时时间
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 30s  # 增加超时时间
      retries: 5    # 增加重试次数
      start_period: 120s  # 给应用更长的启动时间

4.3 处理服务依赖

方案1：使用健康检查依赖

services:
  db:
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  app:
    depends_on:
      db:
        condition: service_healthy  # 等待 db 健康检查通过

方案2：在应用中添加等待脚本

# 在启动命令前添加等待脚本
COPY wait-for-it.sh /wait-for-it.sh
RUN chmod +x /wait-for-it.sh

CMD ["./wait-for-it.sh", "db:5432", "--", "./start_app.sh"]

4.4 解决资源问题

services:
  app:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

4.5 解决端口冲突

# 检查端口占用
sudo lsof -i :8080
sudo netstat -tulpn | grep :8080

# 修改 compose 文件使用其他端口
ports:
  - "8081:8080"  # 将宿主机端口改为 8081

4.6 修复卷挂载问题

services:
  app:
    volumes:
      # 确保本地目录存在且有正确权限
      - ./data:/app/data:rw
      # 或者使用匿名卷
      - /app/temp

4.7 镜像相关问题

# 重新拉取镜像
docker compose pull

# 清除缓存重新构建
docker compose build --no-cache

# 检查镜像完整性
docker images --digests

4.8 网络问题排查

# 检查网络配置
docker network ls
docker network inspect network_name

# 测试容器间连通性
docker compose exec app ping db

5. 高级调试技巧

5.1 增加调试输出

在 docker-compose.yml 中增加调试信息：

services:
  app:
    environment:
      - DEBUG=true
      - LOG_LEVEL=debug
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

5.2 使用 docker-compose 事件

# 查看所有事件
docker compose events

# 过滤特定事件
docker compose events --filter type=container

5.3 临时修改配置测试

# 使用覆盖文件测试
docker compose -f docker-compose.yml -f docker-compose.debug.yml up

# docker-compose.debug.yml
version: '3.8'
services:
  app:
    command: ["sh", "-c", "echo 'Debug mode'; sleep 3600"]

5.4 分析启动时间

# 查看容器启动时间线
docker events --since '1h' --filter type=container

# 使用 docker-compose 的 --timestamps 参数
docker compose up --timestamps

6. 预防措施

6.1 编写健壮的 Dockerfile

# 使用多阶段构建减少镜像大小
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

# 添加健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node healthcheck.js

EXPOSE 3000
CMD ["node", "dist/index.js"]

6.2 优化 Compose 配置

version: '3.8'

services:
  app:
    build: .
    # 设置合理的重启策略
    restart: unless-stopped
    # 配置资源限制
    mem_limit: 1g
    cpus: '0.5'
    # 配置健康检查
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3000/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    # 配置日志
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    # 配置依赖
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started

  db:
    image: postgres:15
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

6.3 监控和告警

# 使用 docker-compose 的退出代码
docker compose up
echo $?  # 非 0 表示有错误

# 设置监控脚本
#!/bin/bash
if ! docker compose ps | grep -q "Up"; then
  echo "有服务未正常运行"
  # 发送告警
fi

7. 总结

docker compose up 卡在 Starting 状态是一个常见问题，通常由以下原因导致：

1. 启动过程耗时过长 - 优化启动命令或拆分初始化步骤
2. 健康检查失败 - 调整健康检查参数或修复应用健康端点
3. 依赖服务未就绪 - 使用健康检查依赖或等待脚本
4. 资源不足 - 调整资源限制或增加系统资源
5. 配置错误 - 检查端口、卷、网络等配置

通过系统的诊断步骤（查看日志、检查状态、进入容器调试）可以快速定位问题。预防措施包括编写健壮的 Dockerfile、优化 Compose 配置以及设置监控告警。

记住：耐心查看日志是解决问题的第一步，大多数 Starting 问题都能通过日志找到线索。