快速入门指南

本文将为你介绍 Apache APISIX 的概念、功能以及如何使用 APISIX。

通过本文你可以了解到以下内容:

  • Apache APISIX 是什么?
  • APISIX 的架构及主要概念。
  • 如何使用 Docker 安装并运行 APISIX。
  • 如何使用 Admin API 创建第一个路由并配置上游。
  • 如何使用 APISIX Dashboard。
  • 如何寻求帮助。

Apache APISIX 是什么?

Apache APISIX 是 Apache 软件基金会下的云原生 API 网关,它兼具动态、实时、高性能等特点,提供了负载均衡、动态上游、灰度发布(金丝雀发布)、服务熔断、身份认证、可观测性等丰富的流量管理功能。我们可以使用 Apache APISIX 来处理传统的南北向流量,也可以处理服务间的东西向流量。同时,它也支持作为 K8s Ingress Controller 来使用。

主要特性

  • 多平台支持:APISIX 提供了多平台解决方案,它不但支持裸机运行,也支持在 Kubernetes 中使用,还支持与 AWS Lambda、Azure Function、Lua 函数和 Apache OpenWhisk 等云服务集成。
  • 全动态能力:APISIX 支持热加载,这意味着你不需要重启服务就可以更新 APISIX 的配置。请访问为什么 Apache APISIX 选择 Nginx + Lua 这个技术栈?以了解实现原理。
  • 精细化路由:APISIX 支持使用 NGINX 内置变量做为路由的匹配条件,你可以自定义匹配函数来过滤请求,匹配路由。
  • 运维友好:APISIX 支持与以下工具和平台集成:HashiCorp VaultZipkinApache SkyWalkingConsulNacosEureka。通过 APISIX Dashboard,运维人员可以通过友好且直观的 UI 配置 APISIX。
  • 多语言插件支持:APISIX 支持多种开发语言进行插件开发,开发人员可以选择擅长语言的 SDK 开发自定义插件。

主要概念

下图为 Apache APISIX 的架构:

flow-software-architecture

下表是本文涉及到的 APISIX 的主要概念和组件:

概念/组件描述
Route通过路由定义规则来匹配客户端请求,根据匹配结果加载并执行相应的插件,最后把请求转发给到指定的上游应用。
Upstream上游的作用是按照配置规则对服务节点进行负载均衡,它的地址信息可以直接配置到路由或服务上。
Admin API用户可以通过 Admin API 控制 APISIX 实例。

前提条件

在开始使用 APISIX 之前,请确保你已经安装以下应用:

  • DockerDocker Compose
  • curl 用于测试 API。你也可以使用 Hoppscotch 之类的工具。
  • 本文使用的上游服务是 httpbin.org,你可以使用它进行测试。这是一个返回服务,它将返回我们在请求中传递的参数。

请求内容:

请求 URL 由以下参数构成:

  • Protocol:即网络传输协议,在示例中,我们使用的是 HTTP 协议。
  • Port:即端口,示例中使用的 80 端口。
  • Host:即主机地址,示例中使用的是 httpbin.org
  • Path:即路径,示例中的路径是 /get
  • Query Parameters:即查询字符串,这里有两个字符串,分别是 foo1foo2

运行以下命令,发送请求:

  1. curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"

响应内容:

  1. {
  2. "args": {
  3. "foo1": "bar1",
  4. "foo2": "bar2"
  5. },
  6. "headers": {
  7. "Accept": "*/*",
  8. "Host": "httpbin.org",
  9. "User-Agent": "curl/7.29.0",
  10. "X-Amzn-Trace-Id": "Root=1-6088fe84-24f39487166cce1f0e41efc9"
  11. },
  12. "origin": "58.152.81.42",
  13. "url": "http://httpbin.org/get?foo1=bar1&foo2=bar2"
  14. }

安装 APISIX

我们将使用 Docker 安装 APISIX 并启用 Admin API

首先,通过 git 命令克隆 apisix-docker 仓库:

  1. git clone https://github.com/apache/apisix-docker.git
  2. cd apisix-docker/example

现在你可以通过 docker-compose 启动 APISIX。

  • x86
  • ARM/M1
  1. docker-compose -p docker-apisix up -d
  1. docker-compose -p docker-apisix -f docker-compose-arm64.yml up -d
快速入门指南 - 图2note

你也可以参考 APISIX 安装指南了解不同的安装方法。

快速入门指南 - 图3IMPORTANT

请确保其他系统进程没有占用 9080、9443 和 2379 端口。

在基于 UNIX 的系统中,可以使用以下命令来终止指定监听端口的运行:

  1. sudo fuser -k 9443/tcp

如果 Docker 容器不能正常运行,你可以通过以下命令检查日志进行问题诊断:

  1. docker logs -f --tail $<container_id>

安装完成后,你可以在运行 Docker 的宿主机上执行 curl 命令访问 Admin API,根据返回数据判断 APISIX 是否成功启动。

  1. # 注意:请在运行 Docker 的宿主机上执行 curl 命令。
  2. curl "http://127.0.0.1:9080/apisix/admin/services/" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'

如果返回数据如下所示,则表示 APISIX 成功启动:

  1. {
  2. "count":0,
  3. "action":"get",
  4. "node":{
  5. "key":"/apisix/services",
  6. "nodes":[],
  7. "dir":true
  8. }
  9. }

完成上述步骤后,你就已经拥有了一个正在运行的 APISIX 的实例了,现在你可以从之后的小节中学习如何创建路由以及了解 APISIX Dashboard 的操作。

创建路由

APISIX 提供了强大的 Admin APIDashboard 供用户使用。在下述示例中,我们将使用 Admin API 创建一个 Route 并与 Upstream 绑定,当一个请求到达 APISIX 时,APISIX 会将请求转发到指定的上游服务中。

以下示例代码中,我们将为路由配置匹配规则,以便 APISIX 可以将请求转发到对应的上游服务:

  1. curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
  2. {
  3. "methods": ["GET"],
  4. "host": "example.com",
  5. "uri": "/anything/*",
  6. "upstream": {
  7. "type": "roundrobin",
  8. "nodes": {
  9. "httpbin.org:80": 1
  10. }
  11. }
  12. }'

该配置意味着,当请求满足下述的所有规则时,请求将被转发到上游服务(httpbin.org:80):

  • 请求的 HTTP 方法为 GET
  • 请求头包含 host 字段,且它的值为 example.com
  • 请求路径匹配 /anything/** 意味着任意的子路径,例如 /anything/foo?arg=10

当路由创建完成后,可以通过以下命令访问上游服务:

  1. curl -i -X GET "http://127.0.0.1:9080/anything/foo?arg=10" -H "Host: example.com"

该请求将被 APISIX 转发到 http://httpbin.org:80/anything/foo?arg=10

使用上游服务创建路由

你可以通过以下命令创建一个上游,并在路由中使用它,而不是直接将其配置在路由中:

  1. curl "http://127.0.0.1:9080/apisix/admin/upstreams/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
  2. {
  3. "type": "roundrobin",
  4. "nodes": {
  5. "httpbin.org:80": 1
  6. }
  7. }'

该上游配置与上一节配置在路由中的上游相同。同样使用了 roundrobin 作为负载均衡机制,并设置了 httpbin.org:80 为上游服务。为了将该上游绑定到路由,此处需要把 upstream_id 设置为 "1"。更多字段信息,请参考 Admin API

上游服务创建完成后,可以通过以下命令绑定到指定路由:

  1. curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
  2. {
  3. "uri": "/get",
  4. "host": "httpbin.org",
  5. "upstream_id": "1"
  6. }'

我们已经创建了路由与上游服务,现在可以通过以下命令访问上游服务:

  1. curl -i -X GET "http://127.0.0.1:9080/get?foo1=bar1&foo2=bar2" -H "Host: httpbin.org"

该请求将被 APISIX 转发到 http://httpbin.org:80/anything/foo?arg=10

使用 APISIX Dashboard

你还可以使用 APISIX Dashboard 创建和配置类似于上述步骤中所创建的路由。

如果你已经完成上述操作步骤,就可以通过 localhost:9000 访问 APISIX Dashboard。

单击侧边栏中的 Route,可以查看已经配置的路由列表。你也可以看到在上述步骤中使用 Admin API 创建的路由。

你也可以通过单击 Create 按钮并按照提示创建新路由:

Creating a Route with APISIX Dashboard

新创建的路由将被添加到路由列表中:

Creating a Route with APISIX Dashboard

想要了解更多关于 APISIX Dashboard 的信息,请参考 APISIX Dashboard 文档

总结

完成上述步骤后,APISIX 就可以正常运行了。如果想利用 APISIX 实现身份验证、安全性、限流限速和可观测性等功能,可通过添加插件实现。各类插件的详细信息请参考插件市场

如果你在使用当中遇到困难,可以通过 APISIX 社区频道或者在 GitHub 上提交一个 issue 寻求帮助。