從 Compute Engine 連線

MySQL   |  PostgreSQL   |  SQL Server

本頁說明如何使用在 Compute Engine 執行個體上安裝的 psql 用戶端，連線至 Cloud SQL。

您可以使用私人 IP、公開 IP、Cloud SQL Auth Proxy 或 Cloud SQL Auth Proxy Docker 映像檔。

如需逐步操作說明，瞭解如何執行連線至 Cloud SQL 的 Compute Engine 範例網頁應用程式，請參閱從 Compute Engine 連線的快速入門指南。

事前準備

這項工作不包含設定 Compute Engine 執行個體的說明。如需建立及設定 Compute Engine 執行個體的相關協助，請參閱 Compute Engine 說明文件。

確認 Compute Engine VM 具備適當的 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. 開啟 Cloud Shell 終端機，連線至 Compute Engine 執行個體。

請根據執行個體的作業系統參考適當指示：

• 如為 Linux，請參閱「 連結至 Linux VM」。
• 如為 Windows，請參閱「 連線至 Windows VM」。

如果 Compute Engine 執行個體執行的是 RHEL 或 CentOS 公開映像檔，SELinux 可能會封鎖 Proxy 連線。如果發生這種情況，您必須設定 SELinux 功能，允許連線。

如要進一步瞭解 RHEL 的 SELinux，請參閱 RHEL 說明文件。如要進一步瞭解 CentOS 的 SELinux，請參閱 CentOS 說明文件。

3. 若尚未在 Compute Engine 執行個體上安裝 psql 用戶端，請執行這個動作。

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 Core Distribution。
   Core Distribution 內含 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 連線存取權一節。

注意：您應只為「靜態」IP 位址授權。臨時 IP 位址是暫時性的，授予這類位址執行個體存取權會造成安全風險，因為這類位址稍後可能會重新指派給其他 Compute Engine 使用者。

3. 開啟 Cloud Shell 終端機，連線至 Compute Engine 執行個體。

請根據執行個體的作業系統參考適當指示：

• 如為 Linux，請參閱「 連結至 Linux VM」。
• 如為 Windows，請參閱「 連線至 Windows VM」。

如果 Compute Engine 執行個體執行的是 RHEL 或 CentOS 公開映像檔，SELinux 可能會封鎖 Proxy 連線。如果發生這種情況，您必須設定 SELinux 功能，允許連線。

如要進一步瞭解 RHEL 的 SELinux，請參閱 RHEL 說明文件。如要進一步瞭解 CentOS 的 SELinux，請參閱 CentOS 說明文件。

4. 若尚未在 Compute Engine 執行個體上安裝 psql 用戶端，請執行這個動作。

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 Core Distribution。
   Core Distribution 內含 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 存留時間。

詳情請參閱 Compute Engine 說明文件中的 執行個體與網際網路之間的通訊。

系統會自動為執行個體保持連線。

Cloud SQL 驗證 Proxy

如要從 Compute Engine 使用 Cloud SQL 驗證 Proxy 連線：

1. 啟用 Cloud SQL Admin API。

Enable the API

2. 建立服務帳戶。

注意：如果 Compute Engine 執行個體具有「Full API access」(完整 API 存取權) 或「Cloud SQL Admin API」(Cloud SQL Admin API) 範圍，您可以略過這個步驟；啟動 Cloud SQL Auth Proxy 時，您不需要提供憑證檔案。

如果您是從 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，然後按一下「建立」。

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

如果 Compute Engine 執行個體位於與 Cloud SQL 執行個體不同的專案，請確保在 Cloud SQL 執行個體所處的專案中，Compute Engine 執行個體的服務帳戶具有適當權限：

1. 前往 Google Cloud 控制台中的 Compute Engine 執行個體清單。

   前往 Compute Engine 執行個體清單

2. 視需要選取與 Compute Engine 執行個體相關聯的專案。
3. 選取 Compute Engine 執行個體，即可顯示其屬性。
4. 在 Compute Engine 執行個體屬性中，複製服務帳戶的名稱。
5. 前往 Google Cloud 控制台中的「IAM & Admin Projects」(IAM 與管理員專案) 頁面。

   前往身分與存取權管理與管理員專案頁面

6. 選取含有 Cloud SQL 執行個體的專案。
7. 搜尋服務帳戶名稱。

8. 如果服務帳戶已經存在，且具有包含 cloudsql.instances.connect 權限的角色，您就能繼續步驟 4。

   與舊版的 Editor 和 Owner 專案角色一樣，Cloud SQL Client、Cloud SQL Editor 和 Cloud SQL Admin 角色都會提供必要的權限。

9. 如果您沒有服務帳戶，則請按一下 [Add] (新增) 來新增服務帳戶。

10. 在「新增主體」對話方塊中，輸入服務帳戶的名稱，然後選取具有 cloudsql.instances.connect 權限的角色 (除了「檢視者」外，其他任何 Cloud SQL 預先定義的角色皆可)。

    或者，您也可以選取「Project」>「Editor」來使用基本編輯者角色，不過編輯者角色包含 Google Cloud中的各種權限。

    如果畫面上未列出這些角色，代表您的 Google Cloud 使用者可能不具 resourcemanager.projects.setIamPolicy 權限。您可以前往 Google Cloud 控制台的 IAM 頁面，然後搜尋您的使用者 ID，藉此檢查您的權限。

11. 按一下 [新增]。

    畫面上應會列出具備指定角色的服務帳戶。

3. 開啟與 Compute Engine 執行個體的終端機連線。

請根據執行個體的作業系統參考適當指示：

• 如為 Linux，請參閱「 連線至 Linux 執行個體」。
• 針對 Windows，請參閱連線至 Windows 執行個體一文。

如果 Compute Engine 執行個體執行的是 RHEL 或 CentOS 公開映像檔，SELinux 可能會封鎖 Proxy 連線。如果發生這種情況，您必須設定 SELinux 功能，允許連線。

如要進一步瞭解 RHEL 的 SELinux，請參閱 RHEL 說明文件。如要進一步瞭解 CentOS 的 SELinux，請參閱 CentOS 說明文件。

4. 若尚未在 Compute Engine 執行個體上安裝 psql 用戶端，請執行這個動作。

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 Core Distribution。
   Core Distribution 內含 psql 用戶端。
2. 按照下載頁面上的指示安裝 PostgreSQL 資料庫。

5. 在 Compute Engine 執行個體上安裝 Cloud SQL Auth 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

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。

6. 啟動 Cloud SQL 驗證 Proxy。

注意：如果 Compute Engine 執行個體具有完整 API 存取權或 Cloud SQL Admin API 範圍，啟動 Cloud SQL Auth Proxy 時就不需要提供憑證檔案。

根據您的語言和環境，您可以使用 TCP 通訊端、Unix 通訊端或 Cloud SQL Auth Proxy Docker 映像檔啟動 Cloud SQL Auth Proxy。Cloud SQL 驗證 Proxy 二進位檔會連線至命令列上指定的一或多個 Cloud SQL 執行個體，並以 TCP 或 Unix Socket 開啟本機連線。其他應用程式和服務 (例如應用程式程式碼或資料庫管理用戶端工具) 可以透過這些 TCP 或 Unix 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 5432 INSTANCE_CONNECTION_NAME

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

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

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

Unix 通訊端

注意： Cloud SQL Auth Proxy 目前不支援 Windows 上的 Unix Socket，因此這個選項僅適用於 Linux 和 macOS 平台。

Cloud SQL Auth Proxy 可以監聽 Unix 通訊端，這是 Posix 標準機制，可使用資料夾管理在同一主機上執行的兩個程序之間的通訊。使用 Unix 通訊端的優點是安全性更高且延遲時間較短，但您無法從外部機器存取 Unix 通訊端。

注意： PostgreSQL 標準規定通訊端路徑必須加上 `.s.PGSQL.5432` 後置字串。部分程式庫會自動套用這個後置字串，但其他程式庫則需要您依照下列方式指定通訊端路徑：

  /cloudsql/INSTANCE_CONNECTION_NAME/.s.PGSQL.5432
  

如要建立及使用 Unix 通訊端，目標目錄必須存在，且 Cloud SQL Auth Proxy 和應用程式都必須具備讀取和寫入權限。

1. 複製INSTANCE_CONNECTION_NAME。您可以在Google Cloud 控制台中，前往執行個體的「總覽」頁面查看，也可以執行下列指令：

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

   例如 myproject:myregion:myinstance。

2. 建立 Cloud SQL 驗證 Proxy 通訊端運作的目錄：

   sudo mkdir /cloudsql; sudo chmod 777 /cloudsql

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

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

   • 使用 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 Shell 終端機中啟動 Cloud SQL 驗證 Proxy，這樣即可避免 Proxy 的輸出內容與其他程式的輸出內容相互混雜，以便您監控 Proxy 的輸出內容。

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

   注意： 使用 Unix 通訊端透過 Cloud SQL Auth Proxy 連線至 Cloud SQL 時，請確保通訊端檔案名稱長度未超過系統限制。這取決於系統，但通常介於 91 到 108 個字元。在 Linux 中，長度通常定義為 108，您可以使用下列指令檢查：

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

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:5432:5432 \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.17.1 \\
  --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 驗證 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 參數。

7. 啟動 psql 工作階段。

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

TCP 通訊端

1. 啟動 psql 用戶端：

   psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"

   即使 sslmode 參數設為 disable，Cloud SQL 驗證 Proxy 仍會提供加密連線。

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

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

使用 Unix 通訊端

1. 啟動 psql 用戶端：

   psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"

   即使 sslmode 參數設為 disable，Cloud SQL 驗證 Proxy 仍會提供加密連線。

2. 輸入密碼。
3. 系統會顯示 psql 提示。

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

後續步驟

• 針對 Cloud SQL 驗證 Proxy 的 連線問題疑難排解，取得相關說明。
• 建立使用者與資料庫。
• 進一步瞭解私人 IP。
• 瞭解從應用程式連線至執行個體的選項。
• 瞭解 psql 用戶端。
• 瞭解支援的選項。