GCP帳號購買服務 Google Cloud SQL連線失敗解決方法

前言：連線失敗不是單一問題

很多人遇到 Google Cloud SQL 的連線失敗，第一反應是「換一個連線字串試試看」或「重啟一下服務」。但實務上，連線失敗通常不是單點錯誤，而是多個環節任一處出問題就會中斷：網路路由、存取控制、身份驗證、連線協定、用到的工具與環境設定。你看到的錯誤訊息往往只是最後的結果，真正原因要靠系統化的排查把「可能性」快速縮小。

本文我會用一種比較實際的方式寫：先描述常見現象與對應方向，再提供你可以照著做的檢查清單。你不需要先懂所有細節，但要能把每個假設驗證掉。最後再談一些避免反覆踩坑的維運做法。

快速判斷：你到底卡在哪一段

GCP帳號購買服務 連線流程大致可以拆成五段：

• GCP帳號購買服務 （1）目的地是否存在且可被訪問：Cloud SQL 實例狀態、所在網路、IP/私網配置。
• （2）通路是否打通：防火牆規則、VPC 連線、是否使用正確的代理或通道。
• GCP帳號購買服務 （3）你選的連線方式是否匹配環境：公網 IP、私網 IP、Auth Proxy、應用是否在同一網路或可路由。
• （4）身份驗證與授權：使用者帳號、權限、憑證/授權機制。
• （5）連線字串與驅動/參數：資料庫名稱、埠號、連線協定、SSL 設定、驅動版本。

很多錯誤其實可以靠關鍵字判斷類別：例如超時通常是網路或路由；拒絕連線常見於防火牆或埠被擋；認證失敗多半是帳號/權限或 SSL/憑證；錯誤的主機名或參數則是字串與工具設定問題。

第一部分：網路與防火牆（最常見）

1. 確認 Cloud SQL 實例狀態與 IP 開啟

先做最基本但最容易被忽略的檢查：實例是否為「可連線狀態」。在主控台確認：

• 實例是否啟用且沒有維護中或卡住的狀態。
• 你使用的是公網 IP 還是私網 IP。
• 如果使用公網 IP：是否已配置授權網路或允許連線的來源。
• 如果使用私網 IP：是否已建立對應的私網連線（Private Service Connect / VPC Peer / Private IP 相關設定依你的架構而定）。

很多人其實以為「已經在同一專案」就一定能連線，但 Cloud SQL 在網路層通常仍需符合特定條件。你必須確認你那端（跑程式的位置）到 Cloud SQL 的路徑確實存在。

2. 公網連線：授權網路與來源 IP

若你透過公網 IP 連線，最常見的問題是「來源 IP 不在授權範圍」。Cloud SQL 對公網入口會檢查授權網路。排查建議：

• 確認你應用實際對 Cloud SQL 送出的來源 IP 是什麼（不是你以為的那個）。如果你在 NAT 後，來源可能是 NAT 的出口 IP。
• 在 Cloud SQL 的授權網路設定中加入正確的 CIDR 或 IP。
• 若公司內網是動態出口，至少要先用可追蹤的出口 IP 測試，避免因為 IP 會變導致偶發失敗。

常見經驗是：測試在你本機成功，但上線失敗。因為上線環境出口 IP 跟你本機不同。你要以「上線實際出口」為準來配置授權網路。

3. 私網連線：VPC 路由與服務存取

若使用私網 IP，常見失敗原因是 VPC 之間沒有路由，或你所在的網段根本無法走到 Cloud SQL 的私網介面。

• 確認 Cloud SQL 的私網地址是否真的分配到你預期的 VPC（同一個 VPC 或已建立跨 VPC 的可達性）。
• 確認你執行程式的環境（例如 Compute Engine、GKE、Cloud Run（視設定而定））能到達該私網地址。
• GCP帳號購買服務 檢查防火牆規則（VPC 防火牆、以及子網路 ACL 若你有使用），是否允許到資料庫埠號的流量（常見是 5432/3306，依你使用的引擎而定）。

私網的問題常常不像公網那樣有「授權網路列表」可直接修，更多是你要確定網路拓撲正確。這也意味著你最好能在同一網路環境裡做連通性測試（例如先確認 DNS 與路由，再談登入）。

4. 使用代理（Cloud SQL Auth Proxy）時：埠轉發與網路綁定

許多人會採用 Cloud SQL Auth Proxy，讓你不用直接處理「來源 IP 授權」或複雜的私網路由。但代理本身也有一些配置與運作細節：代理把連線發到 Cloud SQL，並在你本機或容器內提供一個本地端口。

• 確認代理啟動成功，且提供的本地端口確實在監聽。
• 確認你的應用連到的是代理提供的「本地端口」，而不是直接連到 Cloud SQL 的公網/私網地址時混用設定。
• 若你把代理放在同一個容器或同一個 Pod，確保通訊是透過 localhost/正確網卡，而不是因為容器網路隔離連不到。

這類問題的典型訊號是：你可以看到代理有啟動的輸出，但應用連線仍超時或連不上代理端口。那通常是「埠/網卡/容器內部路由」問題，而不是 Cloud SQL 本身。

第二部分：身份驗證與權限

1. 連線失敗 vs 驗證失敗：先看錯誤訊息

如果你的錯誤訊息顯示「authentication failed」、「access denied」、「user not authorized」之類，通常不是網路層，而是身份驗證或資料庫內權限。

• 確認你連線使用的資料庫使用者帳號是否存在。
• 確認帳號密碼是否正確（尤其是環境變數、密碼管理工具、或部署管線在更新後是否同步）。
• 確認該帳號對目標資料庫是否有必要權限。

很多團隊會把「密碼」交給別人管理，但部署環境並不一定同步更新。你在本機可以連，是因為你用的密碼是最新的；上線用的是另一套環境變數或舊的 Secret。

2. 需要特定角色（IAM）嗎？取決於你的連線方式

如果你透過 Auth Proxy，往往需要代理使用的服務帳號具備特定權限（最常見是能存取該 Cloud SQL 實例）。若你直接用驅動連到 Cloud SQL，也可能牽涉到是否使用 IAM DB Authentication（取決於你採用的驗證機制）。

排查建議：

• 確認你使用的服務帳號（Service Account）是你以為的那一個。
• 確認服務帳號對目標 Cloud SQL 實例的授權。
• 如果你啟用了 IAM DB Authentication，確認資料庫端的設定與對應映射。

最常見的疏忽是：你給了角色給某個服務帳號，但部署時實際使用的是另一個（例如 Compute Engine/ GKE/ Cloud Run 默認服務帳號，或在設定中覆寫過）。你要以「實際部署使用的身份」為準。

第三部分：連線字串、參數與驅動

1. 埠號與引擎類型要對應

Cloud SQL 有不同引擎（例如 PostgreSQL、MySQL、SQL Server）。不同引擎對連線協定、埠號與連線參數有差異。你要確認：

• 你選的驅動程式對應該引擎。
• 埠號正確（例如 PostgreSQL 常見 5432，MySQL 常見 3306；SQL Server 還有其它條件）。
• 資料庫名稱（database/schema）在連線字串中正確。

這一類問題的典型表現是：連線失敗但錯誤訊息看起來像參數錯誤，或是驅動直接報「unknown host / invalid connection string」。

2. SSL/TLS 設定：有些環境不會自動幫你做好

許多連線失敗跟 SSL 相關。尤其當你在某些環境中明確要求 SSL 或限制 TLS 版本時，就會出現握手失敗。

排查方式：

• GCP帳號購買服務 查看錯誤訊息是否包含「SSL」、「TLS」、「handshake」、「certificate」。
• 確認 Cloud SQL 端對 SSL 的要求（例如是否需要強制 SSL）。
• 確認應用端是否提供必要的憑證或已開啟正確的驗證策略。

如果你使用的是代理，SSL 可能由代理處理，你應用端只需連到代理提供的本地端口；若你直接連到 Cloud SQL，SSL 設定就更要確認一致。

3. DNS 與主機名稱：別只看你填的字串

某些連線字串使用主機名（例如 instance connection name、或某些特定結構的主機標記）。如果你在不同環境中（本機、容器、不同網路）該主機名解析方式不同，就會出現「找不到主機」或解析到錯的地址。

• 確認你使用的主機名格式是否符合該驅動/該代理/你的網路環境。
• 檢查環境變數是否被覆寫，導致主機名或連線方式被切換。
• 必要時先在容器內做 DNS 解析/基本連通性測試，再回到登入流程。

第四部分：一個好用的排查流程（照做通常能收斂）

下面提供一個你可以複製到團隊內的排查順序。你不需要做到每一步都很深入，但要讓問題能快速分流。

步驟 1：先把網路分成「通不到」和「通得到」

• GCP帳號購買服務 若你遇到連線超時：先當作網路/路由問題處理。
• 若立刻拒絕：先當作防火牆/埠未開/安全政策問題。
• 若能建立 TCP 連線但登入失敗：再處理身份驗證/權限。

實務上你可以用簡單的方式先測「能否打到埠」，不必一開始就進到完整資料庫驅動。

步驟 2：確認連線方式是否一致

在專案中常見的坑是：同一份設定檔在不同環境切換了「是否走代理」但你沒有同步調整連線字串。結果可能是：

• 你以為連的是代理，但其實連到 Cloud SQL 公網 IP，卻沒有授權來源。
• 你以為連的是私網，但程式在本機跑，沒有私網路由。
• 你以為代理會代替 SSL，但其實你還在應用端要求嚴格 SSL 驗證。

因此你要檢查：目前環境變數或設定開關是否真的跟你的預期一致。

步驟 3：再看身份驗證與資料庫權限

網路打通後，如果錯誤仍存在，就不要再盲目調防火牆。轉而檢查：

• 帳號密碼是否正確（尤其是秘鑰更新流程）。
• 帳號是否具備必要的權限（例如連線、讀寫特定 schema）。
• 若使用 IAM DB Authentication：服務帳號是否正確、IAM 角色是否齊全、資料庫端是否映射。

步驟 4：最後才是驅動與參數

當網路、身份都沒問題，才去檢查驅動版本、連線字串格式、SSL 選項、以及資料庫名稱等細節。

因為驅動問題在比例上其實不如網路/授權常見，但一旦卡在最後一關，就很需要用清楚的訊息來定位。你可以把完整錯誤堆疊保留下來（至少包含錯誤類型與關鍵字），比猜更有效。

GCP帳號購買服務 第五部分：常見錯誤案例與對應解法

案例 A：本機連得上，上線連不上

這通常是出口 IP 或網路路由不同造成的。解法：

• 確認上線環境的實際來源 IP（NAT 出口）。
• 若使用公網 IP：把授權網路調整為包含上線來源 CIDR。
• 若使用私網 IP：確保上線環境所在 VPC 與路由能到達私網地址。

案例 B：使用 Auth Proxy，但應用說連不上本地端口

解法通常不是調 Cloud SQL，而是調代理與容器內部連通性：

• 檢查代理是否真的在監聽你配置的本地端口。
• 確認應用連的是 localhost 還是容器內可達的網卡。
• 檢查容器環境中是否缺少網路權限或代理以不同網卡綁定。

案例 C：認證失敗或密碼錯誤

解法：

• 核對應用端使用的 Secret 是否為最新版本。
• 確定資料庫使用者帳號存在且狀態可用。
• 如果有啟用 IAM 相關機制，確認服務帳號與資料庫端映射。

案例 D：SSL/TLS 握手失敗

解法：

• 檢查應用端 TLS 版本與驗證設定。
• 確認是否需要提供 CA 憑證或啟用特定的 SSL 模式。
• 若使用代理，確認你沒有在應用端再疊加不必要的嚴格 SSL 驗證。

第六部分：把解法變成流程：建議的設定與維運習慣

解決一次還不夠，真正省時間的是建立你們團隊可複用的設定方式與驗證流程。

1. 統一連線方式，避免「同時支援」造成設定漂移

如果你的程式同時支援「直接連」與「走代理」兩種模式，請確保：

• 開關條件清楚且環境變數有一致命名。
• 每個環境只啟用一種預期模式，降低誤用機率。
• 部署時要把實際使用的連線模式寫進日誌（至少在啟動時印出模式名稱與連線端口），讓你之後追問題更快。

2. 讓錯誤訊息可被定位：保留關鍵字與上下文

很多團隊遇到問題最後只能說「連不上」，但缺少關鍵錯誤資訊。建議把錯誤分類做得更清楚：

• 連線超時：網路/路由方向。
• 連線拒絕：防火牆/埠方向。
• 認證失敗：帳號/權限方向。
• SSL/TLS 錯誤：憑證/協定方向。

有了這些分類，你能更快地把任務分配給不同負責人（網路/資料庫/應用/憑證）。

3. 設定變更要可追蹤：特別是授權網路與 Secret

最常見的連線問題其實是「先前能連，後來不能」。所以請把以下變更納入可追蹤範圍：

• GCP帳號購買服務 Cloud SQL 授權網路（公網）調整。
• 私網連線與 VPC 相關設定變更。
• 密碼/Secret 更新與部署節點。

當你能回頭看「到底哪次變更後開始失敗」，排查時間會大幅縮短。

結語：以收斂思維修復連線失敗

Google Cloud SQL 連線失敗的解法，不是靠一次試錯，而是靠你把問題分層：先確認實例與網路通路，再確認授權與身份驗證，最後才是連線字串、驅動與 SSL 細節。只要你遵守這個順序，通常不會陷入無限重試。

如果你願意，把本文的排查流程變成團隊 SOP，並在每次修復後補上你們遇到的具體錯誤訊息與對應結論，長期下來會節省非常多時間。連線問題看似瑣碎，但一旦你建立了可重用的檢查邏輯，就會從「每次都重新猜」變成「每次都快速定位」。