request-id

描述

request-id 插件为每个通过网关代理的请求分配一个唯一 ID，可用于请求跟踪和调试。如果请求在由 header_name 指定的请求头中已包含一个 ID 且其值不为空（""），插件将使用该值作为请求 ID；否则，将生成一个新的 ID，并且不会覆盖已有的有效 ID。

请求 ID 默认包含在网关日志中。当插件启用时，它还会被添加到响应标头中。

属性

名称	类型	必选项	默认值	有效值	描述
header_name	string	否	”X-Request-Id”		携带请求唯一 ID 的标头的名称。请注意，如果请求在 `header_name` 标头中携带 ID，则插件将使用标头值作为唯一 ID，并且不会用生成的 ID 覆盖它。
include_in_response	布尔值	否	true		如果为 true，则将生成的请求 ID 包含在响应标头中，其中标头的名称是 `header_name` 值。
algorithm	string	否	”uuid”	[“uuid”,“nanoid”,“range_id”,“ksuid”]	用于生成唯一 ID 的算法。设置为 `uuid` 时，插件会生成一个通用唯一标识符。设置为 `nanoid` 时，插件会生成一个紧凑的、URL 安全的 ID。设置为 `range_id` 时，插件会生成具有特定参数的连续 ID。设置为 `ksuid` 时，插件会生成具有时间戳和随机值的连续 ID。
range_id	object	否			使用 `range_id` 算法生成请求 ID 的配置。
range_id.char_set	string	否	”abcdefghijklmnopqrstuvwxyzABCDEFGHIGKLMNOPQRSTUVWXYZ0123456789”	最小长度 6	用于 `range_id` 算法的字符集。
range_id.length	integer	否	16	>=6	用于 `range_id` 算法的生成的 ID 的长度。

示例

以下示例演示了如何在不同场景中配置”request-id”。

NOTE

你可以这样从 config.yaml 中获取 admin_key 并存入环境变量：

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

理解网关日志中的请求 ID

从 APISIX 3.15.0 版本开始，无论插件是否启用，请求 ID 都会包含在访问日志和错误日志中。

当插件禁用时，请求 ID 默认使用 NGINX 内置的 $request_id。
当插件启用时，请求 ID 将设置为插件生成的唯一 ID。

这确保了请求追踪始终可用，在启用插件时功能更加完善。

以下示例演示了当插件禁用和启用时，请求 ID 在网关日志中的不同表现。

创建一个不包含 request-id 插件的路由：

admin-api

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

adc

adc.yaml

services:
  - name: request-id-service
    routes:
      - name: request-id-route
        uris:
          - /anything
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

将配置同步到网关：

adc sync -f adc.yaml

aic

gateway-api

request-id-ic.yaml

apiVersion: v1
kind: Service
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: request-id-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
      backendRefs:
        - name: httpbin-external-domain
          port: 80

apisix-crd

request-id-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: request-id-route
spec:
  ingressClassName: apisix
  http:
    - name: request-id-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain

将配置应用到集群：

kubectl apply -f request-id-ic.yaml

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该收到 HTTP/1.1 200 OK 响应。在网关日志中，你应该看到类似以下的条目，其中最后一个值是来自 NGINX 内置 $request_id 的请求 ID：

192.168.215.1 - - [30/Jan/2026:07:21:31 +0000] localhost:9080 "GET /anything HTTP/1.1" 200 391 1.657 "-" "curl/8.6.0" 3.210.41.225:80 200 1.608 "http://localhost:9080" "8a14012e5d0414aff4f15f04b0bd8cb9"

更新路由，添加 request-id 插件：

admin-api

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

adc

adc.yaml

services:
  - name: request-id-service
    routes:
      - name: request-id-route
        uris:
          - /anything
        plugins:
          request-id: {}
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

将配置同步到网关：

adc sync -f adc.yaml

aic

gateway-api

request-id-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: request-id-plugin-config
spec:
  plugins:
    - name: request-id
      config:
        _meta:
          disable: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: request-id-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: request-id-plugin-config
      backendRefs:
        - name: httpbin-external-domain
          port: 80

apisix-crd

request-id-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: request-id-route
spec:
  ingressClassName: apisix
  http:
    - name: request-id-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: request-id
        enable: true

将配置应用到集群：

kubectl apply -f request-id-ic.yaml

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该收到 HTTP/1.1 200 OK 响应。在网关日志中，你应该看到类似以下的条目，其中最后一个值是插件生成的请求 ID：

192.168.215.1 - - [30/Jan/2026:07:36:24 +0000] localhost:9080 "GET /anything HTTP/1.1" 200 391 0.685 "-" "curl/8.6.0" 52.20.30.6:80 200 0.653 "http://localhost:9080" "8c0ac818-f9d6-4160-be60-8fc74e76be73"

将请求 ID 附加到默认响应标头

以下示例演示了如何在路由上配置 request-id，如果请求中未传递标头值，则将生成的请求 ID 附加到默认的 X-Request-Id 响应标头。当在请求中设置 X-Request-Id 标头时，插件将把请求标头中的值作为请求 ID。

使用其默认配置（明确定义）创建带有 request-id 插件的路由：

admin-api

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "header_name": "X-Request-Id",
        "include_in_response": true,
        "algorithm": "uuid"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

adc

adc.yaml

services:
  - name: request-id-service
    routes:
      - name: request-id-route
        uris:
          - /anything
        plugins:
          request-id:
            header_name: X-Request-Id
            include_in_response: true
            algorithm: uuid
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

将配置同步到网关：

adc sync -f adc.yaml

aic

gateway-api

request-id-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: request-id-plugin-config
spec:
  plugins:
    - name: request-id
      config:
        header_name: X-Request-Id
        include_in_response: true
        algorithm: uuid
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: request-id-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: request-id-plugin-config
      backendRefs:
        - name: httpbin-external-domain
          port: 80

apisix-crd

request-id-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: request-id-route
spec:
  ingressClassName: apisix
  http:
    - name: request-id-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: request-id
        enable: true
        config:
          header_name: X-Request-Id
          include_in_response: true
          algorithm: uuid

将配置应用到集群：

kubectl apply -f request-id-ic.yaml

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该会收到一个 HTTP/1.1 200 OK 响应，并且会看到响应包含 X-Request-Id 标头和生成的 ID：

X-Request-Id: b9b2c0d4-d058-46fa-bafc-dd91a0ccf441

使用标头中的自定义请求 ID 向路由发送请求：

curl -i "http://127.0.0.1:9080/anything" -H 'X-Request-Id: some-custom-request-id'

你应该会收到 HTTP/1.1 200 OK 响应，并看到响应包含带有自定义请求 ID 的 X-Request-Id 标头：

X-Request-Id：some-custom-request-id

将请求 ID 附加到自定义响应标头

以下示例演示如何在路由上配置 request-id，将生成的请求 ID 附加到指定的标头。

使用 request-id 插件创建路由，以定义带有请求 ID 的自定义标头，并将请求 ID 包含在响应标头中：

admin-api

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "header_name": "X-Req-Identifier",
        "include_in_response": true
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

adc

adc.yaml

services:
  - name: request-id-service
    routes:
      - name: request-id-route
        uris:
          - /anything
        plugins:
          request-id:
            header_name: X-Req-Identifier
            include_in_response: true
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

将配置同步到网关：

adc sync -f adc.yaml

aic

gateway-api

request-id-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: request-id-plugin-config
spec:
  plugins:
    - name: request-id
      config:
        header_name: X-Req-Identifier
        include_in_response: true
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: request-id-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: request-id-plugin-config
      backendRefs:
        - name: httpbin-external-domain
          port: 80

apisix-crd

request-id-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: request-id-route
spec:
  ingressClassName: apisix
  http:
    - name: request-id-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: request-id
        enable: true
        config:
          header_name: X-Req-Identifier
          include_in_response: true

将配置应用到集群：

kubectl apply -f request-id-ic.yaml

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该收到一个 HTTP/1.1 200 OK 响应，并看到响应包含带有生成 ID 的 X-Req-Identifier 标头：

X-Req-Identifier：1c42ff59-ee4c-4103-a980-8359f4135b21

在响应标头中隐藏请求 ID

以下示例演示如何在路由上配置 request-id，将生成的请求 ID 附加到指定的标头。包含请求 ID 的标头应转发到上游服务，但不会在响应标头中返回。

使用 request-id 插件创建路由，以定义带有请求 ID 的自定义标头，而不在响应标头中包含请求 ID：

admin-api

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "header_name": "X-Req-Identifier",
        "include_in_response": false
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

adc

adc.yaml

services:
  - name: request-id-service
    routes:
      - name: request-id-route
        uris:
          - /anything
        plugins:
          request-id:
            header_name: X-Req-Identifier
            include_in_response: false
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

将配置同步到网关：

adc sync -f adc.yaml

aic

gateway-api

request-id-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: request-id-plugin-config
spec:
  plugins:
    - name: request-id
      config:
        header_name: X-Req-Identifier
        include_in_response: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: request-id-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: request-id-plugin-config
      backendRefs:
        - name: httpbin-external-domain
          port: 80

apisix-crd

request-id-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: request-id-route
spec:
  ingressClassName: apisix
  http:
    - name: request-id-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: request-id
        enable: true
        config:
          header_name: X-Req-Identifier
          include_in_response: false

将配置应用到集群：

kubectl apply -f request-id-ic.yaml

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该收到 HTTP/1.1 200 OK 响应，并在响应标头中看到 X-Req-Identifier 标头。在响应主体中，你应该看到：

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.6.0",
    "X-Amzn-Trace-Id": "Root=1-6752748c-7d364f48564508db1e8c9ea8",
    "X-Forwarded-Host": "127.0.0.1",
    "X-Req-Identifier": "268092bc-15e1-4461-b277-bf7775f2856f"
  },
  ...
}

这表明请求 ID 已转发到上游服务，但未在响应标头中返回。

使用 `nanoid` 算法

以下示例演示如何在路由上配置 request-id 并使用 nanoid 算法生成请求 ID。

使用 request-id 插件创建路由，如下所示：

admin-api

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "algorithm": "nanoid"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

adc

adc.yaml

services:
  - name: request-id-service
    routes:
      - name: request-id-route
        uris:
          - /anything
        plugins:
          request-id:
            algorithm: nanoid
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

将配置同步到网关：

adc sync -f adc.yaml

aic

gateway-api

request-id-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: request-id-plugin-config
spec:
  plugins:
    - name: request-id
      config:
        algorithm: nanoid
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: request-id-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: request-id-plugin-config
      backendRefs:
        - name: httpbin-external-domain
          port: 80

apisix-crd

request-id-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: request-id-route
spec:
  ingressClassName: apisix
  http:
    - name: request-id-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: request-id
        enable: true
        config:
          algorithm: nanoid

将配置应用到集群：

kubectl apply -f request-id-ic.yaml

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该收到一个 HTTP/1.1 200 OK 响应，并看到响应包含 X-Request-Id 标头，其中的 ID 使用 nanoid 算法生成：

X-Request-Id: kepgHWCH2ycQ6JknQKrX2

使用 `ksuid` 算法

以下示例演示如何在路由上配置 request-id 并使用 ksuid 算法生成请求 ID。

使用 request-id 插件创建路由，如下所示：

admin-api

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "algorithm": "ksuid"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

adc

adc.yaml

services:
  - name: request-id-service
    routes:
      - name: request-id-route
        uris:
          - /anything
        plugins:
          request-id:
            algorithm: ksuid
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

将配置同步到网关：

adc sync -f adc.yaml

aic

gateway-api

request-id-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: request-id-plugin-config
spec:
  plugins:
    - name: request-id
      config:
        algorithm: ksuid
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: request-id-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: request-id-plugin-config
      backendRefs:
        - name: httpbin-external-domain
          port: 80

apisix-crd

request-id-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: request-id-route
spec:
  ingressClassName: apisix
  http:
    - name: request-id-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: request-id
        enable: true
        config:
          algorithm: ksuid

将配置应用到集群：

kubectl apply -f request-id-ic.yaml

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该收到一个 HTTP/1.1 200 OK 响应，并看到响应包含 X-Request-Id 标头，其中的 ID 使用 ksuid 算法生成：

X-Request-Id: 325ghCANEKjw6Jsfejg5p6QrLYB

如果装有ksuid命令工具，此 ID 可以通过ksuid -f inspect 325ghCANEKjw6Jsfejg5p6QrLYB查看：

REPRESENTATION:

    String: 325ghCANEKjw6Jsfejg5p6QrLYB
    Raw: 15430DBBD7F68AD7CA0AE277772AB36DDB1A3C13

COMPONENTS:

    Time: 2025-09-01 16:39:23 +0800 CST
    Timestamp: 356715963
    Payload: D7F68AD7CA0AE277772AB36DDB1A3C13

全局和在路由上附加请求 ID

以下示例演示如何将 request-id 配置为全局插件并在路由上附加两个 ID。

admin-api

为 request-id 插件创建全局规则，将请求 ID 添加到自定义标头：

curl -i "http://127.0.0.1:9180/apisix/admin/global_rules" -X PUT -d '{
  "id": "rule-for-request-id",
  "plugins": {
    "request-id": {
      "header_name": "Global-Request-ID"
    }
  }
}'

使用 request-id 插件创建路由，将请求 ID 添加到不同的自定义标头：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "header_name": "Route-Request-ID"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

adc

将 request-id 插件配置为全局规则并在路由上配置：

adc.yaml

global_rules:
  - id: rule-for-request-id
    plugins:
      request-id:
        header_name: Global-Request-ID
services:
  - name: request-id-service
    routes:
      - name: request-id-route
        uris:
          - /anything
        plugins:
          request-id:
            header_name: Route-Request-ID
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

将配置同步到网关：

adc sync -f adc.yaml

aic

gateway-api

更新你的 GatewayProxy 清单以启用 request-id 作为全局插件：

gatewayproxy.yaml

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: aic
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      # ...
      # your control plane connection configuration
  plugins:
  - name: request-id
    enabled: true
    config:
      header_name: Global-Request-ID

创建带有 request-id 插件的路由，将请求 ID 添加到不同的自定义标头：

request-id-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: request-id-plugin-config
spec:
  plugins:
    - name: request-id
      config:
        header_name: Route-Request-ID
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: request-id-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /anything
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: request-id-plugin-config
      backendRefs:
        - name: httpbin-external-domain
          port: 80

将配置应用到集群：

kubectl apply -f gatewayproxy.yaml -f request-id-ic.yaml

apisix-crd

创建全局 request-id 插件的 Kubernetes 清单文件：

global-request-id.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixGlobalRule
metadata:
  namespace: aic
  name: global-request-id
spec:
  ingressClassName: apisix
  plugins:
  - name: request-id
    enable: true
    config:
      header_name: Global-Request-ID

创建带有 request-id 插件的路由，将请求 ID 添加到不同的自定义标头：

request-id-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: request-id-route
spec:
  ingressClassName: apisix
  http:
    - name: request-id-route
      match:
        paths:
          - /anything
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: request-id
        enable: true
        config:
          header_name: Route-Request-ID

将配置应用到集群：

kubectl apply -f global-request-id.yaml -f request-id-ic.yaml

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该会收到 HTTP/1.1 200 OK 响应，并看到响应包含以下标头：

Global-Request-ID：2e9b99c1-08ed-4a74-b347-49c0891b07ad
Route-Request-ID：d755666b-732c-4f0e-a30e-a7a71ace4e26

Edit this page on GitHub Report an issue

request-id

描述

属性

示例

理解网关日志中的请求 ID

将请求 ID 附加到默认响应标头

将请求 ID 附加到自定义响应标头

在响应标头中隐藏请求 ID

使用 nanoid 算法

使用 ksuid 算法

全局和在路由上附加请求 ID

使用 `nanoid` 算法

使用 `ksuid` 算法