本页面总结了 Cloud SQL Auth 代理，并介绍了如何使用它来建立与实例的授权、加密和安全连接。
如需了解 Cloud SQL Auth 代理的分步使用说明，请点击与您的环境所对应的链接：
您无需使用 Cloud SQL Auth 代理，也无需将 SSL 配置为从 App Engine 标准环境或 App Engine 柔性环境连接到 Cloud SQL。
自行试用
如果您是 Google Cloud 新手，请创建一个账号来评估 Cloud SQL 在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。
免费试用 Cloud SQLCloud SQL Auth 代理的优势
Cloud SQL Auth 代理是一个 Cloud SQL 连接器，可让您安全地访问您的实例，而无需使用已获授权的网络，也无需配置 SSL。
Cloud SQL Auth 代理和其他 Cloud SQL 连接器具有以下优势：
- 安全连接：Cloud SQL Auth 代理使用采用 256 位 AES 加密的 TLS 1.3 自动加密进出数据库的流量。SSL 证书用于验证客户端和服务器身份，独立于数据库协议；您无需管理 SSL 证书。
- 简化连接授权：Cloud SQL Auth 代理使用 IAM 权限来控制谁能连接到 Cloud SQL 实例。因此，Cloud SQL Auth 代理会处理 Cloud SQL 的身份验证，让您无需再提供静态 IP 地址。
- IAM 数据库身份验证。（可选）Cloud SQL Auth 代理支持自动刷新 OAuth 2.0 访问令牌。如需了解此功能，请参阅 Cloud SQL IAM 数据库身份验证。
Cloud SQL Auth 代理不提供新的连接路径，而是依赖于现有 IP 连接。如需使用专用 IP 连接到 Cloud SQL 实例，Cloud SQL Auth 代理必须位于可以访问实例所在 VPC 网络的资源中。
Cloud SQL Auth 代理的工作原理
Cloud SQL Auth 代理的工作原理是在本地环境中运行本地客户端。您的应用通过数据库使用的标准数据库协议与 Cloud SQL Auth 代理进行通信。
而 Cloud SQL Auth 代理通过安全隧道与服务器上运行的代理配套进程进行通信。通过 Cloud SQL Auth 代理建立的每个连接都会创建一个与 Cloud SQL 实例的连接。
应用连接到 Cloud SQL Auth 代理时，它会检查其与目标 Cloud SQL 实例之间的现有连接是否可用。如果连接不存在，则它会调用 Cloud SQL Admin API 来获取临时 SSL 证书并使用它来连接到 Cloud SQL。临时 SSL 证书大约在一小时后过期。Cloud SQL Auth 代理会在证书过期之前刷新这些证书。
虽然 Cloud SQL Auth 代理可以侦听任何端口，但它只会在端口 3307 上创建到 Cloud SQL 实例的传出或出站流量连接。由于 Cloud SQL Auth 代理通过域名 sqladmin.googleapis.com 调用 API，而该域名没有固定 IP 地址，因此必须在端口 443 上允许所有出站流量 TCP 连接。如果您的客户端机器具有出站防火墙政策，请确保它允许与 Cloud SQL 实例 IP 上的端口 3307 的传出连接。
Cloud SQL Auth 代理不提供连接池，但可以与其他连接池配对以提高效率。
下图展示了 Cloud SQL Auth 代理如何连接到 Cloud SQL：
Cloud SQL Auth 代理的使用要求
如需使用 Cloud SQL Auth 代理，必须满足以下要求：
- 必须启用 Cloud SQL Admin API。
- 必须向 Cloud SQL Auth 代理提供 Google Cloud 身份验证凭据。
- 必须向 Cloud SQL Auth 代理提供有效的数据库用户账号和密码。
实例必须具有公共 IPv4 地址，或者配置为使用专用 IP。
该公共 IP 地址无需可供任何外部地址访问（无需添加为已获授权的网络地址）。
下载并安装 Cloud SQL Auth 代理
Linux 64 位
- 下载 Cloud SQL Auth 代理：
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.10.1/cloud-sql-proxy.linux.amd64
- 使 Cloud SQL Auth 代理可执行：
chmod +x cloud-sql-proxy
Linux 32 位
- 下载 Cloud SQL Auth 代理：
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.10.1/cloud-sql-proxy.linux.386
- 如果找不到
curl命令，请运行sudo apt install curl并重复执行下载命令。 - 使 Cloud SQL Auth 代理可执行：
chmod +x cloud-sql-proxy
macOS 64 位
- 下载 Cloud SQL Auth 代理：
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.10.1/cloud-sql-proxy.darwin.amd64
- 使 Cloud SQL Auth 代理可执行：
chmod +x cloud-sql-proxy
Mac M1
- 下载 Cloud SQL Auth 代理：
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.10.1/cloud-sql-proxy.darwin.arm64
- 使 Cloud SQL Auth 代理可执行：
chmod +x cloud-sql-proxy
Windows 64 位
右键点击 https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.10.1/cloud-sql-proxy.x64.exe，然后选择链接另存为以下载 Cloud SQL Auth 代理。将文件重命名为cloud-sql-proxy.exe。Windows 32 位
右键点击 https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.10.1/cloud-sql-proxy.x86.exe，然后选择链接另存为以下载 Cloud SQL Auth 代理。将文件重命名为cloud-sql-proxy.exe。Cloud SQL Auth 代理 Docker 映像
Cloud SQL Auth 代理有不同的容器映像，例如 distroless、alpine 和 buster。默认的 Cloud SQL Auth 代理容器映像使用不包含 shell 的 distroless。如果您需要 shell 或相关工具，请下载基于 alpine 或 buster 的映像。如需了解详情，请参阅 Cloud SQL Auth 代理容器映像。
您可以通过 Docker 使用以下命令将最新映像拉取到本地机器：
docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.10.1
其他操作系统
对于此处未列出的其他操作系统，您可以通过源代码编译 Cloud SQL Auth 代理。Cloud SQL Auth 代理启动选项
启动 Cloud SQL Auth 代理时，您需要向其提供以下信息：
- 与哪些 Cloud SQL 实例建立连接
- 该代理将在何处侦听要从您的应用发送到 Cloud SQL 的数据
- 该代理将在何处查找向 Cloud SQL 验证您的应用时要使用的凭据
- 要使用哪种 IP 地址类型（如果需要）。
您提供的 Cloud SQL Auth 代理启动选项决定了它是侦听 TCP 端口还是侦听 Unix 套接字。如果该代理要侦听 Unix 套接字，则会在您选择的位置（通常为 /cloudsql/ 目录）创建套接字。
对于 TCP，Cloud SQL Auth 代理默认侦听 localhost。
运行带参数 --help 的 cloud-sql-proxy 可执行文件，以查看完整的启动选项列表。
您可在本地环境中的任意位置安装 Cloud SQL Auth 代理。Cloud SQL Auth 代理二进制文件的位置不会影响该代理侦听应用中的数据所使用的位置。
如需详细了解如何启动 Cloud SQL Auth 代理，请参阅启动 Cloud SQL Auth 代理。
使用服务账号进行身份验证
Cloud SQL Auth 代理需要以 Cloud SQL IAM 身份进行身份验证，以授权您连接到 Cloud SQL 实例。
使用服务账号进行身份验证的优势在于，您可以专门为 Cloud SQL Auth 代理创建凭据文件；只要 Cloud SQL Auth 代理处于运行状态，这个文件就会明确、永久地关联到 Cloud SQL Auth 代理。因此，对于未在 Compute Engine 实例上运行的生产实例，建议的方法是使用服务账号。
如果需要从多台机器调用 Cloud SQL Auth 代理，您可在系统映像中复制凭据文件。
要使用此方法，必须创建和管理凭证文件。只有拥有 resourcemanager.projects.setIamPolicy 权限的用户（如项目所有者）才能创建服务账号。如果您的 Google Cloud 用户不具备此权限，则您必须让其他人代为创建服务账号，或使用其他方法来验证 Cloud SQL Auth 代理的身份。
了解如何创建服务账号。
服务账号所需的权限
如果使用服务账号为 Cloud SQL Auth 代理提供凭据，则您必须在创建该服务账号时为其分配足够的权限。如果您要使用更精细的 Identity Access and Management (IAM) 角色来管理 Cloud SQL 权限，则必须向服务账号分配一个具有 cloudsql.instances.connect 权限的角色。以下预定义 Cloud SQL 角色拥有这项权限：
- Cloud SQL Client
- Cloud SQL Editor
- Cloud SQL Admin
如果您要使用传统项目角色（查看者、编辑者、所有者），该服务账号必须至少具有编辑者角色。
用于指定 Cloud SQL 实例的选项
您可以通过多种方式告知 Cloud SQL Auth 代理要连接到哪些实例。一些方式是显式的，一些方式是隐式的。在某些配置中，您无需提前告知 Cloud SQL Auth 代理您要连接到哪些实例，因为 Cloud SQL Auth 代理会根据连接请求进行连接。
实例指定选项由您的操作系统和环境而定：
| 选项 | 优势 | 注意事项和要求 | Linux/macOS （Unix 套接字） |
Java | Windows | 备注 |
|---|---|---|---|---|---|---|
| FUSE （用户空间文件系统） |
可根据连接请求创建动态套接字；实例变化时不需要重启代理。 | 必须安装 FUSE。 | 支持 | 否 | 否 |
使用 --fuse 标志。
|
| 自动实例发现 | 无需指定实例；已在默认项目中为所有实例创建套接字。 | Cloud SQL Auth Proxy API 使用量会增加。必须安装 gcloud CLI 并进行身份验证，然后设置默认项目。必须重启 Cloud SQL Auth 代理才能添加新实例。 | 支持 | 否 | 否 | 不适用于生产实例。 |
| 在 Cloud SQL Auth 代理调用中指定的实例 | 实例列表是已知且静态的。 | 必须重启 Cloud SQL Auth 代理才能添加新实例。 | 支持 | 支持使用 TCP 套接字 | 支持使用 TCP 套接字 | 对于多个实例，请使用不带空格的逗号分隔列表。 了解详情。 |
确保 Cloud SQL Auth 代理为最新版本
Google 会不定期发布新版 Cloud SQL Auth 代理。您可以通过查看 Cloud SQL Auth 代理 GitHub 版本页面，了解当前版本。Google Groups Cloud SQL 公告论坛也会公布未来的代理版本。
API 用量
Cloud SQL Auth 代理会向 Cloud SQL Admin API 发出请求，而这些请求将计入项目的 API 配额。
当您启动 Cloud SQL Auth 代理时，API 用量最高。Cloud SQL Auth 代理运行时，每小时针对每个连接的实例发出两个 API 调用。
关于为 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 如何与用户账号搭配使用，请参阅用户。如需了解 MySQL 用户账号，请参阅 MySQL 文档中的保护初始 MySQL 账号的安全。
Cloud SQL Auth 代理参数和标志
Cloud SQL Auth 代理在启动时会接受多个标记和参数。这些选项决定 Cloud SQL Auth 代理在何处以及如何创建用于与 Cloud SQL 通信的套接字，以及如何进行身份验证。
如需有关 Cloud SQL Auth 代理选项的帮助，请参阅以下信息：
- 用于对 Cloud SQL Auth 代理进行身份验证的选项
- 用于指定 Cloud SQL 实例的选项
- Cloud SQL Auth 代理调用示例
- Cloud SQL Auth 代理 GitHub 页面
- Cloud SQL Auth 代理帮助，显示为
./cloud-sql-proxy --help
如何将 FUSE 与 Cloud SQL Auth 代理搭配使用
FUSE 代表“用户空间文件系统”。 根据 Cloud SQL Auth 代理的调用方式，该代理可以选择使用 FUSE 创建用于连接 Cloud SQL 的套接字。
从 Compute Engine 或本地开发环境进行连接时，Cloud SQL Auth 代理使用 FUSE 访问 Cloud SQL 实例，如下所示：
“/cloudsql”目录会由 Cloud SQL Auth 代理作为用户空间文件系统（即 FUSE）进行装载。
进程（如
mysql）会尝试查询名为 $INSTANCE 的文件。Cloud SQL Auth 代理会拦截请求并返回消息，说明
/cloudsql/$INSTANCE是一种指向位于文件系统其他位置的 Unix 套接字的符号链接。进程（如
mysql）会根据该链接打开其指向和连接的 Unix 套接字。
安装 FUSE
对于 Linux：
FUSE 需要 fusermount 程序和内核模块才能正常运行。您可以通过查找 /dev/fuse/ 文件来检查是否已安装该程序。如果您的系统中没有 fusermount，您可以使用软件包管理器进行安装或使用源代码进行编译。
对于 macOS：
安装 FUSE for macOS。
在生产环境中使用 Cloud SQL Auth 代理
在生产环境中使用 Cloud SQL Auth 代理时，可执行一些步骤确保 Cloud SQL Auth 代理为您的应用提供所需的可用性。
确保 Cloud SQL Auth 代理作为永久性服务运行
如果 Cloud SQL Auth 代理进程停止，则通过 Cloud SQL Auth 代理的所有现有连接都会中断，且您的应用无法再使用 Cloud SQL Auth 代理创建与 Cloud SQL 实例的任何连接。如需避免出现这种情况，请确保 Cloud SQL Auth 代理以永久性服务的形式运行，使 Cloud SQL Auth 代理能在因任何原因退出时自动重启。这可通过使用 systemd、upstart 或 supervisor 之类的服务来实现。对于 Windows 操作系统，将 Cloud SQL Auth 代理作为 Windows 服务运行。通常，请确保 Cloud SQL Auth 代理的正常运行时间要求与应用进程相同。
您的应用需要多少个 Cloud SQL Auth 代理副本
无需为每个应用进程创建代理进程；多个应用进程可共享一个 Cloud SQL Auth 代理进程。针对每个工作站或虚拟机运行一个 Cloud SQL Auth 代理客户端进程。
如果要对虚拟机使用自动扩缩功能，请确保您的虚拟机配置中包含 Cloud SQL Auth 代理，这样一来，每次启动新的虚拟机时，该虚拟机都会有专用的 Cloud SQL Auth 代理进程。
您可以通过限制或整合连接来管理应用所需的连接数。Cloud SQL Auth 代理不对新连接速率或永久连接数设定任何限制。
减少 Cloud SQL Auth 代理输出
如果需要减小 Cloud SQL Auth 代理日志的大小，可在启动 Cloud SQL Auth 代理时设置 --quiet。但请注意，这样做会降低 Cloud SQL Auth 代理输出在诊断连接问题时的有效性。
故障切换如何影响 Cloud SQL Auth 代理
如果在配置为高可用性的实例上运行 Cloud SQL Auth 代理，并且发生了故障切换，则通过 Cloud SQL Auth 代理进行的连接受到的影响与通过 IP 进行的连接相同：所有现有连接都将丢失，并且应用必须建立新连接。但是，这无需人工干预；应用可以继续使用与之前相同的连接字符串。
确保 Cloud SQL Auth 代理 Docker 映像为最新版本
Cloud SQL Auth 代理 Docker 映像基于特定版本的 Cloud SQL Auth 代理。当 Cloud SQL Auth 代理推出新版本时，请拉取 Cloud SQL Auth 代理 Docker 映像的新版本，以使您的环境保持最新状态。您可以通过查看 Cloud SQL Auth 代理 GitHub 版本页面，了解 Cloud SQL Auth 代理的当前版本。
如何强制使用 Cloud SQL Auth 代理
您可以使用 ConnectorEnforcement 强制在 Cloud SQL 实例连接中使用 Cloud SQL Auth 代理。强制使用连接器后，直接数据库连接会被拒绝。
如需强制使用连接器，请使用 instances API 中的 ConnectorEnforcement 字段。
如需了解详情，请参阅修改实例。
Cloud SQL 代理 Operator 简介
Cloud SQL 代理 Operator 是一个开源 Kubernetes Operator，可自动将 GKE 集群中的工作负载连接到 Cloud SQL 数据库。Cloud SQL Auth 代理 Operator 利用自定义资源 AuthProxyWorkload，用于指定特定工作负载的 Cloud SQL Auth 代理配置。Cloud SQL Auth 代理 Operator 会读取此资源，并将具有所需配置的 Cloud SQL Auth 代理容器添加到相应的工作负载。
在 GKE 集群中安装该 Operator 并配置工作负载和 Cloud SQL 实例后，Cloud SQL Auth 代理 Operator 会自动配置 Cloud SQL Auth 代理并将 GKE 工作负载连接到 Cloud SQL 实例。
Cloud SQL Auth 代理 Operator 还会检查 Cloud SQL Auth 代理的状态。如果 Cloud SQL Auth 代理无法连接，Cloud SQL Auth 代理 Operator 会输出调试信息，并为您提供排查和修复常见配置问题的指导。
如需了解详情，请参阅使用 Cloud SQL Proxy Operator 连接。