diff --git a/TOC.md b/TOC.md index 83c6f744e6e0..52c552ee2bc4 100644 --- a/TOC.md +++ b/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) @黄东旭 diff --git a/tiup/tiup-cluster.md b/tiup/tiup-cluster.md index 33cd30ac8c18..a958e1c4cacb 100644 --- a/tiup/tiup-cluster.md +++ b/tiup/tiup-cluster.md @@ -63,6 +63,10 @@ tiup cluster deploy [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 --- diff --git a/tiup/manage-tiup-component.md b/tiup/tiup-component-management.md similarity index 98% rename from tiup/manage-tiup-component.md rename to tiup/tiup-component-management.md index 2dc85a540345..6de9a819042a 100644 --- a/tiup/manage-tiup-component.md +++ b/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 命令管理组件 diff --git a/tiup/tiup-documentation-guide.md b/tiup/tiup-documentation-guide.md new file mode 100644 index 000000000000..99886bdfe918 --- /dev/null +++ b/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 列表 diff --git a/tiup/tiup-faq.md b/tiup/tiup-faq.md new file mode 100644 index 000000000000..08e1018dadc6 --- /dev/null +++ b/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 ` 将自己开发的组件发布到 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 中控机，目前不支持检测。 diff --git a/tiup/tiup-overview.md b/tiup/tiup-overview.md index 289af1db626d..0380dabc1570 100644 --- a/tiup/tiup-overview.md +++ b/tiup/tiup-overview.md @@ -127,11 +127,3 @@ Use "tiup [command] --help" for more information about a command. > - 组件的可用版本列表也会持续增加，以 `tiup list --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 组件 \ No newline at end of file diff --git a/tiup/package-tiup-component.md b/tiup/tiup-package.md similarity index 97% rename from tiup/package-tiup-component.md rename to tiup/tiup-package.md index b7495b436bb9..869494caf530 100644 --- a/tiup/package-tiup-component.md +++ b/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 打包并不困难，麻烦在于需要更新仓库的元信息，因为要避免更新元信息的时候破坏已有组件的信息。 diff --git a/tiup/tiup-terminology-and-concepts.md b/tiup/tiup-terminology-and-concepts.md new file mode 100644 index 000000000000..a1a31698c3a4 --- /dev/null +++ b/tiup/tiup-terminology-and-concepts.md @@ -0,0 +1,31 @@ +--- +title: TiUP 术语及核心概念 +category: tools +--- + +# TiUP 术语及核心概念 + +本文主要说明 TiUP 的重要术语和核心概念。 + +## TiUP 组件 + +TiUP 程序只包含少数几个命令，用来下载、更新、卸载组件。TiUP 通过各种组件来扩展其功能。**组件**是一个可以运行的程序或脚本，通过 `tiup ` 运行组件时，TiUP 会添加一组环境变量，并为该程序创建好对应的数据目录，然后运行该程序。 + +通过运行 `tiup ` 命令，你可以运行支持的 TiUP 组件，其中运行的逻辑为： + +1. 如果用户通过 `tiup [:version]` 运行指定某个组件的特定版本： + - 组件在本地未安装任何版本，则从镜像服务器下载最新稳定版本 + - 组件在本地安装有其他版本，但是没有用户指定的版本，则从镜像服务器下载用户指定版本 + - 如果本地已经安装指定版本，则设置环境变量来运行已经安装的版本 +2. 如果用户通过 `tiup ` 运行某个组件，且未指定任何版本： + - 组件在本地未安装任何版本，则从镜像服务器下载最新稳定版本 + - 如果本地已经安装部分版本，则设置环境变量来运行已经安装的版本中的最新版本 + +## 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` diff --git a/tiup/tiup-troubleshooting-guide.md b/tiup/tiup-troubleshooting-guide.md new file mode 100644 index 000000000000..e1213ef46f70 --- /dev/null +++ b/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 ` 看不到一个组件的最新版本信息 + +同 1.1 一样，组件的版本信息只会在本地无缓存的情况下从镜像服务器获取，可以通过 `tiup list --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 -N ` 来重启未完成重启的节点。如果同一组件的未重启节点数量比较多，也可以通过 `tiup cluster restart -R ` 来重启某一个类型的组件。 + +### 2.3 升级发现 `node_exporter-9100.service/blackbox_exporter-9115.service` 不存在 + +这种情况可能是由于之前的集群是由 TiDB Ansible 迁移过来的，且之前 TiDB Ansible 未部署 exporter 导致的。要解决这种情况，可以暂时通过手动从其他节点复制缺少的文件到新的节点。后续我们会在迁移过程中补全缺失的组件。