本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 排除私有连接故障
<a name="configuring-integrations-and-knowledge-troubleshooting-private-connections"></a>

本页介绍在创建或使用 AWS DevOps 代理时可能遇到[连接到私人托管的工具](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)的常见问题以及如何解决这些问题。每个部分都描述了症状、最可能的原因以及修复该症状的步骤。

有关私有连接工作原理的概述，请参阅[连接到私人托管的工具](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 实例、内部应用程序负载均衡器 (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 解析器规则或本地 DNS 服务器中有记录，则公共解析失败，连接永远不会到达您的服务。

**如何确认 DNS 是原因 **
+ 检查您的主机地址是否只能在您的 VPC 内部解析。在同一 VPC 中的 Amazon EC2 实例或 AWS CloudShell 会话中运行`nslookup <your-host-address>`。如果它在那里解析但不是从公有 DNS 解析，而你的私有连接使用`dnsResolution: PUBLIC`，那么 DNS 解析就是原因。
+ 使用 IP 地址而不是名称进行测试。临时创建一个私有连接，使用目标的私有 IP 地址（或负载均衡器 IP）作为主机地址，而不是 DNS 名称。如果连接随后到达您的服务，则之前的故障是 DNS 解析，而不是网络路径或服务本身。

**解决方法**
+ 如果您的主机名仅在您的 VPC 内部解析，请在创建连接时将 ** DNS 解析模式设置为 In 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 地址。**资源网关在您指定的子网中提供弹性网络接口 (ENI)。如果这些子网耗尽，则创建失败。选择具有可用地址空间的子网。

1. **您的子网位于支持的可用区内。**亚马逊 VPC 莱迪思并不支持所有可用区。运行以下命令并与[创建私有连接](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)中列出的不支持的区域进行比较：

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

1. **您尚未达到亚马逊 VPC 莱迪思服务配额。**根据[亚马逊 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)如果您的组织制定了限制亚马逊 VPC Lattice 或 Amazon EC2 API 操作的[服务控制策略 (SCP)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html)，请确保这些策略允许服务相关角色创建这些资源。

如果验证所有这些项目后连接仍然失败，请联系 AWS 支持部门。

## 连接处于活动状态，但功能注册因可访问性错误而失败
<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`）

**原因**

到达 A ** ctive 的私有连接**确认您的 VPC 的网络路径已建立。它无法确认您的目标服务是否在预期的地址和端口上应答。当您注册能力提供者时， AWS DevOps 代理会验证端点是否可访问且可以响应，而这正是配置错误的目标出现的地方。该消息告诉你哪一层失败了：
+ **超时**消息表示连接从未到达监听服务。大多数情况下，主机地址、端口或 DNS 解析错误，或者安全组阻塞了流量。
+ **连接中断**消息表示连接已重置或断开，通常是由于 TLS 握手失败或服务关闭连接所致。
+ **无法访问工具**消息表示终端已响应但拒绝了请求。这通常是授权或提供商端的错误，而不是网络问题。
+ **无法完成向提供商**发出的请求消息是指无法通过私有连接完成对您的终端节点的请求。查看随后的解决步骤。

**解决方法**
+ **将 DNS 指向负载均衡器，而不是任务或实例 IP。**常见的原因是 DNS 记录或主机地址解析为应用程序端口（例如`8100`）上的容器任务或实例 IP，而不是负载均衡器在您配置的端口（例如）上终止 TLS。`443`确认主机地址解析为在目标端口上实际提供 HTTPS 的端点。
+ **确认该服务在配置的端口上提供 HTTPS。**目标必须在连接端口范围中包含的端口上提供至少 TLS 版本 1.2 的 HTTPS。
+ **双向检查安全组规则。**验证连接到资源网关 ENI 的安全组是否允许目标端口上的出站流量，以及您的服务的安全组是否允许该端口上的入站流量。流量来自您的 VPC CIDR 范围内的亚马逊 VPC 莱迪思数据平面 IP。您可以使用安全组引用（允许 ENI 安全组作为来源）或允许从 VPC CIDR 入站。请参阅为私有连接[配置防火墙规则](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)。
+ **验证私有 CA 的完整证书链。**如果私有证书颁发机构颁发了您的服务的 TLS PEM-encoded 证书，请在创建连接时提供完整的证书链。首先放置树叶证书，然后放置中间证书，然后放置根证书。如果链不完整，即使网络路径已启动，TLS 握手也会失败。
+ **确认目标正在运行。**在完成注册之前，请确保您的服务已启动并接受预期端口上的连接。

## 无法访问 OAuth 代币交易所
<a name="oauth-token-exchange-cant-be-reached"></a>

**症状**

您通过私有连接注册了 OAuth-based MCP 服务器功能提供商（客户端凭证或 3LO），但是即使可以访问 MCP 服务器端点，令牌交换也会失败。

**原因**

对于 OAuth-based 能力提供者， AWS DevOps 代理调用两个端点：**目标 URL**（MCP 服务器端点）和**交换 URL**（OAuth 令牌交换端点）。当您选择单个私有连接时，它适用于*两个*端点。如果只能通过不同的网络路径访问这两个端点，则单个私有连接无法路由到两个端点。

**解决方法**
+ 如果两个端点都可以通过相同的路径访问，请确保私有连接的主机地址可以路由到 MCP 服务器端点和令牌交换端点。
+ 如果端点需要不同的网络路径，请使用每个端点字段，而不是单`privateConnectionName`个字段。`targetUrlPrivateConnectionName`为 MCP 服务器端点和`exchangeUrlPrivateConnectionName`令牌交换端点设置。如果您仅设置一个，则另一个终端节点将通过公共互联网访问，并且它不会回退到另一个私有连接。您不能在同一个请求中将每个端点`privateConnectionName`的名称与组合在一起。请参阅通过不同的私有连接[路由端点和 OAuth 令牌交换。](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)

## 删除连接后，资源网关或 ENI 仍然存在
<a name="resource-gateway-or-enis-remain-after-you-delete-a-connection"></a>

**症状**

您预计托管资源网关及其 ENI 将被移除，但它们仍会出现在您的 VPC 中。这可能会产生 ENI 费用，并可能阻止依赖于干净 VPC 的操作，例如`terraform destroy`。

**原因**

只有当您通过 AWS DevOps 代理删除私有连接时，才会移除托管资源网关和 ENI。它们仍然存在的最常见原因`DeletePrivateConnection`是从未实际调用过，或者`AWSAIDevOpsManaged`标签已从托管资源中移除，因此无法继续删除。

**重要**  
** AWS DevOps 代理使用其管理的资源（资源网关及其 ENI）进行`AWSAIDevOpsManaged`标记。服务相关角色只能对带有此标签的资源执行操作，因此**请勿删除或修改`AWSAIDevOpsManaged`标签**。如果缺少标签，则`DeletePrivateConnection`无法清理资源，删除将失败。

**解决方法**
+ **通过 AWS DevOps 代理删除连接。**使用控制台（**能力提供者 ** > ** 私有连接 ** > ** 操作 ** > ** 删除**）或 CLI：

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

`DELETE_IN_PROGRESS`当 AWS DevOps 代理从您的 VPC 中删除托管资源网关和 ENI 时，状态更改为。
+ **如果删除失败，请确认`AWSAIDevOpsManaged`标签仍然存在。**如果标签已从资源网关或其 ENI 中移除，请将其重新应用于这些资源，然后再次运行删除操作。
+ **不要尝试直接删除托管资源网关。**资源网关在您的账户中是只读的，完全由 AWS DevOps 代理管理，您无法通过 Amazon VPC Lattice 自行将其删除。删除私有连接是触发其删除的原因。
+ 如果您删除了私有连接，标签存在，并且资源网关或 ENI 在删除完成后仍然保留，请联系 AWS 支持部门协调资源。

## 请求帮助
<a name="requesting-help"></a>

如果您仔细阅读了问题的相关部分，但问题仍然存在，请联系客 AWS 服。包括您的私有连接名称、其当前状态、 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)