AWS CodeBuild无法连接RDS数据库 求调试排查方案

通过Terraform创建RDS数据库与CodeBuild项目，使用GitHub Action调用aws-actions/aws-codebuild-run-build执行Flyway迁移任务时，出现数据库连接超时错误：

[Container] 2022/10/07 21:03:56 Running command flyway -user=$DB_USER -password=$DB_PASSWORD -url=jdbc:mariadb://$DB_HOST:$DB_PORT/$DB_NAME -createSchemas=true migrate
ERROR: Unable to obtain connection from database (jdbc:mariadb://***:***/***) for user '***': Could not connect to address=(host=***)(port=***)(type=master) : Socket fail to connect to host:***, port:***. connect timed out
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
SQL State  : 08000
Error Code : -1
Message    : Could not connect to address=(host=***)(port=***)(type=master) : Socket fail to connect to host:***, port:***. connect timed out

Caused by: java.sql.SQLNonTransientConnectionException: Could not connect to address=(host=***)(port=***)(type=master) : Socket fail to connect to host:***, port:***. connect timed out
Caused by: java.sql.SQLNonTransientConnectionException: Socket fail to connect to host:***, port:***. connect timed out
Caused by: java.net.SocketTimeoutException: connect timed out

已参考过AWS CodeBuild无法与RDS交互的常规解决方案，NACL使用默认规则，仅配置安全组，且存在一个基于AWS CDK的同类流水线可正常运行，对比后安全组、IAM权限、数据库配置均一致，需排查网络路由缺失问题及调试方向。

1. 验证CodeBuild的网络配置 #

• 确认CodeBuild项目是否正确配置VPC、子网和安全组：若CodeBuild不在公网环境，必须指定RDS所在VPC及对应子网，确保子网网络可达RDS。
• 检查CodeBuild使用的子网是否配置了NAT网关/互联网网关：如果RDS开启公网访问，子网需能访问公网；若为内网访问，需确保子网与RDS子网在同一VPC或已配置VPC对等连接。
• 查看CodeBuild执行日志中的网络信息，确认容器获取的IP属于指定子网，尝试ping RDS私有IP（内网场景）验证连通性。

2. 安全组双向规则验证 #

• RDS安全组：入站规则需允许CodeBuild安全组（或CodeBuild所在子网的IP段）访问RDS端口（MariaDB默认3306）。
• CodeBuild安全组：出站规则需允许访问RDS的IP和端口，可临时设置为允许所有出站流量，排查是否为出站限制导致。
• 注意：安全组为状态化规则，但如果RDS在私有子网，CodeBuild的出站规则必须覆盖RDS所在网络段。

3. RDS网络可达性验证 #

• 检查RDS实例的公网访问开关：若CodeBuild在公网环境，需开启RDS公网访问；若为内网访问，确保RDS私有IP可被CodeBuild所在子网访问。
• 在同一VPC的EC2实例上测试RDS连接：mysql -h <RDS_HOST> -P <PORT> -u <USER> -p，确认RDS本身可正常连接。
• 在CodeBuild容器中执行nslookup $DB_HOST，验证DNS解析是否正确指向RDS的私有IP或公网IP。

4. Terraform配置细节排查 #

• 确认CodeBuild的vpc_config是否正确关联子网和安全组，子网ID必须属于RDS所在VPC。
• 检查RDS的vpc_security_group_ids是否包含允许CodeBuild访问的安全组ID，避免Terraform变量引用错误。
• 通过AWS控制台核对Terraform部署后的实际资源配置，确保CodeBuild和RDS的网络配置与代码定义一致（防止变量替换或部署遗漏）。

5. 权限与环境变量检查 #

• 确认GitHub Action传递给CodeBuild的DB_HOST、DB_PORT等环境变量值正确，是否指向RDS的正确端点。
• 检查CodeBuild的IAM角色是否拥有ec2:CreateNetworkInterface权限，缺失该权限会导致CodeBuild无法在VPC内创建弹性网卡，进而无法访问VPC内资源。

6. 临时调试命令 #

在CodeBuild的buildspec.yml中添加前置调试命令，快速定位问题：

# 验证DNS解析
nslookup $DB_HOST
# 验证网络连通性
ping -c 3 $DB_HOST
# 验证端口可达性
telnet $DB_HOST $DB_PORT

同时可临时放宽安全组规则（如RDS入站允许0.0.0.0/0，CodeBuild出站允许所有流量），验证是否为安全组规则导致的问题，测试后及时恢复规则。

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