虚拟主机属性参考文档

您正在查看 Apigee Edge 文档。
请查看 Apigee X 文档

虚拟主机表示

您用于定义虚拟主机的 XML 对象基于您的 Edge 版本:Cloud 或 Private Cloud。

如果您是私有云客户,则必须确保您的 Edge 版本使用正确的 XML。

Cloud 和 Private Cloud 4.17.01 及更高版本

<VirtualHost name="vhostName">
    <Port>portNumber</Port>
    <BaseUrl>http://myCo.com</BaseUrl>
    <OCSPStapling>offOn</OCSPStapling>
    <HostAliases>
        <HostAlias>hostAlias</HostAlias>
    </HostAliases>
    <Interfaces>
        <!-- Private Cloud only -->
        <Interface>interfaceName</Interface>
    </Interfaces>
    <RetryOptions>
        <RetryOption>option</RetryOption>
    </RetryOptions>
    <ListenOptions>
        <ListenOption>option</ListenOption>
    </ListenOptions>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
        <IgnoreValidationErrors>trueFalse</IgnoreValidationErrors>
    </SSLInfo>
    <!-- UseBuiltInFreeTrialCert is for Edge Cloud only -->
    <UseBuiltInFreeTrialCert>trueFalse</UseBuiltInFreeTrialCert>
    <PropagateTLSInformation>
        <!-- PropagateTLSInformation is Alpha in the Cloud only -->
        <ConnectionProperties>trueFalse</ConnectionProperties>
        <ClientProperties>trueFalse</ClientProperties>
    </PropagateTLSInformation>
    <Properties>
        <Property name="proxy_read_timeout">timeout</Property>
        <Property name="keepalive_timeout">timeout</Property>
        <Property name="proxy_request_buffering">onOff</Property>
        <Property name="proxy_buffering">onOff</Property>
        <!-- ssl_protocols is Private Cloud only -->
        <Property name="ssl_protocols">protocolList</Property>
        <Property name="ssl_ciphers">cipherList</Property>
    </Properties>
</VirtualHost>

Private Cloud 4.16.01 至 4.16.09

<VirtualHost name="vhostName">
    <Port>portNumber</Port>
    <HostAliases>
        <HostAlias>hostAlias</HostAlias>
    </HostAliases>
    <Interfaces>
        <Interface>interfaceName</Interface>
    </Interfaces>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
        <IgnoreValidationErrors>trueFalse</IgnoreValidationErrors>
    </SSLInfo>
</VirtualHost>

Private Cloud 4.15.07 及更早版本

<VirtualHost name="vhostName">
    <Port>portNumber</Port>
    <HostAliases>
        <HostAlias>hostAlias</HostAlias>
    </HostAliases>
    <Interfaces>
        <Interface>interfaceName</Interface>
    </Interfaces>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>keystore</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>truststore</TrustStore>
        <IgnoreValidationErrors>trueFalse</IgnoreValidationErrors>
        <Ciphers>
             <Cipher>cipher</Cipher>
             <Cipher>cipher</Cipher>
         </Ciphers>
         <Protocols>
             <Protocol>protocol</Protocol>
             <Protocol>protocol</Protocol>
         </Protocols>
    </SSLInfo>
</VirtualHost>

虚拟主机配置属性

下表列出了用于配置虚拟主机的属性:

属性 说明 默认 必需
虚拟主机

指定虚拟主机的名称。在配置 API 代理时,您可以使用该名称引用虚拟主机。

名称属性可以使用以下字符:A-Z0-9._\-$%。

兼容
端口

指定虚拟主机使用的端口号。请确保该端口在边缘路由器上处于打开状态。

如果您在 hostalias 元素中指定端口,则 <Port> 指定的端口号必须与它相匹配。

对于 Cloud:您必须在创建虚拟主机时指定端口 443。如果省略,则端口默认设置为 443。如果您有使用 443 以外的端口的现有虚拟主机,则无法更改该端口。

对于从 4.16.01 至 4.17.05 的私有云:创建虚拟主机时,您需要指定虚拟主机使用的路由器端口。例如,端口 9001。默认情况下,路由器以用户“apigee”模式运行,该端口无法访问特权端口(通常为端口 1024 及更低级别)。若要创建将路由器绑定到受保护的端口的虚拟主机,就必须将路由器配置为以有权访问这些端口的用户的身份运行。如需了解详情,请参阅设置虚拟主机

对于 4.16.01 之前的私有云版本:路由器只能针对每个具有特定证书的虚拟主机使用指定的证书监听一个 HTTPS 连接。因此,如果路由器在指定端口上发生 TLS 终止,多个虚拟主机将无法使用同一个端口号。

兼容
基准网址 替换部署到虚拟主机的 API 代理的 Edge 界面显示的网址。在边缘路由器前设置外部负载平衡器时,此功能非常有用。如需了解详情,请参阅为私有云配置对 API 的 TLS 访问

BaseUrl 的值必须包含协议(即“http://”或“https://”)。

OCSPStapting

OCSP(在线证书状态协议)客户端会向 OCSP 响应程序发送状态请求,以确定 TLS 证书是否有效。响应指示 TLS 证书是否有效且未撤消。

启用 OCSP 拼接后,Edge 可以充当单向 TLS 的 TLS 服务器,直接查询 OCSP 响应程序,然后缓存响应。然后,Edge 会将此响应返回至 TLS 客户端,或将其作为 TLS 握手的一部分进行处理。 如需了解详情,请参阅在服务器上启用 OCSP 拼接

必须启用 TLS 才能启用 OCSP 拼接。设置为 on 即可启用。 默认值为 off

关闭
HostAliases
HostAlias

路由器上虚拟主机的公开可见 DNS 名称(可选择添加端口号)。虚拟主机的主机别名和端口号组合对于 Edge 安装中的所有虚拟主机而言必须是唯一的。这意味着,如果多个虚拟主机具有不同的主机别名,则可以使用同一端口号。

您必须创建与主机别名匹配的 DNS 条目和 CNAME 记录,并且主机别名必须与客户端在 Host 标头中传递的字符串匹配。

HostAlias 中的端口号是可选的。如果您将该端口指定为主机别名的一部分,则还必须使用 <Port> 元素指定同一端口。或者,您也可以指定两个 HostAlias 元素,一个指定端口号,另一个不指定端口号。

同一个虚拟主机定义中可以有多个 HostAlias 定义,这个定义对应于虚拟主机的多个 DNS 条目,但不对应多个端口。如果您需要多个端口,请创建具有不同端口的多个虚拟主机定义。

您可以在主机别名中包含“*”通配符。“*”通配符只能位于主机别名的开头(第一个“.”前面),不能与其他字符混合。例如 *.example.com。虚拟主机的 TLS 证书的证书 CN 名称中必须有匹配的通配符。例如,*.example.com。 在虚拟主机别名中使用通配符可让 API 代理处理发送到多个子网域(例如 alpha.example.combeta.example.comlive.example.com)的调用。使用通配符别名还有助于减少每个环境中的虚拟主机数量,以避免超出产品限制,因为具有通配符的虚拟主机仅计为一个虚拟主机。

对于 Cloud:如果您已有使用 443 以外的端口的虚拟主机,则无法添加或移除主机别名。

对于私有云:如果您要使用路由器的 IP 地址(而不是 DNS 条目)设置主机别名,请为每个路由器添加单独的主机别名,并指定每个路由器的虚拟地址和虚拟主机的端口。

兼容
接口 仅适用于 Edge Cloud for Private Cloud。
接口

指定您希望将 port 绑定到的网络接口。如果省略此元素,端口将在所有接口上绑定。

例如,如需指定仅将该端口绑定到 en0,请运行以下命令:

<Interfaces>
  <Interface>en0</Interface>
</Interfaces>

运行“ifconfig -a”命令以确定系统中可用的接口。

所有接口
RetryOptions 适用于 Edge Cloud 和 Private Cloud 4.18.01 及更高版本。
重试选项

配置路由器在消息处理器关闭时对此虚拟主机的反应。

您可以使用 <RetryOption> 指定多个值。有效值包括:

off 停用重试,虚拟主机在收到请求时返回故障代码。
http_599 (默认)如果路由器收到来自消息处理器的 HTTP 599 响应,则会将请求转发给下一个消息处理器。

HTTP 599 是消息处理器在关停时生成的特殊响应代码。消息处理器会尝试完成所有现有请求,但对于任何新请求,它都会以 HTTP 599 响应,以便让路由器在下一个消息处理器中重试该请求。

error 如果在与消息处理器建立连接、向其传递请求或从中读取响应标头时出错,路由器会将请求转发给下一个消息处理器。
timeout 如果在与消息处理器建立连接、向其传递请求或从中读取响应标头后发生超时,路由器会将请求转发给下一个消息处理器。
invalid_header 如果消息处理器返回了空或无效的响应,路由器会将请求转发给下一个消息处理器。
http_XXX 如果消息处理器返回响应并显示 HTTP 代码 XXX,路由器会将请求转发给下一个消息处理器。

如果您指定了多个值,路由器会使用逻辑 OR 将它们结合起来。

例如:

<RetryOptions>
  <RetryOption>http_599</RetryOption>
  <RetryOption>error</RetryOption>
  <RetryOption>timeout</RetryOption>
  <RetryOption>invalid_header</RetryOption>
</RetryOptions>
ListenOptions 通过向 Apigee Edge 支持团队提交申请,适用于 Private Cloud 4.18.01 及更高版本和 Edge Cloud。
ListenOption

如果您使用 TCP 直通模式中的 ELB 来处理对边缘路由器的请求,路由器会将 ELB 的 IP 地址视为客户端 IP,而不是实际客户端 IP。如果路由器需要真实的客户端 IP 地址,请在 ELB 上启用 proxy_protocol,以便路由器在 TCP 数据包中传递客户端 IP 地址。在路由器上,您还必须将虚拟主机上的 <ListenOption> 设置为 proxy_protocol。 由于 ELB 处于 TCP 直通模式,因此您通常终止路由器上的 TLS。因此,当您将虚拟主机配置为使用 TLS 时,通常还必须将虚拟主机配置为使用 proxy_protocol

<ListenOption> 的默认值为空字符串。

例如:

<ListenOptions>
  <ListenOption>proxy_protocol</ListenOption>
</ListenOptions>

稍后如需取消设置 <ListenOption>,请更新虚拟主机,并在更新时省略 <ListenOptions> 标记。

SSL 信息
已启用

启用单向 TLS/SSL。您必须已定义一个包含证书和私钥的密钥库。

对于 Cloud:您必须拥有由可信实体(例如 Symantec 或 VeriSign)签名的证书。您不能使用自签名证书,也不能使用由自签名 CA 签名的叶证书。

对于 Cloud:如果现有虚拟主机配置为使用 443 以外的端口,则您无法更改 TLS 设置。也就是说,您无法将 TLS 设置从“已启用”更改为“已停用”,也无法从“已停用”更改为“已启用”。

false
启用 ClientAuth 在边缘(服务器)与发出请求的应用(客户端)之间启用双向 TLS(即客户端)。要启用双向 TLS,您需要在 Edge 上设置一个包含 TLS 客户端证书的信任库。 false
KeyStore

Edge 上密钥库的名称。

Apigee 建议您使用引用来指定密钥库名称,这样您无需重启路由器即可更改密钥库。如需了解详情,请参阅配置 TLS 的选项

如果“已启用”为 true,则为是
KeyAlias 您在将证书和私钥上传到密钥库时指定的别名。您必须实际指定别名,而不能使用引用。如需了解详情,请参阅配置 TLS 的选项 如果“已启用”为 true,则为是
TrustStore 启动

Edge 上包含双向 TLS 的证书或证书链的信任库的名称。如果 <ClientAuthEnabled> 为 true,则必须提供。

Apigee 建议您使用引用指定 Truststore 名称,这样您无需重启路由器即可更改 TrustStore。如需了解详情,请参阅配置 TLS 的选项

IgnoreValidationErrors

如果为 true,则指定忽略 TLS 证书错误。这与 c网址 的“-k”选项类似。

在为目标服务器和目标端点配置 TLS 以及配置使用双向 TLS 的虚拟主机时,此选项有效。

当与目标端点/目标服务器搭配使用时,如果后端系统使用 SNI,并返回主题标识名 (DN) 与主机名不匹配的证书,则您无法忽略该错误且连接会失败。

false
加密方式

仅适用于 Edge for Private Cloud 版本 4.15.07 及更低版本。

指定虚拟主机支持的加密方式。如果未指定加密方式,将允许可用于 JVM 的所有加密方式。

如需限制加密方式,请添加以下元素:

<Ciphers>
  <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>
  <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
</Ciphers>
JVM 支持全部
协议

仅适用于 Edge for Private Cloud 版本 4.15.07 及更低版本。

指定虚拟主机支持的协议。如果未指定协议,将允许可用于 JVM 的所有协议。

如需限制协议,请添加以下元素:

<Protocols>
  <Protocol>TLSv1</Protocol>
  <Protocol>TLSv1.2</Protocol>
  <Protocol>SSLv2Hello</Protocol>
</Protocols>
JVM 支持全部
使用内置的免费试用认证 仅适用于 Edge Cloud。
使用“免费试用”认证

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

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

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

false
PropagateTLSInformation 仅在适用于 Edge Cloud 的 Alpha 版中提供。
连接属性

允许 Edge 捕获 TLS 连接信息。 此信息随后以 API 代理中的流变量的形式提供。 如需了解详情,请参阅在 API 代理中访问 TLS 连接信息

false
客户端属性

启用 Edge 以双向 TLS 捕获的客户端证书详细信息。此信息随后以 API 代理中的流变量的形式提供。 如需了解详情,请参阅在 API 代理中访问 TLS 连接信息

false
媒体资源 适用于 Edge Cloud 和 Private Cloud 4.17.01 及更高版本。
Proxy_read_timeout

设置消息处理器和路由器之间的超时时长(以秒为单位)。如果路由器在消息过期之前未收到消息处理器的响应,则系统会丢弃连接并返回 HTTP 504 响应。

Proxy_read_timeout 的值应大于消息处理器使用的目标超时值。这样可以确保路由器在消息处理器有时间返回响应之前不会超时。消息处理程序的默认目标超时时间为 55 秒 55000 毫秒,如消息处理器的 conf_http_HTTPTransport.io.timeout.millis 令牌所定义。

57
keepalive_timeout

当客户端发出包含 Keep-Alive 标头的请求时,设置客户端与路由器之间的超时时长(以秒为单位)。路由器会在连接到期前一直保持打开状态。

如果路由器当前正在等待消息处理器的响应,则不会关闭连接。只有在路由器将响应返回给客户端之后,超时才会开始。

65
ssl_cryptos

设置虚拟主机支持的加密方式,替换路由器上设置的默认加密方式。

以英文冒号分隔密码列表,格式如下:

<Property name="ssl_ciphers">HIGH:!aNULL:!MD5:!DH+3DES:!kEDH;</Property>

如需了解此令牌允许的语法和值,请参阅 https://www.openssl.org/docs/man1.0.2/man1/cryptos.html。 请注意,此令牌使用 OpenSSL 加密名称(例如 AES128-SHA256),而不是 Java/JSSE 加密名称,例如 TLS_RSA_WITH_AES_128_CBC_SHA256。

HIGH:!aNULL:

!MD5:

!DH+3DES:

!kEDH

ssl_protocols

仅适用于 Edge Cloud for Private Cloud。

将虚拟主机支持的 TLS 协议设置为空格分隔的列表,以替换路由器上设置的默认协议。

注意:如果两个虚拟主机共享同一个端口,则必须将 ssl_protocols 设置为相同的协议。也就是说,共用同一端口的虚拟主机必须支持完全相同的协议。

按以下格式指定空格分隔的 TLS 协议列表:

<Property name="ssl_protocols">TLSv1 TLSv1.2</Property>
TLSv1 TLSv1.1 TLSv1.2
代理请求缓冲

启用(停用)或停用(停用)请求正文缓冲。启用缓冲功能后,路由器会先缓冲整个请求正文,然后再将其发送到消息处理器。如果发生错误,路由器可以重试其他消息处理器。

如果关闭,缓冲功能会停用,请求正文会在收到消息后立即发送到消息处理器。如果发生错误,路由器不会向其他消息处理器重试请求。

开启
代理_缓冲 启用(启用)或停用(停用)响应缓冲。缓冲开始时,路由器会缓冲响应。关闭缓冲功能后,当路由器收到响应时,系统会立即将响应同步传递给客户端。 开启