本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
排除私有连接故障
本页介绍在创建或使用 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 中的配置问题导致的，而不是服务错误。当连接处于失败状态时， AWS DevOps 代理会在failureMessage字段中描述原因，因此请在完成清单之前阅读该字段。
解决方法
按顺序验证以下内容：
阅读连接
failureMessage的详细信息。此字段描述连接为何处于失败状态，并且在状态为CREATE_FAILED或时出现DELETE_FAILED：
aws devops-agent describe-private-connection \ --name my-mcp-tool-connection
failureMessage也出现在的输出中list-private-connections。如果该字段列出了原因，请采取行动。如果该字段不存在，则不返回任何原因，因此请继续进行剩余检查。
端口范围使用有效格式。将每个端口范围指定为单个端口（例如
443）或具有不同起始和结束端口的真实范围（例如，8080-8090）。起点和终点相同（例如443-443）的 “范围” 将被拒绝。您最多可以指定 11 个端口范围。您的子网有可用的 IP 地址。资源网关在您指定的子网中提供弹性网络接口 (ENI)。如果这些子网耗尽，则创建将失败。选择具有可用地址空间的子网。
您的子网位于支持的可用区内。亚马逊 VPC Lattice 并不支持所有可用区。运行以下命令并与创建私有连接中列出的不支持的区域进行比较：
aws ec2 describe-subnets \ --subnet-ids <your-subnet-ids> \ --query 'Subnets[*].[SubnetId,AvailabilityZoneId]'
您尚未达到亚马逊 VPC 莱迪思服务配额。根据亚马逊 VPC Lattice 配额，尤其是资源网关限制，检查您的账户。
没有 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 握手失败或服务关闭连接所致。
无法访问工具消息表示终端已响应但拒绝了请求。这通常是授权或提供商端的错误，而不是网络问题。
无法完成向提供商发出的请求消息是指无法通过私有连接完成对您的终端节点的请求。查看随后的解决步骤。
来自您的 VPC 中的 Amazon EC2 实例或 AWS CloudShell 会话的成功请求确认该测试环境可以访问该服务。它不确认资源网关使用相同的终端节点 URL、端口、DNS 目标或 TLS 配置。
如何确认
使用您注册的确切端点 URL（包括其路径和任何非默认端口）重复测试。
确认端点 URL 的端口包含在私有连接的端口范围中。
确认私有连接的主机地址解析到终止该端口上的 TLS 的负载均衡器或服务，而不是解析到其他应用程序端口上的任务或实例 IP。
确认目标提供带有 TLS 1.2 或更高版本的 HTTPS，并显示预期的证书链。
确认资源网关安全组允许目标端口上的出站流量，并且目标安全组允许相应的入站流量。
解决方法
确认连接的端口范围包括端点的端口。私有连接仅在创建时配置的端口范围内转发流量。如果您未指定端口范围，则连接仅允许端口
443。该连接会丢弃任何其他端口的流量，而不会出现描述性错误。丢失的流量会以超时、错误或Unable to access tools错误的形式出Could not complete request to provider.现。这通常会影响非标准端口上的端点（例如，https://tools.example.com:8089/mcp）。在同一 VPC 中的 EC2 实例上成功curl运行并不排除这种情况——该测试完全绕过了私有连接。创建后无法更改端口范围。删除私有连接，使用包括终端节点 URL 中所有端口的端口范围重新创建该连接，然后重新注册能力提供商。确认资源网关完全可以到达您的目标。这是首先要排除目标在其他 AWS 账户或本地运行的情况。在服务管理模式下，资源网关是在您指定的 VPC 和子网中创建的，与私有连接使用的账户相同，因此 VPC 需要一条通往目标的路由。连接达到 A ctive 仅表示网关的网络接口已创建且运行正常；这并不意味着它们可以访问您的服务。检查连接模式和网关的 VPC，然后确认路由：
aws devops-agent list-private-connections aws vpc-lattice list-resource-gateways
如果网关的 VPC 没有通往目标的路由，请通过 VPC 对等互连、T AWS ransit Gateway 或虚拟专用网络 (VPN) 连接添加路由，或者使用自管理模式将网关移至目标账户。请参阅创建私有连接。
将 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 握手也会失败。有关由此产生的错误消息，请参阅提供商的 TLS 证书不可信。
确认目标正在运行。在完成注册之前，请确保您的服务已启动并接受预期端口上的连接。
提供商的 TLS 证书不可信
症状
注册或使用能力提供者因证书错误而失败。措辞取决于能力类型，但所有这些都描述了同一类问题：
Could not establish a trusted TLS connection to the provider host: its certificate could not be validated against a publicly trusted certificate authority.The server is using a self-signed TLS certificate. Use a certificate from a publicly trusted certificate authority.The server's TLS certificate could not be verified. Ensure the full certificate chain is served and issued by a publicly trusted certificate authority.The server's TLS certificate has expired. Renew the certificate.The server's TLS certificate does not match the endpoint hostname. Ensure the certificate covers the endpoint's domain.
原因
AWS DevOps 代理无法验证您的服务提供的证书链。常见原因是私有或内部证书颁发机构 (CA) 颁发的证书、缺少中间证书的链、链中证书过期或证书未涵盖您的端点 URL 中的主机名。
注意
这些消息要求公开信任的 CA 颁发证书，但支持私有 CA。如解析步骤所述，通过私有连接供应链。
如何确认
从可以到达目标的 Amazon EC2 实例或 AWS CloudShell 会话中，检查您的服务在您配置的端口上呈现的链，并检查哪个 CA 签署了其顶部：
openssl s_client -connect <your-host-address>:<port> -showcerts
如果内部 CA 签署了证书，则在连接上提供链。如果公共 CA 对其进行了签名，则您的服务发送的链可能不完整。
解决方法
对于来自私有 CA 的证书，请在私有连接上提供完整的链。将控制台中的证书公钥或中的
certificatecreate-private-connection字段设置为完整 PEM-encoded 链：首先是叶子证书，然后是所有中间 CA 证书，然后是根。请参阅创建私有连接。要获得来自公共 CA 的证书，请发送完整的证书链。将您的服务配置为发送分支证书和所有中间证书，而不仅仅是叶子证书。
替换链中所有过期的证书。
确认证书涵盖您的端点 URL 中的主机名。
无法访问 OAuth 代币交易所
症状
您通过私有连接注册了使用 OAuth 客户端凭据的 OAuth-based MCP 服务器（客户端凭据或 3LO）或远程代理，但即使可以访问 MCP 服务器或远程代理端点，令牌交换也会失败。
原因
对于 OAuth-based 能力提供者， AWS DevOps 代理调用两个端点：目标 URL（MCP 服务器或远程代理端点）和交换 URL（OAuth 令牌交换端点）。当您选择单个私有连接时，它适用于两个端点。如果只能通过不同的网络路径访问这两个端点，则单个私有连接无法路由到两个端点。
解决方法
如果两个端点都可以通过相同的路径访问，请确保私有连接的主机地址可以路由到 MCP 服务器或远程代理端点以及令牌交换端点。
如果端点需要不同的网络路径，请使用每个端点字段，而不是单
privateConnectionName个字段。targetUrlPrivateConnectionName为 MCP 服务器或远程代理端点以及令牌交换端点exchangeUrlPrivateConnectionName进行设置。如果您仅设置一个，则另一个终端节点将通过公共互联网访问，并且它不会回退到另一个私有连接。您不能在同一个请求中将每个端点privateConnectionName的名称与组合在一起。请参阅通过不同的私有连接路由端点和 OAuth 令牌交换。
私有连接在使用时无法删除
症状
删除私有连接失败 Private connection '<name>' is in use by one or more services. Deregister the services first.
原因
当注册的能力提供者仍在引用私有连接时，无法删除该连接。 AWS DevOps 代理在删除任何资源之前拒绝删除，因此您的连接将保持当前状态。
解决方法
确定使用该连接的能力提供者，然后取消注册或对其进行更新，使其不再使用该连接。
删除私有连接。
从代理空间中移除能力提供者与取消注册能力提供者并不相同。账户级别存在注册，因此请将其从所有代理空间中删除，然后删除该注册，然后再删除连接。
删除连接后，资源网关或 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 区域以及目标主机地址和端口，以便支持人员可以调查网络路径。
相关主题
