cherry pick pingcap#3425 to release-4.0

Signed-off-by: sre-bot <[email protected]>
sre-bot · Jun 2, 2020 · 6ff944d · 6ff944d
1 parent e94b42a
commit 6ff944d
Show file tree

Hide file tree

Showing 13 changed files with 171 additions and 44 deletions.
diff --git a/TOC.md b/TOC.md
@@ -423,8 +423,7 @@
     + 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-mirror 定制离线镜像](/tiup/tiup-mirror.md)
       + [tiup-bench 进行 TPCC/TPCH 压力测试](/tiup/tiup-bench.md)
   + [错误码](/error-codes.md)
   + [TiCDC 简介](/ticdc/ticdc-overview.md)

diff --git a/maintain-tidb-using-tiup.md b/maintain-tidb-using-tiup.md
@@ -98,7 +98,7 @@ tiup cluster display ${cluster-name}
                 log.slow-threshold: 300
         ```
 
-    参数的格式参考 [TiUP 配置参数模版](https://github.com/pingcap-incubator/tiup-cluster/blob/master/examples/topology.example.yaml)。
+    参数的格式参考 [TiUP 配置参数模版](https://github.com/pingcap/tiup/blob/master/examples/topology.example.yaml)。
 
     **配置项层次结构使用 `.` 表示**。
 

diff --git a/production-deployment-using-tiup.md b/production-deployment-using-tiup.md
@@ -6,7 +6,7 @@ aliases: ['/docs-cn/stable/how-to/deploy/orchestrated/tiup/']
 
 # 使用 TiUP 部署 TiDB 集群
 
-[TiUP](https://github.com/pingcap-incubator/tiup) 是 TiDB 4.0 版本引入的集群运维工具，[TiUP cluster](https://github.com/pingcap-incubator/tiup-cluster) 是 TiUP 提供的使用 Golang 编写的集群管理组件，通过 TiUP cluster 组件就可以进行日常的运维工作，包括部署、启动、关闭、销毁、弹性扩缩容、升级 TiDB 集群；管理 TiDB 集群参数。
+[TiUP](https://github.com/pingcap/tiup) 是 TiDB 4.0 版本引入的集群运维工具，[TiUP cluster](https://github.com/pingcap/tiup/tree/master/components/cluster) 是 TiUP 提供的使用 Golang 编写的集群管理组件，通过 TiUP cluster 组件就可以进行日常的运维工作，包括部署、启动、关闭、销毁、弹性扩缩容、升级 TiDB 集群；管理 TiDB 集群参数。
 
 目前 TiUP 可以支持部署 TiDB、TiFlash、TiDB Binlog、TiCDC。本文将介绍不同集群拓扑的具体部署步骤。
 

diff --git a/production-offline-deployment-using-tiup.md b/production-offline-deployment-using-tiup.md
@@ -7,7 +7,26 @@ category: how-to
 
 本文介绍如何使用 TiUP 离线部署 TiDB 集群，具体的操作步骤如下。
 
-## 1. 部署在线环境 TiUP 组件
+## 1. 准备 TiUP 离线组件包
+
+### 方式一：下载官方 TiUP 离线组件包
+
+在 <download.pingcap.org> 有官方预先打好的离线镜像包，下载指令为：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+wget http://download.pingcap.org/tidb-community-server-${version}-linux-amd64.tar.gz
+mv tidb-community-server-${version}-linux-amd64.tar.gz package.tar.gz
+```
+
+其中 ${version} 处填入希望下载的离线镜像包版本，例如 v4.0.0。
+
+此时，`package.tar.gz` 就是一个独立的离线环境包。
+
+### 方式二：使用 `tiup mirror clone` 命令手动打包离线组件包
+
+#### 1.1 部署在线环境 TiUP 组件
 
 使用普通用户登录一台开放外网访问的机器：
 
@@ -35,7 +54,7 @@ category: how-to
     which tiup
     ```
 
-## 2. 使用 TiUP 拉取镜像
+#### 1.2 使用 TiUP 拉取镜像
 
 以 tidb 用户在隔离的环境中安装一个 v4.0.0 的 TiDB 集群为例，可以执行以下步骤：
 
@@ -44,7 +63,7 @@ category: how-to
     {{< copyable "shell-regular" >}}
 
     ```bash
-    tiup mirrors package --os=linux v4.0.0
+    tiup mirror clone package v4.0.0 --os=linux --arch=amd64
     ```
 
     该命令会在当前目录下创建一个名叫 `package` 的目录，里面有启动一个集群必要的组件包。
@@ -59,20 +78,20 @@ category: how-to
 
     此时，`package.tar.gz` 就是一个独立的离线环境包。
 
-## 3. 部署离线环境 TiUP 组件
+## 2. 部署离线环境 TiUP 组件
 
-1. 将包发送到目标集群的中控机后，执行以下命令安装 TiUP 组件：
+将包发送到目标集群的中控机后，执行以下命令安装 TiUP 组件：
 
-    {{< copyable "shell-regular" >}}
+{{< copyable "shell-regular" >}}
 
-    ```bash
-    tar xzvf package.tar.gz &&
-    cd package &&
-    sh local_install.sh &&
-    source /home/tidb/.bash_profile
-    ```
+```bash
+tar xzvf package.tar.gz &&
+cd package &&
+sh local_install.sh &&
+source /home/tidb/.bash_profile
+```
 
-## 4. TiKV 数据盘挂载
+## 3. TiKV 数据盘挂载
 
 > **注意：**
 >
@@ -172,9 +191,9 @@ category: how-to
     /dev/nvme0n1p1 on /data1 type ext4 (rw,noatime,nodelalloc,data=ordered)
     ```
 
-## 5. 配置初始化参数文件 `topology.yaml`
+## 4. 配置初始化参数文件 `topology.yaml`
 
-集群初始化配置文件需要手动编写，完整的全配置参数模版可以参考 [Github TiUP 项目配置参数模版](https://github.com/pingcap-incubator/tiup-cluster/blob/master/examples/topology.example.yaml)。需要在中控机上面创建 YAML 格式配置文件，例如 `topology.yaml`:
+集群初始化配置文件需要手动编写，完整的全配置参数模版可以参考 [Github TiUP 项目配置参数模版](https://github.com/pingcap/tiup/blob/master/examples/topology.example.yaml)。需要在中控机上面创建 YAML 格式配置文件，例如 `topology.yaml`:
 
 {{< copyable "shell-regular" >}}
 
@@ -222,9 +241,9 @@ alertmanager_servers:
   - host: 10.0.1.4
 ```
 
-## 6. 部署 TiDB 集群
+## 5. 部署 TiDB 集群
 
-`/path/to/mirror` 是 `tiup mirrors <target-dir>` 中输出的 package 所在离线机器的位置:
+`/path/to/mirror` 是执行 `local_install.sh` 命令时输出的离线镜像包的位置:
 
 {{< copyable "shell-regular" >}}
 

diff --git a/tiflash/deploy-tiflash.md b/tiflash/deploy-tiflash.md
@@ -67,7 +67,7 @@ TiUP Cluster 是适用于 TiDB 4.0 及以上版本的部署工具，目前推荐
 
 3. 编写 topology 配置文件，保存为 `topology.yaml`。
 
-    可以参考[全量的配置文件模版](https://github.com/pingcap-incubator/tiup-cluster/blob/master/examples/topology.example.yaml)。
+    可以参考[全量的配置文件模版](https://github.com/pingcap/tiup/blob/master/examples/topology.example.yaml)。
 
     除了部署 TiDB 集群的配置，需要额外在 `tiflash_servers` 下配置 tiflash servers 所在的 ip（目前只支持 ip，不支持域名）。
 

diff --git a/tikv-control.md b/tikv-control.md
@@ -11,7 +11,7 @@ TiKV Control（以下简称 tikv-ctl）是 TiKV 的命令行工具，用于管
 * 如果是使用 TiDB Ansible 部署的集群，在 `ansible` 目录下的 `resources/bin` 子目录下。
 * 如果是使用 TiUP 部署的集群，在 `~/.tiup/components/ctl/{VERSION}/` 目录下。
 
-[TiUP](https://github.com/pingcap-incubator/tiuptiup) 是晚于 `tidb-ansible` 推出的部署工具，使用方式更加简化，`tikv-ctl` 也集成在了 `tiup` 命令中。执行以下命令，即可调用 `tikv-ctl` 工具：
+[TiUP](https://github.com/pingcap/tiup) 是晚于 `tidb-ansible` 推出的部署工具，使用方式更加简化，`tikv-ctl` 也集成在了 `tiup` 命令中。执行以下命令，即可调用 `tikv-ctl` 工具：
 
 {{< copyable "shell-regular" >}}
 

diff --git a/tiup/tiup-cluster.md b/tiup/tiup-cluster.md
@@ -61,7 +61,7 @@ tiup cluster deploy <cluster-name> <version> <topology.yaml> [flags]
 
 该命令需要提供集群的名字、集群使用的 TiDB 版本，以及一个集群的拓扑文件。
 
-拓扑文件的编写可参考[示例](https://github.com/pingcap-incubator/tiup-cluster/blob/master/examples/topology.example.yaml)。以一个最简单的拓扑为例，将下列文件保存为 `/tmp/topology.yaml`：
+拓扑文件的编写可参考[示例](https://github.com/pingcap/tiup/blob/master/examples/topology.example.yaml)。以一个最简单的拓扑为例，将下列文件保存为 `/tmp/topology.yaml`：
 
 > **注意：**
 >

diff --git a/tiup/tiup-documentation-guide.md b/tiup/tiup-documentation-guide.md
@@ -17,12 +17,10 @@ category: tools
 
 - [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-mirror](/tiup/tiup-mirror.md)：介绍如何使用 TiUP Mirror 组件自定义一个本地离线镜像
 - [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 Issues](https://github.com/pingcap/tiup/issues)：TiUP Github Issues 列表
diff --git a/tiup/tiup-faq.md b/tiup/tiup-faq.md
@@ -19,7 +19,7 @@ TiUP Playground 组件主要定位是快速上手和搭建单机的开发环境
 
 ## 怎么样编写 tiup-cluster 组件的拓扑文件？
 
-可以参考拓扑文件的 [样例](https://github.com/pingcap-incubator/tiup-cluster/tree/master/examples)，样例中包含了：
+可以参考拓扑文件的 [样例](https://github.com/pingcap/tiup/tree/master/examples)，样例中包含了：
 
 1. 两地三中心
 2. 最小部署拓扑

diff --git a/tiup/tiup-mirror.md b/tiup/tiup-mirror.md
@@ -0,0 +1,117 @@
+---
+title: 搭建私有镜像
+category: tools
+aliases: ['/docs-cn/dev/tiup/tiup-mirrors/','/docs-cn/dev/reference/tools/tiup/mirror/']
+---
+
+# 搭建私有镜像
+
+在构建私有云时，通常会使用隔离的网络环境，此时无法访问 TiUP 的官方镜像。因此，我们提供了构建私有镜像的方案，它主要由 mirror 指令来实现，该方案也可用于离线部署。
+
+## mirror 指令介绍
+
+`mirror` 指令的帮助文档如下：
+
+{{< copyable "shell-regular" >}}
+
+```bash
+tiup mirror --help
+```
+
+```
+The 'mirror' command is used to manage a component repository for TiUP, you can use
+it to create a private repository, or to add new component to an existing repository.
+The repository can be used either online or offline.
+It also provides some useful utilities to help managing keys, users and versions
+of components or the repository itself.
+
+Usage:
+  tiup mirror <command> [flags]
+
+Available Commands:
+  init        Initialize an empty repository
+  sign        Add signatures to a manifest file
+  genkey      Generate a new key pair
+  clone       Clone a local mirror from remote mirror and download all selected components
+  publish     Publish a component
+
+Flags:
+  -h, --help          help for mirror
+      --repo string   Path to the repository
+
+Global Flags:
+      --skip-version-check   Skip the strict version check, by default a version must be a valid SemVer string
+
+Use "tiup mirror [command] --help" for more information about a command.
+```
+
+构建本地镜像将会使用 `tiup mirror clone` 指令，其基本用法如下：
+
+{{< copyable "shell-regular" >}}
+
+```bash
+tiup mirror clone <target-dir> [global-version] [flags]
+```
+
+- `target-dir`：指需要把克隆下来的数据放到哪个目录里。
+- `global-version`：用于为所有组件快速设置一个共同的版本。
+
+`tiup mirror clone` 命令提供了很多可选参数，日后可能会提供更多。但这些参数其实可以分为四类：
+
+1. 克隆时是否使用前缀匹配方式匹配版本
+
+    如果指定了 `--prefix` 参数，则会才用前缀匹配方式匹配克隆的版本号。例：指定 `--prefex` 时填写版本 "v4.0.0" 将会匹配 "v4.0.0-rc.1", "v4.0.0-rc.2", "v4.0.0"
+
+2. 是否全量克隆
+
+    如果指定了 `--full` 参数，则会完整地克隆官方镜像。
+
+    > **注意：**
+    >
+    > 如果既不指定 `--full` 参数，又不指定 `global-version` 或克隆的 component 版本，那么 TiUP 就只会克隆一些元信息。
+
+3. 限定只克隆特定平台的包
+
+    如果只想克隆某个平台的包，那么可以使用 `--os` 和 `--arch` 来限定：
+
+    - 只想克隆 linux 平台的，则执行 `tiup mirror clone <target-dir> [global-version] --os=linux`
+    - 只想克隆 amd64 架构的，则执行 `tiup mirror clone <target-dir> [global-version] --arch=amd64`
+    - 只想克隆 linux/amd64 的，则执行 `tiup mirror clone <target-dir> [global-version] --os=linux --arch=amd64`
+
+4. 限定只克隆组件的特定版本
+
+    如果只想克隆某个组件的某一个版本而不是所有版本，则使用 `--<component>=<version>` 来限定，例如：
+
+    - 只想克隆 TiDB 的 v4.0.0 版本，则执行 `tiup mirror clone <target-dir> --tidb v4.0.0`
+    - 只想克隆 TiDB 的 v4.0.0 版本，以及 TiKV 的所有版本，则执行 `tiup mirror clone <target-dir> --tidb v4.0.0 --tikv all`
+    - 克隆一个集群的所有组件的 v4.0.0 版本，则执行 `tiup mirror clone <target-dir> v4.0.0`
+
+## 使用示例
+
+### 使用 TiUP 离线安装 TiDB 集群
+
+参考[使用 TiUP 离线部署](/production-offline-deployment-using-tiup.md#方式二使用-tiup-mirror-clone-命令手动打包离线组件包)安装 TiUP 离线镜像，部署并启动 TiDB 集群。
+
+### 构建私有镜像
+
+构建私有镜像的方式和离线安装包的制作过程相同，只需要将 package 目录中的内容上传到 CDN 或者文件服务器即可，最简单的方式是：
+
+{{< copyable "shell-regular" >}}
+
+```bash
+cd package
+python -m SimpleHTTPServer 8000
+```
+
+这样就在 <http://127.0.0.1:8000> 这个地址建立了私有镜像。
+
+通过私有镜像安装 TiUP：
+
+{{< copyable "shell-regular" >}}
+
+```bash
+export TIUP_MIRRORS=http://127.0.0.1:8000
+curl $TIUP_MIRRORS/local_install.sh | sh
+```
+
+导入 PATH 变量之后就可以正常使用 TiUP 了（需要保持 `TIUP_MIRRORS` 变量指向私有镜像）。
diff --git a/tiup/tiup-overview.md b/tiup/tiup-overview.md
@@ -64,16 +64,11 @@ Available Commands:
   update      Update tiup components to the latest version
   status      List the status of instantiated components
   clean       Clean the data of instantiated components
+  mirror      Manage a repository mirror for TiUP components
   help        Help about any command or component
 
-Available Components:
-  playground          Bootstrap a local TiDB cluster
-  client              A simple mysql client to connect TiDB
-  package             A toolbox to package tiup component
-  cluster             Deploy a TiDB cluster for production
-  mirrors             Build a local mirrors and download all selected components
-  bench               Benchmark database with different workloads
-  doc                 Online document for TiDB
+Components Manifest:
+  use "tiup list" to fetch the latest components manifest
 
 Flags:
   -B, --binary <component>[:version]   Print binary path of a specific version of a component <component>[:version]
@@ -82,7 +77,7 @@ Flags:
   -h, --help                           help for tiup
       --skip-version-check             Skip the strict version check, by default a version must be a valid SemVer string
   -T, --tag string                     Specify a tag for component instance
-      --version                        version for tiup
+  -v, --version                        version for tiup
 
 Component instances with the same "tag" will share a data directory ($TIUP_HOME/data/$tag):
   $ tiup --tag mycluster playground
@@ -111,13 +106,12 @@ Use "tiup [command] --help" for more information about a command.
     - update：更新组件版本
     - status：查看组件运行记录
     - clean：清除组件运行记录
+    - mirror：从官方镜像克隆一个私有镜像
     - help：输出帮助信息
 - 可用的组件
     - playground：在本机启动集群
     - client：连接本机的集群
-    - mirrors：从官方镜像克隆一个私有镜像
     - cluster：部署用于生产环境的集群
-    - package：打包一个新的 TiUP 组件
     - bench：对数据库进行压力测试
     - doc：打开在线文档
 

diff --git a/tiup/tiup-troubleshooting-guide.md b/tiup/tiup-troubleshooting-guide.md
@@ -7,7 +7,7 @@ category: tools
 
 本文介绍 TiUP 使用过程中一些常见的故障及排查方式，如果本文不包含你目前遇到的问题，可以通过以下方式求助：
 
-1. [Github Issues](https://github.com/pingcap-incubator/tiup/issues) 新建一个 Issue。
+1. [Github Issues](https://github.com/pingcap/tiup/issues) 新建一个 Issue。
 2. 在 [AskTUG](https://asktug.com/) 提交你的问题。
 
 ## 1. TiUP 命令故障排查
@@ -22,11 +22,11 @@ TiUP 并不会每次都从镜像服务器更新最新的组件列表，可以通
 
 ### 1.3 下载组件的过程中中断
 
-如果下载组件的过程中网络中断，可能是由于网络不稳定导致的，可以尝试重新下载，如果多次不能成功下载，请反馈到 [Github Issues](https://github.com/pingcap-incubator/tiup/issues)，可能是由于 CDN 服务器导致的。
+如果下载组件的过程中网络中断，可能是由于网络不稳定导致的，可以尝试重新下载，如果多次不能成功下载，请反馈到 [Github Issues](https://github.com/pingcap/tiup/issues)，可能是由于 CDN 服务器导致的。
 
 ### 1.4 下载组件过程中出现 checksum 错误
 
-由于 CDN 会有短暂的缓存时间，导致新的 checksum 文件和组件包不匹配，建议过 5 分钟后重试，如果依然不匹配，请反馈到 [Github Issues](https://github.com/pingcap-incubator/tiup/issues)。
+由于 CDN 会有短暂的缓存时间，导致新的 checksum 文件和组件包不匹配，建议过 5 分钟后重试，如果依然不匹配，请反馈到 [Github Issues](https://github.com/pingcap/tiup/issues)。
 
 ## 2. TiUP Cluster 组件故障排查
 

diff --git a/upgrade-tidb-using-tiup.md b/upgrade-tidb-using-tiup.md
@@ -132,7 +132,7 @@ tiup update cluster
     tiup cluster edit-config <cluster-name>
     ```
 
-3. 参考 [topology](https://github.com/pingcap-incubator/tiup-cluster/blob/master/examples/topology.example.yaml) 配置模板的格式，将原集群修改过的参数填到拓扑文件的 `server_configs` 下面。
+3. 参考 [topology](https://github.com/pingcap/tiup/blob/master/examples/topology.example.yaml) 配置模板的格式，将原集群修改过的参数填到拓扑文件的 `server_configs` 下面。
 
 修改完成后 `wq` 保存并退出编辑模式，输入 `Y` 确认变更。