从计算引擎连接

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

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

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

准备工作

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

专用 IP

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

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

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

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

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

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

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

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

Debian/Ubuntu

通过软件包管理器安装 psql 客户端：

sudo apt-get update
sudo apt-get install postgresql-client

CentOS/RHEL

通过软件包管理器安装 psql 客户端：

sudo yum install postgresql

openSUSE

通过软件包管理器安装 psql 客户端：

sudo zypper install postgresql

其他平台

  1. 从 PostgreSQL 下载页面下载适用于您的平台的 PostgreSQL 核心发行版。
    核心发行版包含 psql 客户端。
  2. 按照下载页面上的说明安装 PostgreSQL 数据库。

4.连接 psql 客户端。

psql -h CLOUD_SQL_PRIVATE_IP_ADDRESS -U USERNAME

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

gcloud sql instances list

公共 IP

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

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

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

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

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

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

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

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

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

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

Debian/Ubuntu

通过软件包管理器安装 psql 客户端：

sudo apt-get update
sudo apt-get install postgresql-client

CentOS/RHEL

通过软件包管理器安装 psql 客户端：

sudo yum install postgresql

openSUSE

通过软件包管理器安装 psql 客户端：

sudo zypper install postgresql

其他平台

  1. 从 PostgreSQL 下载页面下载适用于您的平台的 PostgreSQL 核心发行版。
    核心发行版包含 psql 客户端。
  2. 按照下载页面上的说明安装 PostgreSQL 数据库。

5. 连接 psql 客户端。

psql -h CLOUD_SQL_PUBLIC_IP_ADDR -U USERNAME

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

gcloud sql instances list

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

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

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

设置 TCP keepalive。

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

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

Cloud SQL Auth 代理

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

1. 启用 Cloud SQL Admin API。

Enable the API

2.创建服务账号。

  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

  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 实例的终端连接。

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

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

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

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

Debian/Ubuntu

通过软件包管理器安装 psql 客户端：

sudo apt-get update
sudo apt-get install postgresql-client

CentOS/RHEL

通过软件包管理器安装 psql 客户端：

sudo yum install postgresql

openSUSE

通过软件包管理器安装 psql 客户端：

sudo zypper install postgresql

其他平台

  1. 从 PostgreSQL 下载页面下载适用于您的平台的 PostgreSQL 核心发行版。
    核心发行版包含 psql 客户端。
  2. 按照下载页面上的说明安装 PostgreSQL 数据库。

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.3/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.3/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.3/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.3/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.3

其他操作系统

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

6. 启动 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)。因此，当您为实例指定 --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 5432 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 代理可以监听 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 代理调用字符串如下所示：

    • 使用服务账号并明确包含实例连接的名称（建议用于生产环境）：
      ./cloud-sql-proxy --unix-socket /cloudsql
--credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
    • 使用 Cloud SDK 身份验证和自动实例发现： 
      ./cloud-sql-proxy --unix-socket /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 控制台中的实例概览页面上或者通过运行以下命令找到 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:/path/to/service-account-key.json \\
  -p 127.0.0.1:5432:5432 \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.3 \\
  --address 0.0.0.0 --port 5432 \\
  --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.3 --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. 启动 psql 会话。

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

TCP 套接字

  1. 启动 psql 客户端：
    psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"

    即使 sslmode 参数设置为 disable，Cloud SQL Auth 代理也会提供加密连接。

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

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

使用 Unix 套接字

  1. 启动 psql 客户端：
    psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"

    即使 sslmode 参数设置为 disable，Cloud SQL Auth 代理也会提供加密连接。

  2. 输入密码。
  3. 系统会显示 psql 提示符。

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

后续步骤