从计算引擎连接

MySQL   |  PostgreSQL   |  SQL Server

本页面介绍如何使用安装在 Compute Engine 实例上的 mysql 客户端连接到 Cloud SQL。

您可以使用专用 IP、公共 IP、Cloud SQL Auth 代理或 Cloud SQL Auth 代理 Docker 映像。

如需了解运行连接到 Cloud SQL 的 Compute Engine 示例 Web 应用的分步说明，请参阅从 Compute Engine 连接快速入门。

准备工作

此任务不包括有关设置 Compute Engine 实例的说明。如果您在创建和配置 Compute Engine 实例方面需要帮助，请参阅 Compute Engine 文档。

确保您的 Compute Engine 虚拟机具有正确的 scope，以便使用 Cloud SQL Admin API 进行连接。

将服务账号配置为以下任一访问权限范围：

• https://www.googleapis.com/auth/sqlservice.admin
• https://www.googleapis.com/auth/cloud-platform

专用 IP

要使用专用 IP 从某个 Compute Engine 实例连接到 Cloud SQL，您必须为您的环境设置专用服务访问通道，并且必须将 Cloud SQL 实例配置为使用专用 IP。您的 Compute Engine 实例必须与 Cloud SQL 实例位于同一区域中，并且必须位于为专用连接配置的网络上。了解详情。

1.将您的实例配置为使用专用 IP

按照配置专用 IP 连接中的说明进行操作。

2.打开连接到 Compute Engine 实例的 Cloud Shell 终端。

根据实例的操作系统，使用相应的说明：

• 对于 Linux，请参阅连接到 Linux 虚拟机。
• 对于 Windows，请参阅连接到 Windows 虚拟机。

如果您的 Compute Engine 实例正在运行 RHEL 或 CentOS 公开映像，则 SELinux 可能会阻止代理连接。如果发生这种情况，必须配置 SELinux 功能以允许连接。

如需详细了解用于 RHEL 的 SELinux，请参阅 RHEL 文档。 如需详细了解用于 CentOS 的 SELinux，请参阅 CentOS 文档。

3.如果尚未安装 mysql 客户端，请将其安装到 Compute Engine 实例上。

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

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

4.使用 mysql 客户端建立连接。

mysql -h CLOUD_SQL_PRIVATE_IP_ADDRESS -u USERNAME -p

您可以在 Cloud SQL 实例页面上找到专用 IP 地址，也可以运行以下 gcloud 命令：

gcloud sql instances list

公共 IP

如需使用公共 IP 进行连接，请执行以下操作：

---

如需在 Cloud Shell Editor 中直接遵循有关此任务的分步指导，请点击操作演示：

操作演示

---

1. 如果 Compute Engine 实例还没有静态 IPv4 IP 地址，请为其添加一个。

您无法使用 IPv6 连接到 Compute Engine。如需详细了解如何添加静态 IP 地址，请参阅 Compute Engine 文档中的预留新的静态外部 IP 地址。

2.将 Compute Engine 实例的静态 IP 地址授权为可连接到 Cloud SQL 实例的网络。

如需了解详情，请参阅为公共 IP 连接配置访问权限。

注意：只为静态 IP 地址授权。临时 IP 地址是暂时的；为这些地址授予访问实例的权限会带来安全风险，因为它们随后可能会被重新分配给其他 Compute Engine 用户。

3.打开连接到 Compute Engine 实例的 Cloud Shell 终端。

根据实例的操作系统，使用相应的说明：

• 对于 Linux，请参阅连接到 Linux 虚拟机。
• 对于 Windows，请参阅连接到 Windows 虚拟机。

如果您的 Compute Engine 实例正在运行 RHEL 或 CentOS 公开映像，则 SELinux 可能会阻止代理连接。如果发生这种情况，必须配置 SELinux 功能以允许连接。

如需详细了解用于 RHEL 的 SELinux，请参阅 RHEL 文档。 如需详细了解用于 CentOS 的 SELinux，请参阅 CentOS 文档。

4.如果尚未安装 mysql 客户端，请将其安装到 Compute Engine 实例上。

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

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

5. 使用 mysql 客户端建立连接。

mysql -h CLOUD_SQL_PUBLIC_IP_ADDR -u USERNAME -p

您可以在 Cloud SQL 实例页面上找到公共 IP 地址，也可以运行以下 gcloud 命令：

gcloud sql instances list

如需查看有关如何使用 SSL 进行连接的示例，请参阅通过 SSL 连接。

6.系统会显示 mysql 提示符。

7. 如果您需要使未使用的连接保持活跃状态，请执行以下操作：

设置 TCP keepalive。

如需了解详情，请参阅 Compute Engine 文档中的在实例和互联网之间通信。

对于实例，连接会自动保持活跃状态。

Cloud SQL Auth 代理

如需在 Compute Engine 中使用 Cloud SQL Auth 代理进行连接，请执行以下操作：

1. 启用 Cloud SQL Admin API。

Enable the API

2.创建服务账号。

注意：如果 Compute Engine 实例具有完整 API 访问权限或 Cloud SQL Admin API 范围，您可以跳过此步骤；启动 Cloud SQL Auth 代理时无需提供证书文件。

如果您要从 Compute Engine 连接，请确保虚拟机具有正确的 scope，以便使用 Cloud SQL Admin API 进行连接。

将服务账号配置为具有以下任一访问权限范围：

• https://www.googleapis.com/auth/sqlservice.admin
• https://www.googleapis.com/auth/cloud-platform

1. 在 Google Cloud 控制台中，转到服务账号页面。

   转到“服务账号”

2. 选择包含您的 Cloud SQL 实例的项目。
3. 点击创建服务账号。
4. 在服务账号名称字段中输入服务账号的描述性名称。
5. 将服务账号 ID 更改为一个不重复且易于识别的值，然后点击创建并继续。
6. 点击选择角色字段，然后选择以下角色之一：
   • Cloud SQL > Cloud SQL Client
   • Cloud SQL > Cloud SQL Editor
   • Cloud SQL > Cloud SQL Admin
   注意：如需创建具有所需权限的服务账号，您必须拥有 resourcemanager.projects.setIamPolicy 权限。Project Owner、Project IAM Admin 和 Organization Administrator 角色均拥有这项权限。
   此外，您还必须启用 Cloud SQL Admin API。如果您要使用旧版项目角色（Viewer、Editor、Owner），则该服务账号必须至少具有 Editor 角色。
7. 点击完成以完成服务账号的创建过程。
8. 点击新服务账号的操作菜单，然后选择管理密钥。
9. 点击添加键下拉菜单，然后点击创建新密钥。
10. 确认密钥类型是 JSON，然后点击创建。

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

如果 Compute Engine 实例与 Cloud SQL 实例在不同的项目中，请确保其服务账号在包含 Cloud SQL 实例的项目中拥有适当的权限：

1. 转到 Google Cloud 控制台中的 Compute Engine 实例列表。

   转到 Compute Engine 实例列表

2. 如有必要，请选择与 Compute Engine 实例关联的项目。
3. 选择 Compute Engine 实例，显示其属性。
4. 在 Compute Engine 实例属性中，复制服务账号的名称。
5. 转到 Google Cloud 控制台中的 IAM 和管理项目页面。

   转到“IAM 和管理项目”页面

6. 选择包含 Cloud SQL 实例的项目。
7. 搜索服务账号名称。

8. 如果服务账号已存在，且该账号拥有一个包含 cloudsql.instances.connect 权限的角色，则您可以前进至第 4 步。

   Cloud SQL Client、Cloud SQL Editor 和 Cloud SQL Admin 角色均提供必要的权限，就像旧版 Editor 和 Owner 项目角色一样。

9. 否则，请点击添加以添加服务账号。

10. 在添加主账号对话框中，提供服务账号的名称，然后选择一个包含 cloudsql.instances.connect 权限的角色（除 Viewer 之外的任何 Cloud SQL 预定义角色均可）。

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

    如果您看不到这些角色，则表明您的 Google Cloud 用户可能没有 resourcemanager.projects.setIamPolicy 权限。您可以通过转到 Google Cloud 控制台中的 IAM 页面并搜索您的用户 ID 来检查权限。

11. 点击 Add（添加）。

    现在，您将看到拥有指定角色的服务账号。

3.打开连接到 Compute Engine 实例的终端连接。

根据实例的操作系统，使用相应的说明：

• 对于 Linux，请参阅连接到 Linux 实例。
• 对于 Windows，请参阅连接到 Windows 实例。

如果您的 Compute Engine 实例正在运行 RHEL 或 CentOS 公开映像，则 SELinux 可能会阻止代理连接。如果发生这种情况，必须配置 SELinux 功能以允许连接。

如需详细了解用于 RHEL 的 SELinux，请参阅 RHEL 文档。 如需详细了解用于 CentOS 的 SELinux，请参阅 CentOS 文档。

4.如果尚未安装 mysql 客户端，请将其安装到 Compute Engine 实例上。

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

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

5. 在 Compute Engine 实例上安装 Cloud SQL Auth 代理。

Linux 64 位

1. 下载 Cloud SQL Auth 代理：

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.4/cloud-sql-proxy.linux.amd64
   

2. 使 Cloud SQL Auth 代理可执行：

   chmod +x cloud-sql-proxy
   

Linux 32 位

1. 下载 Cloud SQL Auth 代理：

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.4/cloud-sql-proxy.linux.386
   

2. 如果找不到 curl 命令，请运行 sudo apt install curl 并重复执行下载命令。
3. 使 Cloud SQL Auth 代理可执行：

   chmod +x cloud-sql-proxy
   

Windows 64 位

右键点击 https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.4/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.11.4/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.11.4

注意：Cloud SQL Auth 代理使用支持 gcr.io 网域但从 Artifact Registry 传送映像的仓库。如需了解详情，请参阅从 Container Registry 转换。

其他操作系统

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

6. 启动 Cloud SQL Auth 代理。

注意：如果 Compute Engine 实例具有完整 API 访问权限或 Cloud SQL Admin API 范围，则启动 Cloud SQL Auth 代理时无需提供证书文件。

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

警告：将 Cloud SQL 身份验证代理绑定到外部接口时，请务必小心谨慎。任何有权访问该接口/端口的用户都将有权连接到您的实例。

TCP 套接字

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

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

./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME

1. 复制您的 INSTANCE_CONNECTION_NAME。您可以在 Google Cloud 控制台中的实例概览页面上或者通过运行以下命令找到它：

       gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'

   例如：myproject:myregion:myinstance。

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

   --private-ip

3. 如果您要使用服务账号对 Cloud SQL Auth 代理进行身份验证，请记下随服务账号一起创建的私钥文件在客户端机器上的位置。
4. 启动 Cloud SQL Auth 代理。

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

   • 使用 Cloud SDK 身份验证：

     ./cloud-sql-proxy --port 3306 INSTANCE_CONNECTION_NAME
     

     指定的端口必须尚未被本地数据库服务器等所占用。
   • 使用服务账号并明确包含实例连接的名称（建议用于生产环境）：

     ./cloud-sql-proxy \
     --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
     
     

   如需详细了解 Cloud SQL Auth 代理选项，请参阅用于对 Cloud SQL Auth 代理进行身份验证的选项。

Unix 套接字

注意：Cloud SQL Auth 代理目前不支持 Windows 上的 Unix 套接字，因此此选项仅适用于 Linux 和 macOS 平台。

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

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

1. 复制您的 INSTANCE_CONNECTION_NAME。您可以在 Google Cloud 控制台中的实例概览页面上或者通过运行以下命令找到它：

       gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'

   例如：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 代理调用字符串如下所示：

   • 使用 Google Cloud SDK 身份验证：

     ./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &

   • 使用服务账号：

       ./cloud-sql-proxy --unix-socket /cloudsql
       --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &

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

   如需详细了解 Cloud SQL Auth 代理选项，请参阅用于对 Cloud SQL Auth 代理进行身份验证的选项。

   注意：使用 Cloud SQL Auth 代理和 unix 套接字连接到 Cloud SQL 时，请确保套接字文件名的长度不超过系统限制。一般来说，套接字文件名包含 91 到 108 个字符，具体取决于您所用的系统。在 Linux 上，该文件名长度通常定义为 108 个字符；您可以使用以下命令进行检查：

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

Docker

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

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

gcloud sql instances describe INSTANCE_NAME

.

例如：myproject:myregion:myinstance。

注意：在 Windows 上，Cloud SQL Auth 代理不支持监听 Unix 网域套接字。

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

使用 TCP 套接字

docker run -d \\
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\
  -p 127.0.0.1:3306:3306 \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.4 \\
  --address 0.0.0.0 --port 3306 \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

如果您使用的是 Compute Engine 实例提供的凭据，请勿包含 --credentials-file 参数和 -v PATH_TO_KEY_FILE:/path/to/service-account-key.json 行。

请务必在 -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:/path/to/service-account-key.json \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.4 --unix-socket=/cloudsql \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

如果您使用的是 Compute Engine 实例提供的凭据，请勿包含 --credentials-file 参数和 -v PATH_TO_KEY_FILE:/path/to/service-account-key.json 行。

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

-v /mnt/stateful_partition/cloudsql:/cloudsql

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

7. 启动 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 支持页面。

后续步骤

• 获得 Cloud SQL Auth 代理连接问题排查方面的帮助。
• 创建用户和数据库。
• 详细了解专用 IP。
• 了解从应用连接到实例的选项。
• 了解 mysql 客户端。
• 了解其他 MySQL 管理工具。
• 了解支持选项。