Firebase V2可调用函数连接Cloud SQL PostgreSQL 15报错求助

问题描述 #

使用Firebase V2可调用函数连接PostgreSQL 15版本的Cloud SQL实例时，出现错误：

connect ENOENT /cloudsql/<proj>:us-west1:<instance>/.s.PGSQL.5432

已完成以下检查：

• 核对连接配置（敏感值已替换），代码如下：

export const createUnixSocketPool = (config: DatabaseConfig) => {
  return knex({
    client: "pg",
    connection: {
      user: config.user,
      password: config.password,
      database: "default",
      host: "/cloudsql/<proj-id>:us-west1:<instance-name>",
    },
    pool: { min: 0, max: 1 },
  });
};

• 确认project@appspot.gserviceaccount.com账号拥有Cloud SQL Client角色
• 已启用Cloud SQL Admin API

排查与解决步骤 #

1. 验证Cloud SQL实例的套接字访问配置 #

• 登录Cloud SQL控制台，进入目标实例的「连接」标签页，确认：
  • 实例已配置私有IP，或已启用Cloud SQL Auth代理支持
  • 实例状态为「运行中」，无维护、暂停等异常状态
• 确保实例的连接名称（<proj-id>:<region>:<instance-name>）与代码中host路径完全一致

2. 检查Firebase函数的部署配置 #

在firebase.json中为函数添加Cloud SQL实例关联配置，确保cloudSqlInstances字段正确配置：

{
  "functions": [
    {
      "source": "functions",
      "runtime": "nodejs18",
      "env": {
        "CLOUD_SQL_CONNECTION_NAME": "<proj-id>:us-west1:<instance-name>"
      },
      "cloudSqlInstances": ["<proj-id>:us-west1:<instance-name>"]
    }
  ]
}

该配置会自动在函数运行环境中注入Unix套接字路径，缺失此配置会导致套接字文件无法生成。

3. 确认依赖包版本兼容性 #

• pg包需至少8.8.0版本（支持PostgreSQL 15）
• knex包需至少2.4.0版本
  执行以下命令更新依赖：

npm install pg@latest knex@latest

4. 完善服务账号的数据库权限 #

• 除Cloud SQL Client角色外，需在Cloud SQL实例的「用户」标签页，将project@appspot.gserviceaccount.com添加为PostgreSQL数据库用户，并授予目标数据库的访问权限
• 确保该账号拥有SELECT、INSERT等必要的数据库操作权限

5. 核对Unix套接字路径的准确性 #

• 代码中host字段的格式必须严格为/cloudsql/<项目ID>:<区域>:<实例名称>
• 注意使用项目ID（而非项目名称），项目ID可在GCP控制台的项目设置中查看

6. 本地与部署环境的差异测试 #

• 本地测试时，需手动启动Cloud SQL Auth代理：

./cloud_sql_proxy -instances=<proj-id>:us-west1:<instance-name>=tcp:5432

此时代码中的host需改为localhost，端口设为5432；部署时再改回Unix套接字路径

• 部署后可通过Firebase控制台的函数日志查看更详细的错误信息，排查环境变量是否正确传递

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