tiup-troubleshooting-guide.md

title	aliases
TiUP 故障排查	/docs-cn/dev/tiup/tiup-troubleshooting-guide/

TiUP 故障排查

本文介绍 TiUP 使用过程中一些常见的故障及排查方式，如果本文不包含你目前遇到的问题，可以通过以下方式求助：

1. Github Issues 新建一个 Issue。
2. 在 AskTUG 提交你的问题。

1. TiUP 命令故障排查

1.1 使用 tiup list 看不到最新的组件列表

TiUP 并不会每次都从镜像服务器更新最新的组件列表，可以通过 tiup list 来强制刷新组件列表。

1.2 使用 tiup list <component> 看不到一个组件的最新版本信息

同 1.1 一样，组件的版本信息只会在本地无缓存的情况下从镜像服务器获取，可以通过 tiup list <component> 刷新组件列表。

1.3 下载组件的过程中中断

如果下载组件的过程中网络中断，可能是由于网络不稳定导致的，可以尝试重新下载，如果多次不能成功下载，请反馈到 Github Issues，可能是由于 CDN 服务器导致的。

1.4 下载组件过程中出现 checksum 错误

由于 CDN 会有短暂的缓存时间，导致新的 checksum 文件和组件包不匹配，建议过 5 分钟后重试，如果依然不匹配，请反馈到 Github 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.2 使用 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 导致的。要解决这种情况，可以暂时通过手动从其他节点复制缺少的文件到新的节点。后续我们会在迁移过程中补全缺失的组件。