error-page
error-page 插件可自定义网关生成的 404、500、502 和 503 响应，但不会修改上游服务返回的响应。
启用插件
API7 Gateway 默认加载 error-page。在 APISIX 中配置插件元数据前，需要先在网关静态配置中加载该插件。
- 主机或 Docker
- Kubernetes（Helm）
保留 config.yaml 中的现有插件列表，并添加 error-page：
config.yaml
plugins:
# 保留现有插件列表。
- error-page
重新加载 APISIX 使配置生效。
APISIX Helm Chart 的 apisix.plugins 会替换已加载的插件列表。请从网关使用的完整列表开始，添加 error-page，并保持其他插件不变：
values.yaml
apisix:
plugins:
# 保留网关使用的完整插件列表。
- error-page
使用 APISIX Helm Chart 应用该 values 文件。
示例
自定义错误页面
该 示例展示了如何使用插件元数据自定义网关生成的 404 响应。
- Admin API
- ADC
- Ingress Controller
配置自定义错误页面的 插件元数据：
curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/error-page" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"enable": true,
"error_404": {
"body": "<html>\n <head>\n <title>404</title>\n </head>\n <body>\n <center>\n <h1>404 not found</h1>\n </center>\n <hr>\n <center>Gateway</center>\n </body>\n</html>",
"content_type": "text/html"
}
}'
为了演示插件的功能，创建一个带有 serverless-post-function 插件的路由，该插件从网关返回 404 错误代码给所有对该路由的请求：
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/*",
"id": "error-page-route",
"plugins": {
"serverless-post-function": {
"functions": [
"return function (conf, ctx)
local core = require(\"apisix.core\")
core.response.exit(404)
end"
]
},
"error-page": {}
},
"upstream": {
"nodes": {
"httpbin.org:80": 1
},
"type": "roundrobin"
}
}'
❶ 对所有请求返回 404 状态码。
❷ 启用 error-page 以返回自定义错误页面。
配置插件元数据，并创建启用了 serverless-post-function 和 error-page 插件的路由：
adc.yaml
plugin_metadata:
error-page:
enable: true
error_404:
body: "<html>\n <head>\n <title>404</title>\n </head>\n <body>\n <center>\n <h1>404 not found</h1>\n </center>\n <hr>\n <center>Gateway</center>\n </body>\n</html>"
content_type: text/html
services:
- name: error-page-service
routes:
- name: error-page-route
uris:
- /*
plugins:
serverless-post-function:
functions:
- |
return function (conf, ctx)
local core = require("apisix.core")
core.response.exit(404)
end
error-page: {}
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
❶ 对所有请求返回 404 状态码。
❷ 启用 error-page 以返回自定义错误页面。
将配置同步到网关：
adc sync -f adc.yaml
- Gateway API
- APISIX CRD
创建启用了 serverless-post-function 和 error-page 插件的路由：
error-page-ic.yaml
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: error-page-plugin-config
spec:
plugins:
- name: serverless-post-function
config:
functions:
- |
return function (conf, ctx)
local core = require("apisix.core")
core.response.exit(404)
end
- name: error-page
config: {}
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: error-page-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: PathPrefix
value: /
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: error-page-plugin-config
backendRefs:
- name: httpbin-external-domain
port: 80
❶ 对所有请求返回 404 状态码。
❷ 启用 error-page 以返回自定义错误页面。
创建启用了 serverless-post-function 和 error-page 插件的路由：
error-page-ic.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: httpbin-external-domain
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: error-page-route
spec:
ingressClassName: apisix
http:
- name: error-page-route
match:
paths:
- /*
upstreams:
- name: httpbin-external-domain
plugins:
- name: serverless-post-function
enable: true
config:
functions:
- |
return function (conf, ctx)
local core = require("apisix.core")
core.response.exit(404)
end
- name: error-page
enable: true
config: {}
❶ 对所有请求返回 404 状态码。
❷ 启用 error-page 以返回自定义错误页面。
更新 GatewayProxy 清单以配置 error-page 插件元数据：
gatewayproxy.yaml
apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
namespace: aic
name: apisix-config
spec:
provider:
type: ControlPlane
controlPlane:
# ...
# 控制面连接配置
pluginMetadata:
error-page:
enable: true
error_404:
body: "<html>\n <head>\n <title>404</title>\n </head>\n <body>\n <center>\n <h1>404 not found</h1>\n </center>\n <hr>\n <center>Gateway</center>\n </body>\n</html>"
content_type: text/html
将配置应用到集群：
kubectl apply -f gatewayproxy.yaml -f error-page-ic.yaml
发送请求到该路由：
curl -i "http://127.0.0.1:9080/get"
你应该看到 HTTP/1.1 404 Not Found 响应，并包含以下响应体：
<html>
<head>
<title>404</title>
</head>
<body>
<center>
<h1>404 not found</h1>
</center>
<hr>
<center>Gateway</center>
</body>
</html>