为 Cloud 配置虚拟主机

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

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

了解详情

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

虚拟主机创建和修改功能仅适用于 Edge Cloud 中的付费帐号。创建虚拟主机的用户必须是组织管理员角色,或者是有权修改虚拟主机的自定义角色。其他角色的用户无权创建虚拟主机。

例如,付费客户可以:

  • 启用单向和双向 TLS
  • 指定虚拟主机使用的密钥库/truststore

免费试用帐号无法创建或修改虚拟主机,并且仅限于在 Edge 注册时为其创建的虚拟主机。如需详细了解 Edge 定价方案,请参阅 https://apigee.com/api-management/#/pricing

为 Cloud SQL 配置虚拟主机的要求

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

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

Google Cloud 中每个组织/环境最多可以有 20 个虚拟主机。

注意:Private Cloud 中的虚拟主机数量不受限制。

大多数组织/环境使用两个虚拟主机:一个用于 HTTP,另一个用于 HTTPS 访问。如果您的组织/环境允许使用其他域名进行访问,您可能需要其他虚拟主机。

基准网址 包含协议 无论是在界面中或通过 API 定义虚拟主机的基础网址,都必须将协议(即“http://”或“https://”)指定为网址的一部分。
端口 443

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

请注意,您可以在端口 443 上创建多个虚拟主机,前提是这些主机具有唯一的主机别名并且都支持 TLS。

TLS 必需

您只能创建一个支持通过 HTTPS 使用 TLS 的虚拟主机。您必须已经创建了一个包含 TLS 证书和密钥的密钥库和(可选)信任库。

您必须拥有由可信实体(例如 Symantec 或 VeriSign)签署的证书。 您不能使用自签名证书。

如果您需要 HTTP 访问权限,请与 Apigee Edge 支持团队联系。

TLS 协议 TLS 1.2

云端边缘仅支持 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. 选择环境,例如 prodtest
  4. 选择 + Virtual Host 创建虚拟主机,或选择现有虚拟主机的名称进行修改。
  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 路由器上终止 SSL,则只能在虚拟主机中使用密钥库和信任库引用。
  • 如果您在 Apigee Router 之前有一个负载平衡器,并在负载平衡器上终止 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 免费试用证书和密钥的虚拟主机

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

*.apigee.net 的网域定义了 Apigee 免费试用证书。因此,虚拟主机的 <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)创建一个指向 [org]-[environment].apigee.net 的 DNS 条目和 CNAME 记录。
  2. 按照 使用 Edge 界面创建密钥库和信任库中所述的过程创建和配置一个名为 myTestKeystore 的密钥库,在本示例中。对于此示例,请确保密钥库使用别名 myKeyAlias 作为证书和私钥。
  3. 将证书和密钥上传到密钥库。确保您的证书指定的域名与要用于虚拟主机的主机别名匹配。
  4. 使用 Edge 界面或 API 创建对密钥库的引用。该引用将密钥库的名称和引用类型指定为 KeyStore。 如需详细了解如何创建和修改引用,请参阅使用引用

  5. 使用 Create a Virtual Host 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. 使用 Update a Virtual Host 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 支持团队,重启边缘路由器以完成此流程。