docs: update CN getting-started

apache · Jul 6, 2021 · c881d6a · c881d6a
1 parent 220fb83
commit c881d6a
Showing 1 changed file with 85 additions and 64 deletions.
diff --git a/docs/zh/latest/getting-started.md b/docs/zh/latest/getting-started.md
@@ -21,17 +21,33 @@ title: 快速入门指南
 #
 -->
 
-本指南旨在让大家入门 Apache APISIX，我们将配置一个对外提供公共 API 的服务，并由 API key 进行访问保护。
+## 概述
 
-另外，我们将以下面的 `echo` 端点为例，它将返回我们传递的参数。
+本文是 Apache APISIX 的快速入门指南。快速入门分为三个步骤：
 
-**Request**
+1. 通过[Docker](https://www.docker.com/) 和 [Docker Compose](https://docs.docker.com/compose/) 安装 Apache APISIX。
+1. 创建路由并绑定后端服务。
+1. 使用命令行语句 `curl` 验证绑定之后返回的结果是否符合预期。
+
+除此之外，本文也提供了 Apache APISIX 的一些进阶操作技巧，包括：添加身份验证、为路由添加前缀、使用 APISIX Dashboard 以及常见问题排查。
+
+我们将以下面的 `echo` 端点为例，它将返回我们传递的参数。
+
+**请求内容**
+
+请求 URL 由以下这些参数构成：
+
+- Protocol：即网络传输协议，这里使用的是最常见的HTTP协议。
+- Port：即端口，这里使用的 `80` 端口。
+- Host：即宿主机，这里的主机是 `httpbin.org`。
+- Path：`/get`。
+- Query Parameters：即查询字符串，这里有两个字符串，分别是`foo1`和`foo2`。
 
 ```bash
-$ curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"
+curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"
 ```
 
-**Response**
+**响应内容**
 
 ```json
 {
@@ -50,39 +66,39 @@ $ curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"
 }
 ```
 
-让我们来分析一下上面的请求 URL：
-
-- Protocol: HTTP
-- Port: 80
-- Host: `httpbin.org`
-- URI/Path: `/get`
-- Query Parameters: foo1, foo2
+## 前提条件
 
-## 前提
+- 已安装[Docker](https://www.docker.com/) 和 [Docker Compose 组件](https://docs.docker.com/compose/)。
 
-> 如果您已经安装了 Apache APISIX，请直接阅读 [第二步](getting-started.md#第二步:-创建一个-Route)
+- 熟悉`curl`命令。本文使用 [curl](https://curl.se/docs/manpage.html) 命令行进行 API 测试。您也可以使用其他工具例如 [Postman](https://www.postman.com/)等，进行测试。
 
-- 本指南使用 [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/)。
+:::note 说明
+如果您已经安装了 Apache APISIX，请直接阅读 [第二步](getting-started.md#第二步-创建一个-Route)
+:::
 
-## 第一步: 安装 Apache APISIX
+## 第一步：安装 Apache APISIX
 
 得益于 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
+#将 Apache APISIX 的 Docker 镜像下载到本地
+git clone https://github.com/apache/apisix-docker.git
+# 将当前的目录切换到 apisix-docker/example 路径下
+cd apisix-docker/example
+# 运行 docker-compose 命令，安装 Apache APISIX
+docker-compose -p docker-apisix up -d
 ```
 
-下载所需的所有文件将花费一些时间，这取决于您的网络，请耐心等待。下载完成后，我们可以使用 `curl` 访问 Admin API，以判断 Apache APISIX 是否成功启动。
+下载所需的所有文件将花费一些时间，这取决于您的网络，请耐心等待。
+
+下载完成后，在运行 Docker 的宿主机上执行`curl`命令访问 Admin API，根据返回数据判断 Apache APISIX 是否成功启动。
 
 ```bash
 # 注意：请在运行 Docker 的宿主机上执行 curl 命令。
-$ curl "http://127.0.0.1:9080/apisix/admin/services/" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
+curl "http://127.0.0.1:9080/apisix/admin/services/" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
 ```
 
-我们期望获得以下返回数据：
+返回数据如下所示，表示Apache APISIX 成功启动：
 
 ```json
 {
@@ -96,17 +112,17 @@ $ curl "http://127.0.0.1:9080/apisix/admin/services/" -H 'X-API-KEY: edd1c9f0343
 }
 ```
 
-## 第二步: 创建一个 Route
+## 第二步：创建路由
 
-恭喜！您现在已经拥有一个运行中的 Apache APISIX 实例了！接下来，让我们来创建一个 Route。
+您现在已经拥有一个运行中的 Apache APISIX 实例了！接下来，让我们来创建一个路由（Route）。
 
-### 在我们继续之前
+### 工作原理
 
-您知道吗？Apache APISIX 提供了强大的 [Admin API](./admin-api.md) 和 [Dashboard](https://github.com/apache/apisix-dashboard) 可供我们使用，但在本指南中我们使用 Admin API 来做演示。
+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 就会明白这个请求应该转发到哪个上游服务中。
+我们可以创建一个 [Route](./architecture-design/route.md) 并与上游（通常也被称为[Upstream](./architecture-design/upstream.md)，即后端服务）绑定，当一个 `请求（Request）` 到达 Apache APISIX 时，Apache APISIX 就会明白这个请求应该转发到哪个后端服务中。
 
-Apache APISIX 是如何知道的呢？那是因为我们为 Route 对象配置了匹配规则。下面是一个 Route 配置示例：
+因为我们为 Route 对象配置了匹配规则，所以 Apache APISIX 可以将请求转发到对应的后端服务。以下代码是一个 Route 配置示例：
 
 ```json
 {
@@ -122,23 +138,23 @@ Apache APISIX 是如何知道的呢？那是因为我们为 Route 对象配置
 }
 ```
 
-这条路由配置意味着，当它们满足下述的 **所有** 规则时，所有匹配的入站请求都将被转发到 `httpbin.org:80` 上游：
+这条路由配置意味着，当它们满足下述的 **所有** 规则时，所有匹配的入站请求都将被转发到 `httpbin.org:80` 这个后端服务：
 
-- 请求的 HTTP 方法为 `GET`;
-- 请求头包含 `Host` 字段，且它的值为 `example.com`;
+- 请求的 HTTP 方法为 `GET`。
+- 请求头包含 `host` 字段，且它的值为 `example.com`。
 - 请求路径匹配 `/services/users/*`，`*` 意味着任意的子路径，例如 `/services/users/getAll?limit=10`。
 
-当这条路由创建后，我们就可以使用 Apache APISIX 对外暴露的地址去访问后端服务（即上游）：
+当这条路由创建后，我们可以使用 Apache APISIX 对外暴露的地址去访问后端服务：
 
 ```bash
 $ curl -i -X GET "http://{APISIX_BASE_URL}/services/users/getAll?limit=10" -H "Host: example.com"
 ```
 
 这将会被 Apache APISIX 转发到 `http://httpbin.org:80/services/users/getAll?limit=10`。
 
-### 创建一个上游（Upstream）
+### 创建后端服务（Upstream）
 
-读完上一节，我们知道必须为 `路由` 设置 `上游`。只需执行下面的命令即可创建一个上游：
+读完上一节，我们知道必须为 `Route` 设置 `Upstream`。只需执行下面的命令即可创建一个后端服务：
 
 ```bash
 $ curl "http://127.0.0.1:9080/apisix/admin/upstreams/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
@@ -152,44 +168,45 @@ $ curl "http://127.0.0.1:9080/apisix/admin/upstreams/1" -H "X-API-KEY: edd1c9f03
 
 我们使用 `roundrobin` 作为负载均衡机制，并将 `httpbin.org:80` 设置为我们的上游目标（后端服务），其 ID 为 `1`。更多字段信息，请参阅 [Admin API](./admin-api.md)。
 
-**注意：** 创建上游实际上并不是必需的，因为我们可以使用 [插件](./architecture-design/plugin.md) 拦截请求，然后直接响应。但在本指南中，我们假设需要设置至少一个上游。
+:::note 注意
+创建上游实际上并不是必需的，因为我们可以使用 [插件](./architecture-design/plugin.md) 拦截请求，然后直接响应。但在本指南中，我们假设需要设置至少一个上游。
+:::
 
-### 路由与上游绑定
+### 绑定路由与上游
 
-We just created an Upstream(Reference to our backend services), let's bind one Route with it!
-我们刚刚创建了一个上游(引用我们的后端服务)，让我们为它绑定一个路由！
+我们刚刚创建了一个上游(引用我们的后端服务)，现在让我们为它绑定一个路由！
 
 ```bash
-$ curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
+curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
 {
   "uri": "/get",
   "host": "httpbin.org",
   "upstream_id": "1"
 }'
 ```
 
-就是这样！
-
-### 验证
+## 第三步：验证
 
-再次恭喜！我们已创建了路由与上游，并将它们进行了绑定。现在让我们访问 Apache APISIX 来测试这条已经创建的路由：
+我们已创建了路由与后端服务，并将它们进行了绑定。现在让我们访问 Apache APISIX 来测试这条路由：
 
 ```bash
-$ curl -i -X GET "http://127.0.0.1:9080/get?foo1=bar1&foo2=bar2" -H "Host: httpbin.org"
+curl -i -X GET "http://127.0.0.1:9080/get?foo1=bar1&foo2=bar2" -H "Host: httpbin.org"
 ```
 
-哇哦! 它将从我们的上游（实际是 `httpbin.org`）返回数据，结果符合预期！
+它从我们的后端服务（实际是 `httpbin.org`）返回数据，并且结果符合预期。
+
+## 进阶操作
 
-## 进阶
+### 添加身份验证
 
-### 身份验证
+我们在第二步中创建的路由是公共的，只要知道 Apache APISIX 对外暴露的地址，**任何人** 都可以访问这个后端服务，这种访问方式没有保护措施，存在一定的安全隐患。在实际应用场景中，我们需要为路由添加身份验证。
 
-让我们来做一些有趣的事情，由于我们在第二步中创建的路由是公共的，**任何人** 都可以访问，现在我们希望只有 `John` 可以访问它。让我们使用 [消费者（Consumer）](./architecture-design/consumer.md) 和 [插件（Plugin）](./architecture-design/plugin.md) 来实现这个保护措施。
+现在我们希望只有特定的用户 `John` 可以访问这个后端服务，需要使用[消费者（Consumer）](./architecture-design/consumer.md) 和 [插件（Plugin）](./architecture-design/plugin.md) 来实现身份验证。
 
-首先，让我们用 [key-auth](./plugins/key-auth.md) 插件创建一个 [消费者（Consumer）](./architecture-design/consumer.md) `John`，我们需要提供一个指定的密钥:
+首先，让我们用 [key-auth](./plugins/key-auth.md) 插件创建一个 [消费者（Consumer）](./architecture-design/consumer.md) `John`，我们需要提供一个指定的密钥：
 
 ```bash
-$ curl "http://127.0.0.1:9080/apisix/admin/consumers" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
+curl "http://127.0.0.1:9080/apisix/admin/consumers" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
 {
   "username": "john",
   "plugins": {
@@ -200,10 +217,10 @@ $ curl "http://127.0.0.1:9080/apisix/admin/consumers" -H "X-API-KEY: edd1c9f0343
 }'
 ```
 
-接下来，让我们绑定 `消费者（John）` 到路由上，我们仅仅需要为路由 **启用** [key-auth](./plugins/key-auth.md) 插件即可。
+接下来，让我们绑定 `消费者（John）` 到路由上，我们只需要为路由 **启用** [key-auth](./plugins/key-auth.md) 插件即可。
 
 ```bash
-$ curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
+curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
 {
   "uri": "/get",
   "host": "httpbin.org",
@@ -214,20 +231,20 @@ $ curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f03433
 }'
 ```
 
-OK，现在当我们访问第二步创建的路由时，将会产生一个 **Unauthorized Error**（未经授权的错误）。让我们看看如何正确访问那个路由：
+现在当我们访问第二步创建的路由时，会触发 **Unauthorized Error（未经授权的错误）**。
+
+访问那个路由的正确方式是添加一个带有正确密钥的名为 `apikey` 的 `Header`，如下方代码所示。
 
 ```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'
 ```
 
-是的，仅仅添加了一个带有正确密钥的名为 `apikey` 的 `Header`！这样就可以保护任何的路由了。
-
 ### 为路由添加前缀
 
 现在，假设您要向路由添加前缀（例如：samplePrefix），并且不想使用 `host` 头， 则可以使用 `proxy-rewrite` 插件来完成。
 
 ```bash
-$ curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
+curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
 {
   "uri": "/samplePrefix/get",
   "plugins": {
@@ -243,27 +260,31 @@ $ curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f03433
 现在您可以使用以下命令来调用路由：
 
 ```bash
-$ curl -i -X GET "http://127.0.0.1:9080/samplePrefix/get?param1=foo&param2=bar" -H "apikey: key-of-john"
+curl -i -X GET "http://127.0.0.1:9080/samplePrefix/get?param1=foo&param2=bar" -H "apikey: key-of-john"
 ```
 
-### APISIX Dashboard（控制台）
+### APISIX Dashboard
 
 Apache APISIX 提供了一个 [Dashboard](https://github.com/apache/apisix-dashboard)，让我们的操作更直观更轻松。
 
 ![Dashboard](../../assets/images/dashboard.jpeg)
 
-### 故障排查
+:::note 注意
+APISIX Dashboard 目前仍然是一个实验性功能。
+:::
+
+### 常见问题排查
 
 - 确保所需的所有端口（**默认的 9080/9443/2379**）未被其他系统/进程使用。
 
     下面是终止正在侦听特定端口（基于 unix 的系统）的进程的命令。
 
     ```bash
-    $ sudo fuser -k 9443/tcp
+    sudo fuser -k 9443/tcp
     ```
 
-- 如果 Docker 容器持续不断地重启/失败，请登录容器并观察日志以诊断问题。
+- 如果 Docker 容器持续不断地重启或失败，请登录容器并观察日志以诊断问题。
 
     ```bash
-    $ docker logs -f --tail container_id
+    docker logs -f --tail container_id
     ```