配置路由

Apache APISIX 基于路由提供灵活的网关管理能力，其中定义了路由路径和目标上游。

路由是通往上游目标的路由路径。在 Apache APISIX 中，路由负责根据定义的规则匹配客户端请求，加载并执行相应的插件，以及将请求转发到指定的上游服务。一个简单的路由可以使用路径匹配 URI 和相应的上游地址来设置。

上游是一组具有相同工作的目标节点。它定义了一个虚拟主机抽象，根据配置的规则对给定的一组服务节点执行负载均衡。

本教程指导你如何创建路由并对其进行验证。你将：

创建一个路由和一个指向 httpbin 服务的示例上游。
向路由发送请求，查看 APISIX 如何代理请求。

前置条件

完成安装 APISIX 以在 Docker 或 Kubernetes 中安装 APISIX。
如果使用这些工具，请安装 ADC 或 APISIX-MCP。

创建路由

在本节中，你将创建一个路由，将客户端请求转发到 httpbin，这是一个 HTTP 请求和响应服务。

Admin API
ADC
Ingress Controller
APISIX-MCP

curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "getting-started-ip",
  "uri": "/ip",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

如果路由创建成功，你将收到 HTTP/1.1 201 Created 响应。

adc.yaml
services:
  - name: httpbin Service
    routes:
      - uris:
          - /ip
        name: getting-started-ip
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

将配置同步到 APISIX：

adc sync -f adc.yaml

如果配置同步成功，你将收到类似的响应：

[11:25:49 AM] [ADC] › ✔  success   Sync configuration
[11:25:49 AM] [ADC] › ★  star      All is well, see you next time!

在使用 APISIX Ingress Controller 时，建议使用 Gateway API 或 APISIX CRD 而不是 Ingress 资源，因为它们提供了更大的灵活性和扩展性。为了演示目的，本教程展示了所有三种配置方法。后续教程将仅使用 Gateway API 和 APISIX CRD。

虽然本节演示了创建指向公开托管的 httpbin 服务的路由，但你可以相应地修改它以代理到 Kubernetes 集群内的服务请求。

important

如果你使用 Gateway API，应首先配置 GatewayClass 和 Gateway 资源：

显示配置

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: apisix
spec:
  controllerName: apisix.apache.org/apisix-ingress-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  namespace: ingress-apisix
  name: apisix
spec:
  gatewayClassName: apisix
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  infrastructure:
    parametersRef:
      group: apisix.apache.org
      kind: GatewayProxy
      name: apisix-config

请注意，Gateway 监听器中的 port 是必需的，但被忽略。这是由于数据平面的限制：它无法动态打开新端口。由于 Ingress Controller 不管理数据平面部署，它无法自动更新配置或重新启动数据平面以应用端口更改。

如果你使用 Ingress 或 APISIX 自定义资源，则无需额外配置即可继续，因为下面的 IngressClass 资源已随安装一起应用：

显示配置

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: apisix
spec:
  controller: apisix.apache.org/apisix-ingress-controller
  parameters:
    apiGroup: apisix.apache.org
    kind: GatewayProxy
    name: apisix-config
    namespace: ingress-apisix
    scope: Namespace

有关参数的更多信息，请参阅定义控制器和网关。

Gateway API
Ingress
APISIX CRD

创建一个 Kubernetes 清单文件，用于代理请求到 httpbin.org 的路由：

httpbin-route.yaml
apiVersion: v1
kind: Service
metadata:
  namespace: ingress-apisix
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: ingress-apisix
  name: getting-started-ip
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches:
    - path:
        type: Exact
        value: /ip
    backendRefs:
    - name: httpbin-external-domain
      port: 80

创建一个 Kubernetes 清单文件，用于代理请求到 httpbin.org 的路由：

httpbin-route.yaml
apiVersion: v1
kind: Service
metadata:
  namespace: ingress-apisix
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: ingress-apisix
  name: getting-started-ip
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /ip
        pathType: Exact
        backend:
          service:
            name: httpbin-external-domain
            port:
              number: 80

创建一个 Kubernetes 清单文件，用于代理请求到 httpbin.org 的路由：

httpbin-route.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: ingress-apisix
  name: httpbin-external-domain
spec:
  ingressClassName: apisix
  externalNodes:
  - type: Domain
    name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: ingress-apisix
  name: getting-started-ip
spec:
  ingressClassName: apisix
  http:
    - name: getting-started-ip
      match:
        paths:
          - /ip
      upstreams:
      - name: httpbin-external-domain

将配置应用到你的集群：

kubectl apply -f httpbin-route.yaml

在你的 AI 客户端中输入以下提示：

创建一个 ID 为 getting-started-ip 的路由，匹配 URI 为 /ip 的请求，并使用轮询负载均衡将其转发到 httpbin.org 端口 80 上的单个节点的上游。

你应该看到类似的响应：

Successfully created route "getting-started-ip" with the following configuration:

URI: /ip
Upstream: http://httpbin.org:80 (roundrobin load balancing)
Route ID: getting-started-ip
Status: Active (1)
Created at: 1744183830 (2025-04-09 07:30:30 UTC)
The route is now ready to accept requests at the /ip path, which will be forwarded to httpbin.org on port 80.

验证

Admin API
ADC
Ingress Controller
APISIX-MCP

向路由发送请求：

curl "http://127.0.0.1:9080/ip"

你应该看到类似的响应：

{
  "origin": "183.94.122.205"
}

向路由发送请求：

curl "http://127.0.0.1:9080/ip"

你应该看到类似的响应：

{
  "origin": "183.94.122.205"
}

首先，通过端口转发将服务端口暴露给本地机器：

kubectl port-forward svc/apisix-gateway 9080:80 &

上面的命令在后台运行，并将 apisix-gateway 服务的 80 端口映射到本地机器的 9080 端口。

向路由发送请求：

curl "http://127.0.0.1:9080/ip"

你应该看到类似的响应：

{
  "origin": "127.0.0.1"
}

在你的 AI 客户端中输入以下提示：

向路由发送请求以进行验证。

你应该看到类似的响应：

Successfully verified the route "getting-started-ip":

Received HTTP 200 response from httpbin.org
Response shows origin IP address (192.168.107.1, 103.97.2.159)
The route is properly configured and forwarding requests to httpbin.org
The upstream service is responding correctly to requests

下一步

本教程创建了一个指向单个上游节点的路由。在下一个教程中，你将学习如何配置多上游节点的负载均衡。

前置条件​

创建路由​

验证​

下一步​

前置条件

创建路由

验证

下一步