You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2021/07/09 10:08:16 UTC
[apisix] branch master updated: docs: update CN and EN
getting-started documents (#4546)
This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 932865b docs: update CN and EN getting-started documents (#4546)
932865b is described below
commit 932865bdf63a3ab3bd69ed1d79747296e940c80e
Author: yilinzeng <36...@users.noreply.github.com>
AuthorDate: Fri Jul 9 18:08:07 2021 +0800
docs: update CN and EN getting-started documents (#4546)
---
docs/en/latest/getting-started.md | 175 +++++++++++++++++++++-----------------
docs/zh/latest/getting-started.md | 159 +++++++++++++++++++---------------
2 files changed, 190 insertions(+), 144 deletions(-)
diff --git a/docs/en/latest/getting-started.md b/docs/en/latest/getting-started.md
index be8d32d..d5956e0 100644
--- a/docs/en/latest/getting-started.md
+++ b/docs/en/latest/getting-started.md
@@ -21,16 +21,32 @@ title: Getting Started
#
-->
-## Getting Started
+## Summary
-This guide aims to get started with Apache APISIX, we will configure the service that will route to a public API, secured by an API key.
+This article is a quick start guide for Apache APISIX. The Quick Start is divided into the following three steps:
-Also, we will take the following `echo` endpoint as an example, it will return parameters we passed.
+1. Install Apache APISIX via [Docker Compose](https://docs.docker.com/compose/).
+1. Create a route and bind it with a Upstream.
+1. Use `curl` command to verify that the results returned after binding are as expected.
+
+In addition, this article provides some advanced operations on how to use Apache APISIX, including adding authentication, prefixing Route, using the APISIX Dashboard, and troubleshooting.
+
+We will use the following `echo` endpoint as an example, which will return the parameters we passed.
**Request**
+The request URL consists of these parameters:
+
+- Protocol: the network transport protocol, `HTTP` protocol is used in our example.
+- Port: The port, `80` is used in our example.
+- Host: The host, `httpbin.org` is used in our example.
+- Path: The path, `/get` is used in our example.
+- Query Parameters: the query string, two strings `foo1` and `foo2` are listed in our example.
+
+Run the following command to send the request:
+
```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**
@@ -52,41 +68,39 @@ $ curl --location --request GET "http://httpbin.org/get?foo1=bar1&foo2=bar2"
}
```
-Let's deconstruct the above Request URL.
+## Pre-requisites
-- Protocol: HTTP
-- Port: 80
-- Host: `httpbin.org`
-- URI/Path: `/get`
-- Query Parameters: foo1, foo2
+- Installed [Docker](https://www.docker.com/) and [Docker Compose component](https://docs.docker.com/compose/).
-## Prerequisites
+- We use the [curl](https://curl.se/docs/manpage.html) command for API testing. You can also use other tools such as [Postman](https://www.postman.com/) for testing.
-> If you have installed the Apache APISIX, feel free and skip to [Step 2](#step-2-create-a-route) please.
-
-- This guide uses [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/) to setup Apache APISIX.
-- `curl`: This guide uses the [curl](https://curl.se/docs/manpage.html) command for API testing, but you can also use any other tools, e.g [Postman](https://www.postman.com/).
-
-I know you're waiting for this moment for a while, let's go!
+:::note Note
+If you already have Apache APISIX installed, please skip Step 1, and go to [Step 2](getting-started.md#Step-2-Create-a-Route) directly.
+:::
## Step 1: Install Apache APISIX
-Thanks to Docker, we could launch the Apache APISIX and enable the [Admin API](./admin-api.md) by executing the following commands:
+Thanks to Docker, we can start Apache APISIX and enable it by enabling [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
+# Download the Docker image of Apache APISIX
+git clone https://github.com/apache/apisix-docker.git
+# Switch the current directory to the apisix-docker/example path
+cd apisix-docker/example
+# Run the docker-compose command to install Apache APISIX
+docker-compose -p docker-apisix up -d
```
-It will take some time to download all needed files, and this depends on your network, please be patient. Once this step gets done, we could `curl` our Admin API to tell if the Apache APISIX launchs successfully.
+It will take some time to download all required files, please be patient.
+
+Once the download is complete, execute the `curl` command on the host running Docker to access the Admin API, and determine if Apache APISIX was successfully started based on the returned data.
```bash
-# NOTE: Please curl on the machine which you run above Docker commands.
-$ curl "http://127.0.0.1:9080/apisix/admin/services/" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
+# Note: Please execute the curl command on the host where you are running Docker.
+curl "http://127.0.0.1:9080/apisix/admin/services/" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
-We expect the following data to be returned:
+The following data is returned to indicate that Apache APISIX was successfully started:
```json
{
@@ -102,15 +116,15 @@ We expect the following data to be returned:
## Step 2: Create a Route
-Congratulations! You have a running Apache APISIX instance now! Let's create a Route next!
+Now we have a running instance of Apache APISIX! Next, let's create a Route.
-### Before we continue
+### How it works
-Do you know? Apache APISIX provides the powerful [Admin API](./admin-api.md) and a [Dashboard](https://github.com/apache/apisix-dashboard) for us to use, but we will use Admin API here in this guide. Let's go!
+Apache APISIX provides users with a powerful [Admin API](./admin-api.md) and [APISIX Dashboard](https://github.com/apache/apisix-dashboard). In this article, we use the Admin API to walk you through the procedures of creating a Route.
-We could create one [Route](./architecture-design/route.md) and target it to our backend services (We call them [Upstream](./architecture-design/upstream.md) usually), when one `Request` reaches Apache APISIX, Apache APISIX will see where this Request should go.
+We can create a [Route](./architecture-design/route.md) and connect it to an Upstream service(also known as the [Upstream](./architecture-design/upstream.md)). When a `Request` arrives at Apache APISIX, Apache APISIX knows which Upstream the request should be forwarded to.
-Then how does Apache APISIX know this? That's because we have a list of rules configured with Route. Here is a sample Route data:
+Because we have configured matching rules for the Route object, Apache APISIX can forward the request to the corresponding Upstream service. The following code is an example of a Route configuration:
```json
{
@@ -126,26 +140,26 @@ Then how does Apache APISIX know this? That's because we have a list of rules co
}
```
-This Route means all inbound requests will be forwarded to the `httpbin.org:80` Upstream when they meets **ALL** these rules(matched requests):
+This routing configuration means that all matching inbound requests will be forwarded to the Upstream service `httpbin.org:80` when they meet **all** the rules listed below:
-- 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`.
+- The HTTP method of the request is `GET`.
+- The request header contains the `host` field, and its value is `example.com`.
+- The request path matches `/services/users/*`, `*` means any subpath, for example `/services/users/getAll?limit=10`.
-After this Route is created, we could use Apache APISIX's address to access our backend services(Upstream actually):
+Once this route is created, we can access the Upstream service using the address exposed by Apache APISIX.
```bash
-$ curl -i -X GET "http://{APISIX_BASE_URL}/services/users/getAll?limit=10" -H "Host: example.com"
+curl -i -X GET "http://{APISIX_BASE_URL}/services/users/getAll?limit=10" -H "Host: example.com"
```
-This will be forward to `http://httpbin.org:80/services/users/getAll?limit=10` by Apache APISIX.
+This will be forwarded to `http://httpbin.org:80/services/users/getAll?limit=10` by Apache APISIX.
### Create an Upstream
-After reading the above section, we know we have to set the `Upstream` for `Route`. Just executing the following command to create one:
+After reading the previous section, we know that we must set up an `Upstream` for the `Route`. An Upstream can be created by simply executing the following command:
```bash
-$ curl "http://127.0.0.1:9080/apisix/admin/upstreams/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
+curl "http://127.0.0.1:9080/apisix/admin/upstreams/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
"type": "roundrobin",
"nodes": {
@@ -154,16 +168,18 @@ $ curl "http://127.0.0.1:9080/apisix/admin/upstreams/1" -H "X-API-KEY: edd1c9f03
}'
```
-We use `roundrobin` as our load balancer mechanism, and set `httpbin.org:80` as our Upstream target(backend server), and its ID is `1`. For more fields, please refer to [Admin API](./admin-api.md).
+We use `roundrobin` as the load balancing mechanism, and set `httpbin.org:80` as our upstream target (Upstream service) with an ID of `1`. For more information on the fields, see [Admin API](./admin-api.md).
-**NOTE:** `Create an Upstream` is not required actually, because we could use [Plugin](./architecture-design/plugin.md) to interceptor requests then response directly, but let's assume we need to set at least one `Upstream` in this guide.
+:::note Note
+Creating an Upstream service is not actually necessary, as we can use [Plugin](./architecture-design/plugin.md) to intercept the request and then respond directly. However, for the purposes of this guide, we assume that at least one Upstream service needs to be set up.
+:::
-### Bind Route with Upstream
+### Bind the Route to the Upstream
-We just created an Upstream(Reference to our backend services), let's bind one Route with it!
+We've just created an Upstream service (referencing our backend service), now let's bind a Route for 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",
@@ -171,28 +187,30 @@ $ curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f03433
}'
```
-That's it!
-
-### Verification
+## Step 3: Validation
-Congratulations once more! We have created one `Route` and `Upstream`, also we bind them together. Now let's call Apache APISIX to test the `created route`.
+We have created the route and the Upstream service and bound them. Now let's access Apache APISIX to test this 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"
```
-Wow! It will return data from our `Upstream`(`httpbin.org` actually), it works as expected!
+It returns data from our Upstream service (actually `httpbin.org`) and the result is as expected.
-## Advanced
+## Advanced Operations
-### Authentication
+This section provides some advanced operations such as adding authentication, prefixing Route, using the APISIX Dashboard, and troubleshooting.
-Let's do some interesting things, due to **anyone** could access our public `Route` created in the Step2, we would like only `John` could access it. Let's use [Consumer](./architecture-design/consumer.md) and [Plugin](./architecture-design/plugin.md) to implement this protection.
+### Add Authentication
-First, let's create the [consumer](./architecture-design/consumer.md) `John` with [key-auth](./plugins/key-auth.md) plugin, we need to provide a specified secret key:
+The route we created in step 2 is public. Thus, **anyone** can access this Upstream service as long as they know the address that Apache APISIX exposes to the outside world. This is unsafe, it creates certain security risks. In a practical application scenario, we need to add authentication to the route.
+
+Now we want only a specific user `John` to have access to this Upstream service, and we need to use [Consumer](./architecture-design/consumer.md) and [Plugin](./architecture-design/plugin.md) to implement authentication.
+
+First, let's use [key-auth](./plugins/key-auth.md) plugin to create a [Consumer](./architecture-design/consumer.md) `John`, we need to provide a specified key.
```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": {
@@ -203,10 +221,10 @@ $ curl "http://127.0.0.1:9080/apisix/admin/consumers" -H "X-API-KEY: edd1c9f0343
}'
```
-Next, let's bind our `Consumer(John)` to that `Route`, we only need to **Enable** the [key-auth](./plugins/key-auth.md) plugin for that `Route`:
+Next, let's bind `consumer (John)` to the route, we just need to **enable** the [key-auth](./plugins/key-auth.md) plugin.
```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",
@@ -217,21 +235,20 @@ $ curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f03433
}'
```
-Ok, when we access the `Route` created in Step2 from now on, an **Unauthorized Error** will occur. Let's see how to access that `Route`:
+Now when we access the route created in step 2, an **Unauthorized Error** will be triggered.
+
+The correct way to access that route is to add a `Header` named `apikey` with the correct key, as shown in the code below:
```bash
-$ curl -i -X GET "http://127.0.0.1:9080/get" -H "Host: httpbin.org" -H "apikey: key-of-john"
+curl -i -X GET http://127.0.0.1:9080/get -H "Host: httpbin.org" -H 'apikey: superSecretAPIKey'
```
-Ya, just added an `Header` called `apikey` with correct key! It's so easy to protect any `Routes`, right?
+### Prefixing a Route
-### Prefix in Route
-
-Now lets say you want to add a prefix (eg: samplePrefix) to the route and do not want to use the `host` header then you can use
-the proxy-rewrite plugin to do it.
+Now, suppose you want to add a prefix to a route (e.g. samplePrefix) and don't want to use the `host` header, then you can use the `proxy-rewrite` plugin to do so.
```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": {
@@ -244,30 +261,34 @@ $ curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f03433
}'
```
-Now you can invoke the route with the following command:
+You can now use the following command to invoke the route:
```bash
-$ curl -i -X GET "http://127.0.0.1:9080/samplePrefix/get?param1=foo¶m2=bar" -H "apikey: key-of-john"
+curl -i -X GET "http://127.0.0.1:9080/samplePrefix/get?param1=foo¶m2=bar" -H "apikey: key-of-john"
```
### APISIX Dashboard
-Apache APISIX provides a [Dashboard](https://github.com/apache/apisix-dashboard) to let us operate Apache APISIX more easier.
+Apache APISIX provides a [Dashboard](https://github.com/apache/apisix-dashboard) to make our operation more intuitive and easier.
+:::note Note
+APISIX Dashboard is an experimental feature for now.
+:::
+
### Troubleshooting
-- Make sure all required ports (**9080/9443/2379 by default**) are not being used by other systems/processes.
+- Make sure that all required ports (**default 9080/9443/2379**) are not used by other systems or processes.
-The following command will kill the process which is listening on a specific port (in unix based systems).
+ The following are commands to terminate a process that is listening on a specific port (on unix-based systems).
-```bash
-$ sudo fuser -k 9443/tcp
-```
+ ```bash
+ sudo fuser -k 9443/tcp
+ ```
-- If the docker container is restarting/failing continuously, just access to the container and observe the logs to find out what happened.
+- If the Docker container keeps restarting or failing, log in to the container and observe the logs to diagnose the problem.
-```bash
-$ docker logs -f --tail container_id
-```
+ ```bash
+ docker logs -f --tail container_id
+ ```
diff --git a/docs/zh/latest/getting-started.md b/docs/zh/latest/getting-started.md
index 034db6e..150e014 100644
--- a/docs/zh/latest/getting-started.md
+++ b/docs/zh/latest/getting-started.md
@@ -21,17 +21,35 @@ title: 快速入门指南
#
-->
-本指南旨在让大家入门 Apache APISIX，我们将配置一个对外提供公共 API 的服务，并由 API key 进行访问保护。
+## 概述
-另外，我们将以下面的 `echo` 端点为例，它将返回我们传递的参数。
+本文是 Apache APISIX 的快速入门指南。快速入门分为三个步骤：
-**Request**
+1. 通过[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 +68,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 Compose 组件](https://docs.docker.com/compose/)。
-> 如果您已经安装了 Apache APISIX，请直接阅读 [第二步](getting-started.md#第二步:-创建一个-Route)
+- 本文使用 [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 +114,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,26 +140,26 @@ 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"
+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 '
+curl "http://127.0.0.1:9080/apisix/admin/upstreams/1" -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
{
"type": "roundrobin",
"nodes": {
@@ -150,17 +168,18 @@ $ 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)。
+我们使用 `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",
@@ -168,28 +187,30 @@ $ curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H "X-API-KEY: edd1c9f03433
}'
```
-就是这样！
-
-### 验证
+## 第三步：验证
-再次恭喜！我们已创建了路由与上游，并将它们进行了绑定。现在让我们访问 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 的一些进阶操作技巧，包括：添加身份验证、为路由添加前缀、使用 APISIX Dashboard 以及常见问题排查。
-## 进阶
+### 添加身份验证
-### 身份验证
+我们在第二步中创建的路由是公共的，只要知道 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 +221,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 +235,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 +264,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¶m2=bar" -H "apikey: key-of-john"
+curl -i -X GET "http://127.0.0.1:9080/samplePrefix/get?param1=foo¶m2=bar" -H "apikey: key-of-john"
```
-### APISIX Dashboard（控制台）
+### APISIX Dashboard
Apache APISIX 提供了一个 [Dashboard](https://github.com/apache/apisix-dashboard)，让我们的操作更直观更轻松。
-### 故障排查
+:::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
```