GitLab CI流水线中Spring Boot Maven项目无法连接Docker容器内PostgreSQL数据库的集成测试问题

嘿，我完全理解刚接触GitLab CI时碰到这种连接问题有多闹心！本地跑起来顺得不行，一到CI流水线就连不上数据库，确实挺让人挠头的。咱们一步步拆解问题，找到解决办法：

核心问题：CI环境和本地环境的差异 #

本地你是在自己的机器上跑Docker容器，Spring Boot和数据库容器处于同一个网络，用localhost就能访问；但GitLab CI的Job是在独立的容器（或虚拟机）里运行的，默认情况下和你手动启动的数据库容器不在同一网络，而且直接用localhost指向的是Job容器本身，不是数据库容器。

具体解决步骤 #

1. 用GitLab CI的Services管理PostgreSQL服务 #

GitLab CI内置了服务管理功能，可以直接在.gitlab-ci.yml里定义PostgreSQL作为依赖服务，它会自动帮你启动数据库容器，并和你的Job容器放在同一网络里。示例配置如下：

stages:
  - test

integration-test:
  stage: test
  image: maven:3.8.6-openjdk-17
  services:
    - name: postgres:14-alpine
      variables:
        POSTGRES_DB: your_database_name
        POSTGRES_USER: your_db_user
        POSTGRES_PASSWORD: your_db_password
  variables:
    # Spring Boot会自动读取这些环境变量覆盖配置文件
    SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/your_database_name
    SPRING_DATASOURCE_USERNAME: your_db_user
    SPRING_DATASOURCE_PASSWORD: your_db_password
  script:
    - mvn verify

这里要注意：数据库的连接地址不是localhost，而是服务名postgres——GitLab CI会把服务容器的主机名设置为你指定的服务名称，这样Job容器就能直接通过这个主机名访问数据库。

2. 等待数据库完全启动就绪 #

有时候CI里PostgreSQL容器刚启动，还没完成初始化（比如创建数据库、用户），Spring Boot就开始尝试连接，导致连接失败。这时候可以在测试命令前加一段等待脚本，确保数据库就绪：

# 上面的integration-test job里的script修改为：
script:
  # 安装pg_isready工具（maven镜像默认没有，需要手动安装）
  - apt-get update && apt-get install -y postgresql-client
  # 循环等待数据库就绪
  - until pg_isready -h postgres -U your_db_user; do
      echo "Waiting for PostgreSQL to start..."
      sleep 2
    done
  - mvn verify

3. 检查Runner配置（如果用自托管Runner） #

如果你用的是自己搭建的GitLab Runner，要确保Runner的执行器是docker或者docker-in-docker模式（如果需要在Job里手动操作Docker）。另外，确认Runner有足够的资源启动数据库容器，避免因为资源不足导致数据库启动失败。

4. 保持配置一致性 #

确保CI里的数据库用户名、密码、数据库名称和本地完全一致，可以通过GitLab的CI/CD变量来管理敏感信息（比如密码），不要硬编码在配置文件里，既安全又方便统一管理。

避坑提醒 #

尽量不要在CI Job里手动用docker run启动数据库容器——不仅要处理网络问题，还要自己管理容器的生命周期，远不如用GitLab CI的Services功能省心。

备注：内容来源于stack exchange，提问作者Sven Jäger