GitLab流水线中Cypress测试无法连接远程MySQL的排查求助

我在Cypress中编写了一个简单测试，使用mysql包读取远程数据库的数据。该测试在本地运行正常，但在GitLab CI/CD流水线中执行时无法连接数据库，报错如下：

CypressError: cy.task('queryDatabase') failed with the following error:

connect ETIMEDOUT

From Node.js Internals:
Error: connect ETIMEDOUT
at Connection._handleConnectTimeout (/builds/tests/cypress/cy-let/node_modules/mysql/lib/Connection.js:409:13)
at Object.onceWrapper (node:events:627:28)
at Socket.emit (node:events:513:28)
at Socket._onTimeout (node:net:562:8)
at listOnTimeout (node:internal/timers:564:17)
at process.processTimers (node:internal/timers:507:7)

数据库连接通过cypress.config.js实现，代码如下：

const { defineConfig } = require("cypress")
const mysql = require('mysql')

const connections = {
  beta: {
    host: 'XXXXXXXXX',
    user: 'XXXXXX',
    password: 'XXXXXXXXXX',
    database: 'XXXXXXXXX'
  },
  production: {
    host: 'YYYYYYYYYY',
    user: 'YYYYY',
    password: 'YYYYY',
    database: 'YYYYY'
  }
}

// querying the database from Node
function queryDB(connectionInfo, query) {
  const connection = mysql.createConnection(connectionInfo)
  connection.connect()
  return new Promise((resolve, reject) => {
    connection.query(query, (error, results) => {
      if (error) {
        return reject(error)
      }
      connection.end()
      return resolve(results)
    })
  })
}

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('task', {
        queryDatabase({ dbName, query }) {
          const connectionInfo = connections[dbName]
          if (!connectionInfo) {
            throw new Error(`Do not have DB connection under name ${dbName}`)
          }
          return queryDB(connectionInfo, query)
        }
      })
    }
  }
})

排查原因与解决建议 #

• 网络访问限制：GitLab CI/CD运行器所在网络可能未被数据库服务器的防火墙/安全组允许。检查数据库服务器的防火墙规则，确认GitLab CI运行器的公网IP（或托管运行器的出口IP段）已被添加到允许列表，开放MySQL默认端口3306（或自定义端口）。
• CI环境变量配置错误：本地测试用的连接参数正确，但CI环境中可能存在参数错误（如主机名、密码写错），或敏感信息未通过CI变量注入。建议将硬编码的敏感信息改为从CI环境变量读取，同时核对CI中的参数与本地是否一致。
• 连接超时设置不足：CI环境网络延迟可能高于本地，默认超时时间不足以建立连接。可在创建数据库连接时添加超时配置：

  const connection = mysql.createConnection({
    ...connectionInfo,
    connectTimeout: 10000 // 设置10秒超时
  })
  

• GitLab运行器网络配置问题：如果是自托管运行器，检查运行器是否能正常访问外部网络，是否有代理或隔离策略阻止了数据库访问。可在CI流水线中添加连通性测试步骤：

  nc -zv 数据库主机IP 3306
  

• 数据库服务器状态异常：确认CI执行期间数据库服务器正常运行、对外服务未中断。如有监控接口，可在CI中添加测试步骤验证服务可达性。
• 依赖版本不一致：本地与CI环境的mysql包版本可能存在差异，导致连接逻辑异常。检查CI环境的依赖版本，确保与本地一致或升级到稳定版本。

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