Add documentations for TiUP

TOC.md

@@ -80,7 +80,7 @@
   + [告警处理](/handle-alerts.md) @李宋高
   + [日常巡检](/daily-inspection.md) @王军
   + [TiCDC 任务管理](/ticdc/manage-ticdc.md) @沈泰宁
-  + [TiUP 常用运维操作](/tiup/manage-tiup-component.md) @王贤净
+  + [TiUP 常用运维操作](/maintain-tidb-using-tiup.md) @王贤净
   + [TiFlash 常用运维操作](/tiflash/maintain-tiflash.md) @雷宇
 + 故障诊断
   + 硬件故障 @周强
@@ -190,6 +190,19 @@
   + [Loader](/loader-overview.md) @王相
   + [Mydumper](/mydumper-overview.md) @余峻岑
   + [Syncer](/syncer-overview.md) @王相
+  + TiUP @龙恒
+    + [文档指南](/tiup/tiup-documentation-guide.md)
+    + [概览](/tiup/tiup-overview.md)
+    + [术语及核心概念](/tiup/tiup-terminology-and-concepts.md)
+    + [TiUP 组件管理](/tiup/tiup-component-management.md)
+    + [FAQ](/tiup/tiup-faq.md)
+    + [故障排查](/tiup/tiup-troubleshooting-guide.md)
+    + TiUP 组件文档
+      + [tiup-playground 运行本地测试集群](/tiup/tiup-playground.md)
+      + [tiup-cluster 部署运维生产集群](/tiup/tiup-cluster.md)
+      + [tiup-mirrors 定制离线镜像](/tiup/tiup-mirrors.md)
+      + [tiup-package 打包 TiUP 组件](/tiup/tiup-package.md)
+      + [tiup-bench 进行 TPCC/TPCH 压力测试](/tiup/tiup-bench.md)
 + 参考指南
   + 架构
     + [概述](/tidb-architecture.md) @黄东旭

tiup/tiup-cluster.md

@@ -63,6 +63,10 @@ tiup cluster deploy <cluster-name> <version> <topology.yaml> [flags]
 
 拓扑文件的编写可参考[示例](https://github.com/pingcap-incubator/tiup-cluster/blob/master/examples/topology.example.yaml)。以一个最简单的拓扑为例，将下列文件保存为 `/tmp/topology.yaml`：
 
+> **注意：**
+>
+> TiUP Cluster 组件的部署和扩容拓扑是使用 [yaml](https://yaml.org/spec/1.2/spec.html) 语法编写，所以需要注意缩进。
+
 ```yaml
 ---
 

tiup/manage-tiup-component.md → tiup/tiup-component-management.md

@@ -1,7 +1,7 @@
 ---
 title: 使用 TiUP 命令管理组件
 category: tools
-aliases: ['/docs-cn/dev/reference/tools/tiup/manage-component/']
+aliases: ['/docs-cn/dev/reference/tools/tiup/manage-component/','/docs-cn/dev/reference/tools/tiup/manage-tiup-component/']
 ---
 
 # 使用 TiUP 命令管理组件

tiup/tiup-documentation-guide.md

@@ -0,0 +1,28 @@
+---
+title: TiUP 文档指南
+category: tools
+---
+
+# TiUP 文档指南
+
+## TiUP 使用文档
+
+- [TiUP 概览](/tiup/tiup-overview.md)：对 TiUP 进行整体介绍，如何安装和基本的用法
+- [TiUP 术语](/tiup/tiup-terminology-and-concepts.md)：解释使用 TiUP 过程中可能用到的术语，了解 TiUP 的核心概念
+- [TiUP 组件管理](/tiup/tiup-component-management.md)：详细介绍 TiUP 所有命令，如何使用 TiUP 下载、更新、删除组件
+- [TiUP FAQ](/tiup/tiup-faq.md)：TiUP 使用过程中的常见问题，包含 TiUP 第三方组件的 FAQ
+- [TiUP 故障排查](/tiup/tiup-troubleshooting-guide.md)：如果在使用 TiUP 过程中遇到问题，可以参考故障排查文档的解决方案
+
+## TiUP 组件使用文档
+
+- [tiup-playground](/tiup/tiup-playground.md)：介绍如何使用 TiUP Playground 组件快速搭建本地测试集群
+- [tiup-cluster](/tiup/tiup-cluster.md)：介绍 TiUP 的生产集群部署、运维组件 TiUP Cluster 的用法和命令行参数解释
+- [tiup-mirrors](/tiup/tiup-mirrors.md)：介绍如何使用 TiUP Mirrors 组件自定义一个本地离线镜像
+- [tiup-package](/tiup/tiup-package.md)：介绍如何使用 TiUP Package 组件将自已开发的程序打包为一个符合 TiUP 组件规范的包
+- [tiup-bench](/tiup/tiup-bench.md)：介绍如何使用 TiUP Bench 组件进行常见的压力测试，如 TPCC/TPCH
+
+## TiUP 资源
+
+- [AskTUG TiUP](https://asktug.com/c/qa/set-up-deploy)：AskTUG.com 部署板块
+- [TiUP Issues](https://github.com/pingcap-incubator/tiup/issues)：TiUP Github Issues 列表
+- [TiUP Cluster Issues](https://github.com/pingcap-incubator/tiup-cluster/issues)：TiUP Cluster Github Issues 列表

tiup/tiup-faq.md

@@ -0,0 +1,40 @@
+---
+title: TiUP FAQ
+category: tools
+---
+
+# TiUP FAQ
+
+## TiUP 是否可以不使用官方镜像源？
+
+TiUP 支持通过环境变量 TIUP_MIRRORS 指定镜像源，镜像源的地址可以是一个本地目录或 HTTP 服务器地址。如果用户的环境不能访问网络，可以建立自己的离线镜像源使用 TiUP。
+
+## 如何将自己编写的组件放入 TiUP 镜像仓库？
+
+TiUP 暂时不支持外部开发的组件，但是 TiUP Team 已经制定了 TiUP 组件开发规范，同时正在开发 tiup-publish 组件，完成 tiup-publish 组件后，开发者可以通过 `tiup publish <comp> <version>` 将自己开发的组件发布到 TiUP 的官方镜像仓库。
+
+## tiup-playground 和 tiup-cluster 有什么区别？
+
+TiUP Playground 组件主要定位是快速上手和搭建单机的开发环境，支持 Linux/MacOS，要运行一个指定版本的 TiUP 集群更加简单。TiUP Cluster 组件主要是部署生成环境集群，通常是一个大规模的集群，还包含运维相关操作。
+
+## 怎么样编写 tiup-cluster 组件的拓扑文件？
+
+可以参考拓扑文件的 [样例](https://github.com/pingcap-incubator/tiup-cluster/tree/master/examples)，样例中包含了：
+
+1. 两地三中心
+2. 最小部署拓扑
+3. 完整拓扑文件
+
+可以根据自己的需求选择不同的模板，进行编辑。
+
+## 同一个主机是否可以部署多个实例？
+
+同一个主机可以使用 TiUP Cluster 部署多个实例，但是需要配置不同的端口和目录信息，否则可能导致目录以及端口冲突。
+
+## 是否可以检测同一个集群内的端口和目录冲突？
+
+同一个集群的端口和目录冲突会在部署和扩容的时候进行检测，如果有目录和端口冲突，本次部署或扩容会中断。
+
+## 是否可以检测不同集群的端口和目录冲突？
+
+如果不同集群是由同一个 TiUP 中控机部署的，会在部署和扩容时进行检测，如果属于不同的 TiUP 中控机，目前不支持检测。

tiup/tiup-overview.md

@@ -127,11 +127,3 @@ Use "tiup [command] --help" for more information about a command.
 > - 组件的可用版本列表也会持续增加，以 `tiup list <component> --refresh` 输出结果为准。
 
 命令和组件的区别在于，命令是 TiUP 自带的，用于进行包管理的操作。而组件是 TiUP 通过包管理操作安装的独立组件包。比如执行 `tiup list` 命令，TiUP 会直接运行自己内部的代码，而执行 `tiup playground` 命令则会先检查本地有没有叫做 playground 的组件包，若没有则先从镜像上下载过来，然后运行这个组件包。
-
-[使用 TiUP 管理组件](/tiup/manage-tiup-component.md)一节中介绍了所有的 TiUP 命令，组件的介绍则按照不同的组件分为以下几个章节:
-
-- [本地快速部署 TiDB 集群](/tiup/tiup-playground.md)：playground 组件
-- [部署运维 TiDB 线上集群](/tiup/tiup-cluster.md)：cluster 组件
-- [搭建私有镜像](/tiup/tiup-mirrors.md)：mirrors 组件
-- [打包组件](/tiup/package-tiup-component.md)：package 组件
-- [使用 TiUP 压测 TiDB](/tiup/tiup-bench.md)：bench 组件

tiup/package-tiup-component.md → tiup/tiup-package.md

@@ -1,10 +1,10 @@
 ---
-title: 打包组件
+title: 打包 TiUP 组件
 category: tools
-aliases: ['/docs-cn/dev/reference/tools/tiup/package-component/']
+aliases: ['/docs-cn/dev/reference/tools/tiup/package-component/','/docs-cn/dev/reference/tools/tiup/package-tiup-component/']
 ---
 
-# 打包组件
+# 打包 TiUP 组件
 
 当想要新增一个组件或者新增一个已有组件的版本时，需要用 tar 命令将相关文件打包然后传到镜像仓库中。用 tar 打包并不困难，麻烦在于需要更新仓库的元信息，因为要避免更新元信息的时候破坏已有组件的信息。
 

tiup/tiup-terminology-and-concepts.md

@@ -0,0 +1,31 @@
+---
+title: TiUP 术语及核心概念
+category: tools
+---
+
+# TiUP 术语及核心概念
+
+本文主要说明 TiUP 的重要术语和核心概念。
+
+## TiUP 组件
+
+TiUP 程序只包含少数几个命令，用来下载、更新、卸载组件。TiUP 通过各种组件来扩展其功能。**组件**是一个可以运行的程序或脚本，通过 `tiup <component>` 运行组件时，TiUP 会添加一组环境变量，并为该程序创建好对应的数据目录，然后运行该程序。
+
+通过运行 `tiup <component>` 命令，你可以运行支持的 TiUP 组件，其中运行的逻辑为：
+
+1. 如果用户通过 `tiup <component>[:version]` 运行指定某个组件的特定版本：
+    - 组件在本地未安装任何版本，则从镜像服务器下载最新稳定版本
+    - 组件在本地安装有其他版本，但是没有用户指定的版本，则从镜像服务器下载用户指定版本
+    - 如果本地已经安装指定版本，则设置环境变量来运行已经安装的版本
+2. 如果用户通过 `tiup <component>` 运行某个组件，且未指定任何版本：
+   - 组件在本地未安装任何版本，则从镜像服务器下载最新稳定版本
+   - 如果本地已经安装部分版本，则设置环境变量来运行已经安装的版本中的最新版本
+
+## TiUP 镜像仓库
+
+TiUP 的所有组件都从镜像仓库 (mirrors) 下载，镜像仓库包含各个组件的 TAR 包以及对应的元信息（版本、入口启动文件、校验和）。TiUP 默认使用 PingCAP 官方的镜像仓库。用户可以通过 TIUP_MIRRORS 环境变量自定义镜像仓库。
+
+镜像仓库可以是本地文件目录或在线 HTTP 服务器：
+
+1. `TIUP_MIRRORS=/path/to/local tiup list --refresh`
+2. `TIUP_MIRRORS=https://private-mirrors.example.com tiup list --refresh`

tiup/tiup-troubleshooting-guide.md

@@ -0,0 +1,55 @@
+---
+title: TiUP 故障排查
+category: tools
+---
+
+# TiUP 故障排查
+
+本文介绍 TiUP 使用过程中一些常见的故障及排查方式，如果本文不包含你目前遇到的问题，可以通过以下方式求助：
+
+1. [Github Issues](https://github.com/pingcap-incubator/tiup/issues) 新建一个 Issue。
+2. 在 [AskTUG](https://asktug.com/) 提交你的问题。
+
+## 1. TiUP 命令故障排查
+
+### 1.1 使用 `tiup list` 看不到最新的组件列表
+
+TiUP 并不会每次都从镜像服务器更新最新的组件列表，可以通过 `tiup list --refresh` 来强制刷新组件列表。
+
+### 1.2 使用 `tiup list <component>` 看不到一个组件的最新版本信息
+
+同 1.1 一样，组件的版本信息只会在本地无缓存的情况下从镜像服务器获取，可以通过 `tiup list <component> --refresh` 刷新组件列表。
+
+### 1.3 下载组件的过程中中断
+
+如果下载组件的过程中网络中断，可能是由于网络不稳定导致的，可以尝试重新下载，如果多次不能成功下载，请反馈到 [Github Issues](https://github.com/pingcap-incubator/tiup/issues)，可能是由于 CDN 服务器导致的。
+
+### 1.4 下载组件过程中出现 checksum 错误
+
+由于 CDN 会有短暂的缓存时间，导致新的 checksum 文件和组件包不匹配，建议过 5 分钟后重试，如果依然不匹配，请反馈到 [Github Issues](https://github.com/pingcap-incubator/tiup/issues)。
+
+## 2. TiUP Cluster 组件故障排查
+
+### 2.1 部署过程中提示 `unable to authenticate, attempted methods [none publickey]`
+
+由于部署时会向远程主机上传组件包，以及进行初始化，这个过程需要连接到远程主机，该错误是由于找不到连接到远程主机的 SSH 私钥导致的。请确认你是否通过 `tiup cluster deploy -i identity_file` 指定该私钥。
+
+1. 如果没有指定 `-i` 参数，可能是由于 TiUP 没有自动找到私钥路径，建议通过 `-i` 显式指定私钥路径。
+2. 如果指定了 `-i` 参数，可能是由于指定的私钥不能登录，可以通过手动执行 `ssh -i identity_file user@remote` 命令来验证。
+3. 如果是通过密码登录远程主机，请确保指定了 `-p` 参数，同时输入了正确的登录密码。
+
+### 2.3 使用 TiUP Cluster 升级中断
+
+为了避免用户误用，TiUP Cluster 不支持指定部分节点升级，所以升级失败之后，需要重新进行升级操作，包括升级过程中的幂等操作。
+
+升级操作会分为以下几步：
+
+1. 首先备份所有节点的老版本组件
+2. 分发新的组件到远程
+3. 滚动重启所有组件
+
+如果升级操作在滚动重启时中断，可以不用重复进行 `tiup cluster upgrade` 操作，而是通过 `tiup cluster restart -N <node1> -N <node2>` 来重启未完成重启的节点。如果同一组件的未重启节点数量比较多，也可以通过 `tiup cluster restart -R <component>` 来重启某一个类型的组件。
+
+### 2.3 升级发现 `node_exporter-9100.service/blackbox_exporter-9115.service` 不存在
+
+这种情况可能是由于之前的集群是由 TiDB Ansible 迁移过来的，且之前 TiDB Ansible 未部署 exporter 导致的。要解决这种情况，可以暂时通过手动从其他节点复制缺少的文件到新的节点。后续我们会在迁移过程中补全缺失的组件。