Cloud SQL 代理简介

本页面简要介绍了 Cloud SQL 代理,同时介绍了代理选项。

如需了解 Cloud SQL 代理的分步使用说明,请点击与您的环境所对应的链接

您无需使用代理或配置 SSL,即可从 App Engine 标准环境连接到 Cloud SQL从 App Engine 柔性环境连接到 Cloud SQL

代理的优势

Cloud SQL 代理让您可安全地访问自己的实例,而无需已获授权网络配置 SSL

使用 Cloud SQL 代理访问 Cloud SQL 实例具有以下优势:

  • 安全连接:此代理使用采用 128 位 AES 加密的 TLS 1.2 自动加密进出数据库的流量;SSL 证书用于验证客户端和服务器身份。
  • 简化连接管理:此代理处理 Cloud SQL 的身份验证,让您无需再提供静态 IP 地址。

代理不提供新的连接路径,而是依赖于现有 IP 连接。如需使用专用 IP 连接到 Cloud SQL 实例,代理必须位于可以访问实例所在 VPC 网络的资源中。

Cloud SQL 代理的工作原理

Cloud SQL 代理的工作原理是在本地环境中运行一个称为“代理”的本地客户端。您的应用通过数据库使用的标准数据库协议与该代理进行通信。而该代理通过安全隧道与服务器上运行的代理配套进程进行通信。

虽然代理可以侦听任何端口,但它只会在端口 3307 中创建到 Cloud SQL 实例的传出连接。如果您有出站防火墙政策,请确保它允许连接到 Cloud SQL 实例 IP 上的端口 3307。

下图显示了该代理如何连接到 Cloud SQL:

从客户端软件连接到 SQL 实例的代理的示意图

Cloud SQL 代理的使用要求

要使用该代理,必须满足以下要求:

  • 必须启用 Cloud SQL Admin API。
  • 必须向该代理提供 Google Cloud 身份验证凭据
  • 必须向该代理提供有效的数据库用户帐号和密码。
  • 实例必须具有公共 IPv4 地址,或者配置为使用专用 IP

    该公共 IP 地址无需可供任何外部地址访问(无需添加为已获授权的网络地址)。

安装 Cloud SQL 代理

Linux 64 位

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

Linux 32 位

  1. 下载该代理:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. 使该代理可以执行:
    chmod +x cloud_sql_proxy
    

macOS 64 位

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

macOS 32 位

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

Windows 64 位

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

Windows 32 位

右键点击 https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe,然后选择链接另存为以下载该代理。将文件重命名为 cloud_sql_proxy.exe
如果此处未包含您的操作系统,您还可以使用源代码编译代理

代理启动选项

启动代理时,向其提供以下信息:

  • 该代理应与哪些 Cloud SQL 实例建立连接
  • 该代理将在何处侦听要从您的应用发送到 Cloud SQL 的数据
  • 该代理将在何处查找向 Cloud SQL 验证您的应用时要使用的凭据
  • 要使用哪种 IP 地址类型(如果需要)。

您提供的代理启动选项决定了它是侦听 TCP 端口还是侦听 Unix 套接字。如果该代理要侦听 Unix 套接字,则会在您选择的位置(通常为 /cloudsql/ 目录)创建套接字。 对于 TCP,该代理默认侦听 localhost

运行带参数 --helpcloud_sql_proxy 可执行文件,以查看完整的启动选项列表。

您可在本地环境中的任意位置安装该代理。代理二进制文件的位置不影响它侦听您的应用中数据所使用的位置。

使用服务帐号进行身份验证

代理需要进行身份验证。使用服务帐号进行身份验证的优势在于,您可以专门为该代理创建凭据文件;只要该代理处于运行状态,这个文件就会明确、永久地关联到该代理。因此,对于未在 Compute Engine 实例上运行的生产实例,建议的方法是使用服务帐号。

如果需要从多台机器调用 Cloud SQL 代理,您可在系统映像中复制凭据文件。

要使用此方法,必须创建和管理凭证文件。只有拥有 resourcemanager.projects.setIamPolicy 权限的用户(如项目所有者)才能创建服务帐号。如果您的 Google Cloud 用户不具备此权限,则您必须让其他人代为创建服务帐号,或使用其他方法来验证该代理的身份。

如需创建凭据文件方面的帮助,请参阅创建服务帐号

Cloud SQL 代理身份验证选项

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

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

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

    创建访问令牌,然后在启动 Cloud SQL 代理时在命令行中使用 -token 标志提供该令牌。
  3. 由环境变量提供的凭据。

    您可以将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为针对服务帐号创建的 json 密钥文件的路径。
  4. 来自经过身份验证的 Cloud SDK 客户端的凭据。

    如果您已安装了 Cloud SDK 并使用它向 Google Cloud 进行了身份验证,则 Cloud SQL 代理也可使用相同凭据。该方法特别适用于快速启动和运行开发环境。对于生产环境,应使用其他方法进行身份验证。
  5. 与 Compute Engine 实例关联的凭据。

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

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

服务帐号所需的权限

如果使用服务帐号为代理提供凭据,则您必须在创建该服务帐号时为其分配足够的权限。如果您要使用更精细的 Identity Access and Management (IAM) 角色来管理 Cloud SQL 权限,则必须向服务帐号分配一个具有 cloudsql.instances.connect 权限的角色。以下预定义 Cloud SQL 角色拥有这项权限:

  • Cloud SQL Client
  • Cloud SQL Editor
  • Cloud SQL Admin

如果您要使用传统的项目角色(Viewer、Editor、Owner),则该服务帐号必须至少具有 Editor 角色。

用于指定 Cloud SQL 实例的选项

可采用多种方式告知代理您希望连接到哪些实例。一些方式是显式的,一些方式是隐式的。在某些配置中,您无需提前告知代理您想要连接到哪些实例,因为代理会根据连接请求进行连接。

实例指定选项由您的操作系统和环境而定:

选项 优势 注意事项和要求 Linux/macOS
(Unix 套接字)
Java Windows 备注
FUSE
用户空间文件系统
基于连接请求创建动态套接字;实例更改时不需要重启代理。 必须安装 FUSE。 支持 使用 -fuse 标志。
自动发现实例 无需指定实例;已在默认项目中为所有实例创建套接字。 Proxy API 用量会增加。必须安装 Cloud SDK、验证其身份,并设置默认项目。必须重启代理才能添加新实例。 支持 不适用于生产实例。
项目发现 无需指定实例;已在指定项目中为所有实例创建套接字。 Proxy API 用量会增加。必须安装 Cloud SDK 并验证其身份。必须重启代理才能添加新实例。 支持 使用 -projects 参数。建议不要用于生产实例。
在调用代理时指定实例 实例列表是已知且静态的。 必须重启代理才能添加新实例。 支持 支持使用 TCP 套接字 支持使用 TCP 套接字 使用 -instances 参数。对于多个实例,请使用不带空格的逗号分隔列表。 了解详情
使用 Compute Engine 元数据指定实例 通过更改元数据值即可更新实例列表,无需重启代理。 仅适用于 Compute Engine。 支持 支持使用 TCP 套接字 支持使用 TCP 套接字 使用 -instances_metadata 标志。 了解详情

请参阅示例调用和连接字符串

将代理与专用 IP 搭配使用

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

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

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

-ip_address_types=PRIVATE

Cloud SQL 代理的使用提示

调用 Cloud SQL 代理

所有示例代理调用均在后台启动该代理,因此返回提示。建议为该代理预留该终端,避免其输出与其他程序的输出相混淆。此外,该代理的输出可帮助您诊断连接问题,因此最好捕获到日志文件中。如果您不在后台启动代理,则在未经重定向的情况下,代理的输出会转到 stdout。

您不必将 /cloudsql 用作代理套接字的目录(选择此目录名称是为了尽量减少与 App Engine 连接字符串之间的差异)。但是,如果要更改该目录名称,请尽量缩短其总长度;该名称包含在一个较长的字符串中,该字符串需遵循操作系统规定的长度限制。

通过代理连接到多个实例

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

Unix 套接字

如需将代理连接到多个实例,请以不带空格的逗号分隔列表形式提供带有 -instances 参数的实例连接名称。代理会在启动时连接到各个实例。

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

例如:

./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 进行连接时,需指定用于连接实例的机器端口,并且每个实例必须具有自己的端口。 mysql 工具默认使用 3306,但您可以指定其他端口供其使用。

例如:

  # Start the proxy for two instances, each with its own port:

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

  # Connect to "myInstance" on port 3306, and "myInstance2" on port 1234

  mysql -u myInstanceUser --host 127.0.0.1  --port 3306
  mysql -u myInstance2User --host 127.0.0.1  --port 1234

使 Cloud SQL 代理保持最新版本

Google 有时会发布该代理的新版本。您可通过查看 Cloud SQL 代理 GitHub 版本页面,了解当前版本。 Google Groups Cloud SQL 公告论坛也会公布未来的代理版本。

API 的使用

Cloud SQL 代理会向 Cloud SQL Admin API 发出请求,而这些请求将计入项目的 API 配额。

当您启动代理时,API 用量最高;使用自动发现实例这一功能或 -projects 参数时尤其如此。代理运行时,每小时针对每个连接的实例发出两个 API 调用。

关于为代理创建特殊用户帐号

使用代理连接到实例时,您需提供用于登录实例的用户帐号。为此,您可以使用任何数据库用户帐号。但是,由于此代理始终从非此代理不可访问的主机名连接,因此您可以创建只能由此代理使用的用户帐号。此操作的优点是,您可以在没有密码的情况下指定此帐号,且不会影响实例或数据的安全性。

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

'[USER_NAME]'@'cloudsqlproxy~%'

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

如需创建用户方面的帮助,请参阅创建和管理用户。 如需了解 Cloud SQL 如何与用户帐号搭配使用,请参阅用户。如需了解 MySQL 用户帐号,请参阅 MySQL 文档中的保护初始 MySQL 帐号的安全

Cloud SQL 代理参数和标志

Cloud SQL 代理在启动时会接受多个标记和参数。这些选项决定 Cloud SQL 代理在何处以及如何创建用于与 Cloud SQL 通信的套接字,以及如何进行身份验证。

如需代理选项方面的帮助,请参阅以下信息:

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

以属于 myProject 项目且位于 us-central1myInstance 实例为例,您可以在该实例的 MySQL 用户 myUser 命令中使用代理调用和连接字符串。

通过 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:myInstance
对于具有明确实例规范的 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 代理 GitHub 页面

如何将 FUSE 与 Cloud SQL 代理搭配使用

FUSE 代表“用户空间文件系统”。根据 Cloud SQL 代理的调用方式,该代理可以选择使用 FUSE 创建用于连接 Cloud SQL 的套接字。

从 Compute Engine 或本地开发环境进行连接时,Cloud SQL 代理使用 FUSE 访问 Cloud SQL 实例,如下所示:

  • “/cloudsql”目录会由 Cloud SQL 代理作为用户空间中的文件系统(即 FUSE)进行装载。

  • 进程(如 mysql)会尝试查询名为 $INSTANCE 的文件。

  • 代理会拦截请求并返回消息,说明“/cloudsql/$INSTANCE”是一种指向位于文件系统其他位置的 Unix 套接字的符号链接。

  • 进程(如 mysql)会根据该链接打开其指向和连接的 Unix 套接字。

安装 FUSE

对于 Linux

FUSE 需要 fusermount 程序和内核模块才能正常运行。您可以通过查找 /dev/fuse/ 文件来检查是否已安装该程序。如果您的系统中没有 fusermount,您可以使用软件包管理器安装或使用源代码进行编译。

对于 macOS

安装 FUSE for macOS

创建服务帐号并生成密钥文件

如需创建服务帐号,请执行以下操作:

如果使用服务帐号为代理提供凭据,则您必须在创建该服务帐号时为其分配足够的权限。如果要使用更精细的 Identity Access and Management (IAM) 角色来管理 Cloud SQL 权限,您必须向服务帐号分配一个具有 cloudsql.instances.connect 权限的角色。以下预定义 Cloud SQL 角色拥有这项权限:

  • Cloud SQL Client
  • Cloud SQL Editor
  • Cloud SQL Admin

如果您要使用传统的项目角色(Viewer、Editor、Owner),则该服务帐号必须至少具有 Editor 角色。

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

    转到“服务帐号”页面

  2. 选择包含您的 Cloud SQL 实例的项目。
  3. 点击创建服务帐号
  4. 创建服务帐号对话框中,为服务帐号提供一个描述性名称。
  5. 角色部分,选择以下角色之一:
    • Cloud SQL > Cloud SQL Client
    • Cloud SQL > Cloud SQL Editor
    • Cloud SQL > Cloud SQL Admin

    或者,您可以通过选择项目 > Editor 使用原初 Editor 角色,但 Editor 角色拥有整个 Google Cloud 的权限。

    如果您看不到这些角色,则表明您的 Google Cloud 用户可能没有 resourcemanager.projects.setIamPolicy 权限。您可以转到 Google Cloud Console 中的 IAM 页面,然后搜索您的用户 ID 来检查您的权限。

  6. 服务帐号 ID 更改为一个不重复且易于识别的值。
  7. 点击提供新的私钥,并确认密钥类型为 JSON
  8. 点击创建

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

要详细了解服务帐号,请参阅身份验证文档

在生产环境中使用 Cloud SQL 代理

在生产环境中使用 Cloud SQL 代理时,可采取一些步骤确保该代理为您的应用提供所需的可用性。

确保 Cloud SQL 代理以永久性服务的形式运行

如果代理进程终止,则通过该代理的所有现有连接将被移除,且您的应用无法再使用该代理创建与 Cloud SQL 实例的任何连接。要避免出现这种情况,请确保该代理以永久性服务的形式运行,使其能在因任何原因退出时自动重启。这可通过使用 systemdupstartsupervisor 之类的服务来实现。对于 Windows 操作系统,将该代理作为 Windows 服务运行。通常,该代理的正常运行时间要求应与应用进程相同。

您的应用需要多少个 Cloud SQL 代理副本

无需为每个应用进程创建代理进程;多个应用进程可共享一个代理进程。通常,每个工作站或虚拟机应运行一个代理客户端进程。

如果要自动调节虚拟机,请确保您的虚拟机配置中包含该代理,这样一来,每次启动新的虚拟机时,该虚拟机都具有自己的代理进程。

您可以通过限制或整合连接来管理应用所需的连接数。该代理不对新连接率或永久连接数作任何限制。

减少 Cloud SQL 代理输出

如果您需要减小代理日志的大小,可在启动代理时设置 -verbose=false。但请记住,这样做会降低代理输出在诊断连接问题时的有效性。

故障转移如何影响 Cloud SQL 代理

如果在配置为高可用性的实例上运行代理,并且发生了故障转移,则通过代理进行的连接受到的影响与通过 IP 进行的连接相同:所有现有连接都将丢失,并且应用必须建立新连接。但是,这无需人工干预;应用可以继续使用与之前相同的连接字符串。

Cloud SQL 代理连接问题排查

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

  • 检查代理输出。

    通常,代理输出可帮助您确定问题源头和解决方法。请通过管道将输出发送到文件中,或查看启动该代理的终端。

  • 如果您收到 403 notAuthorized 错误,而且您是使用服务帐号来验证代理的身份,请确保该服务帐号具有正确的权限

    您可在 IAM 页面上搜索服务帐号的 ID 进行检查。该帐号应具有 cloudsql.instances.connect 权限。除 Cloud SQL Viewer 外,所有 Cloud SQL 预定义角色都具有此权限。此外,旧版项目角色 EditorOwner 也具有这项必需权限。

  • 请务必启用 Cloud SQL Admin API。

    如果未启用该 API,则您将在代理日志中看到诸如 Error 403: Access Not Configured 之类的输出。

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

  • 如果要尝试通过应用进行连接,请先使用管理客户端进行连接,消除应用的所有问题。

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

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

后续步骤