使用 Cloud SQL 驗證 Proxy 連線

MySQL   |  PostgreSQL   |  SQL Server

本頁說明如何使用 Cloud SQL Auth Proxy 連線至 Cloud SQL 執行個體。

如要進一步瞭解 Cloud SQL 驗證 Proxy 的運作方式，請參閱關於 Cloud SQL 驗證 Proxy 一文。

總覽

建議使用 Cloud SQL Auth Proxy 連線至 Cloud SQL 執行個體。Cloud SQL 驗證 Proxy：

• 適用於公開和私人 IP 端點
• 使用使用者或服務帳戶的憑證驗證連線
• 將連線包裝在 SSL/TLS 層中，並授權給 Cloud SQL 執行個體

部分 Google Cloud 服務和應用程式會使用 Cloud SQL Auth Proxy，透過加密和授權提供公開 IP 路徑的連線，包括：

• App Engine 標準環境
• App Engine 彈性環境
• Cloud Run

在 Google Kubernetes Engine 中執行的應用程式可以使用 Cloud SQL 驗證 Proxy 連線。

注意： 如要從 Google Kubernetes Engine 連線，建議您以 sidecar 模式執行 Cloud SQL Auth Proxy，做為與應用程式共用 Pod 的 額外容器。另請參閱相關的 快速入門導覽課程。

如需基本使用簡介，請參閱使用 Cloud SQL 驗證 Proxy 快速入門導覽課程。

您也可以使用 sqlcmd 用戶端，從本機電腦或 Compute Engine 連線至執行個體，無論是否使用 Cloud SQL 驗證 Proxy 都可以。

事前準備

連線至 Cloud SQL 執行個體前，請先完成下列步驟：

1. • 如果是使用者或服務帳戶，請確認帳戶具備 Cloud SQL 用戶端角色。這個角色包含 cloudsql.instances.connect 權限，可授權主體連線至專案中的所有 Cloud SQL 執行個體。

     前往「IAM」頁面

   • 您也可以在 IAM 政策繫結中加入 IAM 條件，只允許帳戶連線至一個特定的 Cloud SQL 執行個體。

2. Enable the Cloud SQL Admin API.

   Enable the API

3. 安裝並初始化 gcloud CLI。
4. (選用步驟) 安裝 Cloud SQL 驗證 Proxy Docker 用戶端。

下載 Cloud SQL 驗證 Proxy

Linux 64 位元

1. 下載 Cloud SQL 驗證 Proxy：

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

2. 將 Cloud SQL 驗證 Proxy 設為允許執行：

   chmod +x cloud-sql-proxy

Linux 32 位元

1. 下載 Cloud SQL 驗證 Proxy：

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

2. 如果找不到 curl 指令，請執行 sudo apt install curl，然後重複下載指令。
3. 將 Cloud SQL 驗證 Proxy 設為允許執行：

   chmod +x cloud-sql-proxy

macOS 64 位元

1. 下載 Cloud SQL 驗證 Proxy：

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

2. 將 Cloud SQL 驗證 Proxy 設為允許執行：

   chmod +x cloud-sql-proxy

Mac M1

1. 下載 Cloud SQL 驗證 Proxy：

     curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.17.1/cloud-sql-proxy.darwin.arm64
     

2. 將 Cloud SQL 驗證 Proxy 設為允許執行：

     chmod +x cloud-sql-proxy
     

Windows 64 位元

在 https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.17.1/cloud-sql-proxy.x64.exe 上按一下滑鼠右鍵，然後選取「另存連結為」來下載 Cloud SQL Auth Proxy。將檔案重新命名為 cloud-sql-proxy.exe。

Windows 32 位元

在 https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.17.1/cloud-sql-proxy.x86.exe 上按一下滑鼠右鍵，然後選取「另存連結為」來下載 Cloud SQL Auth Proxy。將檔案重新命名為 cloud-sql-proxy.exe。

Cloud SQL 驗證 Proxy Docker 映像檔

Cloud SQL 驗證 Proxy 有不同的容器映像檔，例如 distroless、alpine 和 buster。預設的 Cloud SQL 驗證 Proxy 容器映像檔使用 distroless，其中不含任何殼層。如需 Shell 或相關工具，請根據 alpine 或 buster 下載映像檔。 詳情請參閱「Cloud SQL Auth Proxy 容器映像檔」。

您可以使用 Docker 執行下列指令，將最新映像檔提取至本機電腦：

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.17.1

注意：Cloud SQL Auth Proxy 使用支援 gcr.io 網域的存放區，但會從 Artifact Registry 提供映像檔。詳情請參閱「從 Container Registry 轉換」。

其他 OS

如果您的作業系統不在上述說明內，可以從原始碼編譯 Cloud SQL 驗證 Proxy。

啟動 Cloud SQL 驗證 Proxy

您可以使用 TCP Socket 或 Cloud SQL 驗證 Proxy Docker 映像檔啟動 Cloud SQL 驗證 Proxy。Cloud SQL 驗證 Proxy 二進位檔會連線至命令列上指定的一或多個 Cloud SQL 執行個體，並以 TCP 通訊端的形式開啟本機連線。其他應用程式和服務 (例如應用程式程式碼或資料庫管理用戶端工具) 可以透過該 TCP Socket 連線連線至 Cloud SQL 執行個體。

警告：將 Cloud SQL 驗證 Proxy 繫結至外部介面時，請務必謹慎。只要能存取該介面/連接埠，就能連線至執行個體。

TCP 通訊端

如果是 TCP 連線，Cloud SQL 驗證 Proxy 預設會監聽 localhost(127.0.0.1)。因此，當您為執行個體指定 --port PORT_NUMBER 時，本機連線會位於 127.0.0.1:PORT_NUMBER。

或者，您也可以為本機連線指定其他位址。 舉例來說，以下說明如何讓 Cloud SQL 驗證 Proxy 在 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，而您想讓 Cloud SQL Auth Proxy 使用私人 IP 位址，則必須在啟動 Cloud SQL Auth Proxy 時提供下列選項：

   --private-ip

3. 如果您使用服務帳戶來驗證 Cloud SQL Auth Proxy，請記下您之前建立服務帳戶時，私密金鑰檔案在用戶端機器上的建立位置。
4. 啟動 Cloud SQL 驗證 Proxy。

   以下是幾個可能的 Cloud SQL 驗證 Proxy 叫用字串：

   • 使用 Cloud SDK 驗證：

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

     請勿指定使用中的通訊埠，例如本機資料庫伺服器正在使用的通訊埠。
   • 使用服務帳戶並明確納入執行個體連線的名稱 (建議用於實際工作環境)：

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

   如要進一步瞭解 Cloud SQL 驗證 Proxy 選項，請參閱驗證 Cloud SQL 驗證 Proxy 的選項。

Docker

如要在 Docker 容器中執行 Cloud SQL 驗證 Proxy，請使用 Google Container Registry 提供的 Cloud SQL 驗證 Proxy Docker 映像檔。

您可以使用 TCP 通訊端或 Unix 通訊端啟動 Cloud SQL Auth Proxy，方法如下列指令所示。這些選項會使用 INSTANCE_CONNECTION_NAME 做為連線字串，識別 Cloud SQL 執行個體。您可以在 Google Cloud console 中，前往執行個體的「Overview」(總覽) 頁面找到 INSTANCE_CONNECTION_NAME，或執行下列指令：

gcloud sql instances describe INSTANCE_NAME

。

例如 myproject:myregion:myinstance。

注意：Cloud SQL 驗證 Proxy 不支援在 Windows 上接聽 Unix 網域通訊端。

根據您的語言與環境，您可以使用 TCP 通訊端或 Unix 通訊端啟動 Cloud SQL Auth Proxy。以 Java 程式設計語言編寫的應用程式或 Windows 環境都不支援 Unix 通訊端。

使用 TCP 通訊端

docker run -d \\
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\
  -p 127.0.0.1:1433:1433 \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.17.1 \\
  --address 0.0.0.0 --port 1433 \\
  --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 驗證 Proxy 暴露到本機主機之外。執行個體參數中必須要有「0.0.0.0」，才能讓 Docker 容器以外的環境存取連接埠。

使用 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.17.1 --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 驗證 Proxy 參數。

連線至 sqlcmd 用戶端

Debian/Ubuntu

如果是 Debian/Ubuntu，請 安裝適用的 SQL Server 指令列工具。

CentOS/RHEL

如果是 CentOS/RHEL，請 安裝適用的 SQL Server 指令列工具。

openSUSE

如果是 openSUSE，請 安裝適用的 SQL Server 指令列工具。

其他平台

如要安裝 SQL Server，請參閱 登陸頁面，以及 SQL Server 下載頁面。

使用的連線字串取決於您是使用 TCP 通訊端還是 Docker 啟動 Cloud SQL Auth Proxy。

TCP 通訊端

1. 啟動 sqlcmd 用戶端：

   sqlcmd -S tcp:127.0.0.1,1433 -U USERNAME -P PASSWORD

   使用 TCP Socket 連線時，系統會透過 127.0.0.1存取 Cloud SQL 驗證 Proxy。

2. 系統顯示提示時，請輸入密碼。
3. 系統隨即會顯示 sqlcmd 提示。

需要協助嗎？如需針對 Proxy 進行疑難排解，請參閱「排解 Cloud SQL 驗證 Proxy 連線問題」，或前往 Cloud SQL 支援頁面。

連結至應用程式

任何可讓您連線至 TCP 通訊端的程式語言，都能用來連線至 Cloud SQL 驗證 Proxy。以下是 GitHub 完整範例中的一些程式碼片段，可協助您瞭解它們如何在應用程式中搭配運作。

透過 TCP 連線

Cloud SQL 驗證 Proxy 叫用陳述式：

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

如要查看網頁應用程式中的程式碼片段，請參閱 GitHub 上的 README。

import os

import sqlalchemy


def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of SQL Server."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_host = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 1433

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # mssql+pytds://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="mssql+pytds",
            username=db_user,
            password=db_pass,
            database=db_name,
            host=db_host,
            port=db_port,
        ),
        # ...
    )

    return pool

Java

如要查看網頁應用程式中的程式碼片段，請參閱 GitHub 上的 README。

注意：

• CLOUD_SQL_CONNECTION_NAME 應表示為 <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
• 使用 ipTypes=PRIVATE 引數會強制 SocketFactory 連線至執行個體相關聯的私人 IP
• 請參閱 pom.xml 檔案的 JDBC 通訊端處理站版本規定。

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(
        String.format("jdbc:sqlserver://%s:%s;databaseName=%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "sqlserver"
    config.setPassword(DB_PASS); // e.g. "my-password"


    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

如要查看網頁應用程式中的程式碼片段，請參閱 GitHub 上的 README。

const mssql = require('mssql');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of SQL Server.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    server: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
    port: parseInt(process.env.DB_PORT), // e.g. 1433
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    options: {
      trustServerCertificate: true,
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return mssql.connect(dbConfig);
};

Go

如要查看網頁應用程式中的程式碼片段，請參閱 GitHub 上的 README。

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"
	"strings"

	_ "github.com/denisenkom/go-mssqldb"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of SQL Server.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_tcp.go: %s environment variable not set.\n", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_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'
	)

	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("sqlserver", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

C#

如要查看網頁應用程式中的程式碼片段，請參閱 GitHub 上的 README。

using Microsoft.Data.SqlClient;
using System;

namespace CloudSql
{
    public class SqlServerTcp
    {
        public static SqlConnectionStringBuilder NewSqlServerTCPConnectionString()
        {
            // Equivalent connection string:
            // "User Id=<DB_USER>;Password=<DB_PASS>;Server=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new SqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                DataSource = Environment.GetEnvironmentVariable("INSTANCE_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;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

如要查看網頁應用程式中的程式碼片段，請參閱 GitHub 上的 README。

tcp: &tcp
  adapter: sqlserver
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  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("INSTANCE_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 1433 }%> 

PHP

如要查看網頁應用程式中的程式碼片段，請參閱 GitHub 上的 README。

namespace Google\Cloud\Samples\CloudSQL\SQLServer;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseTcp
{
    public static function initTcpDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceHost = getenv('INSTANCE_HOST'); // e.g. '127.0.0.1' ('172.17.0.1' for GAE Flex)

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

            // Connect to the database
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, and $instanceHost (for TCP mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/sqlserver/connect-external-app',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

其他主題

Cloud SQL 驗證 Proxy 指令列引數

上述範例涵蓋最常見的用途，但 Cloud SQL Auth Proxy 也有其他設定選項，可透過指令列引數設定。如需指令列引數的說明，請使用 --help 旗標查看最新說明文件：

./cloud-sql-proxy --help

如需如何使用 Cloud SQL 驗證 Proxy 指令列選項的其他範例，請參閱 Cloud SQL 驗證 Proxy GitHub 存放區中的 README。

驗證 Cloud SQL 驗證 Proxy 的選項

驗證 Cloud SQL 驗證 Proxy 時，您會使用一組 Google 憑證，讓該 Proxy 代表您的應用程式存取Google Cloud 。這與資料庫使用者驗證不同。

所有這些選項都會使用 INSTANCE_CONNECTION_NAME 做為連線字串，識別 Cloud SQL 執行個體。您可以在 Google Cloud console 中，前往執行個體的「Overview」(總覽) 頁面找到 INSTANCE_CONNECTION_NAME，或執行下列指令：

gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME。

例如：gcloud sql instances describe --project myproject myinstance。

其中部分選項會使用 JSON 憑證檔案，內含帳戶的 RSA 私密金鑰。如需如何為服務帳戶建立 JSON 憑證檔案的操作說明，請參閱「建立服務帳戶」。

Cloud SQL 驗證 Proxy 提供多種驗證替代方案，視您的環境而定。Cloud SQL 驗證 Proxy 會依下列順序檢查每個項目，並使用找到的第一個項目嘗試驗證：

1. credentials-file 旗標提供的憑證。

   使用服務帳戶建立並下載相關聯的 JSON 檔案，然後在啟動 Cloud SQL Auth Proxy 時，將 --credentials-file 旗標設為該檔案的路徑。服務帳戶必須具備 Cloud SQL 執行個體的必要權限。

   如要在指令列使用這個選項，請叫用 cloud-sql-proxy 指令，並將 --credentials-file 旗標設為 JSON 憑證檔案的路徑和檔案名稱。路徑可以是絕對路徑，也可以是相對於目前工作目錄的路徑。 例如：

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

   如需將身分與存取權管理角色新增至服務帳戶的詳細操作說明，請參閱為服務帳戶授予角色一文。

   如要進一步瞭解 Cloud SQL 支援的角色，請參閱「Cloud SQL 的 IAM 角色」。

2. 存取權杖提供的憑證。

   建立存取權杖，並使用 --token 旗標 (設為 OAuth 2.0 存取權杖) 叫用 cloud-sql-proxy 指令。例如：

   ./cloud-sql-proxy --token ACCESS_TOKEN \
   INSTANCE_CONNECTION_NAME
     

3. 環境變數提供的憑證。

   這個選項與使用 --credentials-file 旗標類似，但您指定的是在 GOOGLE_APPLICATION_CREDENTIALS 環境變數中設定的 JSON 憑證檔案，而不是使用 --credentials-file 指令列引數。

4. 已驗證 gcloud CLI 用戶端的憑證。

   如果您已安裝 gcloud CLI 並透過個人帳戶完成驗證，Cloud SQL Auth Proxy 就能使用相同的帳戶憑證。這個方法特別有助於啟動及執行開發環境。

   如要讓 Cloud SQL Auth Proxy 使用 gcloud CLI 憑證，請使用下列指令驗證 gcloud CLI：

   gcloud auth application-default login

5. 與 Compute Engine 執行個體相關聯的憑證。

   如果您是從 Compute Engine 執行個體連線至 Cloud SQL，Cloud SQL Auth Proxy 可以使用與 Compute Engine 執行個體相關聯的服務帳戶。如果服務帳戶具備 Cloud SQL 執行個體的必要權限，Cloud SQL Auth Proxy 就會成功完成驗證。

   如果 Compute Engine 執行個體與 Cloud SQL 執行個體位於相同專案，Compute Engine 執行個體的預設服務帳戶會具備驗證 Cloud SQL 驗證 Proxy 的必要權限。如果這兩個執行個體位於不同專案，您必須將 Compute Engine 執行個體的服務帳戶新增至包含 Cloud SQL 執行個體的專案。

6. 環境的預設服務帳戶

   如果 Cloud SQL Auth Proxy 在上述任何位置都找不到憑證，就會按照「設定伺服器對伺服器正式版應用程式的驗證作業」一文所述的邏輯運作。部分環境 (例如 Compute Engine、App Engine 等) 提供預設服務帳戶，應用程式預設可使用該帳戶進行驗證。如果您使用預設服務帳戶，該帳戶必須具備角色和權限一節中列出的權限。 如要進一步瞭解 Google Cloud 的驗證方法，請參閱「驗證總覽」。

建立服務帳戶

如果您是從 Compute Engine 連線，請確認 VM 具有適當的 scope，可使用 Cloud SQL Admin API 連線。

設定服務帳戶，使其具備下列任一存取範圍：

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

1. 前往 Google Cloud 控制台的「Service accounts」(服務帳戶) 頁面。

   前往「Service accounts」(服務帳戶)

2. 選取含有 Cloud SQL 執行個體的專案。
3. 按一下「建立服務帳戶」。
4. 在「Service account name」(服務帳戶名稱) 欄位中，輸入服務帳戶的描述性名稱。
5. 將「服務帳戶 ID」變更為可辨識的專屬值，然後按一下「建立並繼續」。
6. 按一下「選取角色」欄位，然後選取下列其中一個角色：
   • Cloud SQL > Cloud SQL 用戶端
   • Cloud SQL > Cloud SQL 編輯者
   • Cloud SQL > Cloud SQL 管理員
   注意：如要建立具備必要權限的服務帳戶，您必須擁有 resourcemanager.projects.setIamPolicy 權限。「專案擁有者」、「專案 IAM 管理員」和「機構管理員」角色都具備該權限。
   此外，您還必須啟用 Cloud SQL Admin API。如果您使用舊版專案角色 (檢視者、編輯者、擁有者)，服務帳戶至少要有編輯者角色。
7. 按一下「Done」(完成)，即完成建立服務帳戶。
8. 按一下新服務帳戶的動作選單，然後選取「管理金鑰」。
9. 點選「Add key」(新增金鑰) 下拉式選單，然後點選「Create new key」(建立新的金鑰)。
10. 確認金鑰類型為 JSON，然後按一下「建立」。

    私密金鑰檔案會下載到您的機器中，您可以將它移到其他位置。請妥善保護這個金鑰檔案。

搭配私人 IP 使用 Cloud SQL 驗證 Proxy

如要使用私人 IP 連線至 Cloud SQL 執行個體，Cloud SQL Auth Proxy 必須位於可存取與執行個體相同虛擬私有雲網路的資源上。

Cloud SQL Auth Proxy 會使用 IP 連線至您的 Cloud SQL 執行個體。根據預設，Cloud SQL Auth Proxy 會嘗試使用公開的 IPv4 位址進行連線。

如果 Cloud SQL 執行個體只有私人 IP，或執行個體已設定公開和私人 IP，而您想讓 Cloud SQL Auth Proxy 使用私人 IP 位址，則必須在啟動 Cloud SQL Auth Proxy 時提供下列選項：

--private-ip

搭配啟用 Private Service Connect 的執行個體使用 Cloud SQL Auth Proxy

您可以透過 Cloud SQL Auth Proxy 連線至已啟用 Private Service Connect 的 Cloud SQL 執行個體。

Cloud SQL Auth Proxy 是一種連接器，可安全存取這個執行個體，不需要授權網路或設定 SSL。

如要允許 Cloud SQL Auth Proxy 用戶端連線，您必須設定與執行個體建議的 DNS 名稱相符的 DNS 記錄。DNS 記錄是 DNS 資源與網域名稱之間的對應關係。

如要進一步瞭解如何使用 Cloud SQL Auth Proxy 連線至啟用 Private Service Connect 的執行個體，請參閱「使用 Cloud SQL Auth Proxy 連線」。

在個別程序中執行 Cloud SQL 驗證 Proxy

在個別的 Cloud Shell 終端機程序中執行 Cloud SQL 驗證 Proxy，可避免 Proxy 的控制台輸出內容與其他程式的輸出內容相互混雜，因此相當實用。使用下列語法，在個別程序中叫用 Cloud SQL 驗證 Proxy。

Linux

在 Linux 或 macOS 上，請在指令列使用尾端 &，以啟動獨立程序中的 Cloud SQL Auth Proxy：

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

Windows

在 Windows PowerShell 中，使用 Start-Process 指令在個別程序中啟動 Cloud SQL 驗證 Proxy：

Start-Process --filepath "cloud-sql-proxy.exe"
  --ArgumentList "
  --credentials-file PATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME"

在 Docker 容器中執行 Cloud SQL 驗證 Proxy

如要在 Docker 容器中執行 Cloud SQL 驗證 Proxy，請使用 Google Container Registry 提供的 Cloud SQL 驗證 Proxy Docker 映像檔。您可以使用下列指令安裝 Cloud SQL 驗證 Proxy Docker 映像檔：

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.17.1

您可以使用 TCP 通訊端或 Unix 通訊端啟動 Cloud SQL Auth Proxy，方法如下列指令所示。

注意： 以 Java 程式設計語言編寫的應用程式或 Windows 環境不支援 Unix Socket。

TCP 通訊端

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

Unix 通訊端

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.17.1 --unix-socket /cloudsql \
      --credentials-file /path/to/service-account-key.json/PATH_TO_KEY_FILE \
      INSTANCE_CONNECTION_NAME

如果您要使用將容器最佳化的映像檔，請使用可寫入的目錄來取代 /cloudsql，例如：

v /mnt/stateful_partition/cloudsql:/cloudsql

如果您要使用 Compute Engine 執行個體提供的憑證，請勿加入 credential_file 參數與 -v PATH_TO_KEY_FILE:/path/to/service-account-key.json 這一行指令列。

以服務形式執行 Cloud SQL 驗證 Proxy

您可以選擇將 Cloud SQL 驗證 Proxy 做為背景服務執行，用於本機開發和正式環境工作負載。在開發期間，如要存取 Cloud SQL 執行個體，可以啟動背景服務，完成後再停止。

目前 Cloud SQL Auth Proxy 並未內建支援以 Windows 服務形式執行的功能，但可搭配第三方服務管理工具，以服務形式執行，適用於實際工作環境工作負載。舉例來說，您可以使用 NSSM 將 Cloud SQL Auth Proxy 設定為 Windows 服務，NSSM 會監控 Cloud SQL Auth Proxy，並在停止回應時自動重新啟動。詳情請參閱 NSSM 說明文件。

注意： 如果將 Cloud SQL Auth Proxy 做為服務執行，請注意，該服務會使用安全連線與 Cloud SQL 執行個體通訊，但應用程式與 Cloud SQL Auth Proxy 之間的連線不會加密。因此，請確保只有信任的使用者可以存取 Cloud SQL Auth Proxy 監聽的位址和通訊埠。

在需要 SSL 時連線

注意：如果 SQL Server 執行個體已勾選「Require SSL/TLS」(需要 SSL/TLS)，即使使用 Cloud SQL Auth Proxy 或 Cloud SQL 連接器，用戶端應用程式也必須設定 TLS/SSL，方式與不使用 Cloud SQL Auth Proxy 或 Cloud SQL 連接器時相同，否則連線嘗試可能會失敗。如要成功連線，除了 SQL Server 的原生加密功能外，Cloud SQL Auth Proxy 或 Cloud SQL 連接器還會新增一層加密。換句話說，Proxy 用戶端/Cloud SQL 連接器與 Proxy 伺服器之間的連線會經過雙重加密。
雙重加密可能會對 SQL Server 效能造成負面影響。建議客戶先審慎考慮，再同時要求使用 SSL，並使用 Cloud SQL 驗證 Proxy 或 Cloud SQL 連接器。

強制使用 Cloud SQL 驗證 Proxy

使用 ConnectorEnforcement 在 Cloud SQL 中啟用 Cloud SQL 驗證 Proxy。

如果您使用已啟用 Private Service Connect 的執行個體，則會受到限制。如果執行個體已啟用連接器強制執行功能，就無法為該執行個體建立唯讀備用資源。同樣地，如果執行個體有唯讀備用資源，您就無法為該執行個體啟用連接器強制執行功能。

gcloud

下列指令會強制使用 Cloud SQL 連接器。

    gcloud sql instances patch INSTANCE_NAME \
    --connector-enforcement REQUIRED
  

如要停用強制執行，請使用下列程式碼行： --connector-enforcement NOT_REQUIRED 更新不會觸發重新啟動。

REST v1

下列指令會強制使用 Cloud SQL 連接器

使用任何要求資料之前，請先替換以下項目：

• project-id：專案 ID。
• instance-id：執行個體 ID。

HTTP 方法和網址：

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

JSON 要求主體：

{
  "settings": {                     
    "connectorEnforcement": "REQUIRED"    
  }                                             
}   

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

如要停用強制執行，請改用 "connectorEnforcement": "NOT_REQUIRED"。更新不會觸發重新啟動。

REST v1beta4

下列指令會強制使用 Cloud SQL 連接器。

使用任何要求資料之前，請先替換以下項目：

• project-id：專案 ID。
• instance-id：執行個體 ID。

HTTP 方法和網址：

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

JSON 要求主體：

{
  "settings": {
    "connectorEnforcement": "REQUIRED"
  }
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

如要停用強制執行，請改用 "connectorEnforcement": "NOT_REQUIRED"。更新不會觸發重新啟動。

使用 Cloud SQL 驗證 Proxy 的提示

使用 Cloud SQL 驗證 Proxy 連線至多個執行個體

您可以使用一個本機 Cloud SQL 驗證 Proxy 用戶端，連線至多個 Cloud SQL 執行個體。執行此動作的方式視您使用的是 Unix 通訊端還是 TCP 而定。

TCP 通訊端

使用 TCP 連線時，您要為每個 Cloud SQL 執行個體指定機器上的通訊埠，供 Cloud SQL Auth Proxy 監聽。連線至多個 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 "myProject:us-central1:myInstance?port=1433" \
    "myProject:us-central1:myInstance2?port=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 驗證 Proxy 連線問題

Cloud SQL 驗證 Proxy Docker 映像檔是以特定版本的 Cloud SQL 驗證 Proxy 為基礎。 Cloud SQL 驗證 Proxy 推出新版本時，請提取新版 Cloud SQL 驗證 Proxy Docker 映像檔，確保環境維持在最新狀態。您可以檢查 Cloud SQL 驗證 Proxy GitHub 版本頁面，查看 Cloud SQL 驗證 Proxy 的最新版本。

如果無法使用 Cloud SQL 驗證 Proxy 連線至 Cloud SQL 執行個體，請嘗試下列幾種方法，找出問題原因。

• 確認您是使用 IP 位址連線至執行個體，而不是寫入端點。

• 檢查 Cloud SQL 驗證 Proxy 輸出內容。

  通常，Cloud SQL Auth Proxy 的輸出內容有助於判斷問題來源，以及如何解決問題。將輸出內容傳送至檔案，或監看您啟動 Cloud SQL 驗證 Proxy 時所用的 Cloud Shell 終端機。

• 如果您在使用服務帳戶驗證 Cloud SQL Auth Proxy 時發生 403 notAuthorized 錯誤，請確定服務帳戶擁有正確的權限。

  您可在「IAM」(身分與存取權管理) 頁面搜尋服務帳戶的 ID 以進行檢查。必須具備「cloudsql.instances.connect」權限。Cloud SQL Admin、Client 和 Editor 預先定義的角色具備這項權限。

• 如果您是從 App Engine 連線，並收到 403 notAuthorized 錯誤，請檢查 app.yaml 值，確認執行個體連線名稱是否拼寫錯誤或不正確。cloud_sql_instances執行個體連線名稱的格式一律為「PROJECT:REGION:INSTANCE」。

  此外，請確認 App Engine 服務帳戶 (例如 $[e-mail]) 具有 Cloud SQL 用戶端 IAM 角色。

  如果 App Engine 服務位於一個專案 (專案 A)，而資料庫位於另一個專案 (專案 B)，則這項錯誤表示 App Engine 服務帳戶在資料庫所在的專案 (專案 B) 中，未獲派 Cloud SQL 用戶端 IAM 角色。

• 請務必啟用 Cloud SQL Admin API。

  若未啟用，您將會在 Cloud SQL 驗證 Proxy 記錄中看見像是 Error 403: Access Not Configured 的輸出。

• 如果要將多個執行個體納入執行個體清單，請務必使用逗號做為分隔符號，不包含空格。如果您使用 TCP，請確定每個執行個體都指定了不同的通訊埠。

• 如果您使用 UNIX 通訊端連線，請確認通訊端是透過列出您啟動 Cloud SQL 驗證 Proxy 時提供的目錄建立。

• 如果您有傳出防火牆政策，請確定該政策允許連線至目標 Cloud SQL 執行個體上的 3307 通訊埠。

  注意： Cloud SQL Auth Proxy 會使用 3307 連線至 Cloud SQL Auth Proxy 伺服器。 通訊埠 1433 是透過直接 TCP 連線 (不使用 Cloud SQL 驗證 Proxy) 的 SQL Server 通訊協定預設通訊埠。

• 您可以在Google Cloud 控制台的「Operations」(作業) >「Logging」(記錄) >「Logs explorer」(記錄檔探索工具) 部分查看記錄，確認 Cloud SQL Auth Proxy 是否已正確啟動。成功執行的作業如下所示：

  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 驗證 Proxy 會啟動，並顯示下列錯誤訊息：

  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
  

  應用程式連線至 Proxy 後，Proxy 會回報下列錯誤：

  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 配額。如果啟動時出現配額錯誤，您必須重新部署應用程式，才能重新啟動 Proxy。如果配額錯誤是在啟動後顯示，則不需要重新部署。

後續步驟

• 進一步瞭解 Cloud SQL 驗證 Proxy。
• 進一步瞭解身分與存取權管理 (IAM)。
• 進一步瞭解服務帳戶。
• 瞭解 Cloud SQL 執行個體的兩個存取控管層級。
• 建立使用者與資料庫。
• 瞭解如何 從應用程式連線至執行個體。
• 瞭解支援的選項。