使用 Cloud SQL Auth 代理进行连接

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

如需了解如何使用公共 IP 地址将 sqlcmd 客户端连接到 Cloud SQL 实例,请参阅使用数据库客户端进行连接

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

准备工作

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

  1. 启用 Cloud SQL for SQL Server API。

    启用 API

  2. 创建一个 Cloud SQL 实例,包括配置默认用户。

    如需详细了解实例的创建,请参阅创建实例

    如需详细了解如何配置默认用户,请参阅配置默认用户帐号

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

用于对 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
      

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

    如需详细了解 Cloud SQL 支持的角色,请参阅 Cloud SQL 的项目访问权限控制

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

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

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

    如果您已安装 Cloud 命令行工具并使用您的个人帐号进行了身份验证,则 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. 确认密钥类型是 JSON,然后点击创建

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

下载并安装 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. 使 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
    

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.19.1

其他操作系统

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

启动 Cloud SQL Auth 代理

您可以使用 TCP 套接字或 Cloud SQL Auth 代理 Docker 映像启动 Cloud SQL Auth 代理。Cloud SQL Auth 代理二进制文件连接到命令行中指定的一个或多个 Cloud SQL 实例,并打开本地连接作为 TCP 套接字。其他应用和服务(例如您的应用代码或数据库管理客户端工具)可以通过“该 TCP 套接字连接”连接到 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:1433
      
      指定的端口必须尚未被本地数据库服务器等所占用。
    • 使用服务帐号并明确包含实例连接的名称(建议用于生产环境):
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAM=tcp:1433 \
                        -credential_file=PATH_TO_KEY_FILE &
      

    如需详细了解 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:1433:1433 \\
  gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \\
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1433 -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.19.1 /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 代理参数

其他命令行参数

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

./cloud_sql_proxy -help

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

连接到 Cloud SQL Auth 代理

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

TCP 套接字

  1. 启动 sqlcmd 客户端:
    sqlcmd -S tcp:127.0.0.1,1433 -U USERNAME -P PASSWORD
    

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

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

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

特定于语言的代码示例

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

使用 TCP 进行连接

Cloud SQL Auth 代理调用语句:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:1433 &

Python

如需了解 Web 应用环境下的此代码段,请查看 GitHub 上的 README

# Remember - storing secrets in plaintext is potentially unsafe. Consider using
# something like https://cloud.google.com/secret-manager/docs/overview to help keep
# secrets secret.
db_user = os.environ["DB_USER"]
db_pass = os.environ["DB_PASS"]
db_name = os.environ["DB_NAME"]
db_host = os.environ["DB_HOST"]

# Extract host and port from environment variable DB_HOST
host_args = db_host.split(":")
db_hostname, db_port = host_args[0], int(host_args[1])

# SQL Server drivers don't account for this
if db_hostname == "localhost":
    db_hostname = "127.0.0.1"

# The SQLAlchemy engine will help manage interactions, including automatically
# managing a pool of connections to your database
pool = sqlalchemy.create_engine(
    # Equivalent URL:
    # mssql+pytds://<db_user>:<db_pass>@/<host>:<port>/<db_name>?driver=ODBC+Driver+17+for+SQL+Server
    sqlalchemy.engine.url.URL.create(
        "mssql+pytds",
        username=db_user,
        password=db_pass,
        database=db_name,
        host=db_hostname,
        port=db_port,
    ),
    **db_config
)

Java

如需了解 Web 应用环境下的此代码段,请查看 GitHub 上的 README

注意:

  • CLOUD_SQL_CONNECTION_NAME 应表示为 <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
  • 使用参数 ipTypes=PRIVATE 将强制 SocketFactory 与实例的关联专用 IP 连接
  • 如需查看 pom.xml 文件的 JDBC 套接字工厂版本的要求,请点击此处

// Note: For Java users, the Cloud SQL JDBC Socket Factory can provide authenticated connections
// which is preferred to using the Cloud SQL Proxy with Unix sockets.
// See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.

// The configuration object specifies behaviors for the connection pool.
HikariConfig config = new HikariConfig();

// The following is equivalent to setting the config options below:
// jdbc:sqlserver://;user=<DB_USER>;password=<DB_PASS>;databaseName=<DB_NAME>;
// socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;
// socketFactoryConstructorArg=<CLOUD_SQL_CONNECTION_NAME>

// See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
// https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

// Configure which instance and what database user to connect with.
config
    .setDataSourceClassName("com.microsoft.sqlserver.jdbc.SQLServerDataSource");
config.setUsername(DB_USER); // e.g. "root", "sqlserver"
config.setPassword(DB_PASS); // e.g. "my-password"
config.addDataSourceProperty("databaseName", DB_NAME);

config.addDataSourceProperty("socketFactoryClass",
    "com.google.cloud.sql.sqlserver.SocketFactory");
config.addDataSourceProperty("socketFactoryConstructorArg", CLOUD_SQL_CONNECTION_NAME);

// ... Specify additional connection properties here.

// ...

// Initialize the connection pool using the configuration object.
DataSource pool = new HikariDataSource(config);

Node.js

如需了解 Web 应用环境下的此代码段,请查看 GitHub 上的 README

const createPool = async () => {
  const config = {pool: {}, options: {}};
  config.user = process.env.DB_USER; // e.g. 'my-db-user'
  config.password = process.env.DB_PASS; // e.g. 'my-db-password'
  config.database = process.env.DB_NAME; // e.g. 'my-database'
  // set the server to '172.17.0.1' when connecting from App Engine Flex
  config.server = process.env.DEPLOYED ? '172.17.0.1' : '127.0.0.1';
  config.port = 1433;

  // ...
  config.options.trustServerCertificate = true;
  return await mssql.connect(config);
};

Go

如需了解 Web 应用环境下的此代码段,请查看 GitHub 上的 README

var (
	dbUser    = mustGetenv("DB_USER") // e.g. 'my-db-user'
	dbPwd     = mustGetenv("DB_PASS") // e.g. 'my-db-password'
	dbTCPHost = mustGetenv("DB_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
	dbPort    = mustGetenv("DB_PORT") // e.g. '1433'
	dbName    = mustGetenv("DB_NAME") // e.g. 'my-database'
)

var dbURI string
dbURI = fmt.Sprintf("server=%s;user id=%s;password=%s;port=%s;database=%s;", dbTCPHost, dbUser, dbPwd, dbPort, dbName)

// dbPool is the pool of database connections.
dbPool, err := sql.Open("mssql", dbURI)
if err != nil {
	return nil, fmt.Errorf("sql.Open: %v", err)
}

// ...

return dbPool, nil

C#

如需了解 Web 应用环境下的此代码段,请查看 GitHub 上的 README

            // Equivalent connection string:
            // "User Id=<DB_USER>;Password=<DB_PASS>;Server=<DB_HOST>;Database=<DB_NAME>;"
            var connectionString = new SqlConnectionStringBuilder()
            {
                // Remember - storing secrets in plain text is potentially unsafe. Consider using
                // something like https://cloud.google.com/secret-manager/docs/overview to help keep
                // secrets secret.
                DataSource = Environment.GetEnvironmentVariable("DB_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                UserID = Environment.GetEnvironmentVariable("DB_USER"),         // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"),       // e.g. 'my-db-password'
                InitialCatalog = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance
                Encrypt = false,
            };
            connectionString.Pooling = true;
            // ...
            return connectionString;

Ruby

如需了解 Web 应用环境下的此代码段,请查看 GitHub 上的 README

development:
  adapter: sqlserver
  # Configure additional properties here.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 1433 }%> 

PHP

如需了解 Web 应用环境下的此代码段,请查看 GitHub 上的 README

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

// Connect using TCP
$dsn = sprintf('sqlsrv:server=%s;Database=%s', $dbHost, $dbName);

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);

其他主题

将 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 代理。

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.19.1

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

TCP 套接字

    docker run -d \
      -v PATH_TO_KEY_FILE:/config \
      -p 127.0.0.1:1433:1433 \
      gcr.io/cloudsql-docker/gce-proxy:1.19.1 /cloud_sql_proxy \
      -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1433 \
      -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.19.1 /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 文档

需要 SSL 时连接

Cloud SQL Auth 代理的使用提示

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

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

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:1433,myProject:us-central1:myInstance2=tcp:1234

    # Connect to "myInstance" using port 1433 on your machine:
    sqlcmd -U myUser -S "127.0.0.1,1433"

    # Connect to "myInstance2" using port 1234 on your machine:
    sqlcmd -U myUser -S "127.0.0.1,1234"
  

排查 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 代理的终端。

  • 如果您收到 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 的操作 > 日志记录 > 日志浏览器部分下查看日志,确认 Cloud SQL 身份验证代理已正确启动。操作成功如下所示:

    2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/1433 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 配额。如果配额错误在启动时显示,您必须重新部署应用以重启代理。如果配额错误在启动后出现,则无需重新部署。

后续步骤