關於 Cloud SQL Proxy

本頁面提供 Cloud SQL Proxy 的基本介紹,並說明 Proxy 選項。

如需使用 Cloud SQL Proxy 的逐步操作說明,請針對您的環境點選下列連結:

您不需要使用 Proxy 或設定安全資料傳輸層 (SSL),即可從 App Engine 標準環境或彈性環境連線至 Cloud SQL。

Proxy 提供的內容

您可以透過 Cloud SQL Proxy 安全地存取 Cloud SQL 第二代執行個體,不需要將 IP 位址加入許可清單設定安全資料傳輸層 (SSL)

使用 Cloud SQL Proxy 存取您的 Cloud SQL 執行個體,具備下列優點:

  • 安全的連線:Proxy 會透過傳輸層安全標準 (TLS) 1.2 搭配 128 位元 AES 加密,自動加密進出資料庫的流量,並使用安全資料傳輸層 (SSL) 憑證來驗證用戶端與伺服器身分。
  • 更輕鬆的連線管理:Proxy 會處理 Cloud SQL 的驗證,無需提供靜態 IP 位址。

Proxy 不會提供新的連線路徑,而是仰賴現有的 IP 連線。舉例來說,除非 Proxy 使用的虛擬私人雲端網路已設有私人服務存取權,否則您不得使用 Proxy 連線至使用私人 IP 的執行個體。

Cloud SQL Proxy 的運作方式

Cloud SQL Proxy 的運作方式是讓稱為 Proxy 的本機用戶端在本機環境中執行。您的應用程式會透過資料庫使用的標準資料庫通訊協定與 Proxy 通訊。Proxy 使用安全通道來與其在伺服器上執行的隨附程序通訊。

下圖顯示 Proxy 連結 Cloud SQL 的方式:

從用戶端軟體連線至 SQL 執行個體的 Proxy 圖表

使用 Cloud SQL Proxy 的規定

您必須符合下列規定,才能使用 Proxy:

  • 您必須啟用 Cloud SQL Admin API。
  • 您必須提供 GCP 驗證憑證給 Proxy。
  • 您必須提供有效的資料庫使用者帳戶與密碼給 Proxy。
  • 執行個體必須要有公開 IPv4 位址,或設定為使用私人 IP

    這個公開 IP 位址不需要向任何外部位址提供存取權 (加入許可清單)。

安裝 Cloud SQL Proxy

Linux 64 位元

  1. 下載 Proxy:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. 將 Proxy 設定為可執行:
    chmod +x cloud_sql_proxy
    

Linux 32 位元

  1. 下載 Proxy:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. 將 Proxy 設定為可執行:
    chmod +x cloud_sql_proxy
    

macOS 64 位元

  1. 下載 Proxy:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. 將 Proxy 設定為可執行:
    chmod +x cloud_sql_proxy
    

macOS 32 位元

  1. 下載 Proxy:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. 將 Proxy 設定為可執行:
    chmod +x cloud_sql_proxy
    

Windows 64 位元

https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe 上按一下滑鼠右鍵,然後選取 [Save Link As] (另存連結為) 來下載 Proxy。將檔案重新命名為 cloud_sql_proxy.exe

Windows 32 位元

https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe 上按一下滑鼠右鍵,然後選取 [Save Link As] (另存連結為) 來下載 Proxy。將檔案重新命名為 cloud_sql_proxy.exe
如果這裡沒有列出您的作業系統,您也可以從原始碼編譯 Proxy

Proxy 啟動選項

啟動 Proxy 時會提供下列資訊:

  • Proxy 應與哪些 Cloud SQL 執行個體建立連線
  • Proxy 要在哪裡聆聽應用程式傳送至 Cloud SQL 的資料
  • Proxy 要去哪裡尋找用來向 Cloud SQL 驗證應用程式的憑證
  • (如有需要) 要使用的 IP 位址類型。

您提供的 Proxy 啟動選項會決定 Proxy 是使用 TCP 通訊埠還是 Unix 通訊端聆聽。如果使用 Unix 通訊端聆聽,則會在您所選的位置上建立通訊端 (位置通常會是 /cloudsql/ 目錄)。如果使用 TCP,則 Proxy 預設會在 localhost 上聆聽。

您可在本機環境中的任意位置安裝 Proxy。Proxy 二進位檔的位置並不會影響其聆聽應用程式資料的位置。

驗證 Cloud SQL Proxy 的選項

Cloud SQL Proxy 提供數種驗證的方法 (視您的環境而定)。Proxy 會依序檢查下列每一個項目,並使用其所找到的第一個項目來嘗試驗證:

  1. 透過 Proxy 叫用指令提供的憑證
  2. 本機環境提供的憑證
  3. 與 Compute Engine 執行個體相關聯的憑證
  4. 來自已驗證的 Cloud SDK 用戶端的憑證

請參閱叫用範例與連線字串

透過 Proxy 叫用指令提供的憑證

您可以使用 Google Cloud Platform 主控台建立憑證檔案,並在啟用 Cloud SQL Proxy 時,透過 -credential_file 參數在指令列上提供該憑證。服務帳戶必須具有 Cloud SQL 執行個體的所需權限

這個驗證方法的優點是您可以為 Proxy 建立專屬的憑證檔案。由於只要該檔案保持執行,就可以明確地永久連結至 Proxy,因此對於不在 Compute Engine 執行個體上執行的實際環境執行個體,我們建議您採用此方法。

如果您需要從多部機器叫用 Cloud SQL Proxy,可以在系統映像檔中複製憑證檔案。

您必須建立及管理憑證檔案,才能使用這個方法。唯有授予 resourcemanager.projects.setIamPolicy 權限的使用者 (如專案擁有者) 可以建立服務帳戶。如果您的 GCP 使用者沒有這項權限,您必須透過他人建立服務帳戶,或者使用其他方法驗證 Proxy。

如需建立憑證檔案的說明,請參閱建立服務帳戶

本機環境提供的憑證

這個方法與透過指令列提供憑證檔案的方法相同,但憑證檔案的位置是由 GOOGLE_APPLICATION_CREDENTIALS 環境變數提供。

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

如果您是從 Compute Engine 執行個體連線至 Cloud SQL,Proxy 可以使用與 Compute Engine 執行個體相關聯的服務帳戶。如果服務帳戶具有 Cloud SQL 執行個體的所需權限,Proxy 便能成功完成驗證。

如果 Compute Engine 執行個體所在的專案與 Cloud SQL 執行個體相同,Compute Engine 執行個體的預設服務帳戶就具有驗證 Proxy 的必要權限。如果這兩個執行個體位於不同的專案中,您必須將 Compute Engine 執行個體的服務帳戶新增至含有該 Cloud SQL 執行個體的專案。

來自已驗證的 Cloud SDK 用戶端的憑證

如果您已安裝 Cloud SDK 並用於向 GCP 進行驗證,Cloud SQL Proxy 可以使用相同的憑證。這個方法有助於快速建立及執行開發環境。如果是實際工作環境,則應使用其他方法來驗證。

您可以使用 gcloud auth list 指令確定您目前的 Cloud SDK 憑證。

服務帳戶的所需權限

當您使用服務帳戶為 Proxy 提供憑證時,必須擁有足夠的權限才能建立服務帳戶。如要使用更精細的身分與存取權管理 (IAM) 角色來管理您的 Cloud SQL 權限,則必須將包含 cloudsql.instances.connect 權限的角色提供給服務帳戶。含有這類角色的預先定義 Cloud SQL 角色如下:

  • Cloud SQL 用戶端
  • Cloud SQL 編輯者
  • Cloud SQL 管理員

如果您是使用舊版專案角色 (檢視者、編輯者、擁有者),則服務帳戶至少必須具備「編輯者」角色。

指定 Cloud SQL 執行個體的選項

有數種方法可以告知 Proxy 您要連線至哪些執行個體。某些方法是明確的,某些方法是不明確的。在部分設定中,您不必提前告知 Proxy 您要連線至哪些執行個體,因為 Proxy 是依據連線要求來進行連線。

指定執行個體的選項取決於您的作業系統與環境:

選項 優點 警訊與需求 Linux/macOS
(Unix 通訊端)
Java Windows 附註
Automatic instance discovery 無需指定執行個體;系統會針對預設專案內所有的執行個體建立通訊端。 Proxy API 使用量會增加。必須安裝及驗證 Cloud SDK,並設定預設專案。必須重新啟動 Proxy 才能新增執行個體。 支援 不建議生產環境執行個體使用。
探索專案 無需指定執行個體;系統會針對指定專案內所有的執行個體建立通訊端。 Proxy API 使用量會增加。必須安裝及驗證 Cloud SDK。必須重新啟動 Proxy 才能新增執行個體。 支援 使用 -projects 參數。不建議生產環境執行個體使用。
Proxy 叫用中指定的執行個體 執行個體清單為已知且靜態的。 必須重新啟動 Proxy 才能新增執行個體。 支援 支援 TCP 通訊端 支援 TCP 通訊端 使用 -instances 參數。若為多個執行個體,使用逗號分隔的清單,不含空格。 瞭解詳情
使用 Compute Engine 中繼資料指定的執行個體 可透過變更中繼資料值來更新執行個體清單,而無需重新啟動 Proxy。 僅適用於 Compute Engine。 支援 支援 TCP 通訊端 支援 TCP 通訊端 使用 -instances_metadata 標記。 瞭解詳情

請參閱叫用範例與連線字串

使用具有私人 IP 的 Proxy

Proxy 會使用 IP 連線至您的 Cloud SQL 執行個體。根據預設,Proxy 會嘗試使用公開的 IPv4 位址進行連線。如果 Proxy 使用的虛擬私人雲端網路與 Cloud SQL 執行個體的虛擬私人雲端網路相同,而且該執行個體有私人 IP 位址,則 Proxy 可使用私人 IP 進行連線。

如果您的 Cloud SQL 執行個體只有一個私人 IP,Proxy 會使用該私人 IP 位址進行連線。如果執行個體已設定公開和私人 IP,而您想讓 Proxy 使用私人 IP 位址,則必須在啟動 Proxy 時提供下列選項:

--ip_address_types=PRIVATE

使用 Cloud SQL Proxy 的秘訣

叫用 Cloud SQL Proxy

所有 Proxy 叫用範例都會在背景啟動 Proxy,因此會傳回提示。建議您為 Proxy 保留該終端機,以免將它的輸出與其他程式的輸出搞混。此外,Proxy 的輸出可以協助您診斷連線問題,所以在記錄檔中擷取這些輸出將會十分實用。

您不用非得將 /cloudsql 當成 Proxy 通訊端的目錄 (之所以選擇這個目錄名稱,是為了將名稱與 App Engine 連線字串的差異減到最低程度)。但是,如果您要變更目錄名稱,請儘量縮短整體長度。在作業系統規定的長度限制之下,較長的字串會遭到合併。

使用 Proxy 連線至多個執行個體

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

Unix 通訊端

如要將 Proxy 連線至多個執行個體,您可以透過 -instances 參數,以逗號分隔的清單 (不含空格) 提供執行個體連線名稱。當 Proxy 啟動時,會連線至每個執行個體。

您可以在指定目錄中,使用每個執行個體的通訊端連線至執行個體。

如下所示:

./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance,myProject:us-central1:myInstance2 &
psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2

TCP

當您使用 TCP 連線時,您可指定使用機器上的連接埠連線至執行個體,每個執行個體都必須有它自己的連接埠。 psql 工具預設使用 5432,但您可以指定其他連接埠來讓它使用。

例如:

./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:5432,myProject:us-central1:myInstance2=tcp:5433 &
psql -U myUser -h 127.0.0.1  --port 5433

保持 Cloud SQL Proxy 的最新狀態

Google 有時會發佈新版本的 Proxy。您可以查看 Cloud SQL Proxy GitHub 版本頁面來瞭解目前的版本為何。之後的 Proxy 版本也會註記在 Google Cloud SQL announce 網上論壇中。

API 使用量

Cloud SQL Proxy 會向 Cloud SQL API 發出要求,而這些要求會計入專案的 API 配額。

最高的 API 使用量會在啟動 Proxy 時發生,特別是當您使用自動探索執行個體功能或 -projects 參數時,此情況會更加明顯。當 Proxy 正在執行中時,它會每小時每個連線的執行個體發出 2 次 API 呼叫。

Cloud SQL Proxy 參數與標記

Cloud SQL Proxy 會在啟動時接受幾個標記和參數。這些選項會決定 Cloud SQL Proxy 要在哪裡建立與 Cloud SQL 通訊所用的通訊端和建立方式,以及如何進行驗證。

如需 Proxy 選項說明,請參閱下列資訊:

Proxy 叫用範例與 psql 用戶端連線字串

以下範例顯示 PostgreSQL 使用者 myUser 針對 myInstance 執行個體的 Proxy 叫用與連線字串,其位置在 us-central1,位於 myProject 專案中。

透過 gcloud 憑證,使用自動探索執行個體功能:

./cloud_sql_proxy -dir=/cloudsql &
 psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
透過 gcloud 憑證,使用探索專案功能:

./cloud_sql_proxy -dir=/cloudsql -projects=myProject &
psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
若為 Compute Engine 執行個體,請明確指定執行個體:

./cloud_sql_proxy -dir=/cloudsql -instances=myProject:us-central1:myInstance &
psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
若為 Unix,請使用 TCP:

./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:5432 &
psql -U myUser -h 127.0.0.1
若為 Windows (在指令列提示中):

cloud_sql_proxy.exe -instances=myProject:us-central1:myInstance=tcp:5432
psql -U myUser -h 127.0.0.1

如要進一步瞭解 Cloud SQL Proxy 選項與連線字串,請參閱 Cloud SQL Proxy GitHub 頁面

建立服務帳戶

如何建立服務帳戶:

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

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

  2. 如有需要,請選取包含您的 Cloud SQL 執行個體的專案。
  3. 按一下 [Create service account] (建立服務帳戶)
  4. 在「Create service account」(建立服務帳戶) 對話方塊中,提供服務帳戶的描述性名稱。
  5. 在「Role」(角色) 部分,選取下列其中一個角色:
    • Cloud SQL > Cloud SQL 用戶端
    • Cloud SQL > Cloud SQL 編輯者
    • Cloud SQL > Cloud SQL 管理員

    您也可以選取 [Project] (專案) > [Editor] (編輯者) 來使用原始編輯者角色,但編輯者角色包含跨 Google Cloud Platform 的權限。

    如果您沒有看到這些角色,即表示您的 Google Cloud Platform 使用者可能沒有 resourcemanager.projects.setIamPolicy 權限。您可以前往 Google Cloud Platform 主控台的「IAM」(身分與存取權管理) 頁面,然後搜尋您的使用者 ID,藉以檢查您的權限。

  6. 將「服務帳戶 ID」變更為您可以辨識的唯一值,使您日後能夠在有需要的情況下輕鬆找到這個服務帳戶。
  7. 按一下 [Furnish a new private key] (提供一組新的私密金鑰)
  8. 預設金鑰類型為 JSON,這是要使用的正確值。
  9. 按一下 [Create] (建立)

    私密金鑰檔案就會下載到您的機器。您可以將它移到其他位置。請保證金鑰檔案的安全。

如需進一步瞭解服務帳戶,請參閱驗證說明文件

在生產環境中使用 Cloud SQL Proxy

當您在生產環境中使用 Cloud SQL Proxy 時,可以採取一些步驟確保 Proxy 提供應用程式所需要的可用性。

確保 Cloud SQL Proxy 做為永久服務執行

如果 Proxy 程序終止,所有經由它的現有連線都會中斷,且您的應用程式無法透過 Proxy 與 Cloud SQL 執行個體建立任何連線。為了防止發生這種情形,請確定將 Proxy 做為永久服務執行,以便 Proxy 因任何原因結束時,可以自動重新啟動。您可以使用如 systemdupstartsupervisor 等服務,將 Proxy 設為永久服務。如果為 Windows 作業系統,請將 Proxy 做為 Windows 服務執行。一般而言,Proxy 的運作時間應與您的應用程式程序的運作時間相同。

應用程式需要多少 Cloud SQL Proxy 複本

您不需要為每個應用程式程序都建立一個 Proxy 程序,許多應用程式程序均能共用相同的 Proxy 程序。一般而言,您應為每個工作站或虛擬機器執行一個 Proxy 用戶端程序。

如果您要讓虛擬機器自動調整資源配置,請確保 Proxy 包含在您的虛擬機器設定中,這樣每當啟動新虛擬機器時,虛擬機器都會有自己的 Proxy 程序。

無論是透過限制還是集中管理連線,您都可以自行管理應用程式需要多少連線。Proxy 不會限制新連線速率或永久連線計數。

減少 Cloud SQL Proxy 輸出

如果您需要減少 Proxy 記錄的大小,可以在啟動 Proxy 時設定 -verbose=false 來達到這個目的。但是請記住,這麼做將會在診斷連線問題時降低 Proxy 輸出的效率。

疑難排解 Cloud SQL Proxy 連線

如果您使用 Cloud SQL Proxy 連線至 Cloud SQL 執行個體時發生問題,以下提供一些方法,協助您嘗試尋找問題發生的原因。

  • 檢查 Proxy 輸出。

    Proxy 輸出通常可以協助您確定問題的來源及解決方案。將輸出傳送至檔案,或者監看您啟動 Proxy 時所使用的終端機。

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

    您可在「IAM」(身分與存取權管理) 頁面搜尋服務帳戶的 ID 以進行檢查。服務帳戶應具有 cloudsql.instances.connect 權限。除了 Cloud SQL Viewer 之外,所有 Cloud SQL 預先定義的角色都有此權限。此外,舊版專案角色 EditorOwner 也具有所需權限。

  • 確定 Cloud SQL API 已啟用。

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

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

  • 如果您要嘗試從應用程式連線,請先使用管理用戶端連線,避免應用程式發生任何問題。

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

  • 如果您有傳出防火牆政策,請確定該政策允許連線至目標電腦上的 3307 通訊埠。

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
PostgreSQL 適用的 Cloud SQL