2021-02-26 21:40:08 +08:00
|
|
|
|
---
|
|
|
|
|
title: 快速入门指南
|
|
|
|
|
---
|
|
|
|
|
|
2020-03-21 08:24:24 +08:00
|
|
|
|
<!--
|
|
|
|
|
#
|
|
|
|
|
# Licensed to the Apache Software Foundation (ASF) under one or more
|
|
|
|
|
# contributor license agreements. See the NOTICE file distributed with
|
|
|
|
|
# this work for additional information regarding copyright ownership.
|
|
|
|
|
# The ASF licenses this file to You under the Apache License, Version 2.0
|
|
|
|
|
# (the "License"); you may not use this file except in compliance with
|
|
|
|
|
# the License. You may obtain a copy of the License at
|
|
|
|
|
#
|
|
|
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
#
|
|
|
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
|
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
|
# See the License for the specific language governing permissions and
|
|
|
|
|
# limitations under the License.
|
|
|
|
|
#
|
|
|
|
|
-->
|
2020-04-16 19:21:46 +08:00
|
|
|
|
|
2020-03-21 08:24:24 +08:00
|
|
|
|
本指南的目的是介绍如何使用 APISIX 来配置出一个安全的可以对外提供服务的 API。当您读完本指南,你需要自己安装一下 APISIX 应用,并准备好一个可以对外提供服务的 API,该服务将由 API key 进行访问保护。
|
|
|
|
|
|
|
|
|
|
本指南会使用到以下 GET 请求,该服务可以回显发送到这个 API 的传参。
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
$ curl --location --request GET "https://httpbin.org/get?foo1=bar1&foo2=bar2"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
让我们来分析一下这个 URL 请求
|
|
|
|
|
|
|
|
|
|
- Scheme: HTTPS
|
|
|
|
|
- Host/Address: httpbin.org
|
|
|
|
|
- Port: 443
|
|
|
|
|
- URI: /get
|
|
|
|
|
- Query Parameters: foo1, foo2
|
|
|
|
|
|
|
|
|
|
## 前提
|
|
|
|
|
|
2020-06-19 12:03:55 +08:00
|
|
|
|
- 本指南使用 docker 和 docker compose 来安装 Apache APISIX。 但是, 如果您已经以其他方式安装了 Apache APISIX ,您只需跳到 [第二步](getting-started.md#第二步:-在-APISIX-中设置路由) 。
|
2020-03-21 08:24:24 +08:00
|
|
|
|
- Curl:指南使用 Curl 命令进行 API 测试,但是您也可以使用您选择的任何其他工具( 例如 Postman )。
|
|
|
|
|
|
|
|
|
|
## 第一步: 安装 APISIX
|
|
|
|
|
|
2021-02-06 13:28:47 +08:00
|
|
|
|
Apache APISIX 可以多种操作环境中安装。[如何安装文档](how-to-build.md#通过源码包安装) 显示了多个平台中的安装步骤。
|
2020-08-06 10:29:21 +08:00
|
|
|
|
为了快速入门,让我们基于 docker 容器的安装方式进行安装。启动 Apache APISIX 服务,我们可以参照这个镜像文件[repository](https://github.com/apache/apisix-docker) 并切换到 example 文件夹下执行如下命令。
|
2020-03-21 08:24:24 +08:00
|
|
|
|
|
|
|
|
|
如下命令会启动 Apache APISIX 服务并默认在 9080 端口( https 请求是 9443 端口) 提供 admin API 接口服务
|
|
|
|
|
|
|
|
|
|
```bash
|
2020-08-06 10:29:21 +08:00
|
|
|
|
$ git clone https://github.com/apache/apisix-docker.git
|
|
|
|
|
$ cd apisix-docker/example
|
2020-03-21 08:24:24 +08:00
|
|
|
|
$ docker-compose -p docker-apisix up -d
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
第一次下载源代码需要一段时间,之后将非常快。在 docker 容器启动后,请访问以下链接,检查您是否获得成功的响应。
|
|
|
|
|
|
|
|
|
|
```bash
|
2020-11-28 19:05:14 +08:00
|
|
|
|
$ curl "http://127.0.0.1:9080/apisix/admin/services/" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
|
2020-03-21 08:24:24 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
下面是 Admin API 的接口响应:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"node": {
|
|
|
|
|
"createdIndex": 6,
|
|
|
|
|
"modifiedIndex": 6,
|
|
|
|
|
"key": "/apisix/services",
|
|
|
|
|
"dir": true
|
|
|
|
|
},
|
|
|
|
|
"action": "get"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 第二步: 在 Apache APISIX 中创建 Route
|
|
|
|
|
|
2020-12-15 09:29:47 +08:00
|
|
|
|
为了配置各种 routes / services / plugins ,APISIX 提供了强大的 Admin API 和一个 [web控制台](https://github.com/apache/apisix-dashboard)。
|
2020-03-21 08:24:24 +08:00
|
|
|
|
本指南将会使用到 Admin API 接口。
|
|
|
|
|
|
|
|
|
|
一个微服务可以通过 APISIX 的路由、服务、上游和插件等多个实体之间的关系进行配置。
|
|
|
|
|
Route(路由)与客户端请求匹配,并指定它们到达 APISIX 后如何发送到 Upstream(上游,后端 API 服务)。
|
|
|
|
|
Service(服务)为上游服务提供了抽象。因此,您可以创建单个 Service 并在多个 Route 中引用它。
|
|
|
|
|
查看架构文档可以获取更多信息。
|
|
|
|
|
|
|
|
|
|
从技术上讲,所有这些信息(upstream、service、plugins)都可以包含在路由配置中。 Route 路由是由这三个主要部分组成的。
|
|
|
|
|
|
|
|
|
|
- 路由匹配规则:
|
|
|
|
|
|
|
|
|
|
让我们来看看下面的场景
|
|
|
|
|
http://example.com/services/users
|
|
|
|
|
|
|
|
|
|
上面的URL托管了系统中所有跟用户有关的(getUser/GetAllUsers)微服务。例如,可以通过URL( http://example.com/services/users/GetAllUsers ) 访问到 GetAllUsers 服务接口。
|
|
|
|
|
现在要公开 `users` 路径下的所有 `GET` 服务请求(微服务)。以下是匹配此类请求的路由配置。
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"methods": ["GET"],
|
|
|
|
|
"host": "example.com",
|
|
|
|
|
"uri": "/services/users/*",
|
|
|
|
|
... Additional Configurations
|
|
|
|
|
}
|
|
|
|
|
```
|
2020-04-16 19:21:46 +08:00
|
|
|
|
|
2020-03-21 08:24:24 +08:00
|
|
|
|
通过上面的匹配规则你就可以通过如下的命令跟 APISIX 进行交互了
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
curl -i -X GET "http://{apisix_server.com}:{port}/services/users/getAllUsers?limit=10" -H "Host: example.com"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- Upstream 信息:
|
|
|
|
|
|
|
|
|
|
Upstream 是一个虚拟主机抽象,它根据配置规则在给定的一组服务节点上执行负载平衡。
|
|
|
|
|
因此,单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key(地址/ip:port)和一个 value (节点的权重)。
|
|
|
|
|
服务可以通过轮询或一致哈希(cHash)机制进行负载平衡。
|
|
|
|
|
|
|
|
|
|
配置路由时,可以直接设置 Upstream 信息,也可以使用服务抽象来引用 Upstream 信息。
|
|
|
|
|
|
|
|
|
|
- 各种插件
|
|
|
|
|
|
|
|
|
|
插件允许您扩展 APISIX 的功能,并实现可以与 HTTP request / response 生命周期接口的任意逻辑。
|
|
|
|
|
因此,如果您想对 API 进行身份验证,那么您可以使用密钥验证插件来对每个请求强制进行身份验证。
|
|
|
|
|
|
|
|
|
|
### 设置 Upstream
|
|
|
|
|
|
|
|
|
|
执行以下命令在 APISIX 中创建 id 为 50 的上游信息,并使用 round-robin 机制进行负载平衡。
|
|
|
|
|
|
|
|
|
|
```bash
|
2020-11-28 19:05:14 +08:00
|
|
|
|
curl "http://127.0.0.1:9080/apisix/admin/upstreams/50" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
|
2020-03-21 08:24:24 +08:00
|
|
|
|
{
|
|
|
|
|
"type": "roundrobin",
|
|
|
|
|
"nodes": {
|
|
|
|
|
"httpbin.org:443": 1
|
|
|
|
|
}
|
|
|
|
|
}'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 为转发 Upstream 添加 Route 信息
|
|
|
|
|
|
|
|
|
|
默认情况下,Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中,让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。
|
|
|
|
|
|
|
|
|
|
```bash
|
2020-11-28 19:05:14 +08:00
|
|
|
|
curl "http://127.0.0.1:9080/apisix/admin/routes/5" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
|
2020-03-21 08:24:24 +08:00
|
|
|
|
{
|
|
|
|
|
"uri": "/get",
|
|
|
|
|
"host": "httpbin.org",
|
|
|
|
|
"plugins": {
|
|
|
|
|
"proxy-rewrite": {
|
|
|
|
|
"scheme": "https"
|
|
|
|
|
}
|
|
|
|
|
},
|
|
|
|
|
"upstream_id": 50
|
|
|
|
|
}'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 访问 Apache APISIX 进行测试
|
|
|
|
|
|
|
|
|
|
现在让我们调用 Apache APISIX 来测试新配置的路由。
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
curl -i -X GET "http://127.0.0.1:9080/get?foo1=bar1&foo2=bar2" -H "Host: httpbin.org"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
API 也可以通过 HTTPs(9443)端口服务访问。如果您使用的是自签名证书,那么通过 curl 命令使用 `-k` 参数忽略自签名证书错误。
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
curl -i -k -X GET "https://127.0.0.1:9443/get?foo1=bar1&foo2=bar2" -H "Host: httpbin.org"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 第三步: 为服务增加鉴权
|
|
|
|
|
|
|
|
|
|
由于服务对公众开放,我们需要为新创建的 Apache APISIX 服务接口提供适当的保护。执行以下命令来创建一个名为 John 需要 api-key 的用户。
|
|
|
|
|
|
|
|
|
|
注:Apache APISIX 支持多种认证机制,查看插件文档了解更多。
|
|
|
|
|
|
|
|
|
|
```shell
|
2020-11-28 19:05:14 +08:00
|
|
|
|
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
|
2020-03-21 08:24:24 +08:00
|
|
|
|
{
|
|
|
|
|
"username": "john",
|
|
|
|
|
"plugins": {
|
|
|
|
|
"key-auth": {
|
|
|
|
|
"key": "superSecretAPIKey"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
现在,让我们将服务配置为包含 KEY 验证插件。
|
|
|
|
|
|
|
|
|
|
```bash
|
2020-11-28 19:05:14 +08:00
|
|
|
|
curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
|
2020-03-21 08:24:24 +08:00
|
|
|
|
{
|
|
|
|
|
"uri": "/get",
|
|
|
|
|
"host": "httpbin.org",
|
|
|
|
|
"plugins": {
|
|
|
|
|
"proxy-rewrite": {
|
|
|
|
|
"scheme": "https"
|
|
|
|
|
},
|
|
|
|
|
"key-auth": {}
|
|
|
|
|
},
|
|
|
|
|
"upstream_id": 50
|
|
|
|
|
}'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
由于 route 由密钥验证插件保护,前一个访问 API 的 curl 命令将产生未经授权的访问错误。
|
|
|
|
|
现在使用下面的命令安全地访问请求。
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
curl -i -X GET http://127.0.0.1:9080/get -H "Host: httpbin.org" -H 'apikey: superSecretAPIKey'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 为 route 添加前缀
|
|
|
|
|
|
|
|
|
|
现在,假设您要向路由添加前缀(例如:samplePrefix),并且不想使用 `host` 头, 则可以使用代理来完成。
|
|
|
|
|
|
|
|
|
|
```bash
|
2020-11-28 19:05:14 +08:00
|
|
|
|
curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
|
2020-03-21 08:24:24 +08:00
|
|
|
|
{
|
|
|
|
|
"uri": "/samplePrefix/get",
|
|
|
|
|
"plugins": {
|
|
|
|
|
"proxy-rewrite": {
|
|
|
|
|
"scheme": "https",
|
|
|
|
|
"regex_uri": ["^/samplePrefix/get(.*)", "/get$1"]
|
|
|
|
|
},
|
|
|
|
|
"key-auth": {}
|
|
|
|
|
},
|
|
|
|
|
"upstream_id": 50
|
|
|
|
|
}'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
现在可以使用以下命令调用路由:
|
|
|
|
|
|
|
|
|
|
```bash
|
2020-10-28 22:24:32 +08:00
|
|
|
|
curl -i -X GET 'http://127.0.0.1:9080/samplePrefix/get?param1=foo¶m2=bar' -H 'apikey: superSecretAPIKey'
|
2020-03-21 08:24:24 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Apache APISIX 控制台
|
|
|
|
|
|
|
|
|
|
到目前为止,已经通过使用 admin API 接口编排对 Apache APISIX 的 API 的调用。然而,Apache APISIX 还提供执行类似操作的一个 web 应用,就是web控制台。
|
2020-08-06 10:29:21 +08:00
|
|
|
|
可以在[repository](https://github.com/apache/apisix)中使用。控制台是直观的,您可以通过它编排同样的路由配置。
|
2020-03-21 08:24:24 +08:00
|
|
|
|
|
2021-02-25 16:32:21 +08:00
|
|
|
|
![Dashboard](../../assets/images/dashboard.png)
|
2020-03-21 08:24:24 +08:00
|
|
|
|
|
|
|
|
|
### 故障排查
|
|
|
|
|
|
|
|
|
|
- 确保所需的端口未被其他系统/进程使用(默认端口为:9080、9443、2379)。下面是终止正在侦听特定端口(基于unix的系统)的进程的命令。
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
sudo fuser -k 9443/tcp
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- 如果 docker 容器持续重启或者重启失败,请登录容器并观察日志以诊断问题。
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
docker logs -f --tail container_id
|
|
|
|
|
```
|