View a markdown version of this page

對私有連線進行故障診斷 - AWS DevOps 代理程式
DNS 主機地址無法解析，或流量到達錯誤的位置連線卡在建立失敗連線為作用中，但功能註冊失敗並出現連線能力錯誤無法連線 OAuth 權杖交換在您刪除連線後，資源閘道或 ENIs仍會保留請求協助相關主題

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

對私有連線進行故障診斷

此頁面說明您在建立或使用 連線至私有託管工具 for AWS DevOps 代理程式時可能遇到的常見問題，以及如何解決這些問題。每個區段都會說明症狀、最可能的原因，以及修正該症狀的步驟。

如需私有連線運作方式的概觀，請參閱 連線至私有託管工具。

DNS 主機地址無法解析，或流量到達錯誤的位置

徵狀

您已使用主機地址的 DNS 名稱建立私有連線，但連線無法連線您的服務。當您的目標服務是自我託管的 GitLab 執行個體、內部 Application Load Balancer (ALB) 或主機名稱僅存在於 VPC 中的 MCP 伺服器時，這是最常見的情況。

DNS 解析失敗不會產生提及 DNS 的訊息。相反地，當您註冊或使用功能提供者時，它會顯示為一般連線能力或提供者錯誤。例如，您可能會看到 Could not complete request to provider.、 Unable to connect to the MCP server at <endpoint>. The connection was interrupted.或 等身分驗證錯誤，Authentication with provider failed.因為訊息不會指向 DNS，請使用下列檢查來確認原因。

原因

根據預設，私有連線會使用公有 DNS () 解析主機地址dnsResolution: PUBLIC。如果您的主機名稱在私有託管區域中只有記錄、Amazon Route 53 Resolver 規則或內部部署 DNS 伺服器，則公有解析會失敗，且連線永遠不會到達您的服務。

如何確認 DNS 是原因

  • 檢查您的主機地址是否只在 VPC 內解析。從相同 VPC 中的 Amazon EC2 執行個體或 AWS CloudShell 工作階段中，執行 nslookup <your-host-address>。如果它在那裡解析，但不是從公有 DNS 解析，而且您的私有連線使用 dnsResolution: PUBLIC，則 DNS 解析是原因。

  • 使用 IP 地址而非名稱進行測試。暫時建立私有連線，使用目標的私有 IP 地址 （或負載平衡器 IP) 做為主機地址，而非 DNS 名稱。如果連線接著到達您的服務，則先前的失敗是 DNS 解析，而不是網路路徑或服務本身。

解決方案

  • 如果您的主機名稱僅在 VPC 內解析，請在建立連線時將 DNS 解析模式設為在 VPC () 中。IN_VPC在此模式中，主機地址會從您的 VPC 內容中解析，因此僅限私有的主機名稱會正確解析。請參閱建立私有連線。

  • DNS 解析模式是在建立時選擇，並套用到您提供的主機地址。您無法變更服務受管資源閘道在建立後解析 DNS 的方式，因此請預先選擇正確的模式。如果您選擇了錯誤的模式，請刪除連線，然後使用正確的模式重新建立連線。

  • 如果您為主機地址指定 IP 地址 （而非 DNS 名稱），DNS 解析模式不會生效，且流量會直接進入該 IP。

  • 如果您無法使用 IN_VPC 進行設定，您可以改為將主機地址指向目標的私有 IP 地址，或指向可公開解析但轉送至私有 IP 的負載平衡器的 DNS 名稱。

連線卡在建立失敗

徵狀

建立私有連線後，主控台會將狀態顯示為連線失敗 （並describe-private-connection傳回 的狀態CREATE_FAILED)。回應通常不包含失敗的詳細原因，因此您不會留下錯誤訊息來採取行動。

原因

建立失敗最常見的原因是請求或 VPC 中的組態問題，而不是服務錯誤。由於詳細的失敗原因並非總是出現，即使未顯示錯誤訊息，也請執行下列檢查清單。

解決方案

依序驗證下列項目：

  1. 連接埠範圍使用有效的格式。將每個連接埠範圍指定為單一連接埠 （例如 443) 或具有不同開始和結束連接埠的真正範圍 （例如 8080-8090)。開始和結束相同 （例如 443-443) 的「範圍」會遭到拒絕。您最多可以指定 11 個連接埠範圍。

  2. 您的子網路具有可用的 IP 地址。資源閘道會在您指定的子網路中佈建彈性網路介面 (ENIs)。如果這些子網路用盡，建立會失敗。選擇具有可用地址空間的子網路。

  3. 您的子網路位於支援的可用區域。Amazon VPC Lattice 不支援每個可用區域。執行下列動作，並與建立私有連線 中列出的不支援區域進行比較：

aws ec2 describe-subnets \ --subnet-ids <your-subnet-ids> \ --query 'Subnets[*].[SubnetId,AvailabilityZoneId]'

  1. 您尚未達到 Amazon VPC Lattice 服務配額。檢查您的帳戶是否符合 Amazon VPC Lattice 配額，尤其是資源閘道限制。

  2. 沒有 IAM 政策或 SCP 封鎖服務連結角色。服務受管資源閘道是透過服務連結角色建立。如果您的組織具有限制 Amazon VPC Lattice 或 Amazon EC2 API 動作的服務控制政策 (SCPs)，請確保它們允許服務連結角色建立這些資源。

如果在您驗證所有這些項目後連線仍持續失敗，請聯絡 AWS Support。

連線為作用中，但功能註冊失敗並出現連線能力錯誤

徵狀

私有連線達到作用中狀態，但當您註冊使用它的功能提供者 （例如 MCP 伺服器） 時，註冊會失敗。對於 MCP 伺服器，錯誤訊息會說明連線能力檢查失敗的方式。您可能會看到下列其中一項：

  • The MCP server at '<endpoint>' timed out while initializing the session. （類似的變體是指列出資源）

  • Unable to connect to the MCP server at <endpoint>. The connection was interrupted. Verify the server is running and accessible, then try again.

  • Unable to access tools from the MCP server at '<endpoint>' ...

  • Could not complete request to provider. （也可能顯示為 API error: 504)

原因

到達 Active 的私有連線會確認 VPC 的網路路徑已建立。它不會確認您的目標服務在預期的地址和連接埠上回應。當您註冊功能提供者時， AWS DevOps 代理程式會驗證端點是否可連線和回應，而這是設定錯誤的目標表面。訊息會告訴您哪個 layer 失敗：

  • 逾時訊息表示連線從未到達接聽服務。大多數情況下，主機地址、連接埠或 DNS 解析錯誤，或安全群組封鎖流量。

  • 連線中斷訊息表示連線已重設或捨棄，通常是由於 TLS 交握失敗或服務關閉連線。

  • 無法存取工具訊息表示端點已回應但拒絕請求。這通常是授權或供應商端錯誤，而不是網路問題。

  • 答 無法完成對提供者訊息的請求是一般失敗，無法透過私有連線完成對端點的請求。檢閱接下來的解決步驟。

解決方案

  • 將 DNS 指向負載平衡器，而不是任務或執行個體 IP。常見原因是 DNS 記錄或主機地址，可解析為應用程式連接埠 （例如 8100) 上的容器任務或執行個體 IP，而不是在您設定的連接埠 （例如 ) 上終止 TLS 的負載平衡器443。確認主機地址解析為在目標連接埠上實際提供 HTTPS 的端點。

  • 確認服務在設定的連接埠上提供 HTTPS。目標必須在連線連接埠範圍中包含的連接埠上，提供最低 TLS 版本為 1.2 的 HTTPS。

  • 檢查雙向的安全群組規則。驗證連接至資源閘道 ENIs的安全群組是否允許目標連接埠上的傳出流量，以及您服務的安全群組是否允許該連接埠上的傳入流量。流量來自 VPC CIDR 範圍內的 Amazon VPC Lattice 資料平面 IPs。您可以使用安全群組參考 （允許 ENI 安全群組做為來源） 或允許從 VPC CIDR 傳入。請參閱設定私有連線的防火牆規則。

  • 驗證私有 CA 的完整憑證鏈。如果私有憑證授權機構發行服務的 TLS 憑證，請在建立連線時提供完整的 PEM 編碼憑證鏈。先放置分葉憑證，再放置中繼憑證，再放置根憑證。如果鏈不完整，即使網路路徑啟動，TLS 交握也會失敗。

  • 確認目標正在執行。在完成註冊之前，請確定您的服務已啟動，並在預期的連接埠上接受連線。

無法連線 OAuth 權杖交換

徵狀

您已透過私有連線註冊 OAuth 型 MCP 伺服器功能提供者 （用戶端登入資料或 3LO)，但即使 MCP 伺服器端點可連線，權杖交換仍會失敗。

原因

對於以 OAuth 為基礎的功能提供者， AWS DevOps 代理程式會呼叫兩個端點：目標 URL (MCP 伺服器端點） 和交換 URL (OAuth 字符交換端點）。當您選取單一私有連線時，它會套用到兩個端點。如果兩個端點只能透過不同的網路路徑連接，則單一私有連線無法路由到兩者。

解決方案

  • 如果兩個端點都可以透過相同路徑連線，請確保私有連線的主機地址可以同時路由到 MCP 伺服器端點和字符交換端點。

  • 如果端點需要不同的網路路徑，請使用每個端點欄位，而不是單一 privateConnectionName。targetUrlPrivateConnectionName 為 MCP 伺服器端點和exchangeUrlPrivateConnectionName字符交換端點設定 。如果您只設定一個端點，則會透過公有網際網路到達另一個端點，而不會回到另一個私有連線。您無法在相同的請求privateConnectionName中結合每個端點名稱與 。請參閱透過不同的私有連線路由端點和 OAuth 權杖交換。

在您刪除連線後，資源閘道或 ENIs仍會保留

徵狀

您預期會移除受管資源閘道及其 ENIs，但它們仍會出現在您的 VPC 中。這可能會產生 ENI 費用，並封鎖依賴於乾淨 VPC 的操作，例如 terraform destroy。

原因

只有在您透過 AWS DevOps 代理程式刪除私有連線時，才會移除受管資源閘道和 ENIs。其保留的最常見原因是DeletePrivateConnection從未實際呼叫 ，或AWSAIDevOpsManaged標籤已從受管資源中移除，因此無法繼續刪除。

重要

AWS DevOps 代理程式會使用 標記其管理的資源 （資源閘道及其 ENIs)AWSAIDevOpsManaged。服務連結角色只能對帶有此標籤的資源採取行動，因此請勿移除或修改AWSAIDevOpsManaged標籤 。如果標籤遺失， DeletePrivateConnection 無法清除資源，且刪除失敗。

解決方案

  • 透過 AWS DevOps Agent 刪除連線。使用 主控台 (功能提供者 > 私有連線 > 動作 > 移除) 或 CLI：

aws devops-agent delete-private-connection \ --name my-mcp-tool-connection

狀態會變更為 ，DELETE_IN_PROGRESS而 AWS DevOps 代理程式會從 VPC 中移除受管資源閘道和 ENIs。

  • 如果刪除失敗，請確認AWSAIDevOpsManaged標籤仍然存在。如果標籤已從資源閘道或其 ENIs中移除，請重新套用至這些資源，然後再次執行刪除。

  • 請勿嘗試直接刪除受管資源閘道。資源閘道在您的帳戶中為唯讀，並由 AWS DevOps 代理程式完整管理，您無法透過 Amazon VPC Lattice 自行刪除。刪除私有連線會觸發其移除。

  • 如果您刪除私有連線，且標籤存在，且在刪除完成後資源閘道或 ENIs 仍然保留，請聯絡 AWS Support 以協調資源。

請求協助

如果您處理問題的相關區段，但問題仍然存在，請聯絡 AWS Support。包含您的私有連線名稱、其目前狀態、 AWS 區域，以及目標主機地址和連接埠，以便支援可以調查網路路徑。