spacewander commented on a change in pull request #3980: URL: https://github.com/apache/apisix/pull/3980#discussion_r608435600
########## File path: docs/zh/latest/getting-started.md ########## @@ -21,238 +21,260 @@ title: 快速入门指南 # --> -本指南的目的是介绍如何使用 APISIX 来配置出一个安全的可以对外提供服务的 API。当您读完本指南，你需要自己安装一下 APISIX 应用，并准备好一个可以对外提供服务的 API，该服务将由 API key 进行访问保护。 +本指南旨在让大家入门 Apache APISIX，我们将配置一个对外提供公共 API 的服务，并由 API key 进行访问保护。 -本指南会使用到以下 GET 请求，该服务可以回显发送到这个 API 的传参。 +另外，我们将以下面的 `echo` 端点为例，它将返回我们传递的参数。 + +**Request** ```bash -$ curl --location --request GET "https://httpbin.org/get?foo1=bar1&foo2=bar2"; +$ curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"; +``` + +**Response** + +```json +{ + "args": { + "foo1": "bar1", + "foo2": "bar2" + }, + "headers": { + "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", + "Accept-Encoding": "gzip, deflate, br", + "Accept-Language": "en,zh-CN;q=0.9,zh;q=0.8", + "Cache-Control": "max-age=0", + "Host": "httpbin.org", + "Sec-Ch-Ua": "\"Google Chrome\";v=\"89\", \"Chromium\";v=\"89\", \";Not A Brand\";v=\"99\"", + "Sec-Ch-Ua-Mobile": "?0", + "Sec-Fetch-Dest": "document", + "Sec-Fetch-Mode": "navigate", + "Sec-Fetch-Site": "none", + "Sec-Fetch-User": "?1", + "Upgrade-Insecure-Requests": "1", + "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_2_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.90 Safari/537.36", + "X-Amzn-Trace-Id": "Root=1-606276ab-2b451d4b36057c186d666351" + }, + "origin": "58.152.81.42", + "url": "http://httpbin.org/get?foo1=bar1&foo2=bar2"; +} ``` -让我们来分析一下这个 URL 请求 +让我们来分析一下上面的请求 URL： -- Scheme: HTTPS -- Host/Address: httpbin.org -- Port: 443 -- URI: /get +- Scheme: HTTP +- Port: 80 +- Host: `httpbin.org` +- URI/Path: `/get` - Query Parameters: foo1, foo2 ## 前提 -- 本指南使用 docker 和 docker compose 来安装 Apache APISIX。 但是， 如果您已经以其他方式安装了 Apache APISIX ，您只需跳到 [第二步](getting-started.md#第二步:-在-APISIX-中设置路由) 。 -- Curl：指南使用 Curl 命令进行 API 测试，但是您也可以使用您选择的任何其他工具（ 例如 Postman ）。 +> 如果您已经安装了 Apache APISIX，请直接阅读[第二步](#step-2-create-a-route) Review comment: We should change the anchor? ########## File path: docs/zh/latest/getting-started.md ########## @@ -21,238 +21,260 @@ title: 快速入门指南 # --> -本指南的目的是介绍如何使用 APISIX 来配置出一个安全的可以对外提供服务的 API。当您读完本指南，你需要自己安装一下 APISIX 应用，并准备好一个可以对外提供服务的 API，该服务将由 API key 进行访问保护。 +本指南旨在让大家入门 Apache APISIX，我们将配置一个对外提供公共 API 的服务，并由 API key 进行访问保护。 -本指南会使用到以下 GET 请求，该服务可以回显发送到这个 API 的传参。 +另外，我们将以下面的 `echo` 端点为例，它将返回我们传递的参数。 + +**Request** ```bash -$ curl --location --request GET "https://httpbin.org/get?foo1=bar1&foo2=bar2"; +$ curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"; +``` + +**Response** + +```json +{ + "args": { + "foo1": "bar1", + "foo2": "bar2" + }, + "headers": { + "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", + "Accept-Encoding": "gzip, deflate, br", + "Accept-Language": "en,zh-CN;q=0.9,zh;q=0.8", + "Cache-Control": "max-age=0", + "Host": "httpbin.org", + "Sec-Ch-Ua": "\"Google Chrome\";v=\"89\", \"Chromium\";v=\"89\", \";Not A Brand\";v=\"99\"", + "Sec-Ch-Ua-Mobile": "?0", + "Sec-Fetch-Dest": "document", + "Sec-Fetch-Mode": "navigate", + "Sec-Fetch-Site": "none", + "Sec-Fetch-User": "?1", + "Upgrade-Insecure-Requests": "1", + "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_2_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.90 Safari/537.36", + "X-Amzn-Trace-Id": "Root=1-606276ab-2b451d4b36057c186d666351" + }, + "origin": "58.152.81.42", + "url": "http://httpbin.org/get?foo1=bar1&foo2=bar2"; +} ``` -让我们来分析一下这个 URL 请求 +让我们来分析一下上面的请求 URL： -- Scheme: HTTPS -- Host/Address: httpbin.org -- Port: 443 -- URI: /get +- Scheme: HTTP +- Port: 80 +- Host: `httpbin.org` +- URI/Path: `/get` - Query Parameters: foo1, foo2 ## 前提 -- 本指南使用 docker 和 docker compose 来安装 Apache APISIX。 但是， 如果您已经以其他方式安装了 Apache APISIX ，您只需跳到 [第二步](getting-started.md#第二步:-在-APISIX-中设置路由) 。 -- Curl：指南使用 Curl 命令进行 API 测试，但是您也可以使用您选择的任何其他工具（ 例如 Postman ）。 +> 如果您已经安装了 Apache APISIX，请直接阅读[第二步](#step-2-create-a-route) -## 第一步: 安装 APISIX +- 本指南使用 [Docker](https://www.docker.com/) 和 [Docker Compose](https://docs.docker.com/compose/) 来安装 Apache APISIX。 +- `curl`：本指南使用 [curl](https://curl.se/docs/manpage.html) 命令行进行 API 测试，但是您也可以使用任何其它工具，例如 [Postman](https://www.postman.com/)。 -Apache APISIX 可以多种操作环境中安装。[如何安装文档](how-to-build.md#通过源码包安装) 显示了多个平台中的安装步骤。 -为了快速入门，让我们基于 docker 容器的安装方式进行安装。启动 Apache APISIX 服务，我们可以参照这个镜像文件[repository](https://github.com/apache/apisix-docker) 并切换到 example 文件夹下执行如下命令。 +## 第一步: 安装 Apache APISIX -如下命令会启动 Apache APISIX 服务并默认在 9080 端口（ https 请求是 9443 端口） 提供 admin API 接口服务 +得益于 Docker，我们可以通过执行以下命令来启动 Apache APISIX 并启用 [Admin API](./admin-api.md)。 ```bash $ git clone https://github.com/apache/apisix-docker.git $ cd apisix-docker/example $ docker-compose -p docker-apisix up -d ``` -第一次下载源代码需要一段时间，之后将非常快。在 docker 容器启动后，请访问以下链接，检查您是否获得成功的响应。 +下载所需的所有文件将花费一些时间，这取决于您的网络，请耐心等待。下载完成后，我们可以使用 `curl` 工具访问 Admin API，借此判断 Apache APISIX 是否成功启动。 ```bash +# 注意：请在运行 Docker 的宿主机上执行 curl 命令。 $ curl "http://127.0.0.1:9080/apisix/admin/services/"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' ``` -下面是 Admin API 的接口响应： +我们期望返回以下数据： ```json { - "node": { - "createdIndex": 6, - "modifiedIndex": 6, - "key": "/apisix/services", - "dir": true - }, - "action": "get" + "node": { + "createdIndex": 6, + "modifiedIndex": 6, + "key": "/apisix/services", + "dir": true + }, + "action": "get" } ``` -## 第二步: 在 Apache APISIX 中创建 Route +## 第二步: 创建一个 Route -为了配置各种 routes / services / plugins ，APISIX 提供了强大的 Admin API 和一个 [web控制台](https://github.com/apache/apisix-dashboard)。 -本指南将会使用到 Admin API 接口。 +恭喜！您现在已经拥有一个运行中的 Apache APISIX 实例了！接下来我们创建一个 Route。 -一个微服务可以通过 APISIX 的路由、服务、上游和插件等多个实体之间的关系进行配置。 -Route（路由）与客户端请求匹配，并指定它们到达 APISIX 后如何发送到 Upstream（上游，后端 API 服务）。 -Service（服务）为上游服务提供了抽象。因此，您可以创建单个 Service 并在多个 Route 中引用它。 -查看架构文档可以获取更多信息。 +### 在我们继续之前 -从技术上讲，所有这些信息（upstream、service、plugins）都可以包含在路由配置中。 Route 路由是由这三个主要部分组成的。 +您知道吗？Apache APISIX 提供了强大的 [Admin API](./admin-api.md) 和 [Dashboard](https://github.com/apache/apisix-dashboard) 可供我们使用，但在本指南中我们使用 Admin API 来做演示。 -- 路由匹配规则： +我们可以创建一个 [Route](./architecture-design/route.md) 并与后端服务（通常称为上游： [Upstream](./architecture-design/upstream.md)）绑定，当一个 `请求（Request）` 到达 Apache APISIX 时，Apache APISIX 就会明白这个请求应该转发到哪个上游服务中。 - 让我们来看看下面的场景 - http://example.com/services/users + Apache APISIX 是如何知道的呢？那是因为我们为 Route 对象配置了匹配规则。 - 上面的URL托管了系统中所有跟用户有关的（getUser/GetAllUsers）微服务。例如，可以通过URL（ http://example.com/services/users/GetAllUsers ） 访问到 GetAllUsers 服务接口。 - 现在要公开 `users` 路径下的所有 `GET` 服务请求（微服务）。以下是匹配此类请求的路由配置。 +下面是一个 Route 配置示例： - ```json - { - "methods": ["GET"], - "host": "example.com", - "uri": "/services/users/*", - ... Additional Configurations +```json +{ + "methods": ["GET"], + "host": "example.com", + "uri": "/services/users/*", + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 } - ``` - - 通过上面的匹配规则你就可以通过如下的命令跟 APISIX 进行交互了 - - ```bash - curl -i -X GET "http://{apisix_server.com}:{port}/services/users/getAllUsers?limit=10"; -H "Host: example.com" - ``` + } +} +``` -- Upstream 信息： +这条路由配置是指：当入站请求满足下述规则时，请求将被转发到 `httpbin.org:80` 上游： Review comment: 少翻译了“全部” ########## File path: docs/zh/latest/getting-started.md ########## @@ -21,238 +21,260 @@ title: 快速入门指南 # --> -本指南的目的是介绍如何使用 APISIX 来配置出一个安全的可以对外提供服务的 API。当您读完本指南，你需要自己安装一下 APISIX 应用，并准备好一个可以对外提供服务的 API，该服务将由 API key 进行访问保护。 +本指南旨在让大家入门 Apache APISIX，我们将配置一个对外提供公共 API 的服务，并由 API key 进行访问保护。 -本指南会使用到以下 GET 请求，该服务可以回显发送到这个 API 的传参。 +另外，我们将以下面的 `echo` 端点为例，它将返回我们传递的参数。 + +**Request** ```bash -$ curl --location --request GET "https://httpbin.org/get?foo1=bar1&foo2=bar2"; +$ curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"; +``` + +**Response** + +```json +{ + "args": { + "foo1": "bar1", + "foo2": "bar2" + }, + "headers": { + "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", + "Accept-Encoding": "gzip, deflate, br", + "Accept-Language": "en,zh-CN;q=0.9,zh;q=0.8", + "Cache-Control": "max-age=0", + "Host": "httpbin.org", + "Sec-Ch-Ua": "\"Google Chrome\";v=\"89\", \"Chromium\";v=\"89\", \";Not A Brand\";v=\"99\"", + "Sec-Ch-Ua-Mobile": "?0", + "Sec-Fetch-Dest": "document", + "Sec-Fetch-Mode": "navigate", + "Sec-Fetch-Site": "none", + "Sec-Fetch-User": "?1", + "Upgrade-Insecure-Requests": "1", + "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_2_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.90 Safari/537.36", + "X-Amzn-Trace-Id": "Root=1-606276ab-2b451d4b36057c186d666351" + }, + "origin": "58.152.81.42", + "url": "http://httpbin.org/get?foo1=bar1&foo2=bar2"; +} ``` -让我们来分析一下这个 URL 请求 +让我们来分析一下上面的请求 URL： -- Scheme: HTTPS -- Host/Address: httpbin.org -- Port: 443 -- URI: /get +- Scheme: HTTP +- Port: 80 +- Host: `httpbin.org` +- URI/Path: `/get` - Query Parameters: foo1, foo2 ## 前提 -- 本指南使用 docker 和 docker compose 来安装 Apache APISIX。 但是， 如果您已经以其他方式安装了 Apache APISIX ，您只需跳到 [第二步](getting-started.md#第二步:-在-APISIX-中设置路由) 。 -- Curl：指南使用 Curl 命令进行 API 测试，但是您也可以使用您选择的任何其他工具（ 例如 Postman ）。 +> 如果您已经安装了 Apache APISIX，请直接阅读[第二步](#step-2-create-a-route) -## 第一步: 安装 APISIX +- 本指南使用 [Docker](https://www.docker.com/) 和 [Docker Compose](https://docs.docker.com/compose/) 来安装 Apache APISIX。 +- `curl`：本指南使用 [curl](https://curl.se/docs/manpage.html) 命令行进行 API 测试，但是您也可以使用任何其它工具，例如 [Postman](https://www.postman.com/)。 -Apache APISIX 可以多种操作环境中安装。[如何安装文档](how-to-build.md#通过源码包安装) 显示了多个平台中的安装步骤。 -为了快速入门，让我们基于 docker 容器的安装方式进行安装。启动 Apache APISIX 服务，我们可以参照这个镜像文件[repository](https://github.com/apache/apisix-docker) 并切换到 example 文件夹下执行如下命令。 +## 第一步: 安装 Apache APISIX -如下命令会启动 Apache APISIX 服务并默认在 9080 端口（ https 请求是 9443 端口） 提供 admin API 接口服务 +得益于 Docker，我们可以通过执行以下命令来启动 Apache APISIX 并启用 [Admin API](./admin-api.md)。 ```bash $ git clone https://github.com/apache/apisix-docker.git $ cd apisix-docker/example $ docker-compose -p docker-apisix up -d ``` -第一次下载源代码需要一段时间，之后将非常快。在 docker 容器启动后，请访问以下链接，检查您是否获得成功的响应。 +下载所需的所有文件将花费一些时间，这取决于您的网络，请耐心等待。下载完成后，我们可以使用 `curl` 工具访问 Admin API，借此判断 Apache APISIX 是否成功启动。 ```bash +# 注意：请在运行 Docker 的宿主机上执行 curl 命令。 $ curl "http://127.0.0.1:9080/apisix/admin/services/"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' ``` -下面是 Admin API 的接口响应： +我们期望返回以下数据： ```json { - "node": { - "createdIndex": 6, - "modifiedIndex": 6, - "key": "/apisix/services", - "dir": true - }, - "action": "get" + "node": { + "createdIndex": 6, + "modifiedIndex": 6, + "key": "/apisix/services", + "dir": true + }, + "action": "get" } ``` -## 第二步: 在 Apache APISIX 中创建 Route +## 第二步: 创建一个 Route -为了配置各种 routes / services / plugins ，APISIX 提供了强大的 Admin API 和一个 [web控制台](https://github.com/apache/apisix-dashboard)。 -本指南将会使用到 Admin API 接口。 +恭喜！您现在已经拥有一个运行中的 Apache APISIX 实例了！接下来我们创建一个 Route。 -一个微服务可以通过 APISIX 的路由、服务、上游和插件等多个实体之间的关系进行配置。 -Route（路由）与客户端请求匹配，并指定它们到达 APISIX 后如何发送到 Upstream（上游，后端 API 服务）。 -Service（服务）为上游服务提供了抽象。因此，您可以创建单个 Service 并在多个 Route 中引用它。 -查看架构文档可以获取更多信息。 +### 在我们继续之前 -从技术上讲，所有这些信息（upstream、service、plugins）都可以包含在路由配置中。 Route 路由是由这三个主要部分组成的。 +您知道吗？Apache APISIX 提供了强大的 [Admin API](./admin-api.md) 和 [Dashboard](https://github.com/apache/apisix-dashboard) 可供我们使用，但在本指南中我们使用 Admin API 来做演示。 -- 路由匹配规则： +我们可以创建一个 [Route](./architecture-design/route.md) 并与后端服务（通常称为上游： [Upstream](./architecture-design/upstream.md)）绑定，当一个 `请求（Request）` 到达 Apache APISIX 时，Apache APISIX 就会明白这个请求应该转发到哪个上游服务中。 - 让我们来看看下面的场景 - http://example.com/services/users + Apache APISIX 是如何知道的呢？那是因为我们为 Route 对象配置了匹配规则。 - 上面的URL托管了系统中所有跟用户有关的（getUser/GetAllUsers）微服务。例如，可以通过URL（ http://example.com/services/users/GetAllUsers ） 访问到 GetAllUsers 服务接口。 - 现在要公开 `users` 路径下的所有 `GET` 服务请求（微服务）。以下是匹配此类请求的路由配置。 +下面是一个 Route 配置示例： - ```json - { - "methods": ["GET"], - "host": "example.com", - "uri": "/services/users/*", - ... Additional Configurations +```json +{ + "methods": ["GET"], + "host": "example.com", + "uri": "/services/users/*", + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 } - ``` - - 通过上面的匹配规则你就可以通过如下的命令跟 APISIX 进行交互了 - - ```bash - curl -i -X GET "http://{apisix_server.com}:{port}/services/users/getAllUsers?limit=10"; -H "Host: example.com" - ``` + } +} +``` -- Upstream 信息： +这条路由配置是指：当入站请求满足下述规则时，请求将被转发到 `httpbin.org:80` 上游： - Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。 - 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。 - 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。 +- 请求方法为 `GET`; +- 请求头包含 `Host` 字段，且它的值为 `example.com`; +- 请求路径匹配 `/services/users/*`，`*` 意味着任意的子路径。例如：`/services/users/getAll?limit=10`。 - 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。 +当这条路由创建后，我们可以使用 Apache APISIX 对外暴露的地址去访问后端服务（即上游）： -- 各种插件 +```bash +$ curl -i -X GET "http://{APISIX_BASE_URL}/services/users/getAll?limit=10"; -H "Host: example.com" +``` - 插件允许您扩展 APISIX 的功能，并实现可以与 HTTP request / response 生命周期接口的任意逻辑。 - 因此，如果您想对 API 进行身份验证，那么您可以使用密钥验证插件来对每个请求强制进行身份验证。 +这会被 Apache APISIX 转发到 `http://httpbin.org:80/getAll?limit=10`。 -### 设置 Upstream +### 创建一个上游对象（Upstream） -执行以下命令在 APISIX 中创建 id 为 50 的上游信息，并使用 round-robin 机制进行负载平衡。 +读完上一节，我们知道需要为路由绑定一个上游对象。可以执行下面的命令来创建一个上游： ```bash -curl "http://127.0.0.1:9080/apisix/admin/upstreams/50"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +$ curl "http://127.0.0.1:9080/apisix/admin/upstreams/50"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { - "type": "roundrobin", - "nodes": { - "httpbin.org:443": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } }' ``` -### 为转发 Upstream 添加 Route 信息 +我们使用 `roundrobin` 作为负载均衡机制，并将 `httpbin.org:80` 设置为我们的上游目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。 -默认情况下，Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中，让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。 +**注意：** 实际上，创建上游对象并不是必需的，因为我们可以使用 [插件机制](./architecture-design/plugin.md) 拦截请求、直接响应数据。但在本指南中，我们选择设置一个上游对象。 ```bash -curl "http://127.0.0.1:9080/apisix/admin/routes/5"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +$ curl "http://127.0.0.1:9080/apisix/admin/routes/5"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { - "uri": "/get", - "host": "httpbin.org", - "plugins": { - "proxy-rewrite": { - "scheme": "https" - } - }, - "upstream_id": 50 + "uri": "/get", + "host": "httpbin.org", + "upstream_id": "50" }' ``` -### 访问 Apache APISIX 进行测试 +如此而已。 + +### 验证配置是否正确 -现在让我们调用 Apache APISIX 来测试新配置的路由。 +再次恭喜！我们分别创建了上游与路由对象，并将它们进行绑定。现在让我们访问 Apache APISIX 来测试已经创建的路由： ```bash -curl -i -X GET "http://127.0.0.1:9080/get?foo1=bar1&foo2=bar2"; -H "Host: httpbin.org" +$ curl -i -X GET "http://127.0.0.1:9080/get?foo1=bar1&foo2=bar2"; -H "Host: httpbin.org" ``` -API 也可以通过 HTTPs（9443）端口服务访问。如果您使用的是自签名证书，那么通过 curl 命令使用 `-k` 参数忽略自签名证书错误。 +哇哦! 它将从我们的上游服务（实际是 `httpbin.org`）返回预期数据！ -```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 的用户。 +让我们来做一些有趣的事情。由于我们在第二步中创建的路由是公共的，**任何人** 都可以访问，现在我们希望只有 `John` 可以访问它。让我们使用 [消费者（Consumer）](./architecture-design/consumer.md) 和 [插件（Plugin）](./architecture-design/plugin.md) 来实现这个保护措施。 -注：Apache APISIX 支持多种认证机制，查看插件文档了解更多。 +首先，我们创建一条 [消费者（Consumer）](./architecture-design/consumer.md) 并绑定一个[key-auth](./plugins/key-auth.md) 插件，这需要提供一个指定的秘钥: -```shell -curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +```bash +$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { - "username": "john", - "plugins": { - "key-auth": { - "key": "superSecretAPIKey" - } + "username": "john", + "plugins": { + "key-auth": { + "key": "superSecretAPIKey" } + } }' ``` -现在，让我们将服务配置为包含 KEY 验证插件。 +接下来，让我们绑定 `消费者（John）` 到路由上：我们仅仅需要为路由 **启用** [key-auth](./plugins/key-auth.md) 插件即可。 ```bash -curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +$ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { - "uri": "/get", - "host": "httpbin.org", - "plugins": { - "proxy-rewrite": { - "scheme": "https" - }, - "key-auth": {} + "uri": "/get", + "host": "httpbin.org", + "plugins": { + "proxy-rewrite": { + "scheme": "https" Review comment: Should remove the `scheme` ########## File path: docs/zh/latest/getting-started.md ########## @@ -21,238 +21,260 @@ title: 快速入门指南 # --> -本指南的目的是介绍如何使用 APISIX 来配置出一个安全的可以对外提供服务的 API。当您读完本指南，你需要自己安装一下 APISIX 应用，并准备好一个可以对外提供服务的 API，该服务将由 API key 进行访问保护。 +本指南旨在让大家入门 Apache APISIX，我们将配置一个对外提供公共 API 的服务，并由 API key 进行访问保护。 -本指南会使用到以下 GET 请求，该服务可以回显发送到这个 API 的传参。 +另外，我们将以下面的 `echo` 端点为例，它将返回我们传递的参数。 + +**Request** ```bash -$ curl --location --request GET "https://httpbin.org/get?foo1=bar1&foo2=bar2"; +$ curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"; +``` + +**Response** + +```json +{ + "args": { + "foo1": "bar1", + "foo2": "bar2" + }, + "headers": { + "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", + "Accept-Encoding": "gzip, deflate, br", + "Accept-Language": "en,zh-CN;q=0.9,zh;q=0.8", + "Cache-Control": "max-age=0", + "Host": "httpbin.org", + "Sec-Ch-Ua": "\"Google Chrome\";v=\"89\", \"Chromium\";v=\"89\", \";Not A Brand\";v=\"99\"", + "Sec-Ch-Ua-Mobile": "?0", + "Sec-Fetch-Dest": "document", + "Sec-Fetch-Mode": "navigate", + "Sec-Fetch-Site": "none", + "Sec-Fetch-User": "?1", + "Upgrade-Insecure-Requests": "1", + "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_2_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.90 Safari/537.36", + "X-Amzn-Trace-Id": "Root=1-606276ab-2b451d4b36057c186d666351" + }, + "origin": "58.152.81.42", + "url": "http://httpbin.org/get?foo1=bar1&foo2=bar2"; +} ``` -让我们来分析一下这个 URL 请求 +让我们来分析一下上面的请求 URL： -- Scheme: HTTPS -- Host/Address: httpbin.org -- Port: 443 -- URI: /get +- Scheme: HTTP +- Port: 80 +- Host: `httpbin.org` +- URI/Path: `/get` - Query Parameters: foo1, foo2 ## 前提 -- 本指南使用 docker 和 docker compose 来安装 Apache APISIX。 但是， 如果您已经以其他方式安装了 Apache APISIX ，您只需跳到 [第二步](getting-started.md#第二步:-在-APISIX-中设置路由) 。 -- Curl：指南使用 Curl 命令进行 API 测试，但是您也可以使用您选择的任何其他工具（ 例如 Postman ）。 +> 如果您已经安装了 Apache APISIX，请直接阅读[第二步](#step-2-create-a-route) -## 第一步: 安装 APISIX +- 本指南使用 [Docker](https://www.docker.com/) 和 [Docker Compose](https://docs.docker.com/compose/) 来安装 Apache APISIX。 +- `curl`：本指南使用 [curl](https://curl.se/docs/manpage.html) 命令行进行 API 测试，但是您也可以使用任何其它工具，例如 [Postman](https://www.postman.com/)。 -Apache APISIX 可以多种操作环境中安装。[如何安装文档](how-to-build.md#通过源码包安装) 显示了多个平台中的安装步骤。 -为了快速入门，让我们基于 docker 容器的安装方式进行安装。启动 Apache APISIX 服务，我们可以参照这个镜像文件[repository](https://github.com/apache/apisix-docker) 并切换到 example 文件夹下执行如下命令。 +## 第一步: 安装 Apache APISIX -如下命令会启动 Apache APISIX 服务并默认在 9080 端口（ https 请求是 9443 端口） 提供 admin API 接口服务 +得益于 Docker，我们可以通过执行以下命令来启动 Apache APISIX 并启用 [Admin API](./admin-api.md)。 ```bash $ git clone https://github.com/apache/apisix-docker.git $ cd apisix-docker/example $ docker-compose -p docker-apisix up -d ``` -第一次下载源代码需要一段时间，之后将非常快。在 docker 容器启动后，请访问以下链接，检查您是否获得成功的响应。 +下载所需的所有文件将花费一些时间，这取决于您的网络，请耐心等待。下载完成后，我们可以使用 `curl` 工具访问 Admin API，借此判断 Apache APISIX 是否成功启动。 ```bash +# 注意：请在运行 Docker 的宿主机上执行 curl 命令。 $ curl "http://127.0.0.1:9080/apisix/admin/services/"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' ``` -下面是 Admin API 的接口响应： +我们期望返回以下数据： ```json { - "node": { - "createdIndex": 6, - "modifiedIndex": 6, - "key": "/apisix/services", - "dir": true - }, - "action": "get" + "node": { + "createdIndex": 6, + "modifiedIndex": 6, + "key": "/apisix/services", + "dir": true + }, + "action": "get" } ``` -## 第二步: 在 Apache APISIX 中创建 Route +## 第二步: 创建一个 Route -为了配置各种 routes / services / plugins ，APISIX 提供了强大的 Admin API 和一个 [web控制台](https://github.com/apache/apisix-dashboard)。 -本指南将会使用到 Admin API 接口。 +恭喜！您现在已经拥有一个运行中的 Apache APISIX 实例了！接下来我们创建一个 Route。 -一个微服务可以通过 APISIX 的路由、服务、上游和插件等多个实体之间的关系进行配置。 -Route（路由）与客户端请求匹配，并指定它们到达 APISIX 后如何发送到 Upstream（上游，后端 API 服务）。 -Service（服务）为上游服务提供了抽象。因此，您可以创建单个 Service 并在多个 Route 中引用它。 -查看架构文档可以获取更多信息。 +### 在我们继续之前 -从技术上讲，所有这些信息（upstream、service、plugins）都可以包含在路由配置中。 Route 路由是由这三个主要部分组成的。 +您知道吗？Apache APISIX 提供了强大的 [Admin API](./admin-api.md) 和 [Dashboard](https://github.com/apache/apisix-dashboard) 可供我们使用，但在本指南中我们使用 Admin API 来做演示。 -- 路由匹配规则： +我们可以创建一个 [Route](./architecture-design/route.md) 并与后端服务（通常称为上游： [Upstream](./architecture-design/upstream.md)）绑定，当一个 `请求（Request）` 到达 Apache APISIX 时，Apache APISIX 就会明白这个请求应该转发到哪个上游服务中。 - 让我们来看看下面的场景 - http://example.com/services/users + Apache APISIX 是如何知道的呢？那是因为我们为 Route 对象配置了匹配规则。 - 上面的URL托管了系统中所有跟用户有关的（getUser/GetAllUsers）微服务。例如，可以通过URL（ http://example.com/services/users/GetAllUsers ） 访问到 GetAllUsers 服务接口。 - 现在要公开 `users` 路径下的所有 `GET` 服务请求（微服务）。以下是匹配此类请求的路由配置。 +下面是一个 Route 配置示例： - ```json - { - "methods": ["GET"], - "host": "example.com", - "uri": "/services/users/*", - ... Additional Configurations +```json +{ + "methods": ["GET"], + "host": "example.com", + "uri": "/services/users/*", + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 } - ``` - - 通过上面的匹配规则你就可以通过如下的命令跟 APISIX 进行交互了 - - ```bash - curl -i -X GET "http://{apisix_server.com}:{port}/services/users/getAllUsers?limit=10"; -H "Host: example.com" - ``` + } +} +``` -- Upstream 信息： +这条路由配置是指：当入站请求满足下述规则时，请求将被转发到 `httpbin.org:80` 上游： - Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。 - 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。 - 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。 +- 请求方法为 `GET`; +- 请求头包含 `Host` 字段，且它的值为 `example.com`; +- 请求路径匹配 `/services/users/*`，`*` 意味着任意的子路径。例如：`/services/users/getAll?limit=10`。 - 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。 +当这条路由创建后，我们可以使用 Apache APISIX 对外暴露的地址去访问后端服务（即上游）： -- 各种插件 +```bash +$ curl -i -X GET "http://{APISIX_BASE_URL}/services/users/getAll?limit=10"; -H "Host: example.com" +``` - 插件允许您扩展 APISIX 的功能，并实现可以与 HTTP request / response 生命周期接口的任意逻辑。 - 因此，如果您想对 API 进行身份验证，那么您可以使用密钥验证插件来对每个请求强制进行身份验证。 +这会被 Apache APISIX 转发到 `http://httpbin.org:80/getAll?limit=10`。 -### 设置 Upstream +### 创建一个上游对象（Upstream） -执行以下命令在 APISIX 中创建 id 为 50 的上游信息，并使用 round-robin 机制进行负载平衡。 +读完上一节，我们知道需要为路由绑定一个上游对象。可以执行下面的命令来创建一个上游： ```bash -curl "http://127.0.0.1:9080/apisix/admin/upstreams/50"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +$ curl "http://127.0.0.1:9080/apisix/admin/upstreams/50"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { - "type": "roundrobin", - "nodes": { - "httpbin.org:443": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } }' ``` -### 为转发 Upstream 添加 Route 信息 +我们使用 `roundrobin` 作为负载均衡机制，并将 `httpbin.org:80` 设置为我们的上游目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。 -默认情况下，Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中，让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。 +**注意：** 实际上，创建上游对象并不是必需的，因为我们可以使用 [插件机制](./architecture-design/plugin.md) 拦截请求、直接响应数据。但在本指南中，我们选择设置一个上游对象。 ```bash -curl "http://127.0.0.1:9080/apisix/admin/routes/5"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +$ curl "http://127.0.0.1:9080/apisix/admin/routes/5"; -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { - "uri": "/get", - "host": "httpbin.org", - "plugins": { - "proxy-rewrite": { - "scheme": "https" - } - }, - "upstream_id": 50 + "uri": "/get", + "host": "httpbin.org", + "upstream_id": "50" }' ``` -### 访问 Apache APISIX 进行测试 +如此而已。 + +### 验证配置是否正确 -现在让我们调用 Apache APISIX 来测试新配置的路由。 +再次恭喜！我们分别创建了上游与路由对象，并将它们进行绑定。现在让我们访问 Apache APISIX 来测试已经创建的路由： ```bash -curl -i -X GET "http://127.0.0.1:9080/get?foo1=bar1&foo2=bar2"; -H "Host: httpbin.org" +$ curl -i -X GET "http://127.0.0.1:9080/get?foo1=bar1&foo2=bar2"; -H "Host: httpbin.org" ``` -API 也可以通过 HTTPs（9443）端口服务访问。如果您使用的是自签名证书，那么通过 curl 命令使用 `-k` 参数忽略自签名证书错误。 +哇哦! 它将从我们的上游服务（实际是 `httpbin.org`）返回预期数据！ -```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 的用户。 +让我们来做一些有趣的事情。由于我们在第二步中创建的路由是公共的，**任何人** 都可以访问，现在我们希望只有 `John` 可以访问它。让我们使用 [消费者（Consumer）](./architecture-design/consumer.md) 和 [插件（Plugin）](./architecture-design/plugin.md) 来实现这个保护措施。 -注：Apache APISIX 支持多种认证机制，查看插件文档了解更多。 +首先，我们创建一条 [消费者（Consumer）](./architecture-design/consumer.md) 并绑定一个[key-auth](./plugins/key-auth.md) 插件，这需要提供一个指定的秘钥: -```shell -curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +```bash +$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { - "username": "john", - "plugins": { - "key-auth": { - "key": "superSecretAPIKey" - } + "username": "john", + "plugins": { + "key-auth": { + "key": "superSecretAPIKey" } + } }' ``` -现在，让我们将服务配置为包含 KEY 验证插件。 +接下来，让我们绑定 `消费者（John）` 到路由上：我们仅仅需要为路由 **启用** [key-auth](./plugins/key-auth.md) 插件即可。 ```bash -curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +$ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { - "uri": "/get", - "host": "httpbin.org", - "plugins": { - "proxy-rewrite": { - "scheme": "https" - }, - "key-auth": {} + "uri": "/get", + "host": "httpbin.org", + "plugins": { + "proxy-rewrite": { + "scheme": "https" }, - "upstream_id": 50 + "key-auth": {} + }, + "upstream_id": 50 }' ``` -由于 route 由密钥验证插件保护，前一个访问 API 的 curl 命令将产生未经授权的访问错误。 -现在使用下面的命令安全地访问请求。 +OK，现在当我们访问第二步创建的路由时，将会产生一个 **Unauthorized Error**（未经授权错误）。让我看看如何正确访问那个路由： ```bash -curl -i -X GET http://127.0.0.1:9080/get -H "Host: httpbin.org" -H 'apikey: superSecretAPIKey' +$ curl -i -X GET http://127.0.0.1:9080/get -H "Host: httpbin.org" -H 'apikey: superSecretAPIKey' ``` -## 为 route 添加前缀 +是的，仅仅添加了一个带有正确密钥的名为 `apikey` 的 `Header`！这样就可以保护任何的路由了。 + +### 为路由添加前缀 -现在，假设您要向路由添加前缀（例如：samplePrefix），并且不想使用 `host` 头， 则可以使用代理来完成。 +现在，假设您要向路由添加前缀（例如：samplePrefix），并且不想使用 `host` 头， 则可以使用 `proxy-rewrite` 插件来完成。 ```bash -curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +$ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { - "uri": "/samplePrefix/get", - "plugins": { - "proxy-rewrite": { - "scheme": "https", - "regex_uri": ["^/samplePrefix/get(.*)", "/get$1"] - }, - "key-auth": {} + "uri": "/samplePrefix/get", + "plugins": { + "proxy-rewrite": { + "scheme": "https", Review comment: Should remove the `scheme` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
