11 KiB
title |
---|
快速入门指南 |
概述
本文是 Apache APISIX 的快速入门指南。快速入门分为三个步骤:
- 通过 Docker Compose 安装 Apache APISIX。
- 创建路由并绑定上游。
- 使用命令行语句
curl
验证绑定之后返回的结果是否符合预期。
除此之外,本文也提供了 Apache APISIX 的一些进阶操作技巧,包括:添加身份验证、为路由添加前缀、使用 APISIX Dashboard 以及常见问题排查。
我们将以下面的 echo
端点为例,它将返回我们传递的参数。
请求内容
请求 URL 由以下这些参数构成:
- Protocol:即网络传输协议,示例中使用的是最常见的
HTTP
协议。 - Port:即端口,示例中使用的
80
端口。 - Host:即宿主机,示例中的主机是
httpbin.org
。 - Path:即路径,示例中的路径是
/get
。 - Query Parameters:即查询字符串,这里有两个字符串,分别是
foo1
和foo2
。
运行以下命令,发送请求:
curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"
响应内容
{
"args": {
"foo1": "bar1",
"foo2": "bar2"
},
"headers": {
"Accept": "*/*",
"Host": "httpbin.org",
"User-Agent": "curl/7.29.0",
"X-Amzn-Trace-Id": "Root=1-6088fe84-24f39487166cce1f0e41efc9"
},
"origin": "58.152.81.42",
"url": "http://httpbin.org/get?foo1=bar1&foo2=bar2"
}
前提条件
-
已安装 Docker Compose 组件。
:::note 说明 如果您已经安装了 Apache APISIX,请直接阅读 第二步 :::
第一步:安装 Apache APISIX
得益于 Docker,我们可以通过执行以下命令来启动 Apache APISIX 并启用 Admin API。
#将 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
Apache APISIX 已支持 ARM64 架构。如果您正在使用 ARM64,请在最后一步执行
docker-compose -p docker-apisix -f docker-compose-arm64.yml 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":0,
"action":"get",
"node":{
"key":"/apisix/services",
"nodes":[],
"dir":true
}
}
第二步:创建路由
您现在已经拥有一个运行中的 Apache APISIX 实例了!接下来,让我们来创建一个路由(Route)。
工作原理
Apache APISIX 提供了强大的 Admin API 和 Dashboard 可供我们使用。在本文中,我们使用 Admin API 来做演示。
我们可以创建一个 Route 并与上游服务(通常也被称为 Upstream 或后端服务)绑定,当一个 请求(Request)
到达 Apache APISIX 时,Apache APISIX 就会明白这个请求应该转发到哪个上游服务中。
因为我们为 Route 对象配置了匹配规则,所以 Apache APISIX 可以将请求转发到对应的上游服务。以下代码会创建一个示例 Route 配置:
curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
"methods": ["GET"],
"host": "example.com",
"uri": "/anything/*",
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
这条路由配置意味着,当它们满足下述的 所有 规则时,所有匹配的入站请求都将被转发到 httpbin.org:80
这个上游服务:
- 请求的 HTTP 方法为
GET
。 - 请求头包含
host
字段,且它的值为example.com
。 - 请求路径匹配
/anything/*
,*
意味着任意的子路径,例如/anything/foo?arg=10
。
当这条路由创建后,我们可以使用 Apache APISIX 对外暴露的地址去访问上游服务:
curl -i -X GET "http://127.0.0.1:9080/anything/foo?arg=10" -H "Host: example.com"
这将会被 Apache APISIX 转发到 http://httpbin.org:80/anything/foo?arg=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",
"upstream_id": "1"
}'
第三步:验证
我们已创建了路由与上游服务,并将它们进行了绑定。现在让我们访问 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 以及常见问题排查。
添加身份验证
我们在第二步中创建的路由是公共的,只要知道 Apache APISIX 对外暴露的地址,任何人 都可以访问这个上游服务,这种访问方式没有保护措施,存在一定的安全隐患。在实际应用场景中,我们需要为路由添加身份验证。
现在我们希望只有特定的用户 John
可以访问这个上游服务,需要使用 消费者(Consumer) 和 插件(Plugin) 来实现身份验证。
首先,让我们用 key-auth 插件创建一个 消费者(Consumer) John
,我们需要提供一个指定的密钥:
curl "http://127.0.0.1:9080/apisix/admin/consumers" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
"username": "john",
"plugins": {
"key-auth": {
"key": "key-of-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: key-of-john"
为路由添加前缀
现在,假设您要向路由添加前缀(例如: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¶m2=bar" -H "apikey: key-of-john"
APISIX Dashboard
Apache APISIX 提供了一个 Dashboard,让我们的操作更直观更轻松。
常见问题排查
-
确保所需的所有端口(默认的 9080/9443/2379)未被其他系统/进程使用。
下面是终止正在侦听特定端口(基于 unix 的系统)的进程的命令。
sudo fuser -k 9443/tcp
-
如果 Docker 容器持续不断地重启或失败,请登录容器并观察日志以诊断问题。
docker logs -f --tail container_id