View a markdown version of this page

排除私有连接故障 - AWS DevOps 代理人
DNS 主机地址无法解析，或者流量到达错误的地方连接停滞在 “创建失败”连接处于活动状态，但功能注册因可访问性错误而失败无法访问 OAuth 代币交易所删除连接后，资源网关或 ENI 仍然存在请求帮助相关主题

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

排除私有连接故障

本页介绍在创建或使用 AWS DevOps 代理时可能遇到连接到私人托管的工具的常见问题以及如何解决这些问题。每个部分都描述了症状、最可能的原因以及修复该症状的步骤。

有关私有连接工作原理的概述，请参阅连接到私人托管的工具。

DNS 主机地址无法解析，或者流量到达错误的地方

症状

您使用主机地址的 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) 解析主机地址。如果您的主机名仅在私有托管区域、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 环境中解析的，因此仅限私有的主机名可以正确解析。请参阅创建私有连接。

  • 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 地址。资源网关在您指定的子网中提供弹性网络接口 (ENI)。如果这些子网耗尽，则创建失败。选择具有可用地址空间的子网。

  3. 您的子网位于支持的可用区内。亚马逊 VPC 莱迪思并不支持所有可用区。运行以下命令并与创建私有连接中列出的不支持的区域进行比较：

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

  1. 您尚未达到亚马逊 VPC 莱迪思服务配额。根据亚马逊 VPC Lattice 配额，尤其是资源网关限制，检查您的账户。

  2. 没有 IAM 政策或 SCP 阻止服务相关角色。服务管理的资源网关是通过服务相关角色创建的。如果您的组织制定了限制亚马逊 VPC Lattice 或 Amazon EC2 API 操作的服务控制策略 (SCP)，请确保这些策略允许服务相关角色创建这些资源。

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

连接处于活动状态，但功能注册因可访问性错误而失败

症状

私有连接处于活动状态，但是当您注册使用该连接的能力提供者（例如 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 入站。请参阅为私有连接配置防火墙规则。

  • 验证私有 CA 的完整证书链。如果私有证书颁发机构颁发了您的服务的 TLS PEM-encoded 证书，请在创建连接时提供完整的证书链。首先放置树叶证书，然后放置中间证书，然后放置根证书。如果链不完整，即使网络路径已启动，TLS 握手也会失败。

  • 确认目标正在运行。在完成注册之前，请确保您的服务已启动并接受预期端口上的连接。

无法访问 OAuth 代币交易所

症状

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

原因

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

解决方法

  • 如果两个端点都可以通过相同的路径访问，请确保私有连接的主机地址可以路由到 MCP 服务器端点和令牌交换端点。

  • 如果端点需要不同的网络路径，请使用每个端点字段，而不是单privateConnectionName个字段。targetUrlPrivateConnectionName为 MCP 服务器端点和exchangeUrlPrivateConnectionName令牌交换端点设置。如果您仅设置一个，则另一个终端节点将通过公共互联网访问，并且它不会回退到另一个私有连接。您不能在同一个请求中将每个端点privateConnectionName的名称与组合在一起。请参阅通过不同的私有连接路由端点和 OAuth 令牌交换。

删除连接后，资源网关或 ENI 仍然存在

症状

您预计托管资源网关及其 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 支持部门协调资源。

请求帮助

如果您仔细阅读了问题的相关部分，但问题仍然存在，请联系客 AWS 服。包括您的私有连接名称、其当前状态、 AWS 区域以及目标主机地址和端口，以便支持人员可以调查网络路径。