From 76fdb02a1b6364c6e87f93e3b1daa39a720a71ea Mon Sep 17 00:00:00 2001 From: Wilson Wu Date: Fri, 29 Sep 2023 09:28:15 +0800 Subject: [PATCH] Improve format for Chinese example doc (#13931) --- .../setup-kubernetes-cluster/index.md | 48 ++++++++------ .../setup-local-computer/index.md | 3 +- .../microservices-istio/single/index.md | 63 ++++++++++--------- 3 files changed, 67 insertions(+), 47 deletions(-) diff --git a/content/zh/docs/examples/microservices-istio/setup-kubernetes-cluster/index.md b/content/zh/docs/examples/microservices-istio/setup-kubernetes-cluster/index.md index 18ca3baa4e..a7a4eebc18 100644 --- a/content/zh/docs/examples/microservices-istio/setup-kubernetes-cluster/index.md +++ b/content/zh/docs/examples/microservices-istio/setup-kubernetes-cluster/index.md @@ -8,18 +8,20 @@ test: no {{< boilerplate work-in-progress >}} -在这个模块，您将设置一个安装了 Istio 的 Kubernetes 集群，还将设置整个教程要用到的一个命名空间。 +在这个模块，您将设置一个安装了 Istio 的 Kubernetes 集群， +还将设置整个教程要用到的一个命名空间。 {{< warning >}} -如果您在培训班且讲师已准备好了集群，直接前往[设置本地机器](/zh/docs/examples/microservices-istio/setup-local-computer)。 +如果您在培训班且讲师已准备好了集群， +直接前往[设置本地机器](/zh/docs/examples/microservices-istio/setup-local-computer)。 {{}} 1. 确保您有 [Kubernetes 集群](https://kubernetes.io/zh-cn/docs/tutorials/kubernetes-basics/)的访问权限。 - 您可以使用 [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/docs/quickstart) 或 - [IBM Cloud Kubernetes Service](https://cloud.ibm.com/docs/containers?topic=containers-getting-started)。 + 您可以使用 [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/docs/quickstart) 或 + [IBM Cloud Kubernetes Service](https://cloud.ibm.com/docs/containers?topic=containers-getting-started)。 1. 生成一个环境变量用于存储运行教程指令要用到的命名空间的名字。 - 可以用任何名字，比如 `tutorial`。 + 可以用任何名字，比如 `tutorial`。 {{< text bash >}} $ export NAMESPACE=tutorial @@ -32,12 +34,15 @@ test: no {{< /text >}} {{< tip >}} - 如果您是一位讲师，可以为每个参与者分配独立的命名空间。本教程支持多个参与者在不同的命名空间下同时运行。 + 如果您是一位讲师，可以为每个参与者分配独立的命名空间。 + 本教程支持多个参与者在不同的命名空间下同时运行。 {{< /tip >}} 1. 使用 `demo` 配置文件[安装 Istio](/zh/docs/setup/)。 -1. 本示例中使用了 [Kiali](/zh/docs/ops/integrations/kiali/) 和 [Prometheus](/zh/docs/ops/integrations/prometheus/) 附加组件，需要安装它们。使用以下命令安装所有插件： +1. 本示例中使用了 [Kiali](/zh/docs/ops/integrations/kiali/) + 和 [Prometheus](/zh/docs/ops/integrations/prometheus/) 附加组件， + 需要安装它们。使用以下命令安装所有插件： {{< text bash >}} $ kubectl apply -f @samples/addons@ @@ -48,7 +53,8 @@ test: no 因为再次运行命令时可以解决一些时序引起的问题。 {{< /tip >}} -1. 使用 `kubectl` 命令为这些通用 Istio 服务创建一个 Kubernetes Ingress 资源。在教程目前这个阶段要熟悉这些服务并不是必须的。 +1. 使用 `kubectl` 命令为这些通用 Istio 服务创建一个 Kubernetes Ingress 资源。 + 在教程目前这个阶段要熟悉这些服务并不是必须的。 - [Grafana](https://grafana.com/docs/guides/getting_started/) - [Jaeger](https://www.jaegertracing.io/docs/1.13/getting-started/) @@ -111,7 +117,8 @@ test: no EOF {{< /text >}} -1. 创建一个角色为 `istio-system` 命名空间提供读权限。要在下面的步骤中限制参与者的权限，这个角色是必须要有的。 +1. 创建一个角色为 `istio-system` 命名空间提供读权限。 + 要在下面的步骤中限制参与者的权限，这个角色是必须要有的。 {{< text bash >}} $ kubectl apply -f - <}} -1. 限制每个参与者的权限。在教程中，参与者只需要在他们自己的命名空间中创建资源以及从 `istio-system` 命名空间中读取资源。 - 即使使用您自己的集群，这也是一个好的实践，它可以避免影响您集群中的其他命名空间。 +1. 限制每个参与者的权限。在教程中，参与者只需要在他们自己的命名空间中创建资源以及从 + `istio-system` 命名空间中读取资源。即使使用您自己的集群，这也是一个好的实践， + 它可以避免影响您集群中的其他命名空间。 - 创建一个角色为每个参与者的命名空间提供读写权限。为每个参与者赋予这个角色，以及读取 `istio-system` 资源的角色： + 创建一个角色为每个参与者的命名空间提供读写权限。 + 为每个参与者赋予这个角色，以及读取 `istio-system` 资源的角色： {{< text bash >}} $ kubectl apply -f - <}} -1. 每个参与者需要使用他们自己的 Kubernetes 配置文件。这个配置文件指明了集群的详细信息、服务账号、证书和参与者的命名空间。 - `kubectl` 命令使用这个配置文件在集群上操作。 +1. 每个参与者需要使用他们自己的 Kubernetes 配置文件。 + 这个配置文件指明了集群的详细信息、服务账号、证书和参与者的命名空间。 + `kubectl` 命令使用这个配置文件在集群上操作。 为每个参与者创建 Kubernetes 配置文件： {{< tip >}} - 该命令假定您的集群名为 `tutorial-cluster`。如果集群的名称不同，则将所有引用替换为集群的名称。 + 该命令假定您的集群名为 `tutorial-cluster`。 + 如果集群的名称不同，则将所有引用替换为集群的名称。 {{}} {{< text bash >}} @@ -241,11 +252,12 @@ test: no 在输出中可以看到命名空间的名字。 -1. 如果您为自己设置好了集群，复制前面步骤中提到的 `${NAMESPACE}-user-config.yaml` 文件到您的本地机器，`${NAMESPACE}` 就是前面步骤中的命名空间。比如，`tutorial-user-config.yaml`。 - 教程中您将会再次用到这个文件。 +1. 如果您为自己设置好了集群，复制前面步骤中提到的 `${NAMESPACE}-user-config.yaml` + 文件到您的本地机器，`${NAMESPACE}` 就是前面步骤中的命名空间。 + 比如，`tutorial-user-config.yaml`。教程中您将会再次用到这个文件。 如果您是讲师，则将生成的配置文件发送给每个学员。学员必须将该配置文件复制到自己本地的计算机。 -恭喜, 您为您的教程设置好了集群！ +恭喜，您为您的教程设置好了集群！ 您已经准备好[设置本地机器](/zh/docs/examples/microservices-istio/setup-local-computer)了。 diff --git a/content/zh/docs/examples/microservices-istio/setup-local-computer/index.md b/content/zh/docs/examples/microservices-istio/setup-local-computer/index.md index 9be80f4f43..102c41e95f 100644 --- a/content/zh/docs/examples/microservices-istio/setup-local-computer/index.md +++ b/content/zh/docs/examples/microservices-istio/setup-local-computer/index.md @@ -33,7 +33,8 @@ test: no 您应该在输出中看到命名空间的名称，该命名空间由讲师分配或者在上一个模块中由您自己分配。 -1. 下载一个 [Istio 发行版](https://github.com/istio/istio/releases) ，从 `bin` 目录下提出命令行工具 `istioctl`，使用下边的命令验证 `istioctl` 是否可以正常使用： +1. 下载一个 [Istio 发行版](https://github.com/istio/istio/releases)， + 从 `bin` 目录下提出命令行工具 `istioctl`，使用下边的命令验证 `istioctl` 是否可以正常使用： {{< text bash >}} $ istioctl version diff --git a/content/zh/docs/examples/microservices-istio/single/index.md b/content/zh/docs/examples/microservices-istio/single/index.md index 9c62ee09dc..1dd221f490 100644 --- a/content/zh/docs/examples/microservices-istio/single/index.md +++ b/content/zh/docs/examples/microservices-istio/single/index.md @@ -8,31 +8,35 @@ test: no {{< boilerplate work-in-progress >}} -在微服务架构出现之前，开发团队会将整个应用程序作为一个大型软件进行构建、部署和运行。想要测试模块中一个微小的改变， -开发人员不仅要通过单元测试，他们必须重新构建整个程序。因此，构建需要花费大量的时间。完成构建后， -开发人员将应用程序版本部署到测试服务器上。他们会把服务跑在远程或本地计算机中。在后一种情况下，开发者会在他们 -的本地计算机上安装并管理一个相当复杂的环境。 +在微服务架构出现之前，开发团队会将整个应用程序作为一个大型软件进行构建、 +部署和运行。想要测试模块中一个微小的改变，开发人员不仅要通过单元测试， +他们必须重新构建整个程序。因此，构建需要花费大量的时间。完成构建后， +开发人员将应用程序版本部署到测试服务器上。他们会把服务跑在远程或本地计算机中。 +在后一种情况下，开发者会在他们的本地计算机上安装并管理一个相当复杂的环境。 -在微服务架构时代，开发人员编写、构建、测试和运行小型的软件服务。构建是快速的。使用类似 -[Node.js](https://nodejs.org/zh-cn/) 这样的现代框架, 由于服务是作为常规进程来运行的，就不需要安装并管理 -复杂的服务环境来测试它了。您不再仅仅为了测试您的服务就得将它部署到某个环境了，您只需要构建您的服务并且直接在您本地机器上运行即可。 +在微服务架构时代，开发人员编写、构建、测试和运行小型的软件服务。构建是快速的。 +使用类似 [Node.js](https://nodejs.org/zh-cn/) 这样的现代框架， +由于服务是作为常规进程来运行的，就不需要安装并管理复杂的服务环境来测试它了。 +您不再仅仅为了测试您的服务就得将它部署到某个环境了， +您只需要构建您的服务并且直接在您本地机器上运行即可。 -该模块涵盖了在本地机器上开发单个服务所涉及的不同方面。不过，您无需编写代码，只需要编译、运行和测试现有服务 `rating`。 +该模块涵盖了在本地机器上开发单个服务所涉及的不同方面。 +不过，您无需编写代码，只需要编译、运行和测试现有服务 `rating`。 -`ratings` 服务是用 [Node.js](https://nodejs.org/zh-cn/) 编写的一个可以单独运行的小型 Web 应用程序。 -它与其他 Web 应用程序执行类似的操作： +`ratings` 服务是用 [Node.js](https://nodejs.org/zh-cn/) +编写的一个可以单独运行的小型 Web 应用程序。它与其他 Web 应用程序执行类似的操作： - 监听它作为参数接受的端口。 -- 接受在 `/ratings/{productID}` 路径上的 `HTTP GET` 请求，并返回与客户端指定的 `productID` - 的值所匹配的产品的评级。 -- 接受在 `/ratings/{productID}` 路径上的 `HTTP POST` 请求，并更新与您指定的 `productID` - 的值所匹配的产品的评级。 +- 接受在 `/ratings/{productID}` 路径上的 `HTTP GET` 请求， + 并返回与客户端指定的 `productID` 的值所匹配的产品的评级。 +- 接受在 `/ratings/{productID}` 路径上的 `HTTP POST` 请求， + 并更新与您指定的 `productID` 的值所匹配的产品的评级。 请按照下列步骤下载应用程序的代码，安装其依赖项，然后在本地运行它： 1. 将[服务代码]({{< github_blob >}}/samples/bookinfo/src/ratings/ratings.js)和 - [其 package 文件]({{< github_blob >}}/samples/bookinfo/src/ratings/package.json) - 下载到一个单独的目录中： + [其 package 文件]({{< github_blob >}}/samples/bookinfo/src/ratings/package.json) + 下载到一个单独的目录中： {{< text bash >}} $ mkdir ratings @@ -42,22 +46,23 @@ test: no {{< /text >}} 1. 浏览服务的代码，并注意代码中以下元素： - - Web 服务器的特征: + - Web 服务器的特征： - 监听一个端口 - 处理请求和响应 - - 与 HTTP 相关的方面: + - 与 HTTP 相关的方面： - 请求头 - 路径 - 状态码 {{< tip >}} - 在 Node.js 中，Web 服务器的功能嵌入在应用程序的代码中。一个 Node.js Web 应用程序作为一个独立进程运行。 + 在 Node.js 中，Web 服务器的功能嵌入在应用程序的代码中。 + 一个 Node.js Web 应用程序作为一个独立进程运行。 {{< /tip >}} -1. Node.js 应用程序是用 JavaScript 编写的，这意味着没有显式编译步骤。相反， - 它们使用 [just-in-time 即时编译](https://zh.wikipedia.org/wiki/%E5%8D%B3%E6%99%82%E7%B7%A8%E8%AD%AF)。 - 要构建 Node.js 应用程序，则意味着要安装其依赖库。 - 将 `rating` 服务的依赖库安装在存储服务代码和 package 文件的同一目录下： +1. Node.js 应用程序是用 JavaScript 编写的，这意味着没有显式编译步骤。 + 相反，它们使用 [just-in-time 即时编译](https://zh.wikipedia.org/wiki/%E5%8D%B3%E6%99%82%E7%B7%A8%E8%AD%AF)。 + 要构建 Node.js 应用程序，则意味着要安装其依赖库。 + 将 `rating` 服务的依赖库安装在存储服务代码和 package 文件的同一目录下： {{< text bash >}} $ npm install @@ -79,13 +84,15 @@ test: no {{< /text >}} {{< tip >}} -该 `ratings` 服务是一个 Web 应用程序，您可以像访问其他 Web 应用程序那样访问它。 -您可以使用浏览器或者像 +该 `ratings` 服务是一个 Web 应用程序， +您可以像访问其他 Web 应用程序那样访问它。您可以使用浏览器或者像 [`curl`](https://curl.haxx.se) 或 [`Wget`](https://www.gnu.org/software/wget/) -的命令行 Web 客户端。由于您在本地运行了 `rating` 服务，因此您也可以通过 `localhost` 主机名访问它。 +的命令行 Web 客户端。由于您在本地运行了 `rating` 服务， +因此您也可以通过 `localhost` 主机名访问它。 {{< /tip >}} -1. 在浏览器中打开 [http://localhost:9080/ratings/7](http://localhost:9080/ratings/7) 或者使用 `curl` 命令来访问 `ratings`： +1. 在浏览器中打开 [http://localhost:9080/ratings/7](http://localhost:9080/ratings/7) + 或者使用 `curl` 命令来访问 `ratings`： {{< text bash >}} $ curl localhost:9080/ratings/7 @@ -108,6 +115,6 @@ test: no 1. 在运行服务的终端上使用 `Ctrl-C` 停止该服务。 -恭喜, 您现在可以在本地计算机上构建、测试和运行服务了！ +恭喜，您现在可以在本地计算机上构建、测试和运行服务了！ 您已经做好了[如何打包服务](/zh/docs/examples/microservices-istio/package-service)到容器的准备了。