快速入门指南

本指南旨在让大家入门 Apache APISIX,我们将配置一个对外提供公共 API 的服务,并由 API key 进行访问保护。

另外,我们将以下面的 echo 端点为例,它将返回我们传递的参数。

Request

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

Response

  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. }

让我们来分析一下上面的请求 URL:

  • Protocol: HTTP
  • Port: 80
  • Host: httpbin.org
  • URI/Path: /get
  • Query Parameters: foo1, foo2

前提

如果您已经安装了 Apache APISIX,请直接阅读 第二步

  • 本指南使用 DockerDocker Compose 来安装 Apache APISIX。
  • curl:本指南使用 curl 命令行进行 API 测试,但是您也可以使用任何其它工具,例如 Postman

第一步: 安装 Apache APISIX

得益于 Docker,我们可以通过执行以下命令来启动 Apache APISIX 并启用 Admin API

  1. $ git clone https://github.com/apache/apisix-docker.git
  2. $ cd apisix-docker/example
  3. $ docker-compose -p docker-apisix up -d

下载所需的所有文件将花费一些时间,这取决于您的网络,请耐心等待。下载完成后,我们可以使用 curl 访问 Admin API,以判断 Apache APISIX 是否成功启动。

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

我们期望获得以下返回数据:

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

第二步: 创建一个 Route

恭喜!您现在已经拥有一个运行中的 Apache APISIX 实例了!接下来,让我们来创建一个 Route。

在我们继续之前

您知道吗?Apache APISIX 提供了强大的 Admin APIDashboard 可供我们使用,但在本指南中我们使用 Admin API 来做演示。

我们可以创建一个 Route 并与后端服务(通常称之为上游: Upstream)绑定,当一个 请求(Request) 到达 Apache APISIX 时,Apache APISIX 就会明白这个请求应该转发到哪个上游服务中。

Apache APISIX 是如何知道的呢?那是因为我们为 Route 对象配置了匹配规则。下面是一个 Route 配置示例:

  1. {
  2. "methods": ["GET"],
  3. "host": "example.com",
  4. "uri": "/services/users/*",
  5. "upstream": {
  6. "type": "roundrobin",
  7. "nodes": {
  8. "httpbin.org:80": 1
  9. }
  10. }
  11. }

这条路由配置意味着,当它们满足下述的 所有 规则时,所有匹配的入站请求都将被转发到 httpbin.org:80 上游:

  • 请求的 HTTP 方法为 GET;
  • 请求头包含 Host 字段,且它的值为 example.com;
  • 请求路径匹配 /services/users/** 意味着任意的子路径,例如 /services/users/getAll?limit=10

当这条路由创建后,我们就可以使用 Apache APISIX 对外暴露的地址去访问后端服务(即上游):

  1. $ curl -i -X GET "http://{APISIX_BASE_URL}/services/users/getAll?limit=10" -H "Host: example.com"

这将会被 Apache APISIX 转发到 http://httpbin.org:80/services/users/getAll?limit=10

创建一个上游(Upstream)

读完上一节,我们知道必须为 路由 设置 上游。只需执行下面的命令即可创建一个上游:

  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 设置为我们的上游目标(后端服务),其 ID 为 1。更多字段信息,请参阅 Admin API

注意: 创建上游实际上并不是必需的,因为我们可以使用 插件 拦截请求,然后直接响应。但在本指南中,我们假设需要设置至少一个上游。

路由与上游绑定

We just created an Upstream(Reference to our backend services), let’s bind one Route with it! 我们刚刚创建了一个上游(引用我们的后端服务),让我们为它绑定一个路由!

  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. }'

就是这样!

验证

再次恭喜!我们已创建了路由与上游,并将它们进行了绑定。现在让我们访问 Apache APISIX 来测试这条已经创建的路由:

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

哇哦! 它将从我们的上游(实际是 httpbin.org)返回数据,结果符合预期!

进阶

身份验证

让我们来做一些有趣的事情,由于我们在第二步中创建的路由是公共的,任何人 都可以访问,现在我们希望只有 John 可以访问它。让我们使用 消费者(Consumer)插件(Plugin) 来实现这个保护措施。

首先,让我们用 key-auth 插件创建一个 消费者(Consumer) John,我们需要提供一个指定的密钥:

  1. $ curl "http://127.0.0.1:9080/apisix/admin/consumers" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
  2. {
  3. "username": "john",
  4. "plugins": {
  5. "key-auth": {
  6. "key": "key-of-john"
  7. }
  8. }
  9. }'

接下来,让我们绑定 消费者(John) 到路由上,我们仅仅需要为路由 启用 key-auth 插件即可。

  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. "plugins": {
  6. "key-auth": {}
  7. },
  8. "upstream_id": "1"
  9. }'

OK,现在当我们访问第二步创建的路由时,将会产生一个 Unauthorized Error(未经授权的错误)。让我们看看如何正确访问那个路由:

  1. $ curl -i -X GET http://127.0.0.1:9080/get -H "Host: httpbin.org" -H 'apikey: superSecretAPIKey'

是的,仅仅添加了一个带有正确密钥的名为 apikeyHeader!这样就可以保护任何的路由了。

为路由添加前缀

现在,假设您要向路由添加前缀(例如:samplePrefix),并且不想使用 host 头, 则可以使用 proxy-rewrite 插件来完成。

  1. $ curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
  2. {
  3. "uri": "/samplePrefix/get",
  4. "plugins": {
  5. "proxy-rewrite": {
  6. "regex_uri": ["^/samplePrefix/get(.*)", "/get$1"]
  7. },
  8. "key-auth": {}
  9. },
  10. "upstream_id": "1"
  11. }'

现在您可以使用以下命令来调用路由:

  1. $ curl -i -X GET "http://127.0.0.1:9080/samplePrefix/get?param1=foo&param2=bar" -H "apikey: key-of-john"

APISIX Dashboard(控制台)

Apache APISIX 提供了一个 Dashboard,让我们的操作更直观更轻松。

Dashboard

故障排查

  • 确保所需的所有端口(默认的 9080/9443/2379)未被其他系统/进程使用。

    下面是终止正在侦听特定端口(基于 unix 的系统)的进程的命令。

    1. $ sudo fuser -k 9443/tcp
  • 如果 Docker 容器持续不断地重启/失败,请登录容器并观察日志以诊断问题。

    1. $ docker logs -f --tail container_id