为 Cloud 配置虚拟主机

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。信息

拥有付费账号的 Cloud 客户可以在组织中创建虚拟主机。

了解详情：

谁可以在 Cloud 中创建和修改虚拟主机

只有付费账号才能在 Edge Cloud 中创建和修改虚拟主机。 创建虚拟主机的用户必须具有组织管理员角色，或者具有修改虚拟主机权限的自定义角色。其他角色的用户无权创建虚拟主机。

例如，付费客户可以：

  • 启用单向和双向 TLS
  • 指定虚拟主机使用的密钥库/信任存储区

免费账号和试用账号无法创建或修改虚拟主机，只能使用在注册 Edge 时为其创建的虚拟主机。如需详细了解 Edge 价格方案，请参阅 https://apigee.com/api-management/#/pricing。

为 Cloud 配置虚拟主机的要求

下表总结了创建虚拟主机的要求：

类别 要求 说明
账号类型 付费 免费试用账号和试用账号无法创建或修改虚拟主机。
用户角色 组织管理员 只有组织管理员才能创建虚拟主机，或者拥有修改虚拟主机权限的自定义角色用户。
虚拟主机数量 最多 20 个

Cloud 中的每个组织/环境最多只能使用 20 个虚拟主机。

注意：私有云中的虚拟主机数量没有限制。

大多数组织/环境使用两个虚拟主机：一个用于 HTTP，另一个用于 HTTPS 访问。如果贵组织/环境允许使用不同的域名进行访问，您可能需要额外的虚拟主机。
基准网址 包含协议 在界面中或使用 API 为虚拟主机定义基本网址时，您必须在网址中指定协议（即“http://”或“https://”）。
端口 443

您只能在端口 443 上创建虚拟主机。

请注意，您可以在端口 443 上创建多个虚拟主机，前提是它们具有唯一的主机别名且都支持 TLS。
TLS 必填

您只能创建支持通过 HTTPS 使用 TLS 的虚拟主机。您必须已创建包含 TLS 证书和密钥的密钥库（以及可选的信任库）。

您必须拥有由可信实体（例如 Symantec 或 VeriSign）签署的证书。 您无法使用自签名证书。

如果您需要 HTTP 访问权限，请与 Apigee Edge 支持团队联系。
TLS 协议 TLS 1.2

Edge in the Cloud 仅支持 TLS 1.2 版。
主机别名 在组织和环境中是唯一的 其他组织/环境组合不存在主机别名。
域名 归客户所有

您必须拥有虚拟主机中指定的域名。边缘检查以确保域名（由主机别名定义）与 TLS 证书中的元数据匹配。

具体而言，Edge 会检查证书中的以下信息：

  • CN - 通用名称
  • SAN - 主题备用名称

SAN 或 CN 允许使用通配符，例如 *.myco.net。

Edge 还会验证证书是否未过期。
客户端应用 SNI 支持 访问虚拟主机的所有客户端应用都必须支持 SNI。

所有应用都需要 SNI 支持。

使用浏览器创建虚拟主机

本部分中的大多数示例都使用 Edge API 创建或修改虚拟主机，但您也可以在 Edge 界面中创建虚拟主机。

如需使用 Edge 界面创建虚拟主机，请执行以下操作：

  1. 登录 apigee.com/edge。
  2. 依次选择管理 > 虚拟主机。
  3. 选择环境，例如 prod 或 test。
  4. 选择 + 虚拟主机以创建虚拟主机，或选择现有虚拟主机的名称对其进行修改。
  5. 如需详细了解如何填充虚拟主机字段，请参阅上表。

为单向 TLS 定义虚拟主机

用于定义虚拟主机的 XML 对象。例如，以下 XML 对象定义了单向 TLS 的虚拟主机：

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>api.myCompany.com</HostAlias> 
    </HostAliases> 
    <Port>443</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>
</VirtualHost>

在此定义中，您将：

  • 将名称指定为 myTLSVHost。您可以在 API 代理或 API 调用中使用该名称来引用虚拟主机。
  • 将主机别名指定为 api.myCompany.com。这是用于访问 API 的公开网域，如 DNS 定义和 CNAME 记录所定义。
  • 将端口号指定为 443。如果省略，则默认端口设置为 443。
  • 根据需要启用 TLS。

    将 <Enable> 元素设置为 true 可启用单向 TLS，<KeyStore> 元素则用于指定 TLS 连接使用的密钥库和密钥别名。

    如需启用双向 TLS，请将 <ClientAuthEnabled> 设置为 true，并使用 <TrustStore> 元素指定信任库。信任库包含客户端的证书颁发者和证书的 CA 链，这是必需的。

    注意：由于 Edge 最初支持 SSL，因此您用于配置 TLS 的标记名为 <SSLInfo>。

请注意，您可以在虚拟主机中设置其他属性。如需查看所有属性的参考文档，请参阅虚拟主机属性参考文档。

确定如何在虚拟主机中指定密钥库和信任库名称

在将虚拟主机配置为支持 TLS 时，您可以使用引用来指定密钥库。引用是一个包含密钥库或信任库名称的变量，而不是直接指定密钥库或信任库名称，如下所示：

    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>

使用引用的优势在于，您可以更改引用的值以更改虚拟主机使用的密钥库，更改的原因通常是因为当前密钥库中的证书即将过期。更改引用的值不需要重启边缘路由器。如需详细了解如何创建和修改引用，请参阅使用引用。

您只能使用密钥库和信任库的引用；而不能使用别名的引用。更改密钥库的引用时，确保证书的别名与旧密钥库中的别名相同。

使用对密钥库和信任库的引用的限制

在使用对密钥库和信任库的引用时，您必须考虑以下限制：

  • 如果您支持 SNI 并在 Apigee Router 上终止 SSL，则只能在虚拟主机中使用密钥库和信任库引用。
  • 如果您在 Apigee 路由器前面具有负载平衡器，并且您在负载平衡器上终止 TLS，则无法在虚拟主机中使用密钥库和信任库引用。

为双向 TLS 定义虚拟主机

如需启用双向 TLS，请将 <ClientAuthEnabled> 元素设置为 true，并使用带有 <TrustStore> 元素的引用来指定信任库。信任库包含客户端的证书颁发机构和证书的 CA 链，这是必需的。客户端也必须正确配置为双向 TLS。

如需为双向 TLS 创建虚拟主机，请创建一个定义虚拟主机的 XML 对象：

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>api.myCompany.com</HostAlias> 
    </HostAliases> 
    <Port>443</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://myTestKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://myTestTruststoreRef</TrustStore> 
    </SSLInfo>
</VirtualHost>

在此定义中，您可以：

  • 将 <ClientAuthEnabled> 设置为 true 以启用双向 TLS。
  • 使用 <TrustStore> 元素指定对信任库的引用。信任库包含客户端的证书颁发者和证书的 CA 链，这是必需的。

定义使用 Apigee 免费试用证书和密钥的虚拟主机

如果您有付费 Edge for Cloud 账号，并且还没有 TLS 证书和密钥，则可以创建一个使用 Apigee 免费试用证书和密钥的虚拟主机。这意味着您可以创建虚拟主机，而无需先创建密钥库。

Apigee 免费试用证书针对网域 *.apigee.net 进行了定义。因此，虚拟主机的 <HostAlias> 也必须采用 *.apigee.net 格式。

如果您要执行双向 TLS，则仍必须将 <ClientAuthEnabled> 元素设置为 true，并使用带有 <TrustStore> 元素的引用来指定信任库，如为双向 TLS 定义虚拟主机中所述。

使用 Apigee 免费试用证书和密钥定义虚拟主机的 XML 对象会省略 <KeyStore> 和 <KeyAlias> 元素，并将其替换为 <UseBuiltInFreeTrialCert> 元素，如下所示：

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

<UseBuiltInFreeTrialCert> 元素的默认值为 false。

对于双向 TLS，请将虚拟主机定义为：

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <TrustStore>ref://myTestTruststoreRef</TrustStore>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

在 Edge 界面中，创建虚拟主机时选择使用内置的免费试用证书选项，以使用免费的 Apigee 证书和密钥：

选择“使用内置的免费试用证书”

创建虚拟主机

请按照以下步骤创建虚拟主机：

  1. 为面向公众的网域（例如 api.myCompany.com）创建 DNS 条目和 CNAME 记录，并将其指向 [org]-[environment].apigee.net。
  2. 按照此处所述的 使用 Edge 界面创建密钥库和信任库中的步骤，创建并配置一个密钥库（在此示例中名为 myTestKeystore）。在本例中，请确保密钥库使用别名 myKeyAlias 作为证书和私钥。
  3. 将证书和密钥上传到密钥库。确保证书指定的域名与您要为虚拟主机使用的主机别名一致。

  4. 使用 Edge 界面或 API 创建对密钥库的引用。此引用将密钥库的名称和引用类型指定为 KeyStore。 如需详细了解如何创建和修改引用，请参阅使用引用。

  5. 使用创建虚拟主机 API 创建虚拟主机。请务必指定正确的密钥库引用和密钥别名。 要使用该 API，请使用以下 POST API 调用来创建名为 myTLSVHost 的密钥库： 
    curl -X POST -H "Content-Type:application/xml" \
  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts \
  -d '<VirtualHost name="myTLSVHost">
    <HostAliases>
      <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>false</ClientAuthEnabled>
      <KeyStore>ref://myTestKeystoreRef</KeyStore>
      <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
  </VirtualHost>' \
  -u orgAdminEmail:password

    如果您要使用客户端执行双向 TLS，请将 <ClientAuthEnabled> 设置为 true，并使用 <TrustStore> 元素指定信任库。客户端必须正确配置为双向 TLS，这意味着 Edge 有一个包含客户端证书颁发者和证书链的信任库。使用此处所述的步骤创建信任库： 使用 Edge 界面创建密钥库和信任库。

  6. 如果您当前有任何 API 代理，请将虚拟主机添加到 ProxyEndpoint 的 <HTTPConnection> 元素。虚拟主机会自动添加到所有新的 API 代理。 请参阅 将 API 代理配置为使用虚拟主机。

将 API 代理更新为使用虚拟主机并为主机别名创建 DNS 条目和 CNAME 记录后，您可以按如下所示访问 API 代理：

https://api.myCompany.com/v1/{project-base-path}/{resource-path}

例如：

https://api.myCompany.com/v1/weather/forecastrss?w=12797282

修改虚拟主机

付费 Cloud 客户修改现有虚拟主机时，需要执行以下两项主要任务：

  1. 修改对密钥库或信任库的引用的值。

    注意：将 <KeyStore> 或 <TrustStore> 设置为使用引用后，您可以随时更改引用的值。不过，如果您想更改 <KeyStore> 或 <TrustStore> 以使用其他引用，或者更改 <KeyAlias> 以使用其他别名，则必须与 Apigee Edge 支持团队联系。
  2. 修改虚拟主机的 TLS 属性。

修改引用的值

您可以修改引用的值来更改虚拟主机使用的密钥库或信任库。

在修改引用的值之前，请执行以下操作：

  1. 创建新的密钥库，然后上传证书和密钥，如 使用 Edge 界面创建密钥库和信任库中所述。在新密钥库中，确保为密钥别名使用与现有密钥库中相同的名称。
  2. 如有必要，请按照 使用 Edge 界面创建密钥库和信任库中所述创建新的信任库并上传证书。
  3. 按照使用引用中所述的步骤修改引用。

修改虚拟主机的 TLS 属性

付费客户可以使用 Update a Virtual Host API 来更新虚拟主机。借助此 API，您可以为虚拟主机属性参考文档中所述的虚拟主机设置所有属性。

修改虚拟主机时，Edge 会执行与创建虚拟主机时类似的验证。也就是说，在修改时，Edge 会验证以下内容：

  • 主机别名指定的网域未在其他组织和环境中使用。
  • 您拥有相应域名。具体而言，Edge 会检查证书中的以下信息是否与主机别名匹配：
    • CN - 通用名称
    • SAN - 主题备用名称
    • Edge 会验证证书是否未过期。

如需使用 Edge API 修改虚拟主机，请执行以下操作：

  1. 使用 更新虚拟主机 API 更新虚拟主机。使用 API 时，您必须在请求正文中指定虚拟主机的完整定义，而不仅仅是要更改的元素。在此示例中，您将 proxy_read_timeout 属性的值设置为：

    curl -X PUT -H "Content-Type:application/xml" \
  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \
  -d '<VirtualHost name="myTLSVHost">
    <HostAliases>
      <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>false</ClientAuthEnabled>
      <KeyStore>ref://myTestKeystoreRef</KeyStore>
      <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
    <Properties>
       <Property name="proxy_read_timeout">50</Property>
         </Properties>
  </VirtualHost>' \
  -u orgAdminEmail:password

修改虚拟主机以使用对密钥库和信任库的引用

Cloud 中 Edge 的所有新虚拟主机都使用对密钥库和信任库的引用。借助引用，您无需与 Apigee Edge 支持团队联系即可更改密钥库和信任库。

Apigee Edge 上的旧版虚拟主机可能未配置为使用密钥库和信任库的引用。在这种情况下，您可以更新虚拟主机以使用引用。

更新虚拟主机以使用引用

请按以下步骤更新虚拟主机：

  1. 如有必要，请按照 使用 Edge 界面创建密钥库和信任库中所述创建新的密钥库并上传证书。如果您已有密钥库，则可以配置一个指向它的引用。
  2. 创建对密钥库的新引用。
  3. 根据需要，创建新的信任库并上传证书。如果您已有信任库，则可以配置一个指向该信任库的引用。
  4. 创建对信任库的新引用。
  5. 更新虚拟主机以设置密钥库、别名、信任库和任何其他 TLS 属性。此调用的载荷为： 
    curl -X PUT -H "Content-Type:application/xml" \
  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \
  -d '<VirtualHost  name="myTLSVHost">
        <HostAliases>
          <HostAlias>api.myCompany.com</HostAlias>
        </HostAliases>
        <Port>443</Port>
        <OCSPStapling>off</OCSPStapling>
        <SSLInfo>
          <Enabled>true</Enabled>
          <ClientAuthEnabled>true</ClientAuthEnabled>
          <KeyStore>ref://myKeyStore2Way</KeyStore>
          <KeyAlias>keyAlias</KeyAlias>
          <TrustStore>ref://myTrustStore2Way</TrustStore>
          <IgnoreValidationErrors>false</IgnoreValidationErrors>
        </SSLInfo>
      </VirtualHost>' \
    -u orgAdminEmail:pWord
  6. 请与 Apigee 支持团队联系，重启边缘路由器以完成此流程。