使用 Cloud SQL Auth 代理连接

本页面介绍了如何使用 Cloud SQL Auth 代理连接到 Cloud SQL 实例。

如需详细了解 Cloud SQL Auth 代理的工作原理,请参阅 Cloud SQL Auth 代理简介

概览

如需连接到 Cloud SQL 实例,建议使用方法 Cloud SQL Auth 代理。Cloud SQL Auth 代理:

  • 适用于公共和专用 IP 端点
  • 使用用户或服务帐号的凭据验证连接
  • 将连接封装在针对 Cloud SQL 实例授权的 SSL/TLS 层中。

某些 Google Cloud 服务和应用使用 Cloud SQL Auth 代理,通过加密和授权为公共 IP 路径提供连接,包括:

Google Kubernetes Engine 中运行的应用可以使用 Cloud SQL Auth 代理进行连接。

请参阅 Cloud SQL Auth 代理使用快速入门,以便大致了解其使用方式。

您还可以使用 mysql 客户端从本地机器或 Compute Engine 进行连接,无论是否有 Cloud SQL Auth 代理。

准备工作

在连接到 Cloud SQL 实例之前,请执行以下操作:

    • 对于用户或服务帐号,请确保该帐号具有 Cloud SQL Client 角色。此角色包含 cloudsql.instances.connect 权限,此权限向主帐号授予连接到项目中的所有 Cloud SQL 实例的权限。

      转到 IAM 页面

    • 您可以选择在 IAM 政策绑定中添加 IAM 条件,向帐号授予仅连接到一个特定 Cloud SQL 实例的权限。
  1. 启用 Cloud SQL Admin API。

    启用 API

  2. 安装并初始化 gcloud CLI
  3. 可选。安装 Cloud SQL Auth 代理 Docker 客户端

下载 Cloud SQL Auth 代理

Linux 64 位

  1. 下载 Cloud SQL Auth 代理:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. 使 Cloud SQL Auth 代理可执行:
    chmod +x cloud_sql_proxy
    

Linux 32 位

  1. 下载 Cloud SQL Auth 代理:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. 如果找不到 wget 命令,请运行 sudo apt-get install wget 并重复执行下载命令。
  3. 使 Cloud SQL Auth 代理可执行:
    chmod +x cloud_sql_proxy
    

macOS 64 位

  1. 下载 Cloud SQL Auth 代理:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. 使 Cloud SQL Auth 代理可执行:
    chmod +x cloud_sql_proxy
    

macOS 32 位

  1. 下载 Cloud SQL Auth 代理:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. 使 Cloud SQL Auth 代理可执行:
    chmod +x cloud_sql_proxy
    

Mac M1

  1. 下载 Cloud SQL Auth 代理:
      curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.arm64
      
  2. 使 Cloud SQL Auth 代理可执行:
      chmod +x cloud_sql_proxy
      

Windows 64 位

右键点击 https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe,然后选择链接另存为以下载 Cloud SQL Auth 代理。将文件重命名为 cloud_sql_proxy.exe

Windows 32 位

右键点击 https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe,然后选择链接另存为以下载 Cloud SQL Auth 代理。将文件重命名为 cloud_sql_proxy.exe

Cloud SQL Auth 代理 Docker 映像

为方便起见,GitHub 上的 Cloud SQL Auth 代理代码库中提供了多个包含 Cloud SQL Auth 代理的容器映像。您可以通过 Docker 使用以下命令将最新映像拉取到本地机器:
docker pull gcr.io/cloudsql-docker/gce-proxy:1.31.0

其他操作系统

对于此处未列出的其他操作系统,您可以通过源代码编译 Cloud SQL Auth 代理

启动 Cloud SQL Auth 代理

您可以使用 TCP 套接字、Unix 套接字或 Cloud SQL Auth 代理 Docker 映像启动 Cloud SQL Auth 代理,具体使用哪一个要取决于您所用的语言和环境。Cloud SQL Auth 代理二进制文件连接到命令行中指定的一个或多个 Cloud SQL 实例,并打开本地连接作为 TCP 或 Unix 套接字。其他应用和服务(例如您的应用代码或数据库管理客户端工具)可以通过这些 TCP 或 Unix 套接字连接连接到 Cloud SQL 实例。

TCP 套接字

对于 TCP 连接,Cloud SQL Auth 代理默认侦听 localhost (127.0.0.1)。因此,当您为实例指定 tcp:PORT_NUMBER 时,本地连接位于 127.0.0.1:PORT_NUMBER

或者,您也可以为本地连接指定其他地址。例如,下方展示了如何让 Cloud SQL Auth 代理侦听 0.0.0.0:1234 的本地连接:

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234
  1. 复制您的 INSTANCE_CONNECTION_NAME。您可以在 Google Cloud Console 中的实例概览页面上找到它,也可以通过运行以下命令获取该信息:

    gcloud sql instances describe INSTANCE_NAME
    .

    例如:myproject:myregion:myinstance

  2. 如果实例同时配置了公共 IP 和专用 IP,并且您希望 Cloud SQL Auth 代理使用专用 IP 地址,您必须在启动 Cloud SQL Auth 代理时提供以下选项:
    -ip_address_types=PRIVATE
  3. 如果您要使用服务帐号对 Cloud SQL Auth 代理进行身份验证,请记下随服务帐号一起创建的私钥文件在客户端机器上的位置。
  4. 启动 Cloud SQL Auth 代理。

    一些可能的 Cloud SQL Auth 代理调用字符串如下所示:

    • 使用 Cloud SDK 身份验证:
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:3306
      
      指定的端口必须尚未被本地数据库服务器等所占用。
    • 使用服务帐号并明确包含实例连接的名称(建议用于生产环境):
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:3306 \
                        -credential_file=PATH_TO_KEY_FILE &
      

    如需详细了解 Cloud SQL Auth 代理选项,请参阅用于验证 Cloud SQL Auth 代理身份的选项用于指定实例的选项

Unix 套接字

Cloud SQL Auth 代理可以侦听 Unix 套接字,该套接字是 Posix 标准机制,该机制使用文件夹来管理同一主机上运行的两个进程之间的通信。使用 Unix 套接字的优势在于提高了安全性并缩短了延迟时间,但您无法从外部机器访问 Unix 套接字。

如需创建和使用 Unix 套接字,目标目录必须存在,并且 Cloud SQL Auth 代理和应用必须对其具有读写权限。

  1. 如果您要明确指定实例,请复制您的 INSTANCE_CONNECTION_NAME。您可以在 Google Cloud Console 中的实例概览页面上找到它,也可以通过运行以下命令获取该信息:

    gcloud sql instances describe INSTANCE_NAME
    .

    例如:myproject:myregion:myinstance

  2. 创建要用来存放 Cloud SQL Auth 代理套接字的目录:
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  3. 如果您要使用服务帐号对 Cloud SQL Auth 代理进行身份验证,请记下随服务帐号一起创建的私钥文件在客户端机器上的位置。
  4. 打开新的 Cloud Shell 终端窗口并启动 Cloud SQL Auth 代理。

    一些可能的 Cloud SQL Auth 代理调用字符串如下所示:

    • 使用服务帐号并明确包含实例连接的名称(建议用于生产环境):
      ./cloud_sql_proxy -dir=/cloudsql -instances=INSTANCE_CONNECTION_NAME
      -credential_file=PATH_TO_KEY_FILE &
    • 使用 Cloud SDK 身份验证和自动实例发现:
      ./cloud_sql_proxy -dir=/cloudsql &

    在 Cloud SQL Auth 代理自身的 Cloud Shell 终端中启动 Cloud SQL Auth 代理以便监控其输出,避免与其他程序的输出相混淆。

    如需详细了解 Cloud SQL Auth 代理选项,请参阅用于验证 Cloud SQL Auth 代理身份的选项用于指定实例的选项

Docker

如需在 Docker 容器中运行 Cloud SQL Auth 代理,请使用 Google Container Registry 提供的 Cloud SQL Auth 代理 Docker 映像。

您可以使用以下所示命令通过 TCP 套接字或 Unix 套接字启动 Cloud SQL Auth 代理。这些选项使用 INSTANCE_CONNECTION_NAME 作为连接字符串来标识 Cloud SQL 实例。您可以在 Google Cloud Console 中的实例概览页面上或者通过运行以下命令找到 INSTANCE_CONNECTION_NAME

gcloud sql instances describe INSTANCE_NAME

例如:myproject:myregion:myinstance

您可以使用 TCP 套接字或 Unix 套接字启动 Cloud SQL Auth 代理,具体使用哪一个要取决于您所用的语言和环境。采用 Java 编程语言编写的应用或 Windows 环境不支持 Unix 套接字。

使用 TCP 套接字

docker run -d \\
  -v PATH_TO_KEY_FILE:/config \\
  -p 127.0.0.1:3306:3306 \\
  gcr.io/cloudsql-docker/gce-proxy:1.31.0 /cloud_sql_proxy \\
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:3306 -credential_file=/config

如果您使用的是 Compute Engine 实例提供的凭据,请勿包含 credential_file 参数和 -v PATH_TO_KEY_FILE:/config 行。

请务必在 -p 中指定 127.0.0.1 前缀,以免 Cloud SQL Auth 代理在本地主机外部公开。若要从 Docker 容器外部访问端口,需要在实例参数中指定“0.0.0.0”。

使用 Unix 套接字

docker run -d -v /cloudsql:/cloudsql \\
  -v PATH_TO_KEY_FILE:/config \\
  gcr.io/cloudsql-docker/gce-proxy:1.31.0 /cloud_sql_proxy -dir=/cloudsql \\
  -instances=INSTANCE_CONNECTION_NAME -credential_file=/config

如果您使用的是 Compute Engine 实例提供的凭据,请勿包含 credential_file 参数和 -v PATH_TO_KEY_FILE:/config 行。

如果您使用的是容器优化型映像,请使用可写目录代替 /cloudsql,例如:

-v /mnt/stateful_partition/cloudsql:/cloudsql

您可以指定多个实例(用英文逗号分隔),您还可以使用 Compute Engine 元数据以动态方式确定要连接的实例。 详细了解 Cloud SQL Auth 代理参数

用 mysql 客户端建立连接

  1. MySQL Community Server 下载页面下载适用于您的平台的 MySQL Community Server。
    Community Server 包含 MySQL 客户端。
  2. 按照下载页面上的说明安装 Community Server。

如需详细了解如何安装 MySQL,请参阅安装和升级 MySQL

使用的连接字符串取决于您是使用 TCP 套接字还是 UNIX 套接字启动 Cloud SQL Auth 代理。

TCP 套接字

  1. 启动 mysql 客户端:
    mysql -u USERNAME -p --host 127.0.0.1
    

    使用 TCP 套接字建立连接时,可通过 127.0.0.1 访问 Cloud SQL Auth 代理。

  2. 如果出现提示,请输入密码。
  3. 系统会显示 mysql 提示符。

使用 Unix 套接字

  1. 启动 mysql 客户端:
    mysql -u USERNAME -p -S /cloudsql/INSTANCE_CONNECTION_NAME
    
  2. 输入密码。
  3. 系统会显示 mysql 提示符。

需要帮助?如需获得代理问题排查方面的帮助,请参阅 Cloud SQL Auth 代理连接问题排查,或参阅我们的 Cloud SQL 支持页面。

连接到应用

您可以使用支持连接到 Unix 或 TCP 套接字的任何语言连接到 Cloud SQL Auth 代理。以下是 GitHub 上完整示例的一些代码段,可帮助您了解它们在您的应用中如何协同工作。

其他主题

Cloud SQL Auth 代理命令行参数

上面的示例涵盖了最常见的用例,但 Cloud SQL Auth 代理还具有其他可通过命令行参数设置的配置选项。如需有关命令行参数的帮助,请使用 -help 标志查看最新文档:

./cloud_sql_proxy -help

如需查看有关如何使用 Cloud SQL Auth 代理命令行选项的更多示例,请参阅 Cloud SQL Auth 代理 GitHub 代码库中的 README

用于对 Cloud SQL Auth 代理进行身份验证的选项

所有这些选项都使用 INSTANCE_CONNECTION_NAME 作为连接字符串来标示 Cloud SQL 实例。您可以在 Google Cloud Console 中的实例概览页面上或者通过运行以下命令找到 INSTANCE_CONNECTION_NAME

gcloud sql instances describe INSTANCE_NAME --project PROJECT_ID

例如:gcloud sql instances describe myinstance --project myproject

其中一些选项使用包含帐号的 RSA 私钥的 JSON 凭据文件。如需了解如何为服务帐号创建 JSON 凭据文件,请参阅创建服务帐号

Cloud SQL Auth 代理提供了多种身份验证备选选项,具体取决于您的环境。Cloud SQL Auth 代理会按照以下顺序检查以下各项,并使用找到的第一项尝试进行身份验证:

  1. 由 credential_file 标志提供的凭据。

    使用服务帐号创建和下载关联的 JSON 文件,并在启动 Cloud SQL Auth 代理时将 -credential_file 标志设置为该文件的路径。服务帐号必须具有 Cloud SQL 实例所需的权限

    要在命令行中使用此选项,请调用 cloud_sql_proxy 命令,并将 -credential_file 标志设置为 JSON 凭据文件的路径和文件名。该路径可以是绝对路径,也可以是相对于当前工作目录的路径。 例如:

    ./cloud_sql_proxy -credential_file=PATH_TO_KEY_FILE \
                      -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
      

    如需详细了解如何将 IAM 角色添加到服务帐号,请参阅向服务帐号授予角色

    如需详细了解 Cloud SQL 支持的角色,请参阅适用于 Cloud SQL 的 IAM 角色

  2. 由访问令牌提供的凭据。

    创建访问令牌,然后调用 cloud_sql_proxy 命令,并将 -token 标志设置为 OAuth 2.0 访问令牌。例如:
    ./cloud_sql_proxy -token=ACCESS_TOKEN \
                      -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
      
  3. 由环境变量提供的凭据。

    此选项与使用 -credential_file 标志类似,只是指定您在 GOOGLE_APPLICATION_CREDENTIALS 环境变量中设置的 JSON 凭据文件,而不是使用 -credential_file 命令行参数。
  4. 来自经过身份验证的 gcloud 客户端的凭据。

    如果您已安装 gcloud CLI 并已使用您的个人帐号进行身份验证,则 Cloud SQL Auth 代理可以使用相同的帐号凭据。该方法特别适用于启动和运行开发环境。

    如果未为 gcloud auth login 选择任何帐号,则 Cloud SQL Auth 代理将检查是否为 gcloud auth application-default login 选择了一个帐号。

  5. 与 Compute Engine 实例关联的凭据。

    如果您要从 Compute Engine 实例连接到 Cloud SQL,则 Cloud SQL Auth 代理可使用与该 Compute Engine 实例关联的服务帐号。如果该服务帐号具有 Cloud SQL 实例的必需权限,则 Cloud SQL Auth 代理会成功通过身份验证。

    如果 Compute Engine 实例与 Cloud SQL 实例位于同一项目中,则 Compute Engine 实例的默认服务帐号具有可验证 Cloud SQL Auth 代理身份的必要权限。如果这两个实例属于不同的项目,则您必须将 Compute Engine 实例的服务帐号添加到 Cloud SQL 实例所属的项目中。

  6. 环境的默认服务帐号

    如果 Cloud SQL Auth 代理在先前介绍的任何位置都找不到凭据,则其将遵循为服务器到服务器生产应用设置身份验证中记录的逻辑。某些环境(例如 Compute Engine、App Engine 等)会提供一个默认服务帐号,您的应用默认情况下可以使用该帐号进行身份验证。如果您使用默认服务帐号,则该帐号必须具有角色和权限中所述的权限。如需详细了解 Google Cloud 的身份验证方法,请参阅身份验证概览

创建服务帐号

  1. 在 Google Cloud Console 中,转到服务帐号页面。

    转到“服务帐号”

  2. 选择包含您的 Cloud SQL 实例的项目。
  3. 点击创建服务帐号
  4. 服务帐号名称字段中输入服务帐号的描述性名称。
  5. 服务帐号 ID 更改为一个不重复且易于识别的值,然后点击创建并继续
  6. 点击选择角色字段,然后选择以下角色之一:
    • Cloud SQL > Cloud SQL Client
    • Cloud SQL > Cloud SQL Editor
    • Cloud SQL > Cloud SQL Admin
  7. 点击完成以完成服务帐号的创建过程。
  8. 点击新服务帐号的操作菜单,然后选择管理密钥
  9. 点击添加键下拉菜单,然后点击创建新密钥
  10. 确认密钥类型是 JSON,然后点击创建

    私钥文件将下载到您的机器上。您可以将此文件移至其他位置,但要确保密钥文件的安全。

将 Cloud SQL Auth 代理与专用 IP 结合使用

如需使用专用 IP 连接到 Cloud SQL 实例,Cloud SQL Auth 代理必须位于可以访问实例所在 VPC 网络的资源中。

Cloud SQL Auth 代理使用 IP 与您的 Cloud SQL 实例建立连接。默认情况下,Cloud SQL Auth 代理尝试使用公共 IPv4 地址进行连接。如果您的 Cloud SQL 实例只有专用 IP,则 Cloud SQL Auth 代理使用专用 IP 地址进行连接。

如果实例同时配置了公共 IP 和专用 IP,并且您希望 Cloud SQL Auth 代理使用专用 IP 地址,您必须在启动 Cloud SQL Auth 代理时提供以下选项:

-ip_address_types=PRIVATE

为 Cloud SQL Auth 代理创建数据库用户帐号

使用 Cloud SQL Auth 代理连接到实例时,您需要提供一个用户帐号以登录该实例。为此,您可以使用任何数据库用户帐号。但是,由于 Cloud SQL Auth 代理始终从非 Cloud SQL Auth 代理无法访问的主机名进行连接,因此您可以创建只能由 Cloud SQL Auth 代理使用的用户帐号。这样做的好处是,您可以指定此帐号不使用密码,且不会影响实例或数据的安全性。

要创建专供 Cloud SQL Auth 代理使用的用户帐号,请将主机名指定为 'cloudsqlproxy~[IP_ADDRESS]'。您也可以使用 IP 地址通配符,即 'cloudsqlproxy~%'。完整的用户帐号名称是:

'[USER_NAME]'@'cloudsqlproxy~%'

'[USER_NAME]'@'cloudsqlproxy~[IP_ADDRESS]'

如需创建用户方面的帮助,请参阅创建和管理用户。 如需了解 Cloud SQL 如何与用户帐号搭配使用,请参阅用户

在单独的进程中运行 Cloud SQL Auth 代理

在单独的 Cloud Shell 终端进程中运行 Cloud SQL Auth 代理可能会很有用,可避免将其控制台输出与其他程序的输出混淆。使用下面所示的语法可以在单独的进程中调用 Cloud SQL Auth 代理。

Linux

在 Linux 或 macOS 上,在命令行上使用尾随 & 可以在单独的进程中启动 Cloud SQL Auth 代理:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE &

Windows

在 Windows PowerShell 中,使用 Start-Process 命令可以在单独的进程中启动 Cloud SQL Auth 代理:

Start-Process -filepath "cloud_sql_proxy.exe"
  -ArgumentList "-instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE"

在 Docker 容器中运行 Cloud SQL Auth 代理

如需在 Docker 容器中运行 Cloud SQL Auth 代理,请使用 Google Container Registry 提供的 Cloud SQL Auth 代理 Docker 映像。您可以使用此 gcloud 命令安装 Cloud SQL Auth 代理 Docker 映像:

docker pull gcr.io/cloudsql-docker/gce-proxy:1.31.0

您可以使用以下所示命令通过 TCP 套接字或 Unix 套接字启动 Cloud SQL Auth 代理。

TCP 套接字

    docker run -d \
      -v PATH_TO_KEY_FILE:/config \
      -p 127.0.0.1:3306:3306 \
      gcr.io/cloudsql-docker/gce-proxy:1.31.0 /cloud_sql_proxy \
      -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:3306 \
      -credential_file=/config

Unix 套接字

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/config \
      gcr.io/cloudsql-docker/gce-proxy:1.31.0 /cloud_sql_proxy -dir=/cloudsql \
      -instances=INSTANCE_CONNECTION_NAME
      -credential_file=/config/PATH_TO_KEY_FILE

如果您使用的是容器优化型映像,请使用可写目录代替 /cloudsql,例如:

-v /mnt/stateful_partition/cloudsql:/cloudsql

如果您使用的是 Compute Engine 实例提供的凭据,请勿包含 credential_file 参数和 -v PATH_TO_KEY_FILE:/config 行。

将 Cloud SQL Auth 代理作为服务运行

将 Cloud SQL Auth 代理作为后台服务运行可方便本地开发和测试。当您需要访问 Cloud SQL 实例时,可以在后台启动该服务,并在完成后停止该服务。

  • 目前,Cloud SQL Auth 代理不为作为 Windows 服务运行提供内置支持,但第三方服务管理器可用来作为服务运行 Cloud SQL Auth 代理。例如,您可以使用 NSSM 将 Cloud SQL Auth 代理配置为 Windows 服务,NSSM 会监控 Cloud SQL Auth 代理,并在其停止响应时自动重启。如需了解详情,请参阅 NSSM 文档

Cloud SQL Auth 代理的使用提示

调用 Cloud SQL Auth 代理

所有示例代理调用均在后台启动 Cloud SQL Auth 代理,因此系统会返回提示。为 Cloud SQL Auth 代理预留该 Cloud Shell 终端,以避免其输出与其他程序的输出相混淆。此外,Cloud SQL Auth 代理的输出可帮助您诊断连接问题,从而有助于在日志文件中进行捕获。如果您不在后台启动 Cloud SQL Auth 代理,则除非重定向,否则输出将转到 stdout。

您无需将 /cloudsql 用作 Cloud SQL Auth 代理套接字的目录。(选择此目录名称是为了尽量减少与 App Engine 连接字符串之间的差异)。但是,如果要更改该目录名称,请尽量缩短其总长度;该名称包含在一个较长的字符串中,该字符串需遵循操作系统规定的长度限制。 一般来说,套接字文件名包含 91 到 108 个字符,具体取决于您所用的系统。在 Linux 上,该文件名通常包含 108 个字符;您可以使用以下命令进行检查:

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

使用 Cloud SQL Auth 代理连接到多个实例

您可以使用一个本地 Cloud SQL Auth 代理客户端连接到多个 Cloud SQL 实例。具体操作方式取决于您要使用 Unix 套接字还是 TCP。

Unix 套接字

如需将 Cloud SQL Auth 代理连接到多个实例,您需要以英文逗号分隔列表(无空格)的形式提供带有“-instances”参数的实例连接名称。Cloud SQL Auth 代理在启动时会连接到每个实例。

您可在指定的目录中使用实例的套接字连接到每个实例。

例如:

      ./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance,myProject:us-central1:myInstance2 &
      mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance2
  

TCP 套接字

使用 TCP 建立连接时,请在您的计算机上指定端口,以供 Cloud SQL 身份验证代理侦听每个 Cloud SQL 实例。连接到多个 Cloud SQL 实例时,指定的每个端口都必须唯一并且可用于您的机器。

例如:

    # Start the Cloud SQL Auth proxy to connect to two different Cloud SQL instances.
    # Give the Cloud SQL Auth proxy a unique port on your machine to use for each Cloud SQL instance.

    ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:3306,myProject:us-central1:myInstance2=tcp:1234

    # Connect to "myInstance" using port 3306 on your machine:
    mysql -u myInstanceUser --host 127.0.0.1  --port 3306

    # Connect to "myInstance2" using port 1234 on your machine:
    mysql -u myInstance2User --host 127.0.0.1  --port 1234
  

Cloud SQL Auth 代理调用和 mysql 客户端连接字符串

例如,您可以在针对 MySQL 用户 myUsermyInstance 实例(位于 myProject 项目的 us-central1)的命令中使用 Cloud SQL Auth 代理调用和连接字符串。

通过 gcloud 凭据使用自动实例发现:
    ./cloud_sql_proxy -dir=/cloudsql &
    mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance
通过 gcloud 凭据使用项目发现:
    ./cloud_sql_proxy -dir=/cloudsql -projects=myProject &
    mysql -u myUser -S /cloudsql/myProject:us-central1:

对于 Compute Engine 实例,明确指定实例:
    ./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance &
    mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance
对于 Unix,使用 TCP:
    ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:3306 &
    mysql -u myUser --host 127.0.0.1
对于 Windows(在命令行提示符处):
    cloud_sql_proxy.exe -instances=myProject:us-central1:myInstance=tcp:3306
    mysql -u myUser --host 127.0.0.1

如需详细了解 Cloud SQL 代理选项和连接字符串,请参阅 Cloud SQL Auth 代理 GitHub 页面

排查 Cloud SQL Auth 代理连接问题

Cloud SQL Auth 代理 Docker 映像基于特定版本的 Cloud SQL Auth 代理。当 Cloud SQL Auth 代理推出新版本时,请拉取 Cloud SQL Auth 代理 Docker 映像的新版本,以使您的环境保持最新状态。您可以通过查看 Cloud SQL Auth 代理 GitHub 版本页面,了解 Cloud SQL Auth 代理的当前版本。

如果在使用 Cloud SQL Auth 代理连接到 Cloud SQL 实例时遇到问题,可尝试通过以下几种方法来找出问题原因:

  • 检查 Cloud SQL Auth 代理输出。

    通常,Cloud SQL Auth 代理输出可帮助您确定问题根源和解决方法。将输出传送到文件中,或查看在其中启动 Cloud SQL Auth 代理的 Cloud Shell 终端。

  • 如果您收到 403 notAuthorized 错误,并且您使用服务帐号来验证 Cloud SQL Auth 代理,请确保服务帐号具有正确的权限

    您可在 IAM 页面上搜索服务帐号的 ID 进行检查。该帐号必须具有 cloudsql.instances.connect 权限。Cloud SQL AdminClientEditor 预定义角色具有此权限。

  • 如果您要从 App Engine 进行连接并且收到 403 notAuthorized 错误,请检查 app.yamlcloud_sql_instances 是否有拼写错误或不正确的实例连接名称。实例连接名称始终采用 PROJECT:REGION:INSTANCE 格式。

    此外,请检查 App Engine 服务帐号(例如 $PROJECT_ID@appspot.gserviceaccount.com)是否具有 Cloud SQL Client IAM 角色。

    如果 App Engine 服务位于一个项目(项目 A)中,而数据库位于另一个项目(项目 B)中,则此错误表示 App Engine 服务帐号尚未获得 Cloud SQL Client IAM 角色(位于项目 B 中)。

  • 请务必启用 Cloud SQL Admin API。

    如果未启用,则 Cloud SQL Auth 代理日志中会显示 Error 403: Access Not Configured 之类的输出。

  • 如果要在实例列表中包含多个实例,请确保使用英文逗号作为分隔符且不使用空格。如果要使用 TCP,请确保为每个实例指定不同的端口。

  • 如果要使用 UNIX 套接字进行连接,请确认已通过列出启动 Cloud SQL Auth 代理时提供的目录创建了套接字。

  • 如果设置了出站防火墙政策,请确保它允许连接到目标 Cloud SQL 实例上的端口 3307。

  • 您可以通过在 Google Cloud Console 的操作 > Logging > 日志浏览器部分下查看日志来确认 Cloud SQL Auth 代理已正确启动。操作成功如下所示:

    2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/3306 for $PROJECT_ID:$REGION:$INSTANCE_NAME
    2021/06/14 15:47:56 Ready for new connections
    
  • 配额问题:当 Cloud SQL Admin API 配额用完时,Cloud SQL 身份验证代理将启动并显示以下错误消息:

    There was a problem when parsing a instance configuration but ignoring due
    to the configuration. Error: googleapi: Error 429: Quota exceeded for quota
    metric 'Queries' and limit 'Queries per minute per user' of service
    'sqladmin.googleapis.com' for consumer 'project_number:$PROJECT_ID.,
    rateLimitExceeded
    

    应用连接到代理后,代理会报告以下错误:

    failed to refresh the ephemeral certificate for $INSTANCE_CONNECTION_NAME:
    googleapi: Error 429: Quota exceeded for quota metric 'Queries' and limit
    'Queries per minute per user' of service 'sqladmin.googleapis.com' for
    consumer 'project_number:$PROJECT_ID., rateLimitExceeded
    

    解决方案:确定配额问题的来源,例如,应用滥用连接器,并且不必要地创建新连接,或与支持团队联系以请求增加 Cloud SQL Admin API 配额。如果配额错误在启动时显示,您必须重新部署应用以重启代理。如果配额错误在启动后出现,则无需重新部署。

后续步骤