创建应用程序网关自定义错误页

应用程序网关允许你创建自定义错误页而非显示默认错误页。 可以使用品牌和布局来呈现与不同的响应代码相关的错误。 设置自定义错误页的一些方案包括

  • 显示 502 Bad Gateway 响应代码的维护或状态页。 当你的应用程序网关在计划性维护期间没有可将流量路由到的后端服务器或后端池服务器出现不可预见的问题时,这非常有用。
  • 显示 WAF 处于防护模式并阻止恶意流量时发生的 403 Forbidden 响应代码的自定义未经授权的访问页面
  • 在出现问题时显示包含联系人详细信息的公司品牌页面。

支持的响应代码

以下响应代码支持自定义错误页:

响应代码 说明
400 错误的请求(预览版)
403 已禁止
405 方法不受允许(预览版)
408 请求超时(预览版)
500 内部服务器错误(预览版)
502 网关错误
503 服务不可用(预览版)
504 网关超时(预览版)

注意

  • 应使用 API 版本 2022-09-01 或更高版本为新的响应代码配置错误页(预览版)。
  • 当前不支持响应代码 404(找不到页面)。
  • 对于应用程序网关生成的响应代码,将显示自定义错误页。 如果错误源自后端服务器,则它会被不作修改地传递给客户端。

配置级别

可以在全局或侦听器级别定义自定义错误页:

  • 全局级别 - 在全局级别设置的错误页将应用于该应用程序网关的所有侦听器。 当前不支持通过 Azure 门户对它进行配置。
  • 侦听器级别 - 侦听器级别的错误页让你能够精细控制,以便为该侦听器服务的应用程序设置错误页。

注意

将全局和侦听器级错误页结合用于网关时,必须显式提及该侦听器的所有所需响应代码的 URL。 特定于侦听器的配置会替代所有先前适用于该侦听器的全局配置。

要求

若要创建自定义错误页,你应该

  • 了解需要自定义错误页的响应代码。
  • 了解 HTML 页的相应远程位置 (URL)。 这必须是可公开访问的文件。
  • 确保错误页可公开访问,并返回 200 响应。
  • 确保错误页应是 *.htm 或 *.html 扩展类型。
  • 确保页面大小小于 1 MB。

可以为此 HTML 文件引用内部或外部图像/CSS。 对于在外部引用的资源,请使用可公开访问的绝对 URL。 在使用 base64 编码的内联图像、JavaScript 或 CSS 时,请注意 HTML 文件大小。

注意

  • 在 Azure 生态系统中,必须使用 Azure Blob 存储帐户或虚拟机来托管错误页。 请注意,Blob 存储应直接访问,因为 Azure CDN 服务前端的存储帐户当前不受支持。
  • 还可以选择在任何远程位置托管错误页。
  • 不支持相对链接。

工作原理

在应用程序网关的配置中指定错误页后,你的网关会验证通过 Internet 与 HTML 页面的连接。 然后,它会将文件下载到其本地缓存中。

当客户端遇到错误时,你的应用程序网关将返回响应代码和该 HTML 页。 任何外部引用的资源(如图像、JavaScript 和 CSS 文件)都直接由客户端提取。

应用程序网关不会定期检查源文件的位置来提取新版本。 你可以在网关上执行任何配置更新,以手动更新文件的缓存。 例如,将错误 URL 从页面 1 更改为页面 2,然后更改回页面 1,或者在添加新的侦听器时也会更新。

门户配置

配置特定于侦听器的自定义错误页的步骤:

  1. 在门户中导航到“应用程序网关”,并选择所需的资源。

  2. 选择“侦听器”并导航到你要为其指定错误页的特定侦听器。

  3. 在“自定义错误页”部分下,为所需的状态代码指定可公开访问的 URL。

  4. 选择“保存”。

    Screenshot of Application Gateway custom error page.

Azure PowerShell 配置

可使用 Azure PowerShell 来配置自定义缩放页。 例如,全局自定义错误页:

$appgw   = Get-AzApplicationGateway -Name <app-gateway-name> -ResourceGroupName <resource-group-name>

$updatedgateway = Add-AzApplicationGatewayCustomError -ApplicationGateway $appgw -StatusCode HttpStatus502 -CustomErrorPageUrl "http://<website-url>"

Set-AzApplicationGateway -ApplicationGateway $appgw

或侦听器级别错误页:

$appgw   = Get-AzApplicationGateway -Name <app-gateway-name> -ResourceGroupName <resource-group-name>

$listener01 = Get-AzApplicationGatewayHttpListener -Name <listener-name> -ApplicationGateway $appgw

$updatedlistener = Add-AzApplicationGatewayHttpListenerCustomError -HttpListener $listener01 -StatusCode HttpStatus502 -CustomErrorPageUrl "http://<website-url>"

Set-AzApplicationGateway -ApplicationGateway $appgw

有关详细信息,请参阅 Add-AzApplicationGatewayCustomErrorAdd-AzApplicationGatewayHttpListenerCustomError

后续步骤

有关应用程序网关诊断的信息,请参阅应用程序网关的后端运行状况、诊断日志和指标