使用Prisma Client、Cloud Run与Cloud SQL时Socket连接失败排查

问题分析 #

你的逻辑是对的：Cloud Run与Cloud SQL的Socket连接依赖Cloud Run在容器运行时自动挂载的Unix Socket路径（/cloudsql/<INSTANCE_CONNECTION_NAME>），应用必须通过这个Socket路径访问数据库，而非TCP连接的localhost:5432。报错显示Prisma仍在尝试连接localhost的5432端口，说明配置并未让Prisma正确使用Socket连接，或构建/部署环节存在遗漏。

可能遗漏的配置点 #

1. Prisma连接URL格式错误

你提到将host设为/cloudsql/<MY CLOUD SQL CONNECTION NAME>/<DB>，这里存在错误：PostgreSQL的Socket连接URL中，host仅需指向Cloud SQL实例的连接名路径，不需要追加<DB>。正确的URL格式应为：

postgresql://<DB_USER>:<DB_PASSWORD>@/<DB_NAME>?host=%2Fcloudsql%2F<INSTANCE_CONNECTION_NAME>

• 注意@/后面直接跟数据库名，host参数是百分编码后的/cloudsql/<INSTANCE_CONNECTION_NAME>（无后续的/<DB>）
• 不要包含端口号（Socket连接不需要端口）

2. Cloud Build构建阶段尝试连接数据库

如果你的Cloud Build步骤中包含prisma migrate deploy、prisma db push或启动应用的命令，构建阶段的Cloud Build容器并未挂载Cloud SQL Socket，因此会触发连接失败。解决方式：

• 将数据库迁移操作移至Cloud Run运行时（比如在NestJS启动时执行迁移，注意添加幂等性判断）
• 或在Cloud Build中配置Cloud SQL代理，临时建立连接以执行迁移：
  在cloudbuild.yaml中添加代理启动步骤：

  steps:
    - name: 'gcr.io/cloudsql-docker/gce-proxy:1.33.1'
      args: ['/cloud_sql_proxy', '-instances=<INSTANCE_CONNECTION_NAME>=tcp:5432']
      background: true
    - name: 'node:18'
      args: ['npm', 'run', 'migrate']
      env:
        - 'DATABASE_URL=postgresql://<USER>:<PASSWORD>@localhost:5432/<DB_NAME>'
  

3. Cloud Run服务未关联Cloud SQL实例

即使URL配置正确，如果Cloud Run服务未添加Cloud SQL连接，容器内不会生成/cloudsql路径。检查：

• 进入Cloud Run服务的「编辑与部署新版本」页面
• 在「连接」>「Cloud SQL连接」下，添加你的PostgreSQL实例
• 部署新版本后，容器内才会出现对应的Socket路径

4. 环境变量未正确传递到Cloud Run

确保DATABASE_URL环境变量已在Cloud Run服务的配置中设置，而非仅在本地或Cloud Build的构建环境中定义：

• 在Cloud Run服务的「环境变量」部分添加DATABASE_URL，值为正确的Socket连接URL
• 不要在Dockerfile中硬编码数据库凭证，避免安全风险

5. Dockerfile中Prisma客户端生成逻辑

确保Dockerfile中执行了prisma generate以生成适配生产环境的客户端：

# 构建阶段
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npx prisma generate  # 生成Prisma客户端
RUN npm run build

# 运行阶段
FROM node:18-slim
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/prisma ./prisma
CMD ["npm", "run", "start:prod"]

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