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

# 對私有連線進行故障診斷
<a name="configuring-integrations-and-knowledge-troubleshooting-private-connections"></a>

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

如需私有連線運作方式的概觀，請參閱 [連線至私有託管工具](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)。

## DNS 主機地址無法解析，或流量到達錯誤的位置
<a name="a-dns-host-address-doesnt-resolve-or-traffic-reaches-the-wrong-place"></a>

**徵狀**

您已使用主機地址的 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`。如果您的主機名稱在[私有託管區域中](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html)只有記錄、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 內容中解析，因此僅限私有的主機名稱會正確解析。請參閱[建立私有連線](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)。
+ DNS 解析模式是在建立時選擇，並套用到您提供的主機地址。您無法變更服務受管資源閘道在建立後解析 DNS 的方式，因此請預先選擇正確的模式。如果您選擇了錯誤的模式，請刪除連線，然後使用正確的模式重新建立連線。
+ 如果您為主機**地址指定 IP** 地址 （而非 DNS 名稱），DNS 解析模式不會生效，且流量會直接進入該 IP。
+ 如果您無法使用 `IN_VPC` 進行設定，您可以改為將主機地址指向目標的私有 IP 地址，或指向可公開解析但轉送至私有 IP 的負載平衡器的 DNS 名稱。

## 連線卡在建立失敗
<a name="the-connection-is-stuck-in-create-failed"></a>

**徵狀**

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

**原因**

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

**解決方案**

依序驗證下列項目：

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

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

1. **您的子網路位於支援的可用區域。**Amazon VPC Lattice 不支援每個可用區域。執行下列動作，並與[建立私有連線](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md) 中列出的不支援區域進行比較：

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

1. **您尚未達到 Amazon VPC Lattice 服務配額。**檢查您的帳戶是否符合 [Amazon VPC Lattice 配額](https://docs.aws.amazon.com/vpc-lattice/latest/ug/quotas.html)，尤其是資源閘道限制。

1. **沒有 IAM 政策或 SCP 封鎖服務連結角色。**服務受管資源閘道是透過[服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)建立。如果您的組織具有限制 Amazon VPC Lattice 或 Amazon EC2 API 動作[的服務控制政策 (SCPs)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html)，請確保它們允許服務連結角色建立這些資源。

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

## 連線為作用中，但功能註冊失敗並出現連線能力錯誤
<a name="the-connection-is-active-but-capability-registration-fails-with-a-reachability-error"></a>

**徵狀**

私有連線達到**作用中**狀態，但當您註冊使用它的功能提供者 （例如 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 傳入。請參閱[設定私有連線的防火牆規則](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)。
+ **驗證私有 CA 的完整憑證鏈。**如果私有憑證授權機構發行服務的 TLS 憑證，請在建立連線時提供完整的 PEM 編碼憑證鏈。先放置分葉憑證，再放置中繼憑證，再放置根憑證。如果鏈不完整，即使網路路徑啟動，TLS 交握也會失敗。
+ **確認目標正在執行。**在完成註冊之前，請確定您的服務已啟動，並在預期的連接埠上接受連線。

## 無法連線 OAuth 權杖交換
<a name="oauth-token-exchange-cant-be-reached"></a>

**徵狀**

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

**原因**

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

**解決方案**
+ 如果兩個端點都可以透過相同路徑連線，請確保私有連線的主機地址可以同時路由到 MCP 伺服器端點和字符交換端點。
+ 如果端點需要不同的網路路徑，請使用每個端點欄位，而不是單一 `privateConnectionName`。`targetUrlPrivateConnectionName` 為 MCP 伺服器端點和`exchangeUrlPrivateConnectionName`字符交換端點設定 。如果您只設定一個端點，則會透過公有網際網路到達另一個端點，而不會回到另一個私有連線。您無法在相同的請求`privateConnectionName`中結合每個端點名稱與 。請參閱[透過不同的私有連線路由端點和 OAuth 權杖交換](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)。

## 在您刪除連線後，資源閘道或 ENIs仍會保留
<a name="resource-gateway-or-enis-remain-after-you-delete-a-connection"></a>

**徵狀**

您預期會移除受管資源閘道及其 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 以協調資源。

## 請求協助
<a name="requesting-help"></a>

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

## 相關主題
<a name="related-topics"></a>
+ [連線至私有託管工具](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)
+ [設定私有連線的防火牆規則](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)
+ [VPC 端點 (AWS PrivateLink)](aws-devops-agent-security-vpc-endpoints-aws-privatelink.md)
+ [連接 MCP 伺服器](configuring-integrations-and-knowledge-connecting-mcp-servers.md)
+ [AWS DevOps 代理程式安全性](aws-devops-agent-security.md)