Merge pull request #1343 from aFlyBird0/docs-cn

docs: update core-concepts

Author: daniel-hutao

docs/core-concepts/apps.md

@@ -0,0 +1 @@
+# Apps

docs/core-concepts/apps.zh.md

@@ -1,23 +1,109 @@
-# 应用
+# 应用(Apps)
 
-## 概念
+## 1 概念
 
-应用在 devstream 中表示对一个服务的生命周期配置，包括对服务的项目脚手架，CI 流程以及 CD 流程的配置，在 devstream 中使用应用可以使用少数几行配置就构建出服务的整条 CI/CD 流水线配置。
+应用在 DevStream 中表示对一个服务的生命周期配置，包括对服务的项目脚手架，CI 流程以及 CD 流程的配置，在 devstream 中使用应用可以使用少数几行配置就构建出服务的整条 CI/CD 流水线配置。
 
-## 应用配置
+### 1.1 应用(Apps)
 
-应用的示例配置如下：
+有时候，你需要为一个应用/微服务定义多个 工具。例如，对于一个 web 应用程序，你可能需要指定以下工具：
+
+- 仓库脚手架
+- 持续集成
+- 持续部署
+
+如果你有多个应用需要管理，你需要在配置中创建多个 工具，这可能会很繁琐，而且配置文件难以阅读。
+
+为了更容易地管理多个应用/微服务，DevStream 提供了另一层抽象，称为 应用。你可以在一个应用中定义所有内容（例如，上面提到的仓库脚手架、持续集成、持续部署等），只需要几行配置，就可以使配置文件更容易阅读和管理。
+
+在底层，DevStream 仍然会将你的 应用 配置转换为 工具 的定义，但你不需要关心它。
+
+## 1.2 流水线模板（pipelineTemplates）
+
+一个 DevStream 应用 可以引用一个或多个 流水线模板，这些模板主要是 CI/CD 定义，这样 应用 的定义可以更短，以在多个微服务之间共享公共的 CI/CD 流水线。
+
+## 2 配置方式
+
+### 2.1 应用
+
+应用在配置中由 `apps` 来定义，它是一个数组，每个元素的字段如下：
+
+- name: 应用的名称，必须是唯一的
+- spec: 配置应用特定的信息
+- repo: 代码仓库信息
+- repoTemplate: 可选。结构和 repo 一致。若非空，DevStream 将使用项目脚手架来创建仓库。
+- ci: 可选，一个 CI 流水线的数组，每个元素包含以下字段：
+    - type: 类型。值为 `template` 或某个插件的名称。
+    - templateName: 可选。当 type 为 `template` 时，指定使用的模板名称。
+    - vars: 可选。传入模板的变量，仅当 type 为 `template` 时有效。
+    - options: 可选。
+        - 当 type 是某个插件名时，就是该插件的 Options
+        - 当 type 为 `template` 时，覆盖模板中的 Options。你需要写清想要覆盖的选项的完整路径，例如 `options.docker.registry.type`。
+- cd: 与 `ci` 类似，是 CD 流水线列表。dtm 会先执行 ci 流水线，再执行 cd 流水线。
+
+### 2.2 流水线模板
+
+流水线模板在配置中由 `pipelineTemplates` 来定义，它是一个数组，每个元素的字段如下：
+
+- name: 流水线模板的名称，必须是唯一的
+- type: 对应插件的名称
+- options: 插件的 Options （可能和原始的插件 Options 不同）
+
+### 2.3 局部变量
+
+DevStream 已经有了全局变量，所有的 工具 和 应用 都可以直接引用。
+
+但有时，我们想多次引用某个 DevOps 工具，但他们只有一些细微的差别。例如，除了项目名称不同，其他的都相同。
+
+在这种情况下，我们可以定义一个流水线模板，在其中定义一个局部变量，然后在 应用 引用该流水线模板时，传入不同的值。
+
+```yaml hl_lines="13 15 23 30" title="流水线模板的使用与局部变量"
+apps:
+- name: my-app
+  spec:
+    language: java
+    framework: springboot
+    repo: 
+      url: https://github.com/testUser/testApp.git
+      branch: main
+    ci:
+    - type: github-actions # 不定义 pipelineTemplates，直接使用插件
+    cd:
+    - type: template # 使用流水线模板
+      templateName: my-cd-template # 对应 pipelineTemplates 中的 name
+      vars:
+        appName: my-app # 传入模板的变量
+
+pipelineTemplates:
+cd:
+- name: my-cd-template
+  type: argocdapp
+  options:
+    app:
+      name: [[ appName ]] # 定义一个局部变量，在引用使用模板时传入
+      namespace: argocd # argocd 的命名空间
+    destination:
+      server: https://kubernetes.default.svc # 部署的 kubernetes 服务地址
+      namespace: default # 应用要部署的命名空间
+    source:
+      valuefile: values.yaml # 项目中的 helm 变量文件名
+      path: charts/[[ appName ]] # 项目中的 helm 配置路径
+```
+
+## 3 完整配置示例
+
+应用 的真实示例配置如下：
 
 ```yaml
 apps:
-- name: testApp #应用名称
+- name: testApp # 应用名称
   spec: # 该配置项用于配置应用特定的信息
     language: java #应用所使用的编程语言
     framework: springboot #应用所使用的编程框架
   repo: # 该配置项用于应用的代码仓库信息
     url: https://github.com/testUser/testApp.git
     branch: main
-  repoTemplate: # 该配置用于创建应用的脚手架
+  repoTemplate: # 可选，用于创建应用的脚手架。不为空时，会使用该脚手架创建应用的代码仓库
     url: https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git
     vars:
       imageRepoOwner: repoOwner # 用于渲染脚手架模版的变量
@@ -39,45 +125,49 @@ apps:
   - type: github-actions
     options:
       imageRepo:
-        owner: repoOwner
+        owner: repoOwner # 覆盖 插件/模板 原有的 Options，YAML 路径要写完全
   cd: # 配置应用的 cd，如果为使用 argocdapp 运行应用的 cd 流程
   - type: argocdapp
 ```
 
-使用该配置就会在 `gitlab` 仓库中创建两个应用，项目的脚手架均为 devstream 官方提供的 [springboot](https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git) 项目。应用 `testApp` 会在每次代码提交后使用 `github-actions` 运行测试。应用 `testApp2` 会在每次代码提交后使用 `github-actions` 运行测试并构建镜像推送到 `repoOwner` 的镜像仓库中，最后使用 argocd 将应用部署到集群中。
+使用该配置就会在 `gitlab` 仓库中创建两个应用，项目的脚手架均为 DevStream 官方提供的 [SpringBoot](https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git) 项目。应用 `testApp` 会在每次代码提交后使用 `github-actions` 运行测试。应用 `testApp2` 会在每次代码提交后使用 `github-actions` 运行测试并构建镜像推送到 `repoOwner` 的镜像仓库中，最后使用 Argo CD 将应用部署到集群中。
 
 ### repo/repoTemplate 配置
 
-应用配置中的 `repo` 和 `repoTemplate` 均表示一个代码仓库，支持以下两种配置代码仓库的方式：
+应用配置中的 `repo` 和 `repoTemplate` 均表示一个代码仓库，支持通过 url 或 详细字段来配置：
 
-#### 使用 url 来配置代码仓库：
+!!! note "两种配置代码仓库的方式"
 
-```yaml
-  repo:
-    url: [email protected]:root/myapps.git # url 表示仓库的地址，支持 git 地址和 http 地址
-    apiURL: https://gitlab.example.com # 非必填，如果使用 gitlab 而且 url 使用的是 git 地址，则需要配置该字段用于表示 gitlab 的 api 请求地址
-    branch: "" #非必填，github 默认为 main 分支，gitlab 默认为 master 分支
-```
-
-该配置表示使用的仓库为 `gitlab`, 要使用 `[email protected]:root/myapps.git` 来克隆代码，devstream 会使用使用 `https://gitlab.example.com` 和 gitlab 进行交互，仓库的主分支为 `master` 分支。
-
-#### 使用仓库的详细字段来配置仓库：
-
-```yaml
-  repo:
-    org: "" # 非必填，仓库的拥有组织名称，如果使用 github 的组织则需要填写此字段
-    owner："test_user" # 如果仓库是非组织的，则需要填写该字段表示仓库拥有者
-    name: "" # 非必填，默认为应用名
-    baseURL:  https://gitlab.example.com # 非必填，如果使用 gitlab 则需要填写该字段表示 gitlab 的域名
-    branch: master #非必填，github 默认为 main 分支，gitlab 默认为 master 分支
-    type:  gitlab #必填，表示该仓库的类型，目前支持 gitlab/github
-```
-
-该配置表示代码仓库使用的是 `gitlab` 且其地址为 `https://gitlab.example.com`，仓库名称为应用名，仓库的所有者为 `test_user`，主分支为 `master` 分支。
+    === "使用 url 来配置"
+    
+        ```yaml title=""
+          repo:
+            url: [email protected]:root/myapps.git # url 表示仓库的地址，支持 git 地址和 http 地址
+            apiURL: https://gitlab.example.com # 非必填，如果使用 gitlab 而且 url 使用的是 git 地址，则需要配置该字段用于表示 gitlab 的 api 请求地址
+            branch: "" # 非必填，github 默认为 main 分支，gitlab 默认为 master 分支
+        ```
+    
+        该配置表示使用的仓库为 `gitlab`, 要使用 `[email protected]:root/myapps.git` 来克隆代码，devstream 会使用使用 `https://gitlab.example.com` 和 gitlab 进行交互，仓库的主分支为 `master` 分支。
+    
+    === "使用仓库的详细字段来配置"
+    
+        ```yaml title=""
+          repo:
+            org: "" # 非必填，仓库的拥有组织名称，如果使用 github 的组织则需要填写此字段
+            owner："test_user" # 如果仓库是非组织的，则需要填写该字段表示仓库拥有者
+            name: "" # 非必填，默认为应用名
+            baseURL:  https://gitlab.example.com # 非必填，如果使用 gitlab 则需要填写该字段表示 gitlab 的域名
+            branch: master #非必填，github 默认为 main 分支，gitlab 默认为 master 分支
+            type:  gitlab #必填，表示该仓库的类型，目前支持 gitlab/github
+        ```
+    
+        该配置表示代码仓库使用的是 `gitlab` 且其地址为 `https://gitlab.example.com`，仓库名称为应用名，仓库的所有者为 `test_user`，主分支为 `master` 分支。
 
 ### ci 配置
 
-应用配置中的 `ci` 目前支持 `github-actions`/`gitlab-ci`/`jenkins-pipeline`/`template` 4 种类型，前 3 种类型分别对应了 `github` 中的 actions 流水线，`gitlab` 中 ci 流水线和 `jenkins` 中的 pipeline，它们的具体配置如下：
+应用配置中的 `ci` 目前支持 `github-actions`/`gitlab-ci`/`jenkins-pipeline`/`template` 4 种类型。
+
+其中 `template` 类型表示使用 流水线模板 来运行流水线，前 3 种类型分别对应了 `github` 中的 actions 流水线，`gitlab` 中 ci 流水线和 `jenkins` 中的 pipeline，它们的具体配置如下：
 
 ```yaml
   ci:
@@ -132,7 +222,7 @@ apps:
   - type: template # 表示该 ci 流程使用模版
     templateName: ci-pipeline # ci 使用的模版名称
     vars:
-      dingdingAccessToken: tokenForProject2 #用于渲染 ci 模版的变量
+      dingdingAccessToken: tokenForProject2 # 设置传入模版 "ci-pipeline" 的变量
       dingdingSecretValue: secretValProject2
 
 pipelineTemplates: # 即配置的 ci/cd 模版
@@ -149,7 +239,7 @@ pipelineTemplates: # 即配置的 ci/cd 模版
       name: dingTalk
       webhook: https://oapi.dingtalk.com/robot/send?access_token=[[ dingdingAccessToken ]] # 用于被 app 渲染的模版，这样就可以实现不同应用使用同一个模版发送通知到不同的钉钉群
       securityType: SECRET
-      securityValue: [[ dingdingSecretValue ]]
+      securityValue: [[ dingdingSecretValue ]] # 局部变量，应用 在引用此模板时通过 vars 来传入
     sonarqube:
         url: http://sonar.example.com
         token: sonar_token

docs/core-concepts/config.zh.md

@@ -1,113 +1,65 @@
-# DevStream配置
+# 配置(Config)
 
-TODO: 需要跟英文文档同步。请暂且阅读英文文档。
+DevStream使用 YAML 文件来声明 DevOps 工具链的配置。
 
-DevStream使用YAML文件来描述你的DevOps工具链配置。
+## 配置内容
 
-## 主配置文件
+正如概述中所提到的，配置包含了以下几个部分：
 
-默认情况下，`dtm` 会使用当前目录下的`config.yaml`来作为主配置。
+- `config`
+- `vars`
+- `tools`
+- `apps`
+- `pipelineTemplates`
 
-主配置包含三个部分：
+其中，`config` 必选，`tools` 和 `apps` 至少有一个不为空，其余部分可选。
 
-- `state`: 指定DevStream状态存储位置
+## 组织方式
 
-### 主配置文件示例
+DevStream 支持两种组织配置的方式：
 
-`config.yaml` 的结构通常如下：
+- 单文件：你可以把这些部分写到一个 YAML 文件中
+- 目录：也可以把它们分开放到同一个文件夹下的多个 YAML 文件中，只要这些文件的名字以 `.yaml` 或 `.yml` 结尾，且内容拼接后包含了 DevStream 所需的各个部分即可。
 
-```yaml
-varFile: variables.yaml
-toolFile: tools.yaml
-state:
-  backend: local
-  options:
-    stateFile: devstream.state
-```
+然后在执行 `init` 等命令时，加上 `-f` 或 `--config-file` 参数指定配置文件/目录的路径。
 
-### varFile
+如：
 
-变量文件是一个用`key: value`格式来定义变量的YAML文件。
+- 单文件：`dtm init -f config.yaml`
+- 目录：`dtm init -f dirname`
 
-_At the moment, nested/composite values (for example, the value is a list/dictionary) are not supported yet._
+## 主配置
 
-`variables.yaml` 的结构通常如下:
-
-```yaml
-githubUsername: daniel-hutao
-repoName: dtm-test-go
-defaultBranch: main
-dockerhubUsername: exploitht
-```
+指 DevStream 本身的配置，即 `config` 部分，比如状态存储的方式等。详见 [这里](./state.zh.md)
 
-### toolFile
+## 变量语法
 
-插件文件是一个包含多种插件的Yaml文件。
+DevStream 提供了变量语法。使用 `vars` 用来定义变量的值，而后可以在 `tools`、`apps`、`pipelineTemplates` 中使用，语法是 `[[ varName ]]`。
 
-- 插件文件只包含一个`tools`
-- `tools`是一个定义多个插件的列表
-- 列表中的每个对象都定义了一个由DevStream插件管理的工具
-    - `name`: 是一个不带下划线的字符串，用来定义插件的名称
-    - `instanceID`: 插件id
-    - 你可以在一个插件文件中重复定义`name`，也可以在一个插件文件中重复定义`instanceID`，但是`name + instanceID`组合在一个插件文件中必须是唯一的
-- 每个插件都有一个可选字段，即“选项”，它又是一个包含该特定插件参数的字典。关于插件的参数，请参见本文档的“插件”部分
-- 每个插件都有一个可选字段，即“dependsOn”。继续阅读有关依赖项的详细信息。
-
-`tools.yaml` 的结构通常如下:
+示例：
 
 ```yaml
+vars:
+  githubUsername: daniel-hutao # 定义变量
+  repoName: dtm-test-go
+  defaultBranch: main
+
 tools:
 - name: repo-scaffolding
-  instanceID: golang-github
+  instanceID: default
   options:
     destinationRepo:
-      owner: [[ githubUsername ]]
+      owner: [[ githubUsername ]] # 使用变量
       name: [[ repoName ]]
       branch: [[ defaultBranch ]]
       scmType: github
-    vars:
-      ImageRepo: "[[ dockerhubUsername ]]/[[ repoName ]]"
-    sourceRepo:
-      org: devstream-io
-      name: dtm-scaffolding-golang
-      scmType: github
-- name: jira-github-integ
-  instanceID: default
-  dependsOn: [ "repo-scaffolding.golang-github" ]
-  options:
-    owner: [[ githubUsername ]]
-    repo: [[ repoName ]]
-    jiraBaseUrl: https://xxx.atlassian.net
-    jiraUserEmail: [email protected]
-    jiraProjectKey: zzz
-    branch: main
-```
-
-### state
-
-`state`用来指定DevStream状态存储的位置，v0.5.0以前，DevStream仅支持状态记录存放在本地。
-
-从v0.6.0开始，我们将支持`local`和`s3`两种存储。
-
-更多状态存储细节请参见[DevStream状态存储](./state.zh.md)
-
-## 默认值
-
-默认，`dtm` 使用 `config.yaml` 来作为主配置文件
-
-### 指定主配置文件
-
-你可以通过`dtm -f` or `dtm --config-file`来指定主配置文件。例如：
-
-```shell
-dtm apply -f path/to/your/config.yaml
-dtm apply --config-file path/to/your/config.yaml
+    # <后面略...>
 ```
 
-### varFile和toolFile默认没有值
+## 工具的配置
 
-对于`varFile`和`toolFile`, 默认没有任何值。
+`tools` 部分声明了工具链中的工具，详见 [这里](./tools.zh.md)
 
-如果主配置中没有指定`varFile`，`dtm`将不会使用任何var文件，即使当前目录下已经有一个名为`variables.yaml`的文件。
+## 应用与流水线模板的配置
 
-同样，如果主配置中没有指定`toolFile`，即使当前目录下有`tools.yaml`文件，`dtm`也会抛出错误。
+`apps` 部分声明了 应用 的配置，`pipelineTemplates` 声明了 流水线模板，详见 [这里](./apps.zh.md)