You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2021/04/03 07:51:55 UTC
[GitHub] [apisix] juzhiyuan commented on a change in pull request #3980: doc: update the Getting Started guide in Chinese
juzhiyuan commented on a change in pull request #3980:
URL: https://github.com/apache/apisix/pull/3980#discussion_r606631591
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 ：
Review comment:
```suggestion
让我们来分析一下上面的请求 URL：
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
Review comment:
```suggestion
我们可以创建一个 [Route](./architecture-design/route.md) 并与后端服务（通常称为上游： [Upstream](./architecture-design/upstream.md)）绑定，当一个 `请求（Request）` 到达 Apache APISIX 时，Apache APISIX 就会明白这个请求应该转发到哪个上游服务中。
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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 机制进行负载平衡。
+读完上一节，我们知道了必须要为 `Route` 设置 `Upstream` 。可以执行下面的命令来创建一个 `Upstream`。
```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` 设置为我们的 Upstream 目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
-默认情况下，Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中，让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。
+**注意：** 实际上，创建 Upstream 并不是必需的，因为我们可以使用 [Plugin](./architecture-design/plugin.md) 拦截器请求，然后直接响应，但是假设我们在本指南中需要至少设置一个 `Upstream`。
```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 来测试新配置的路由。
+再次恭喜！我们创建了 `Route` 和 `Upstream`，并且为它们做了绑定。现在让我们访问 Apache APISIX 来测试已经创建的 `Route`。
```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` 参数忽略自签名证书错误。
+哇哦! 它将从我们的 `Upstream` （实际是 `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 的用户。
+让我们来做一些有趣的事情，由于我们在第二步中创建的 `Route` 是公共的，**任何人** 都可以访问，现在我们希望只有 `John` 可以访问它。让我们使用 [Consumer](./architecture-design/consumer.md) 和 [Plugin](./architecture-design/plugin.md) 来实现这个保护措施。
-注：Apache APISIX 支持多种认证机制，查看插件文档了解更多。
+首先，我们使用 [key-auth](./plugins/key-auth.md) 插件创建 [consumer](./architecture-design/consumer.md) `John`，我们需要提供一个指定的秘钥:
Review comment:
```suggestion
首先，我们创建一条 [消费者（Consumer）](./architecture-design/consumer.md) 并绑定一个[key-auth](./plugins/key-auth.md) 插件，这需要提供一个指定的秘钥:
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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``
Review comment:
```suggestion
- URI/Path: `/get`
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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/) ）。
Review comment:
```suggestion
- `curl`：本指南使用 [curl](https://curl.se/docs/manpage.html) 命令行进行 API 测试，但是您也可以使用任何其它工具，例如 [Postman](https://www.postman.com/)。
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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:
```suggestion
> 如果您已经安装了 Apache APISIX，请直接阅读[第二步](#step-2-create-a-route)
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 是否成功启动。
Review comment:
```suggestion
下载所需的所有文件将花费一些时间，这取决于您的网络，请耐心等待。下载完成后，我们可以使用 `curl` 工具访问 Admin API，借此判断 Apache APISIX 是否成功启动。
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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``
Review comment:
```suggestion
- Host: `httpbin.org`
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 的接口响应：
+我们希望返回以下数据：
Review comment:
```suggestion
我们期望返回以下数据：
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- http://example.com/services/users
+ Apache APISIX 是如何知道的呢？那是因为我们有一个用 Route 配置的规则列表。
- 上面的URL托管了系统中所有跟用户有关的（getUser/GetAllUsers）微服务。例如，可以通过URL（ http://example.com/services/users/GetAllUsers ） 访问到 GetAllUsers 服务接口。
- 现在要公开 `users` 路径下的所有 `GET` 服务请求（微服务）。以下是匹配此类请求的路由配置。
+下面是一个 Route 数据示例：
Review comment:
```suggestion
下面是一个 Route 配置示例：
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 来做演示。出发!
Review comment:
```suggestion
您知道吗？Apache APISIX 提供了强大的 [Admin API](./admin-api.md) 和 [Dashboard](https://github.com/apache/apisix-dashboard) 可供我们使用，但在本指南中我们使用 Admin API 来做演示。
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
Review comment:
We could remove this sentence :)
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
Review comment:
```suggestion
这条 Route 配置是指：当入站请求满足下述规则时，请求将被转发到 `httpbin.org:80` 上游：
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
Review comment:
```suggestion
- 请求方法为 `GET`;
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- http://example.com/services/users
+ Apache APISIX 是如何知道的呢？那是因为我们有一个用 Route 配置的规则列表。
Review comment:
```suggestion
Apache APISIX 是如何知道的呢？那是因为我们为 Route 对象配置了匹配规则。
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
Review comment:
```suggestion
- 请求头包含 `Host` 字段，且它的值为 `example.com`;
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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`。
Review comment:
```suggestion
这会被 Apache APISIX 转发到 `http://httpbin.org:80/getAll?limit=10`。
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
Review comment:
```suggestion
当这条路由创建后，我们可以使用 Apache APISIX 对外暴露的地址去访问后端服务（即上游）：
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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 机制进行负载平衡。
+读完上一节，我们知道了必须要为 `Route` 设置 `Upstream` 。可以执行下面的命令来创建一个 `Upstream`。
Review comment:
```suggestion
读完上一节，我们知道需要为路由绑定一个上游对象。可以执行下面的命令来创建一个上游：
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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
Review comment:
```suggestion
### 创建一个上游对象（Upstream）
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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 机制进行负载平衡。
+读完上一节，我们知道了必须要为 `Route` 设置 `Upstream` 。可以执行下面的命令来创建一个 `Upstream`。
```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` 设置为我们的 Upstream 目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
Review comment:
```suggestion
我们使用 `roundrobin` 作为负载均衡机制，并将 `httpbin.org:80` 设置为我们的上游目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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 机制进行负载平衡。
+读完上一节，我们知道了必须要为 `Route` 设置 `Upstream` 。可以执行下面的命令来创建一个 `Upstream`。
```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` 设置为我们的 Upstream 目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
-默认情况下，Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中，让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。
+**注意：** 实际上，创建 Upstream 并不是必需的，因为我们可以使用 [Plugin](./architecture-design/plugin.md) 拦截器请求，然后直接响应，但是假设我们在本指南中需要至少设置一个 `Upstream`。
```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 来测试新配置的路由。
+再次恭喜！我们创建了 `Route` 和 `Upstream`，并且为它们做了绑定。现在让我们访问 Apache APISIX 来测试已经创建的 `Route`。
Review comment:
```suggestion
再次恭喜！我们分别创建了上游与路由对象，并将它们进行绑定。现在让我们访问 Apache APISIX 来测试已经创建的路由：
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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 机制进行负载平衡。
+读完上一节，我们知道了必须要为 `Route` 设置 `Upstream` 。可以执行下面的命令来创建一个 `Upstream`。
```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` 设置为我们的 Upstream 目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
-默认情况下，Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中，让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。
+**注意：** 实际上，创建 Upstream 并不是必需的，因为我们可以使用 [Plugin](./architecture-design/plugin.md) 拦截器请求，然后直接响应，但是假设我们在本指南中需要至少设置一个 `Upstream`。
Review comment:
```suggestion
**注意：** 实际上，创建上游对象并不是必需的，因为我们可以使用 [插件机制](./architecture-design/plugin.md) 拦截请求、直接响应数据。但在本指南中，我们选择设置一个上游对象。
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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 机制进行负载平衡。
+读完上一节，我们知道了必须要为 `Route` 设置 `Upstream` 。可以执行下面的命令来创建一个 `Upstream`。
```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` 设置为我们的 Upstream 目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
-默认情况下，Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中，让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。
+**注意：** 实际上，创建 Upstream 并不是必需的，因为我们可以使用 [Plugin](./architecture-design/plugin.md) 拦截器请求，然后直接响应，但是假设我们在本指南中需要至少设置一个 `Upstream`。
```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 进行测试
+如此而已。
+
+### 验证
Review comment:
```suggestion
### 验证配置是否正确
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
Review comment:
```suggestion
- 请求路径匹配 `/services/users/*`，`*` 意味着任意的子路径。例如：`/services/users/getAll?limit=10`。
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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 机制进行负载平衡。
+读完上一节，我们知道了必须要为 `Route` 设置 `Upstream` 。可以执行下面的命令来创建一个 `Upstream`。
```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` 设置为我们的 Upstream 目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
-默认情况下，Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中，让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。
+**注意：** 实际上，创建 Upstream 并不是必需的，因为我们可以使用 [Plugin](./architecture-design/plugin.md) 拦截器请求，然后直接响应，但是假设我们在本指南中需要至少设置一个 `Upstream`。
```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 来测试新配置的路由。
+再次恭喜！我们创建了 `Route` 和 `Upstream`，并且为它们做了绑定。现在让我们访问 Apache APISIX 来测试已经创建的 `Route`。
```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` 参数忽略自签名证书错误。
+哇哦! 它将从我们的 `Upstream` （实际是 `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 的用户。
+让我们来做一些有趣的事情，由于我们在第二步中创建的 `Route` 是公共的，**任何人** 都可以访问，现在我们希望只有 `John` 可以访问它。让我们使用 [Consumer](./architecture-design/consumer.md) 和 [Plugin](./architecture-design/plugin.md) 来实现这个保护措施。
-注：Apache APISIX 支持多种认证机制，查看插件文档了解更多。
+首先，我们使用 [key-auth](./plugins/key-auth.md) 插件创建 [consumer](./architecture-design/consumer.md) `John`，我们需要提供一个指定的秘钥:
-```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 验证插件。
+接下来，让我们绑定 `Consumer(John)` 到 `Route` 上，我们仅仅需要为 `Route` **启用** [key-auth](./plugins/key-auth.md) 插件即可。
Review comment:
```suggestion
接下来，让我们绑定 `消费者（John）` 到路由上：我们仅仅需要为路由 **启用** [key-auth](./plugins/key-auth.md) 插件即可。
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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 机制进行负载平衡。
+读完上一节，我们知道了必须要为 `Route` 设置 `Upstream` 。可以执行下面的命令来创建一个 `Upstream`。
```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` 设置为我们的 Upstream 目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
-默认情况下，Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中，让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。
+**注意：** 实际上，创建 Upstream 并不是必需的，因为我们可以使用 [Plugin](./architecture-design/plugin.md) 拦截器请求，然后直接响应，但是假设我们在本指南中需要至少设置一个 `Upstream`。
```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 来测试新配置的路由。
+再次恭喜！我们创建了 `Route` 和 `Upstream`，并且为它们做了绑定。现在让我们访问 Apache APISIX 来测试已经创建的 `Route`。
```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` 参数忽略自签名证书错误。
+哇哦! 它将从我们的 `Upstream` （实际是 `httpbin.org`）返回数据，它的运行符合预期!
Review comment:
```suggestion
哇哦! 它将从我们的上游服务（实际是 `httpbin.org`）返回预期数据！
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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 机制进行负载平衡。
+读完上一节，我们知道了必须要为 `Route` 设置 `Upstream` 。可以执行下面的命令来创建一个 `Upstream`。
```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` 设置为我们的 Upstream 目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
-默认情况下，Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中，让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。
+**注意：** 实际上，创建 Upstream 并不是必需的，因为我们可以使用 [Plugin](./architecture-design/plugin.md) 拦截器请求，然后直接响应，但是假设我们在本指南中需要至少设置一个 `Upstream`。
```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 来测试新配置的路由。
+再次恭喜！我们创建了 `Route` 和 `Upstream`，并且为它们做了绑定。现在让我们访问 Apache APISIX 来测试已经创建的 `Route`。
```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` 参数忽略自签名证书错误。
+哇哦! 它将从我们的 `Upstream` （实际是 `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 的用户。
+让我们来做一些有趣的事情，由于我们在第二步中创建的 `Route` 是公共的，**任何人** 都可以访问，现在我们希望只有 `John` 可以访问它。让我们使用 [Consumer](./architecture-design/consumer.md) 和 [Plugin](./architecture-design/plugin.md) 来实现这个保护措施。
Review comment:
```suggestion
让我们来做一些有趣的事情。由于我们在第二步中创建的路由是公共的，**任何人** 都可以访问，现在我们希望只有 `John` 可以访问它。让我们使用 [消费者（Consumer）](./architecture-design/consumer.md) 和 [插件（Plugin）](./architecture-design/plugin.md) 来实现这个保护措施。
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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 机制进行负载平衡。
+读完上一节，我们知道了必须要为 `Route` 设置 `Upstream` 。可以执行下面的命令来创建一个 `Upstream`。
```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` 设置为我们的 Upstream 目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
-默认情况下，Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中，让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。
+**注意：** 实际上，创建 Upstream 并不是必需的，因为我们可以使用 [Plugin](./architecture-design/plugin.md) 拦截器请求，然后直接响应，但是假设我们在本指南中需要至少设置一个 `Upstream`。
```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 来测试新配置的路由。
+再次恭喜！我们创建了 `Route` 和 `Upstream`，并且为它们做了绑定。现在让我们访问 Apache APISIX 来测试已经创建的 `Route`。
```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` 参数忽略自签名证书错误。
+哇哦! 它将从我们的 `Upstream` （实际是 `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 的用户。
+让我们来做一些有趣的事情，由于我们在第二步中创建的 `Route` 是公共的，**任何人** 都可以访问，现在我们希望只有 `John` 可以访问它。让我们使用 [Consumer](./architecture-design/consumer.md) 和 [Plugin](./architecture-design/plugin.md) 来实现这个保护措施。
-注：Apache APISIX 支持多种认证机制，查看插件文档了解更多。
+首先，我们使用 [key-auth](./plugins/key-auth.md) 插件创建 [consumer](./architecture-design/consumer.md) `John`，我们需要提供一个指定的秘钥:
-```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 验证插件。
+接下来，让我们绑定 `Consumer(John)` 到 `Route` 上，我们仅仅需要为 `Route` **启用** [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，现在当我们访问第二步创建的 `Route` 时，将会产生一个 **Unauthorized Error**（未经授权错误）。让我看看如何正确访问那个 `Route`：
Review comment:
```suggestion
OK，现在当我们访问第二步创建的路由时，将会产生一个 **Unauthorized Error**（未经授权错误）。让我看看如何正确访问那个路由：
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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 机制进行负载平衡。
+读完上一节，我们知道了必须要为 `Route` 设置 `Upstream` 。可以执行下面的命令来创建一个 `Upstream`。
```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` 设置为我们的 Upstream 目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
-默认情况下，Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中，让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。
+**注意：** 实际上，创建 Upstream 并不是必需的，因为我们可以使用 [Plugin](./architecture-design/plugin.md) 拦截器请求，然后直接响应，但是假设我们在本指南中需要至少设置一个 `Upstream`。
```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 来测试新配置的路由。
+再次恭喜！我们创建了 `Route` 和 `Upstream`，并且为它们做了绑定。现在让我们访问 Apache APISIX 来测试已经创建的 `Route`。
```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` 参数忽略自签名证书错误。
+哇哦! 它将从我们的 `Upstream` （实际是 `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 的用户。
+让我们来做一些有趣的事情，由于我们在第二步中创建的 `Route` 是公共的，**任何人** 都可以访问，现在我们希望只有 `John` 可以访问它。让我们使用 [Consumer](./architecture-design/consumer.md) 和 [Plugin](./architecture-design/plugin.md) 来实现这个保护措施。
-注：Apache APISIX 支持多种认证机制，查看插件文档了解更多。
+首先，我们使用 [key-auth](./plugins/key-auth.md) 插件创建 [consumer](./architecture-design/consumer.md) `John`，我们需要提供一个指定的秘钥:
-```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 验证插件。
+接下来，让我们绑定 `Consumer(John)` 到 `Route` 上，我们仅仅需要为 `Route` **启用** [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，现在当我们访问第二步创建的 `Route` 时，将会产生一个 **Unauthorized Error**（未经授权错误）。让我看看如何正确访问那个 `Route`：
```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` ！这样就可以保护任何的 `Route` 了，so easy，不是吗？
+
+### 为 Route 添加前缀
Review comment:
```suggestion
### 为路由添加前缀
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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 机制进行负载平衡。
+读完上一节，我们知道了必须要为 `Route` 设置 `Upstream` 。可以执行下面的命令来创建一个 `Upstream`。
```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` 设置为我们的 Upstream 目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
-默认情况下，Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中，让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。
+**注意：** 实际上，创建 Upstream 并不是必需的，因为我们可以使用 [Plugin](./architecture-design/plugin.md) 拦截器请求，然后直接响应，但是假设我们在本指南中需要至少设置一个 `Upstream`。
```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 来测试新配置的路由。
+再次恭喜！我们创建了 `Route` 和 `Upstream`，并且为它们做了绑定。现在让我们访问 Apache APISIX 来测试已经创建的 `Route`。
```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` 参数忽略自签名证书错误。
+哇哦! 它将从我们的 `Upstream` （实际是 `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 的用户。
+让我们来做一些有趣的事情，由于我们在第二步中创建的 `Route` 是公共的，**任何人** 都可以访问，现在我们希望只有 `John` 可以访问它。让我们使用 [Consumer](./architecture-design/consumer.md) 和 [Plugin](./architecture-design/plugin.md) 来实现这个保护措施。
-注：Apache APISIX 支持多种认证机制，查看插件文档了解更多。
+首先，我们使用 [key-auth](./plugins/key-auth.md) 插件创建 [consumer](./architecture-design/consumer.md) `John`，我们需要提供一个指定的秘钥:
-```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 验证插件。
+接下来，让我们绑定 `Consumer(John)` 到 `Route` 上，我们仅仅需要为 `Route` **启用** [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，现在当我们访问第二步创建的 `Route` 时，将会产生一个 **Unauthorized Error**（未经授权错误）。让我看看如何正确访问那个 `Route`：
```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` ！这样就可以保护任何的 `Route` 了，so easy，不是吗？
Review comment:
```suggestion
是的，仅仅添加了一个带有正确密钥的名为 `apikey` 的 `Header`！这样就可以保护任何的路由了。
```
##########
File path: docs/zh/latest/getting-started.md
##########
@@ -21,238 +21,262 @@ 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 就会明白这个 Request 应该去哪里。
- 让我们来看看下面的场景
- 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"
- ```
+这条 Route 意思着所有入站请求都将被转发到 `httpbin.org:80` Upstream，当它们满足 **所有** 这些规则 （即，匹配的请求） ：
-- Upstream 信息：
+此路由表示所有入站请求在满足**所有**以下规则(匹配请求)时，将被转发到`httpbin.org：80`上游：
- Upstream 是一个虚拟主机抽象，它根据配置规则在给定的一组服务节点上执行负载平衡。
- 因此，单个上游配置可以由提供相同服务的多个服务器组成。每个节点将包括一个 key（地址/ip:port）和一个 value （节点的权重）。
- 服务可以通过轮询或一致哈希（cHash）机制进行负载平衡。
+- Request's HTTP method is `GET`;
+- Request has `Host` Header, and its value is `example.com`;
+- Request's path matches `/services/users/*`, `*` means all subpaths, like `/services/users/getAll?limit=10`.
- 配置路由时，可以直接设置 Upstream 信息，也可以使用服务抽象来引用 Upstream 信息。
+当这条 Route 创建后，我们就可以使用 Apache APISIX 的地址去访问我们的后端服务（实际上是 Upstream）：
-- 各种插件
+```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 机制进行负载平衡。
+读完上一节，我们知道了必须要为 `Route` 设置 `Upstream` 。可以执行下面的命令来创建一个 `Upstream`。
```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` 设置为我们的 Upstream 目标（后端服务），其 ID 为 `50`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
-默认情况下，Apache APISIX 通过 HTTP 协议代理请求。如果我们的后端托管在 HTTPS 环境中，让我们使用 proxy-rewrite 插件将方案更改为 HTTPS 。
+**注意：** 实际上，创建 Upstream 并不是必需的，因为我们可以使用 [Plugin](./architecture-design/plugin.md) 拦截器请求，然后直接响应，但是假设我们在本指南中需要至少设置一个 `Upstream`。
```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 来测试新配置的路由。
+再次恭喜！我们创建了 `Route` 和 `Upstream`，并且为它们做了绑定。现在让我们访问 Apache APISIX 来测试已经创建的 `Route`。
```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` 参数忽略自签名证书错误。
+哇哦! 它将从我们的 `Upstream` （实际是 `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 的用户。
+让我们来做一些有趣的事情，由于我们在第二步中创建的 `Route` 是公共的，**任何人** 都可以访问，现在我们希望只有 `John` 可以访问它。让我们使用 [Consumer](./architecture-design/consumer.md) 和 [Plugin](./architecture-design/plugin.md) 来实现这个保护措施。
-注：Apache APISIX 支持多种认证机制，查看插件文档了解更多。
+首先，我们使用 [key-auth](./plugins/key-auth.md) 插件创建 [consumer](./architecture-design/consumer.md) `John`，我们需要提供一个指定的秘钥:
-```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 验证插件。
+接下来，让我们绑定 `Consumer(John)` 到 `Route` 上，我们仅仅需要为 `Route` **启用** [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，现在当我们访问第二步创建的 `Route` 时，将会产生一个 **Unauthorized Error**（未经授权错误）。让我看看如何正确访问那个 `Route`：
```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` ！这样就可以保护任何的 `Route` 了，so easy，不是吗？
+
+### 为 Route 添加前缀
-现在，假设您要向路由添加前缀（例如：samplePrefix），并且不想使用 `host` 头， 则可以使用代理来完成。
+现在，假设您要向路由添加前缀（例如：samplePrefix），并且不想使用 `host` 头， 则可以使用proxy-rewrite 插件来完成。
Review comment:
```suggestion
现在，假设您要向路由添加前缀（例如：samplePrefix），并且不想使用 `host` 头， 则可以使用 `proxy-rewrite` 插件来完成。
```
--
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:
users@infra.apache.org