快速入门指南 - 《Apache APISIX v2.8 官方文档》

第一步：安装 Apache APISIX
进阶操作

通过安装 Apache APISIX。
创建路由并绑定上游。
使用命令行语句验证绑定之后返回的结果是否符合预期。

除此之外，本文也提供了 Apache APISIX 的一些进阶操作技巧，包括：添加身份验证、为路由添加前缀、使用 APISIX Dashboard 以及常见问题排查。

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

请求内容

请求 URL 由以下这些参数构成：

Protocol：即网络传输协议，示例中使用的是最常见的 HTTP 协议。
Port：即端口，示例中使用的 80 端口。
Host：即宿主机，示例中的主机是 httpbin.org。
Path：即路径，示例中的路径是/get。
Query Parameters：即查询字符串，这里有两个字符串，分别是foo1和foo2。

运行以下命令，发送请求：

响应内容

{
  "args": {
    "foo1": "bar1",
    "foo2": "bar2"
  },
  "headers": {
    "Accept": "*/*",
    "Host": "httpbin.org",
    "User-Agent": "curl/7.29.0",
    "X-Amzn-Trace-Id": "Root=1-6088fe84-24f39487166cce1f0e41efc9"
  },
  "url": "http://httpbin.org/get?foo1=bar1&foo2=bar2"
}

前提条件

已安装。
本文使用 curl 命令行进行 API 测试。您也可以使用其他工具例如等，进行测试。

:::note 说明如果您已经安装了 Apache APISIX，请直接阅读第二步 :::

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

#将 Apache APISIX 的 Docker 镜像下载到本地
git clone https://github.com/apache/apisix-docker.git
# 将当前的目录切换到 apisix-docker/example 路径下
cd apisix-docker/example
# 运行 docker-compose 命令，安装 Apache APISIX
docker-compose -p docker-apisix up -d

下载所需的所有文件将花费一些时间，这取决于您的网络，请耐心等待。

下载完成后，在运行 Docker 的宿主机上执行curl命令访问 Admin API，根据返回数据判断 Apache APISIX 是否成功启动。

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

返回数据如下所示，表示Apache APISIX 成功启动：

{
  "count":1,
  "node":{
    "key":"/apisix/services",
    "nodes":{},
    "dir":true
  }
}

第二步：创建路由

Apache APISIX 提供了强大的和 Dashboard 可供我们使用。在本文中，我们使用 Admin API 来做演示。

我们可以创建一个并与上游服务（通常也被称为Upstream或后端服务）绑定，当一个 请求（Request） 到达 Apache APISIX 时，Apache APISIX 就会明白这个请求应该转发到哪个上游服务中。

因为我们为 Route 对象配置了匹配规则，所以 Apache APISIX 可以将请求转发到对应的上游服务。以下代码是一个 Route 配置示例：

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

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

当这条路由创建后，我们可以使用 Apache APISIX 对外暴露的地址去访问上游服务：

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）

读完上一节，我们知道必须为 Route 设置 Upstream。只需执行下面的命令即可创建一个上游服务：

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

我们使用 roundrobin 作为负载均衡机制，并将 httpbin.org:80 设置为我们的上游服务，其 ID 为 1。更多字段信息，请参阅 Admin API。

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

我们刚刚创建了一个上游服务，现在让我们为它绑定一个路由！

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

我们已创建了路由与上游服务，并将它们进行了绑定。现在让我们访问 Apache APISIX 来测试这条路由：

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

它从我们的上游服务（实际是 httpbin.org）返回数据，并且结果符合预期。

进阶操作

本节提供了 Apache APISIX 的一些进阶操作技巧，包括：添加身份验证、为路由添加前缀、使用 APISIX Dashboard 以及常见问题排查。

添加身份验证

现在我们希望只有特定的用户 John 可以访问这个上游服务，需要使用消费者（Consumer）和来实现身份验证。

首先，让我们用 key-auth 插件创建一个 John，我们需要提供一个指定的密钥：

接下来，让我们绑定 消费者（John） 到路由上，我们只需要为路由启用 key-auth 插件即可。

curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
  "uri": "/get",
  "host": "httpbin.org",
  "plugins": {
    "key-auth": {}
  },
  "upstream_id": "1"
}'

现在当我们访问第二步创建的路由时，会触发 Unauthorized Error（未经授权的错误）。

访问那个路由的正确方式是添加一个带有正确密钥的名为 apikey 的 Header，如下方代码所示。

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

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

curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
  "uri": "/samplePrefix/get",
  "plugins": {
    "proxy-rewrite": {
      "regex_uri": ["^/samplePrefix/get(.*)", "/get$1"]
    },
    "key-auth": {}
  },
  "upstream_id": "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，让我们的操作更直观更轻松。

:::note 注意 APISIX Dashboard 目前仍然是一个实验性功能。 :::

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

下面是终止正在侦听特定端口（基于 unix 的系统）的进程的命令。
如果 Docker 容器持续不断地重启或失败，请登录容器并观察日志以诊断问题。