Merge pull request #1415 from merico-dev/docs-ht

daniel-hutao · web-flow · commit 4efa862a432b · 2023-01-04T11:41:53.000+08:00
Docs: update installation related documents
diff --git a/docs/install.md b/docs/install.md
@@ -1,10 +1,11 @@
 # Installation
 
-## 0 Currently supported operating systems and chip architectures
+!!! note
+    Currently supported operating systems and chip architectures:
 
-* Darwin/arm64
-* Darwin/amd64
-* Linux/amd64
+    1. Darwin/arm64
+    2. Darwin/amd64
+    3. Linux/amd64
 
 ## 1 Install dtm binary with script
 
@@ -16,26 +17,21 @@ sh -c "$(curl -fsSL https://download.devstream.io/download.sh)"
 
 This will download the corresponding `dtm` binary to your working directory according to your OS and chip architecture, and grant the binary execution permission.
 
-> Optional: you can then move `dtm` to a place which is in your PATH. For example: `mv dtm /usr/local/bin/`.
+!!! note "Optional"
 
-## 2 Install dtm with [asdf](https://asdf-vm.com/)
+    Move `dtm` to a place which is in your PATH. For example: `mv dtm /usr/local/bin/`.
+
+## 2 Download manually from the GitHub Release page
+
+You could find the latest version of `dtm` on the [Release](https://github.com/devstream-io/devstream/releases/) page and click Download.
+
+If your browser isn't working properly, "curl" is also a good option:
 
 ```shell
-# Plugin
-asdf plugin add dtm
-# Show all installable versions
-asdf list-all dtm
-# Install specific version
-asdf install dtm latest
-# Set a version globally (on your ~/.tool-versions file)
-asdf global dtm latest
-# Now dtm commands are available
-dtm help
+# Version v0.10.3, OS type linux and CPU arch amd64 need to be modified as needed
+$ curl -o dtm https://download.devstream.io/v0.10.3/dtm-linux-amd64
 ```
 
-## 3 Download manually from the GitHub Release page
-
-You could find the latest version of `dtm` on the [Release](https://github.com/devstream-io/devstream/releases/) page and click Download.
 Note that there are multiple versions of `dtm` available, so you will need to choose the correct version for your operating system and chip architecture. Once downloaded locally, you can choose to rename it, move it to the directory containing `$PATH` and give it executable permissions, for example, on Linux you can do this by running the following command.
 
 ```shell
@@ -47,5 +43,20 @@ Then you can verify that the permissions and version of dtm are correct with the
 
 ```shell
 $ dtm version
-0.10.0
+0.10.3
+```
+
+## 3 Install dtm with [asdf](https://asdf-vm.com/)
+
+```shell
+# Plugin
+asdf plugin add dtm
+# Show all installable versions
+asdf list-all dtm
+# Install specific version
+asdf install dtm latest
+# Set a version globally (on your ~/.tool-versions file)
+asdf global dtm latest
+# Now dtm commands are available
+dtm help
 ```
diff --git a/docs/install.zh.md b/docs/install.zh.md
@@ -1,10 +1,11 @@
 # 安装
 
-## 0 当前支持的操作系统与芯片架构
+!!! note "提示"
+    当前 dtm 发行版支持如下操作系统与 CPU 架构组合：
 
-*  Darwin/arm64
-*  Darwin/amd64
-*  Linux/amd64
+    1. Darwin/arm64
+    2. Darwin/amd64
+    3. Linux/amd64
 
 ## 1 用脚本安装
 
@@ -16,26 +17,21 @@ sh -c "$(curl -fsSL https://download.devstream.io/download.sh)"
 
 这个命令会根据你的操作系统和芯片架构下载对应的 `dtm` 二进制文件到你的工作目录中，并赋予二进制文件执行权限。
 
-> 可选：建议你将 dtm 移动到包含于 PATH 的目录下，比如 `mv dtm /usr/local/bin/`。
+!!! note "可选"
 
-## 2 用 [asdf](https://asdf-vm.com/) 安装
+    将 dtm 移动到包含于 PATH 的目录下，比如 `mv dtm /usr/local/bin/`。
+
+## 2 从 GitHub Release 页面手动下载安装
+
+在 [Release](https://github.com/devstream-io/devstream/releases/) 页面找到当前最新版本 `dtm`，然后点击下载。
+
+如果你不方便使用浏览器下载，也可以选择使用 curl：
 
 ```shell
-# 安装 dtm 插件
-asdf plugin add dtm
-# 列出所有可用版本
-asdf list-all dtm
-# 安装特定版本
-asdf install dtm latest
-# 设置全局版本 (在 ~/.tool-versions 文件中)
-asdf global dtm latest
-# 现在你就能使用 dtm 了
-dtm help
+# 版本号 v0.10.3，系统类型 linux 和 CPU 架构 amd64 根据需要灵活修改
+$ curl -o dtm https://download.devstream.io/v0.10.3/dtm-linux-amd64
 ```
 
-## 3 从 GitHub Release 页面手动下载
-
-在 [Release](https://github.com/devstream-io/devstream/releases/) 页面找到当前最新版本 `dtm`，然后点击下载。
 需要注意的是当前 `dtm` 提供了多个版本，你需要根据操作系统和芯片架构选择自己需要的正确版本。下载到本地后，你可以选择将其重命名，移入包含在"$PATH"的目录里并赋予其可执行权限，比如在 Linux 上你可以执行如下命令完成这些操作：
 
 ```shell
@@ -47,5 +43,20 @@ chmod +x dtm
 
 ```shell
 $ dtm version
-0.10.0
+0.10.3
+```
+
+## 3 用 [asdf](https://asdf-vm.com/) 安装
+
+```shell
+# 安装 dtm 插件
+asdf plugin add dtm
+# 列出所有可用版本
+asdf list-all dtm
+# 安装特定版本
+asdf install dtm latest
+# 设置全局版本 (在 ~/.tool-versions 文件中)
+asdf global dtm latest
+# 现在你就能使用 dtm 了
+dtm help
 ```
diff --git a/docs/use-cases/gitlab-jenkins-harbor/2-gitlab-jenkins-harbor.zh.md b/docs/use-cases/gitlab-jenkins-harbor/2-gitlab-jenkins-harbor.zh.md
@@ -8,7 +8,11 @@
 
     本文基于 kubeadm 部署的单节点 k8s 环境，不适用于 minikube 和 kind 等 docker-in-docker 类型的 k8s 集群。
 
-##  2、准备配置文件
+## 2、安装 dtm
+
+你可以参考[这个文档](../../install.zh.md)完成 dtm 的下载与安装。
+
+## 3、准备配置文件
 
 DevStream 可以简单地以 **local** 作为[状态](../../core-concepts/state.zh.md) Backend，也就是将状态保存到本地文件。如果你在本地测试，可以选择使用这种方式；
 而企业 On premise 环境部署可能需要使用 **k8s** Backend 将状态通过 `kube-apiserver` 存入 etcd，两种方式配置分别如下：
@@ -144,7 +148,7 @@ tools:
             size: 1Gi
 ```
 
-## 3、初始化
+## 4、初始化
 
 你可以将上面这个配置文件（config-tools.yaml）放到服务器上任意一个合适的目录，比如 `~/devstream-test/`，然后在该目录下执行：
 
@@ -154,7 +158,7 @@ dtm init -f config-tools.yaml
 
 这个命令会帮助你下载所有需要的 DevStream 插件。
 
-## 4、开始部署
+## 5、开始部署
 
 接着你就可以执行 apply 命令了：
 
@@ -214,11 +218,11 @@ Stdout: 34cdd2a834a1c21be192064eacf1e29536ff45c52562956b97d6d376a5dae11b
 
 从日志里你可以看到，这时候 GitLab、Jenkins 和 Harbor 就已经部署完成了。
 
-## 5、验证部署结果
+## 6、验证部署结果
 
 你可以通过如下方式验证 GitLab + Jenkins + Harbor 三个工具的部署结果。
 
-### 5.1、DNS 配置
+### 6.1、DNS 配置
 
 前面你给 GitLab + Jenkins + Harbor 三个工具的配置文件里都设置了域名，然后你可以直接将这些域名与 IP 的映射关系配置到 DNS 服务器里。
 
@@ -250,7 +254,7 @@ echo "44.33.22.11 jenkins.example.com" >> /etc/hosts
 exit
 ```
 
-### 5.2、访问 GitLab
+### 6.2、访问 GitLab
 
 你可以在自己的 PC 里配置 `44.33.22.11 gitlab.example.com` 静态域名解析记录，然后在浏览器里通过 `http://gitlab.example.com:30080` 访问到 GitLab：
 
@@ -268,7 +272,7 @@ gitlab-rake "gitlab:password:reset" # 执行后按照提示输入用户名 root
 
 拿到 root 密码后，你可以尝试用 root/YOUR_PASSWORD 来登录 GitLab。
 
-### 5.3、访问 Jenkins
+### 6.3、访问 Jenkins
 
 前面你可能已经通过 `curl http://jenkins.example.com` 在主机内验证了 Jenkins 的网络连通性，想要远程通过域名访问 Jenkins，你还需要在自己的 PC 里配置 `44.33.22.11 jenkins.example.com` 静态域名解析记录。
 
@@ -286,7 +290,7 @@ Jenkins 的 admin 用户初始登录密码是 `changeme`，如果你仔细看了
   <figcaption>Jenkins dashboard</figcaption>
 </figure>
 
-### 5.4、访问 Harbor
+### 6.4、访问 Harbor
 
 前面你可能也已经通过 `curl http://harbor.example.com` 在主机内验证了 Harbor 的网络连通性，同样你可以通过 `docker login harbor.example.com:80` 命令来尝试登录 Harbor。
 
@@ -306,7 +310,7 @@ Harbor 的 admin 用户初始登录密码是 `Harbor12345`，你可以尝试用
   <figcaption>Harbor dashboard</figcaption>
 </figure>
 
-## 6、环境清理
+## 7、环境清理
 
 你可以通过如下命令清理环境：
 
diff --git a/docs/use-cases/gitlab-jenkins-harbor/3-gitlab-jenkins-harbor-air-gapped.zh.md b/docs/use-cases/gitlab-jenkins-harbor/3-gitlab-jenkins-harbor-air-gapped.zh.md
@@ -17,39 +17,9 @@
 
 ### 1.1、下载 dtm
 
-如果你的 PC 和服务器操作系统以及 CPU 架构一致，比如都是 Linux/amd64，那么你可以直接在 PC 上运行如下命令完成 dtm 的下载：
+你可以参考[这个文档](../../install.zh.md)下载 dtm。
 
-```shell
-sh -c "$(curl -fsSL https://download.devstream.io/download.sh)"
-```
-
-如果使用的 shell 不是 bash，可能会执行上述命令失败，这时候你也可以选择直接用 curl 下载 dtm。这时候你需要先访问 DevStream 的 [Release](https://github.com/devstream-io/devstream/releases/) 页面找到当前最新版本 `dtm`，然后找到和你的服务器匹配的版本。当前 `dtm` 提供了多个版本，分别是：
-
-1. Darwin/arm64
-2. Darwin/amd64
-3. Linux/amd64
-
-这时候，相信你可以很容易拼接出类似下面这个命令：
-
-```shell
-curl -o dtm https://download.devstream.io/v0.10.3/dtm-linux-amd64
-```
-
-注意：这里的版本、系统类型、CPU 架构等信息需要灵活调整。
-
-等 dtm 下载到你的 PC 后，你需要通过内网将其传输到某一台内部服务器上，移入包含在"$PATH"的目录里并赋予其可执行权限，比如在 Linux 上你可以执行如下命令完成这些操作：
-
-```shell
-chmod +x dtm
-mv dtm /usr/local/bin/
-```
-
-然后在服务器上你可以通过如下命令验证 dtm 的权限以及版本等是否正确：
-
-```shell
-$ dtm version
-0.10.3
-```
+唯一需要注意的是，下载完之后，请记得将 dtm 传输到你需要使用它的机器上。
 
 ### 1.2、下载 plugins
 
diff --git a/docs/use-cases/gitlab-jenkins-harbor/5-java-springboot-pipeline-with-gitlab-jenkins-harbor.zh.md b/docs/use-cases/gitlab-jenkins-harbor/5-java-springboot-pipeline-with-gitlab-jenkins-harbor.zh.md
@@ -19,7 +19,11 @@
 2. DevStream 根据你给定配置，使用 CI 模板创建 CI 流程，过程中会涉及到 CI 工具的配置（比如调用 Jenkins API 完成一些 Jenkins 插件的安装等）；
 3. 最终 DevStream 完成全部配置后，如果你提交代码到 DevStream 为你创建的代码库中，GitLab 便会出发 Jenkins 执行相应的 CI 流程，Jenkins 上的流水线运行结果也会实时回显到 GitLab 上，并且这个过程中构建出来的容器镜像会被自动推送到 Harbor 上。
 
-## 2、准备配置文件
+## 2、安装 dtm
+
+你可以参考[这个文档](../../install.zh.md)完成 dtm 的下载与安装。
+
+## 3、准备配置文件
 
 DevStream 可以简单地以 **local** 作为[状态](../../core-concepts/state.zh.md) Backend，也就是将状态保存到本地文件。如果你在本地测试，可以选择使用这种方式；
 而企业 On premise 环境部署可能需要使用 **k8s** Backend 将状态通过 `kube-apiserver` 存入 etcd，两种方式配置分别如下：
@@ -109,11 +113,11 @@ pipelineTemplates:
 
 你可以将这个配置文件放到服务器上的某一个路径内，比如 `~/devstream-test/config-apps.yaml`。
 
-## 3、让配置生效
+## 4、让配置生效
 
 你还需要几个简单的步骤来让上述配置生效。
 
-### 3.1、准备 GitLab Token
+### 4.1、准备 GitLab Token
 
 你可以参考下图方式在 GitLab 上创建一个 token，这个 token 将给 DevStream 必要的权限用来在 GitLab 上创建项目脚手架等：
 
@@ -142,7 +146,7 @@ export JENKINS_PASSWORD=changeme
 
 你可以将这个配置文件放到服务器上同一个目录，比如 `~/devstream-test/`，然后在该目录下执行：
 
-### 3.2、开始执行
+### 4.2、开始执行
 
 首先你需要执行初始化命令：
 
@@ -201,7 +205,7 @@ root@dtm-realk8sdev:~# ./dtm apply -y -f config-apps.yaml
 2022-12-02 01:04:59 ✔ [SUCCESS]  Apply finished.
 ```
 
-## 4、查看执行结果
+## 5、查看执行结果
 
 这时候你可以在 GitLab 上看到 dtm 为你准备的 Java Spring Boot 项目脚手架：
 
@@ -233,7 +237,7 @@ root@dtm-realk8sdev:~# ./dtm apply -y -f config-apps.yaml
   <figcaption>Image in Harbor</figcaption>
 </figure>
 
-## 5、环境清理
+## 6、环境清理
 
 你可以通过如下命令清理环境：
 
diff --git a/docs/use-cases/gitlab-jenkins-harbor/6-gitlab-jenkins-harbor-java-springboot.zh.md b/docs/use-cases/gitlab-jenkins-harbor/6-gitlab-jenkins-harbor-java-springboot.zh.md
@@ -40,7 +40,11 @@
 
     这个图中的 GitLab 和 GitHub 可以随意互换，它们只是被当做保存项目脚手架模板库存放地址和脚手架模板渲染后的最终项目存放地址，DevStream 对 GitHub 和 GitLab 都支持。换言之，如果你将模板保存到 GitLab，最终项目也托管在 GitLab，便可以完全不依赖 GitHub 而使用 DevStream。
 
-### 1.2、相关插件概览
+### 1.2 安装 dtm
+
+你可以参考[这个文档](../../install.zh.md)完成 dtm 的下载与安装。
+
+### 1.3、相关插件概览
 
 当前工具链主要涉及如下 DevStream 插件：
 
@@ -56,7 +60,7 @@
     1. 上述插件不是必选集，你可以根据实际情况灵活调整。比如你本地已经有 GitLab 环境了，那么你可以果断忽略 `gitlab-ce-docker` 插件。
     2. 你不再需要关心 repo-scaffolding 和 jenkins-pipeline 这类“非工具部署”相关插件的配置，你只要定义好自己的“app”，剩下的工作 DevStream 会帮你完成。至于 app 如何定义，下文会详细介绍。
 
-### 1.3、部署流程介绍
+### 1.4、部署流程介绍
 
 你将分2步来完成这条工具链的搭建过程。
 
diff --git a/docs/use-cases/gitlab-jenkins-harbor/7-java-springboot-pipeline-with-gitlab-jenkins-harbor-air-gapped.zh.md b/docs/use-cases/gitlab-jenkins-harbor/7-java-springboot-pipeline-with-gitlab-jenkins-harbor-air-gapped.zh.md
@@ -19,39 +19,9 @@
 
 ### 1.1、下载 dtm
 
-如果你的 PC 和服务器操作系统以及 CPU 架构一致，比如都是 Linux/amd64，那么你可以直接在 PC 上运行如下命令完成 dtm 的下载：
+你可以参考[这个文档](../../install.zh.md)下载 dtm。
 
-```shell
-sh -c "$(curl -fsSL https://download.devstream.io/download.sh)"
-```
-
-如果使用的 shell 不是 bash，可能会执行上述命令失败，这时候你也可以选择直接用 curl 下载 dtm。这时候你需要先访问 DevStream 的 [Release](https://github.com/devstream-io/devstream/releases/) 页面找到当前最新版本 `dtm`，然后找到和你的服务器匹配的版本。当前 `dtm` 提供了多个版本，分别是：
-
-1. Darwin/arm64
-2. Darwin/amd64
-3. Linux/amd64
-
-这时候，相信你可以很容易拼接出类似下面这个命令：
-
-```shell
-curl -o dtm https://download.devstream.io/v0.10.2/dtm-linux-amd64
-```
-
-注意：这里的版本、系统类型、CPU 架构等信息需要灵活调整。
-
-等 dtm 下载到你的 PC 后，你需要通过内网将其传输到某一台内部服务器上，移入包含在"$PATH"的目录里并赋予其可执行权限，比如在 Linux 上你可以执行如下命令完成这些操作：
-
-```shell
-chmod +x dtm
-mv dtm /usr/local/bin/
-```
-
-然后在服务器上你可以通过如下命令验证 dtm 的权限以及版本等是否正确：
-
-```shell
-$ dtm version
-0.10.2
-```
+唯一需要注意的是，下载完之后，请记得将 dtm 传输到你需要使用它的机器上。
 
 ### 1.2、下载 plugins
 
diff --git a/docs/use-cases/gitops-python-flask/4-gitlab-dtm-apps.zh.md b/docs/use-cases/gitops-python-flask/4-gitlab-dtm-apps.zh.md
@@ -310,6 +310,3 @@ cd ../
 rm -rf test/
 rm -rf ~/.devstream/
 ```
-
-
-
