pingcap · yikeke · Jul 1, 2020 · Jun 28, 2020 · Jun 28, 2020 · Jun 28, 2020
diff --git a/TOC.md b/TOC.md
@@ -411,12 +411,16 @@
       + [Overview](/tiflash/tiflash-overview.md)
       + [Use TiFlash](/tiflash/use-tiflash.md)
   + TiUP
+    + [Documentation Guide](/tiup/tiup-documentation-guide.md)
     + [Overview](/tiup/tiup-overview.md)
-    + [Manage TiUP Components](/tiup/manage-tiup-component.md)
+    + [Terminology and Concepts](/tiup/tiup-terminology-and-concepts.md)
+    + [Manage TiUP Components](/tiup/tiup-component-management.md)
+    + [FAQ](/tiup/tiup-faq.md)
+    + [Troubleshooting Guide](/tiup/tiup-troubleshooting-guide.md)
     + TiUP Components
       + [tiup-playground](/tiup/tiup-playground.md)
       + [tiup-cluster](/tiup/tiup-cluster.md)
-      + [tiup-mirror](/tiup/tiup-mirrors.md)
+      + [tiup-mirror](/tiup/tiup-mirror.md)
       + [tiup-bench](/tiup/tiup-bench.md)
   + [Telemetry](/telemetry.md)
   + [Errors Codes](/error-codes.md)

diff --git a/production-offline-deployment-using-tiup.md b/production-offline-deployment-using-tiup.md
@@ -15,7 +15,7 @@ You can either download the official package, or manually pack a component packa
 
 ### Download the official TiUP offline component package
 
-Download the prepared offline mirror package at <http://download.pingcap.org> by running the following command:
+Download the prepared offline mirror package at `http://download.pingcap.org` by running the following command:
 
 {{< copyable "shell-regular" >}}
 

diff --git a/tiup/tiup-cluster.md b/tiup/tiup-cluster.md
@@ -63,7 +63,11 @@ tiup cluster deploy <cluster-name> <version> <topology.yaml> [flags]
 
 This command requires you to provide the cluster name, the TiDB cluster version, and a topology file of the cluster.
 
-To write a topology file, refer to [the example](https://github.com/pingcap-incubator/tiup-cluster/blob/master/examples/topology.example.yaml). The following file is an example of the simplest topology:
+To write a topology file, refer to [the example](https://github.com/pingcap/tiup/blob/master/examples/topology.example.yaml). The following file is an example of the simplest topology:
+
+> **Note:**
+>
+> The topology file used by the TiUP cluster component for deployment and scaling is written using [yaml](https://yaml.org/spec/1.2/spec.html) syntax, so make sure that the indentation is correct.
 
 ```yaml
 ---

diff --git a/tiup/manage-tiup-component.md → tiup/tiup-component-management.md b/tiup/manage-tiup-component.md → tiup/tiup-component-management.md
@@ -2,7 +2,7 @@
 title: Manage TiUP Components with TiUP Commands
 summary: Learn how to manage TiUP components using TiUP commands.
 category: tools
-aliases: ['/docs/dev/tiup/manage-tiup-component/','/docs/dev/reference/tools/tiup/manage-component/']
+aliases: ['/tidb/dev/manage-tiup-component','/docs/dev/tiup/manage-tiup-component/','/docs/dev/reference/tools/tiup/manage-component/']
 ---
 
 # Manage TiUP Components with TiUP Commands
@@ -26,10 +26,11 @@ You can use the `tiup list` command to query the component list. This usage of t
 - `tiup list`: checks which components can be installed.
 - `tiup list ${component}`: checks which versions of a specific component can be installed.
 
-You can also use the following two flags in the above commands:
+You can also use the following flags in the above commands:
 
 - `--installed`: checks which components or which version of a specific component has been installed locally.
-- `--refresh`: gets the latest list of components on the server and the version list of each component.
+-`--all`: views all components, including the hidden ones
+-`--verbose`: views all columns (including installed versions and supported platforms)
 
 Example 1: View all currently installed components.
 

diff --git a/tiup/tiup-documentation-guide.md b/tiup/tiup-documentation-guide.md
@@ -0,0 +1,26 @@
+---
+title: TiUP Documentation Guide
+summary: Guide you through TiUP documentation with links and introductions.
+category: tools
+---
+
+# TiUP Documentation Guide
+
+## TiUP user guide
+
+- [TiUP Overview](/tiup/tiup-overview.md): Gives an overall introduction to TiUP, for example, how to install and use TiUP
+- [TiUP Terminology and Concepts](/tiup/tiup-terminology-and-concepts.md): Explains the terms that you might bump into when using TiUP, and help you understand the key concepts of TiUP
+- [TiUP Component Management](/tiup/tiup-component-management.md): Introduces all TiUP commands in detail, and how to use TiUP to download, update and delete components
+- [TiUP FAQ](/tiup/tiup-faq.md): Introduces common issues when you use TiUP, including FAQs of the third-party components of TiUP
+- [TiUP Troubleshooting Guide](/tiup/tiup-troubleshooting-guide.md): Introduces the troubleshooting methods and solutions if you encounter issues when using TiUP
+
+## TiUP component user guide
+
+- [tiup-playground](/tiup/tiup-playground.md): Introduces how to use the TiUP playground component to quickly build a local TiDB cluster for testing
+- [tiup-cluster](/tiup/tiup-cluster.md): Introduces the usage and command-line flags of the TiUP cluster component, which is used to deploy and maintain a TiDB cluster for production
+- [tiup-mirror](/tiup/tiup-mirror.md): Introduces how to use the TiUP mirror component to customize a local offline mirror
+- [tiup-bench](/tiup/tiup-bench.md): Introduces how to use the TiUP bench component for common stress testings, such as TPCC/TPCH
+
+## TiUP resources
+
+- [TiUP Issues](https://github.com/pingcap/tiup/issues): Lists TiUP Github issues
diff --git a/tiup/tiup-faq.md b/tiup/tiup-faq.md
@@ -0,0 +1,56 @@
+---
+title: TiUP FAQ
+summary: Provide answers to common questions asked by TiUP users.
+category: tools
+---
+
+# TiUP FAQ
+
+## Can TiUP not use the official mirror source?
+
+TiUP supports specifying the mirror source through the `TIUP_MIRRORS` environment variable. The address of the mirror source can be a local directory or an HTTP server address. If your environment cannot access the network, you can create your own offline mirror source to use TiUP.
+
+## How do I put my own component into the TiUP mirrors?
+
+TiUP does not support third-party components for the time being, but the TiUP Team has developed the TiUP component development specifications and is developing the tiup-publish component. After everything is ready, a contributor can publish their own components to TiUP's official mirrors by using the `tiup publish <comp> <version>` command.
+
+## What is the difference between the TiUP playground and TiUP cluster components?
+
+The TiUP playground component is mainly used to build a stand-alone development environment on Linux or macOS operating systems. It helps you get started quickly and run a specified version of the TiUP cluster easily. The TiUP cluster component is mainly used to deploy and maintain a production environment cluster, which is usually a large-scale cluster.
+
+## How do I write the topology file for the TiUP cluster component?
+
+Refer to [these templates](https://github.com/pingcap/tiup/tree/master/examples) to write the topology file. The templates include:
+
+- Multi-DC deployment topology
+- Minimal deployment topology
+- Complete topology file
+
+You can edit your topology file based on the templates and your needs.
+
+## Can multiple instances be deployed on the same host?
+
+You can use the TiUP cluster component to deploy multiple instances on the same host, but with different ports and directories configured; otherwise, directory and port conflicts might occur.
+
+## Are port and directory conflicts detected within the same cluster?
+
+Port and directory conflicts in the same cluster are detected during deployment and scaling. If there is any directory or port conflict, the deployment or scaling process is interrupted.
+
+## Are port and directory conflicts detected among different clusters?
+
+If multiple different clusters are deployed by the same TiUP control machine, the port and directory conflicts among these clusters are detected during deployment and scaling. If the clusters are deployed by different TiUP control machines, conflict detection is not supported currently.
+
+## During cluster deployment, TiUP received an `ssh: handshake failed: read tcp 10.10.10.34:38980 -> 10.10.10.34:3600: read: connection reset by peer` error
+
+The error might occur because the default number of concurrent threads of TiUP exceeds the default maximum number of SSH connections. To solve the issue, you can increase the default number of SSH connections, and then restart the sshd service:
+
+{{< copyable "shell-regular" >}}
+
+```shell
+vi /etc/ssh/sshd_config
+```
+
+```bash
+MaxSessions 1000
+MaxStartups 1000 
+```
diff --git a/tiup/tiup-mirror.md b/tiup/tiup-mirror.md
@@ -0,0 +1,91 @@
+---
+title: Create a Private Mirror
+summary: Learn how to create a private mirror.
+category: tools
+aliases: ['/tidb/dev/tiup-mirrors','/docs/dev/tiup/tiup-mirrors/','/docs/dev/reference/tools/tiup/mirrors/']
+---
+
+# Create a Private Mirror
+
+When creating a private cloud, usually, you need to use an isolated network environment, where the official mirror of TiUP is not accessible. Therefore, you can create a private mirror, which is mainly implemented by the `mirror` command. You can also use the `mirror` command for offline deployment.
+
+## TiUP `mirror` overview
+
+Execute the following command to get the help information of the `mirror` command:
+
+{{< copyable "shell-regular" >}}
+
+```bash
+tiup mirror --help
+```
+
+```bash
+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.
+```
+
+The `tiup mirror clone` command is used to build a local mirror. The basic usage is as follows:
+
+{{< copyable "shell-regular" >}}
+
+```bash
+tiup mirror clone <target-dir> [global-version] [flags]
+```
+
+- `target-dir`: used to specify the directory in which cloned data is stored.
+- `global-version`: used to quickly set a global version for all components.
+
+The `tiup mirror clone` command provides many optional flags (might provide more in the future). These flags can be divided into the following categories according to their intended usages:
+
+- Determines whether to use prefix matching to match the version when cloning
+
+    If the `--prefix` flag is specified, the version number is matched by prefix for the clone. For example, if you specify `--prefix` as "v4.0.0", then "v4.0.0-rc.1", "v4.0.0-rc.2", and "v4.0.0" are matched.
+
+- Determines whether to use the full clone
+
+    If you specify the `--full` flag, you can clone the official mirror fully.
+
+    > **Note:**
+    >
+    > If `--full`, `global-version` flags, and the component versions are not specified, only some meta information is cloned.
+
+- Determines whether to clone packages from the specific platform
+
+    If you want to clone packages only for a specific platform, use `-os` and `-arch` to specify the platform. For example:
+
+    - Execute the `tiup mirror clone <target-dir> [global-version] --os=linux` command to clone for linux.
+    - Execute the `tiup mirror clone <target-dir> [global-version] --arch=amd64` command to clone for amd64.
+    - Execute the `tiup mirror clone <target-dir> [global-version] --os=linux --arch=amd64` command to clone for linux/amd64.
+
+- Determines whether to clone a specific version of a package
+
+    If you want to clone only one version (not all versions) of a component, use `--<component>=<version>` to specify this version. For example:
+
+    - Execute the `tiup mirror clone <target-dir> --tidb v4.0.0` command to clone the v4.0.0 version of the TiDB component.
+    - Execute the `tiup mirror clone <target-dir> --tidb v4.0.0 --tikv all` command to clone the v4.0.0 version of the TiDB component and all versions of the TiKV component.
+    - Execute the `tiup mirror clone <target-dir> v4.0.0` command to clone the v4.0.0 version of all components in a cluster.
+
+## Usage examples
+
+This section introduces the usage examples of the `mirror` command.
-This section introduces the usage examples of the `mirror` command.
+This section introduces the usage example of the `mirror` command.
-This section introduces the usage examples of the `mirror` command.
+This section introduces the usage example of the `mirror` command.
+
+### Deploy a TiDB Cluster offline using TiUP
+
+Refer to [Deploy a TiDB Cluster Offline Using TiUP](/production-offline-deployment-using-tiup.md#manually-pack-an-offline-component-package-using-tiup-mirror-clone) to install the TiUP offline mirror, deploy a TiDB cluster, and start it.