App Engine无法连接Cloud SQL报Connection refused错误求助

问题概述 #

新建GCP项目中，在App Engine标准环境部署Python应用时，尝试连接Cloud SQL PostgreSQL实例出现如下报错：

OperationalError: (psycopg2.OperationalError) connection to server on socket "/cloudsql/<project_id>:southamerica-east1:test-instance/.s.PGSQL.5432" failed: Connection refused

环境与代码说明 #

• 应用为基于FastAPI开发的API服务，使用sqlmodel/sqlalchemy实现数据库操作逻辑，采用psycopg2-binary作为数据库适配器
• 数据库连接核心代码如下：

import sqlalchemy
from sqlmodel import create_engine

connection_name = "<project_id>:southamerica-east1:test-instance" # 此处隐去真实项目ID

url = sqlalchemy.engine.url.URL.create(
    drivername="postgresql+psycopg2",
    username="some-username",
    password="some-password",
    database="some-database-name",
    connection_name = connection_name,
    query={"host": "{}/{}".format("/cloudsql", connection_name)},
)
engine = create_engine(url)

def create_db_and_tables():
    SQLModel.metadata.create_all(engine)

• 异常背景：完全相同的连接代码数月前在其他GCP项目中可正常连通Cloud SQL，本次部署未调整连接逻辑即出现连接异常

完整报错信息 #

sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) could not connect to server: 
Connection refused
Is the server running locally and accepting
connections on Unix domain socket
 "/cloudsql/<project_id>:southamerica-east1:test-instance/.s.PGSQL.5432"?

已尝试的排查操作 #

• 本地通过pgAdmin 4可正常连接该Cloud SQL数据库
• 移除应用中所有数据库相关逻辑后，应用可正常部署到App Engine
• 已尝试将依赖psycopg2-binary替换为psycopg2，问题未解决
• 已尝试重启、关停后重启Cloud SQL实例，问题未解决
• 已尝试更换异步数据库适配器，未生效；此前同逻辑使用psycopg2即可正常部署连通

排查与解决方案 #

按优先级从高到低逐一验证：

1. 补全App Engine部署配置
   App Engine标准环境通过Unix套接字连接Cloud SQL时，必须在部署配置文件app.yaml中显式声明要连接的Cloud SQL实例，否则应用侧不会启动Cloud SQL Auth代理，对应套接字文件不会生成，直接触发连接拒绝错误。
   在app.yaml中添加以下配置后重新部署：

beta_settings:
  cloud_sql_instances: "<project_id>:southamerica-east1:test-instance"

如果需要同区域连接多个Cloud SQL实例，多个实例连接名用逗号分隔即可
2. 配置服务账号权限
新建GCP项目默认的App Engine服务账号（格式为<project-id>@appspot.gserviceaccount.com）默认没有Cloud SQL连接权限，给该账号绑定Cloud SQL Client（最小权限，推荐）角色，或Cloud SQL Editor/Cloud SQL Admin角色即可。
3. 核对实例连接信息
逐一核对代码中填写的实例连接名、区域、数据库账号密码、数据库名是否和Cloud SQL控制台显示的信息完全一致，重点确认区域标识：当前代码使用的区域为southamerica-east1，如果实例实际创建在其他区域，套接字路径不匹配也会报连接拒绝。
4. 校验网络连通配置

• 如果Cloud SQL实例仅开启私有IP，提前配置Serverless VPC Access，确保App Engine服务和Cloud SQL实例在同一个VPC网络内
• 如果Cloud SQL实例开启公共IP，不需要额外配置VPC，完成前两步配置即可连通

5. 修正数据库连接代码
   原有代码中在URL.create方法内传入了不属于URL构造参数的connection_name字段，该字段不会被SQLAlchemy识别，旧版本依赖未触发问题不代表逻辑兼容，建议调整为官方推荐的配置格式，同时添加连接池配置避免连接泄漏：

import sqlalchemy
from sqlmodel import create_engine

connection_name = "<project_id>:southamerica-east1:test-instance"
db_user = "some-username"
db_pass = "some-password"
db_name = "some-database-name"

engine = create_engine(
    sqlalchemy.engine.url.URL.create(
        drivername="postgresql+psycopg2",
        username=db_user,
        password=db_pass,
        database=db_name,
        query={
            "host": f"/cloudsql/{connection_name}"
        }
    ),
    pool_size=5,
    max_overflow=2,
    pool_timeout=30,
    pool_recycle=1800
)

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