使用docker-compose部署Google SQL Auth Proxy未生成Unix Socket问题

问题场景 #

本地运行Cloud SQL Proxy时，.cloudsql目录会正常生成Unix Socket文件：

~/cloud-sql-proxy --unix-socket ~/.cloudsql --credentials-file ~/.cloud-sql.credentials.json project:region:instance

但使用Docker Compose部署后，代理日志显示启动成功，却未在共享卷中生成Socket文件，API应用连接时报错：

Error: connect ENOENT /cloudsql/project:region:instance at PipeConnectWrap.afterConnect [as oncomplete]

已确认：数据库凭证有效（TCP方式可正常连接），API的socketPath配置正确（可连接本地MySQL的Unix Socket）。

疑问解答与问题修复 #

1. 卷默认是否可写？ #

Docker命名卷默认是可写的，容器对挂载的卷目录拥有读写权限，此场景下权限不是问题。

2. 多容器环境能否通过Unix Socket连接？ #

可以。Unix Socket是文件系统中的实体文件，只要多个容器挂载同一个Docker卷，就能通过共享的文件路径访问Socket，这是跨容器共享Unix Socket的标准方式。

3. 配置错误分析 #

核心问题是Cloud SQL Proxy的启动命令参数顺序错误：
原命令中，--unix-socket /cloudsql放在了实例名称前面，但代理的参数规则是：全局参数（如--unix-socket、--credentials-file）需要放在实例参数之前，否则会被解析错误。

原命令的参数顺序导致代理无法识别正确的实例配置，最终只启动了TCP监听（日志里的Listening on 127.0.0.1:3307），没有生成Unix Socket。

修正后的Docker Compose配置 #

调整代理的command参数顺序，将全局参数放在实例名称之前：

volumes:
  socket:

services:
  proxy:
    container_name: proxy
    image: gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.8.2
    # 修正参数顺序：先全局参数，再实例
    command: --unix-socket /cloudsql --credentials-file /secrets/cloudsql/credentials.json project:region:instance
    ports:
      - 3307:3307
    volumes:
      - ./cloud-sql.credentials.json:/secrets/cloudsql/credentials.json
      - socket:/cloudsql
    restart: always

  web-api:
    container_name: web-api
    build:
      context: .
      dockerfile: ./apps/web-api/Dockerfile
    ports:
      - 3333:3333
    volumes:
      - socket:/cloudsql
    depends_on:
      - proxy
    env_file:
      - .env
    restart: always

  data-api:
    # 同web-api配置，省略

验证修复 #

启动容器后，查看代理日志，如果出现类似以下内容，说明Unix Socket已正常生成：

[project:region:instance] Listening on unix socket: /cloudsql/project:region:instance

此时API应用即可通过/cloudsql/project:region:instance路径连接数据库。

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