配置虚拟主机

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

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

观看视频介绍虚拟主机。

创建虚拟主机

使用以下基本过程创建虚拟主机。 实际使用的过程取决于您是云客户还是私有云客户,以及您是否启用了 TLS:

  1. 为公开显示的域名创建 DNS 条目和 CNAME 记录。
  2. 如果在虚拟主机上启用 TLS:
    1. 按照下述步骤创建和配置密钥库:密钥库和信任库
    2. 将证书和密钥上传到密钥库。确保您的证书指定的域名与要用于虚拟主机的主机别名匹配。
    3. 使用 Edge 界面或 API 创建对密钥库的引用。该引用将密钥库的名称和引用类型指定为 KeyStore。如需详细了解如何创建和修改引用,请参阅使用引用
    4. 如果您要执行双向 TLS,请创建信任库,上传证书,然后创建对信任库的引用。按照此处所述的过程创建信任库:密钥库和信任库
  3. 使用 Create a Virtual Host API 创建虚拟主机。如果启用 TLS,请务必指定正确的密钥库引用、信任库引用和密钥别名。
  4. 如果您有任何现有的 API 代理,请将虚拟主机添加到 ProxyEndpoint。 系统会自动将虚拟主机添加到所有新的 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

使用 API 或界面创建虚拟主机

您可以使用 Edge API 或 Edge 界面创建虚拟主机。

下面的大多数示例都使用 Edge API。如需访问该界面以在 Edge 界面中创建、修改和删除虚拟主机,请执行以下操作:

  1. 登录 apigee.com/edge

    面向私有云客户的边缘使用 http://ms-ip:9000(本地),其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。

  2. 在左侧导航栏中,依次选择 Admin > Virtual Hosts
  3. 选择环境,例如 prodtest
    系统会显示为环境定义的虚拟主机。
  4. 选择 + Virtual Host 创建虚拟主机,或选择现有虚拟主机的名称进行修改。

为 HTTP 创建虚拟主机

Edge for Private Cloud 客户可以使用 HTTP 创建虚拟主机。

如需创建不支持 TLS 的虚拟主机,请创建一个定义该虚拟主机的 XML 对象。例如,以下 XML 对象定义了使用 HTTP 协议的虚拟主机:

<VirtualHost name="myVHost">
   <HostAliases>
     <HostAlias>api.myCompany.com</HostAlias>
   </HostAliases>
   <Interfaces/>
   <Port>80</Port>
</VirtualHost>

在此定义中,您:

  • name 指定为 myVHost。使用名称在 API 代理或 API 调用中引用虚拟主机。
  • 主机别名指定为 api.myCompany.com。这是用于访问 API(根据 DNS 定义和 CNAME 记录所定义)的公开网域。
  • 端口编号指定为 80。如果省略,则端口默认设置为 443。
  • 您可以在虚拟主机中设置其他属性。如需查看所有属性的参考信息,请参阅虚拟主机属性参考文档

如果您有任何现有的 API 代理,请将虚拟主机添加到代理端点的 <HTTPConnection> 元素中。系统会自动将虚拟主机添加到所有新的 API 代理。 请参阅配置 API 代理以使用虚拟主机。 如果您创建了不应通过特定虚拟主机访问的新 API 代理,则必须修改 API 代理,以将该虚拟主机从其 ProxyEndpoint 中移除。

然后,您可以向以下地址发出请求,通过此虚拟主机访问 API 代理:

http://api.myCompany.com/proxy-base-path/resource-path
https://api.myCompany.com/proxy-base-path/resource-path

使用 Create a Virtual Host API 创建虚拟主机:

curl -X POST -H "Content-Type:application/xml" \
  http://ms-IP:8080/v1/o/org_name/environments/env_name/virtualhosts \
  -d '<VirtualHost name="myVHost">
        <HostAliases>
            <HostAlias>api.myCompany.com</HostAlias>
        </HostAliases>
        <Interfaces/>
        <Port>80</Port>
    </VirtualHost>' \
  -u sysAdminEmail:password

为单向 TLS 创建虚拟主机

以下 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>

在此定义中,您可以通过将 <Enable> 元素设置为 true 来启用 TLS,并使用 <KeyStore><KeyAliase> 元素指定 TLS 连接使用的密钥库和密钥别名。

如需详细了解如何使用 TLS,请参阅 TLS/SSL

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

配置虚拟主机以支持 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 链,这是必需的。

如需详细了解如何使用 TLS,请参阅 TLS/SSL

修改虚拟主机

拥有付费帐号的 Cloud 客户和所有 Edge for Private Cloud 客户均可使用 Update a Virtual Host API 来更新虚拟主机。您可以使用此 API 设置虚拟主机属性参考文档中介绍的虚拟主机的所有属性。

使用 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

删除虚拟主机

如需从环境中删除虚拟主机,您必须更新所有引用该虚拟主机的 API 代理以移除该引用。请参阅配置 API 代理以使用虚拟主机

使用 Delete a Virtual Host API 删除虚拟主机:

curl -X DELETE \
  https://api.enterprise.apigee.com/v1/o/org_name/e/env_name/virtualhosts/vhost_name \
  -u orgAdminEmail:password

查看有关虚拟主机的信息

查看在环境中定义的虚拟主机的相关信息,如下所述。

边缘

如需使用 Edge 界面查看有关虚拟主机的信息,请执行以下操作:

  1. 登录 apigee.com/edge

    面向私有云客户的边缘使用 http://ms-ip:9000(本地),其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。

  2. 在左侧导航栏中,依次选择 Admin > Virtual Hosts
  3. 选择环境,例如 prodtest

    此时,系统会显示为环境定义的虚拟主机。如果虚拟主机配置为使用密钥库或信任库,请点击 Show 以查看更多信息。

如果虚拟主机配置为使用 TLS/SSL,虚拟主机的名称旁边会显示一个锁形图标。这意味着 TLS/SSL 证书、密钥和证书链已上传到 Edge 并与虚拟主机关联。如需查看可用证书的相关信息,请执行以下操作:

  1. 在左侧导航栏中依次选择管理 > 环境 > TLS 密钥库
  2. 选择环境(通常是 prodtest)。
  3. 展开密钥库以查看证书。

传统 Edge (Private Cloud)

如需使用传统版 Edge 界面查看虚拟主机的相关信息,请执行以下操作:

  1. 登录 http://ms-ip:9000,其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。
  2. 在左侧导航栏中,依次选择 Admin > Virtual Hosts
  3. 选择环境,例如 prodtest
  4. 点击 Virtual Hosts 标签页。

    此时,系统会显示为环境定义的虚拟主机。如果虚拟主机配置为使用密钥库或信任库,请点击 Show 以查看更多信息。

    “Virtual Hosts”标签页显示名称、端口、别名等信息。

如果虚拟主机配置为使用 TLS/SSL,虚拟主机的名称旁边会显示一个锁形图标。这意味着 TLS/SSL 证书、密钥和证书链已上传到 Edge 并与虚拟主机关联。如需查看可用证书的相关信息,请执行以下操作:

  1. 在顶部导航栏中依次选择管理 > TLS 证书
  2. 选择环境(通常是 prodtest)。
  3. 展开密钥库以查看证书。

使用 Edge API 查看虚拟主机

您还可以使用 Edge API 查看有关虚拟主机的信息。例如,List Virtual Hosts API 会返回所有虚拟主机的列表:

curl -X GET -H "accept:application/xml" \
    https://api.enterprise.apigee.com/v1/o/org_name/environments/env_name/virtualhosts \
    -u orgAdminEmail:pWord

其中 orgAdminEmail:pWord 是组织管理员的用户名和密码,org_name/env_name 指定包含虚拟主机的组织和环境。示例响应:

[
 "default",
 "secure"
]

如需查看特定虚拟主机的相关信息,请使用 Get Virtual Host API:

curl -X GET -H "accept:application/xml" \
    https://api.enterprise.apigee.com/v1/o/org_name/environments/env_name/virtualhosts/vhost_name \
    -u orgAdminEmail:pWord

其中 vhost_name 是虚拟主机的名称。例如,您可以将 vhost_name 指定为“安全”,以查看 Apigee 创建的默认安全虚拟主机的配置:

<VirtualHost name="secure">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <Properties/>
    <Interfaces/>
    <RetryOptions/>
    <SSLInfo>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <Enabled>true</Enabled>
        <KeyAlias>freetrial</KeyAlias>
        <KeyStore>ref://freetrial</KeyStore>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
    </SSLInfo>
</VirtualHost>

将 API 代理配置为使用虚拟主机

创建新的 API 代理时,Edge 会自动将其配置为使用组织中所有可用的虚拟主机。通过虚拟主机向 API 代理发出的请求使用以下形式:

https://host-alias/proxy-base-path/resource-path

其中:

  • host-alias 通常是虚拟主机的 DNS 名称。
  • proxy-base-path 会在您创建 API 代理时定义,并且对于每个 API 代理而言都是唯一的。
  • resource-path 是可通过 API 代理访问的资源的路径。

控制 API 代理使用的虚拟主机

在 API 代理的 XML 配置中,您可以使用 virtualhost 标记指定与 API 代理关联的虚拟主机的名称

<HTTPProxyConnection>
  <BasePath>/v1/my/proxy/basepath</BasePath>
  <VirtualHost>secure</VirtualHost>
  <VirtualHost>default</VirtualHost>
</HTTPProxyConnection>

例如,<VirtualHost>secure</VirtualHost> 表示客户端可以使用“安全”虚拟主机的主机别名调用 API 代理。

在以下情况下,您通常需要修改与 API 代理关联的虚拟主机:

  • 您创建了一个新的虚拟主机,并且已有 API 代理。您必须修改任何现有的 API 代理才能添加新的虚拟主机。
  • 您创建了一个不应通过特定虚拟主机访问的新 API 代理。您必须修改 API 代理才能将该虚拟主机从其定义中移除。

如需修改与 API 代理关联的虚拟主机,请执行以下操作:

  1. 访问 API 代理编辑器,如下所述。

    Edge

    如需使用 Edge 界面访问 API 代理编辑器,请执行以下操作:

    1. 登录 apigee.com/edge

      面向私有云客户的边缘使用 http://ms-ip:9000(本地),其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。

    2. 在左侧导航栏中,依次选择开发 > API 代理
    3. 从列表中选择您要修改的 API 代理。

    传统 Edge (Private Cloud)

    如需使用传统版 Edge 界面访问 API 代理编辑器,请执行以下操作:

    1. 登录 http://ms-ip:9000,其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。
    2. 在顶部导航栏中依次选择 API > API 代理
    3. 从列表中选择您要修改的 API 代理。
  2. 点击开发标签页。
  3. 代理端点下,选择默认
  4. 在代码区域中:
    1. 移除 API 代理不支持的虚拟主机的所有 <VirtualHost> 元素。
    2. 使用新虚拟主机的名称添加新的 <VirtualHost> 元素。例如,如果新虚拟主机的名称为 MyVirtualHost,请添加以下标记:
      <HTTPProxyConnection>
        <BasePath>/v1/my/proxy/basepath</BasePath>
        <VirtualHost>default</VirtualHost>
        <VirtualHost>secure</VirtualHost>
        <VirtualHost>MyVirtualHost</VirtualHost>
      </HTTPProxyConnection>
  5. 保存 API 代理。如果 API 代理已部署,则保存该代理后,系统会使用新设置重新部署该代理。

设置由 API 代理的 Edge 界面显示的基本网址

Edge 界面会根据与代理部署位置相对应的虚拟主机中的设置来显示 API 代理的网址。此屏幕可以包含虚拟主机的路由器端口号。

在大多数情况下,Edge 界面中显示的网址是向代理发出外部请求的正确网址。不过,对于某些配置,显示的网址不正确。例如,以下任何配置都可能会导致显示的网址与用于向代理发出外部请求的实际网址不对应:

  • SSL 在负载平衡器上终止
  • 负载平衡器和 Apigee 路由器之间发生端口映射
  • 配置了路径重写的负载平衡器

Edge 支持虚拟主机上名为 <BaseUrl> 的属性,可让您替换 Edge 界面显示的网址。以下示例展示了具有 <BaseUrl> 属性的虚拟主机对象。 在以下示例中,值“http://myCo.com”显示在 Edge 界面中:

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

请注意,<BaseUrl> 的值必须包含协议(即“http://”或“https://”)。

如果未设置 <BaseUrl>,则 Edge 界面呈现的默认网址将显示为“api.myCompany.com”,而实际的主机别名为“http://myCo.com”。