GitLab CI中Docker Compose部署FastAPI服务遇ConnectionError

本地运行docker-compose up -d后执行pytest tests一切正常，但GitLab CI流水线中容器启动后，测试和docker exec内的curl均报连接拒绝错误，可按以下思路排查解决：

1. 等待服务完全启动后再执行校验 #

流水线中容器启动后，服务可能还未完成初始化就被执行curl或测试。替换原before_script中的curl命令，添加循环等待逻辑：

- |
  until docker exec fitai-pro curl -s http://localhost:8000/health; do
    echo "等待服务启动..."
    sleep 2
  done

2. 修正测试代码的访问地址 #

GitLab CI的Docker-in-Docker环境中，localhost指向运行pytest的job容器，而非服务容器。需调整测试代码的访问地址：

• 将测试代码中的URL改为http://fitai-pro:8000（Docker Compose会自动为服务名创建内部DNS解析）
• 若需确保网络连通性，可在docker-compose.yml中添加自定义网络，并让job容器加入该网络：
  修改docker-compose.yml：

  services:
    fitai-pro-service:
      # 原有配置保留
      networks:
        - test-network
  networks:
    test-network:
      name: test-network
      driver: bridge
  

  在.gitlab-ci.yml的before_script中添加：

  - docker network connect test-network $(hostname)
  

3. 验证Docker Compose文件路径正确性 #

检查DOCKER_COMPOSE_FILE指定的app/docker-compose.yml在CI环境中是否存在，可在before_script中添加：

- ls -la app/

确认文件路径无误，避免因路径错误导致服务未正确启动。

4. 检查服务容器内进程状态 #

在before_script中添加命令，验证uvicorn进程是否正常运行：

- docker exec fitai-pro ps aux

确认进程监听地址为0.0.0.0:8000，若进程未启动，排查Dockerfile依赖安装是否完整或容器启动命令是否正确。

5. 调整Docker-in-Docker网络配置 #

Docker-in-Docker环境中，端口映射可能无法直接从job容器访问服务容器。优先使用Docker内部服务名访问，而非依赖端口映射；若必须使用端口映射，确认DOCKER_HOST配置正确，且服务容器端口已暴露到dind服务中。

内容的提问来源于stack exchange，提问作者tabeqc