View a markdown version of this page

設定閘道端點的自訂網域名稱 - Amazon Bedrock AgentCore
先決條件解決方案概觀實作步驟測試您的自訂網域設定 MCP 用戶端其他考量疑難排解結論

設定閘道端點的自訂網域名稱

根據預設，閘道端點會以 格式提供 AWS受管網域名稱<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com。對於生產環境或建立更易於使用的體驗，您可能需要為閘道端點使用自訂網域名稱。本節會引導您使用 Amazon CloudFront 做為反向代理來設定自訂網域名稱。

先決條件

開始前，請確保您具備以下條件：

  • 運作中的閘道端點

  • DNS 委派 （如果您的 Route 53 網域需要可公開存取）

  • AWS 安裝並設定 CDK （如果遵循 CDK 方法）

  • 建立和管理 CloudFront 分佈、Route 53 託管區域和 ACM 憑證的適當 IAM 許可

解決方案概觀

此解決方案包含下列元件：

  • Route 53 託管區域 ：管理自訂網域的 DNS 記錄

  • ACM 憑證 ：為您的自訂網域提供 SSL/TLS 加密

  • CloudFront 分佈：充當反向代理，將請求從您的自訂網域轉送到閘道端點

  • Route 53 A Record：將您的自訂網域映射至 CloudFront 分佈

下列步驟將引導您使用 AWS CDK 設定這些元件。

實作步驟

步驟 1：建立 Route 53 託管區域

首先，為您的自訂網域建立 Route 53 託管區域：

import { RemovalPolicy } from 'aws-cdk-lib';
import { PublicHostedZone } from 'aws-cdk-lib/aws-route53';

const domainName = 'my.example.com';

const hostedZone = new PublicHostedZone(this, 'HostedZone', {
    zoneName: domainName,
});
this.hostedZone.applyRemovalPolicy(RemovalPolicy.RETAIN);
注意

我們會套用 的移除政策RETAIN，以防止在堆疊更新或刪除期間意外刪除託管區域。

步驟 2：建立 DNS 驗證的憑證

接著，使用 Certificate Manager (ACM) 搭配 DNS 驗證，為您的自訂網域建立 SSL/TLS AWS 憑證：

import { RemovalPolicy } from 'aws-cdk-lib';
import { Certificate, CertificateValidation } from 'aws-cdk-lib/aws-certificatemanager';

const certificate = new Certificate(this, 'SSLCertificate', {
    domainName: domainName, // route53 hosted zone domain name from step 1
    validation: CertificateValidation.fromDns(hostedZone), // route53 hosted zone from step 1
});
this.certificate.applyRemovalPolicy(RemovalPolicy.RETAIN);

DNS 驗證會自動在您的 Route 53 託管區域中建立必要的驗證記錄。

步驟 3：建立 CloudFront 分佈

建立 CloudFront 分佈，做為閘道端點的反向代理：

import {
  AllowedMethods,
  CachePolicy,
  Distribution,
  OriginProtocolPolicy,
  ViewerProtocolPolicy
} from 'aws-cdk-lib/aws-cloudfront';
import { HttpOrigin } from 'aws-cdk-lib/aws-cloudfront-origins';

const bedrockAgentCoreGatewayHostName = '<mymcpserver>.gateway.bedrock-agentcore.<region>.amazonaws.com'
const bedrockAgentCoreGatewayPath = '/mcp' // can also be left undefined, depending on your requirement

const distribution = new Distribution(this, 'Distribution', {
    defaultBehavior: {
        origin: new HttpOrigin(bedrockAgentCoreGatewayHostName, {
            protocolPolicy: OriginProtocolPolicy.HTTPS_ONLY,
            originPath: bedrockAgentCoreGatewayPath,
        }),
        viewerProtocolPolicy: ViewerProtocolPolicy.HTTPS_ONLY,
        cachePolicy: CachePolicy.CACHING_DISABLED, // important since caching is enabled by default and hence is not suitable for a reverse proxy
        allowedMethods: AllowedMethods.ALLOW_ALL,
    },
    domainNames: [domainName], // route53 hosted zone domain name from step 1
    certificate: certificate, // ssl certificate for the route53 domain from step 2
});
重要

設定 cachePolicy: CachePolicy.CACHING_DISABLED 以確保 CloudFront 不會快取閘道端點的回應，這對於動態 API 互動很重要。

<mymcpserver> 將 取代為您的閘道 ID，並將 <region>取代為您的 AWS 區域 us-east-1 （例如 )。

步驟 4：建立 Route 53 A 記錄

建立 Route 53 將自訂網域指向 CloudFront 分佈的記錄：

import { ARecord, RecordTarget } from 'aws-cdk-lib/aws-route53';
import { CloudFrontTarget } from 'aws-cdk-lib/aws-route53-targets';

const aRecord = new ARecord(this, 'AliasRecord', {
    zone: hostedZone, // route53 hosted zone from step 1
    recordName: domainName, // route53 hosted zone domain name from step 1
    target: RecordTarget.fromAlias(new CloudFrontTarget(distribution)), // cloudfront distribution from step 3
});

這會建立別名記錄，將您的自訂網域映射至 CloudFront 分佈。

步驟 5：部署您的基礎設施

部署您的 CDK 堆疊以建立資源：

cdk deploy

部署程序可能需要一些時間，尤其是憑證驗證和 CloudFront 分佈建立。

測試您的自訂網域

部署基礎設施之後，請確認您的自訂網域已正確設定：

驗證 DNS 解析

使用 dig命令來驗證您的自訂網域是否解析為 CloudFront 分佈：

dig my.example.com

輸出應會顯示您的網域解析為 CloudFront 的 IP 地址。

驗證 SSL 憑證

使用 curl來驗證 SSL 憑證是否已正確設定：

curl -v https://my.example.com

輸出應會顯示成功的 SSL 交握，沒有憑證錯誤。

設定 MCP 用戶端

設定並驗證自訂網域後，您可以設定 MCP 用戶端來使用它：

游標組態

對於游標，請更新您的組態檔案：

{
  "mcpServers": {
    "my-mcp-server": {
      "url": "https://my.example.com"
    }
  }
}

其他 MCP 用戶端

對於原生不支援可串流 HTTP 的 MCP 用戶端：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/path/to/uvx",
        "args": [
            "mcp-proxy",
            "--transport",
            "streamablehttp",
            "https://my.example.com"
        ]
    }
  }
}

其他考量

成本影響

使用 CloudFront 做為反向代理會產生資料傳輸和請求處理的額外成本。檢閱 CloudFront 定價模型，以了解特定使用案例的成本影響。

安全考量

請考慮實作其他安全措施，例如：

  • 保護您的端點免受常見 Web 入侵的 WAF 規則

  • 限制存取特定地理區域的地理限制

  • 自訂標頭或請求簽署，以新增額外的身分驗證層

監控和記錄

啟用 CloudFront 存取日誌並設定 CloudWatch 警示，以監控自訂網域設定的運作狀態和效能。

憑證續約

只要 DNS 記錄保持到位，透過 DNS 驗證發行的 ACM 憑證會自動續約。請確定您不會刪除驗證記錄。

具有自訂網域的 OAuth 保護資源端點

根據預設，/.well-known/oauth-protected-resource端點會傳回資源 URL，其中包含閘道網域，而不是您的自訂網域。這可能會導致 OAuth 用戶端在使用自訂網域時驗證失敗。

若要解決此問題，您可以實作 Lambda@Edge 函數來攔截 OAuth 探索回應，並使用正確的自訂網域 URL 產生新的回應。以下是方法：

  • 使用 Lambda@Edge 搭配 ORIGIN_RESPONSE 事件類型 ：建立在原始伺服器回應上觸發的函數，以攔截 OAuth 保護的資源端點回應。

  • 產生新的回應 ：Lambda@Edge 無法讀取原始伺服器回應內文，因此不使用修改現有的回應，而是使用自訂網域產生全新的 JSON 回應。

  • 與 CloudFront 行為建立關聯 ：將 Lambda@Edge 函數設定為專門針對/.well-known/oauth-protected-resource路徑模式觸發。

    實作此解決方案後，OAuth 保護的資源端點將傳回正確的自訂網域：

    curl https://my-custom-domain.com/.well-known/oauth-protected-resource
{
  "authorization_servers": ["https://my-org.okta.com/oauth2/default"],
  "resource": "https://my-custom-domain.com/mcp"
}
    注意

    雖然 Lambda@Edge 為此問題提供了解決方案，但在未內建支援的情況下實作 AgentCore Gateway 的自訂網域，需要額外的複雜性，這些複雜性可能並非所有客戶都適合。將此方法視為解決方法，直到有自訂網域的 OAuth 探索原生支援可用為止。

疑難排解

DNS 解析問題

如果您的自訂網域無法正確解析：

  • 確認 A 記錄已在您的 Route 53 託管區域中正確設定

  • 檢查網域的名稱伺服器是否已在網域註冊商正確設定

  • DNS 傳播的允許時間 （在某些情況下最多 48 小時）

SSL 憑證問題

如果您遇到 SSL 憑證錯誤：

  • 在 ACM 主控台中驗證憑證是否已發出並處於作用中狀態

  • 檢查憑證是否正確與您的 CloudFront 分佈相關聯

  • 確定憑證涵蓋您使用的確切網域名稱

閘道連線問題

如果您的自訂網域未連線至閘道：

  • 驗證 CloudFront 分佈中的原始網域和路徑是否正確

  • 檢查您的閘道端點是否可以直接存取

  • 檢閱 CloudFront 分佈日誌是否有任何錯誤

結論

為您的閘道端點設定自訂網域名稱可增強應用程式的專業外觀，並提供管理 API 端點的彈性。透過遵循本指南中概述的步驟，您可以使用 CloudFront 作為反向代理來建立安全可靠的自訂網域組態。

如需閘道功能的詳細資訊，請參閱 Amazon Bedrock AgentCore Gateway：將工具和其他資源安全地連接到閘道。