作者： dengqee 原文来源：https://tidb.net/blog/eeebe568

当需要在离线环境中部署 tidb 时需要使用 tiup 的离线镜像，本文介绍了 tiup 的离线镜像管理，并在最后举出几个离线镜像管理的例子。

tiup 镜像

tiup 镜像为部署集群或通过 tiup 执行相关工具的源，可以是本地的离线镜像（本地的一个目录）或远程镜像（官方镜像 https://tiup-mirrors.pingcap.com）。

官网介绍的 tiup 的安装命令如下：

curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh

当在可连接互联网的机器上执行官方 tiup 的命令时，实际上只是按照 tiup 的二进制文件，并且将 tiup 镜像设置为 https://tiup-mirrors.pingcap.com。对于无法连接互联网的环境中就需要使用 tiup 的离线镜像，官方搭建的指定版本和架构的 tiup 的离线镜像包可在官网下载 。

tiup 的离线镜像目录的结构如下：

+ <mirror-dir>                                  # 镜像根目录|-- root.json                                   # 镜像根证书|-- {2..N}.root.json                            # 镜像根证书|-- {1..N}.index.json                           # 组件/用户索引|-- {1..N}.{component}.json                     # 组件元信息|-- {component}-{version}-{os}-{arch}.tar.gz    # 组件二进制包|-- snapshot.json                               # 镜像最新快照|-- timestamp.json                              # 镜像最新时间戳|--+ commits                                    # 镜像更新日志（可删除）   |--+ commit-{ts1..tsN}      |-- {N}.root.json      |-- {N}.{component}.json      |-- {N}.index.json      |-- {component}-{version}-{os}-{arch}.tar.gz      |-- snapshot.json      |-- timestamp.json|--+ keys                                       # 镜像私钥（可移动到其他位置）   |-- {hash1..hashN}-root.json                 # 根证书私钥   |-- {hash}-index.json                        # 索引私钥   |-- {hash}-snapshot.json                     # 快照私钥   |-- {hash}-timestamp.json                    # 时间戳私钥

tiup 离线镜像的介绍可参考https://docs.pingcap.com/zh/tidb/dev/tiup-mirror-reference#tiup-%E9%95%9C%E5%83%8F%E5%8F%82%E8%80%83%E6%8C%87%E5%8D%97

将镜像包解压后，直接运行安装脚本 local_install.sh 即可离线安装 tiup，安装完后会自动设置 tiup 的 mirror 为它自己所在的离线镜像目录，并会自动在~/.bash_profile 的 PATH 中添加 tiup 所在的运行目录。

tiup 镜像源设置

文件~/.tiup/tiup.toml 中设置了 tiup 镜像的地址或目录，可通过查看 tiup.toml 中的内容得知当前镜像的地址，或通过命令 tiup mirror show 查看当前镜像的地址。

修改离线镜像可以通过设置方式：

• 环境变量 TIUP_MIRRORS，当执行 tiup 命令时，将会自动设置 mirror 为 TIUP_MIRRORS 指定的地址

• 执行tiup mirror set {PATH}命令设置 mirror，PATH 为离线镜像的目录或远程镜像的地址

在设置 mirror 后，tiup 会重新从镜像中下载各个组件的元信息文件 (component.json) 到.tiup/manifests中。

通过 tiup list {组件}可以查看当前镜像中存在的组件以及工具以及版本，例如：

$ tiup list tidb Available versions for tidb:Version  Installed  Release               Platforms-------  ---------  -------               ---------v7.1.3              2024-01-15T07:06:27Z  linux/amd64,linux/arm64

该镜像中包括了 v7.1.3 版本，amd64 和 arm64 两种架构的 tidb-server

tiup 离线镜像管理

tiup mirror 命令清单如下：

• genkey: 生成私钥文件

• sign: 使用私钥文件对特定文件进行签名

• init: 创建一个空的镜像

• set: 设置当前镜像

• grant: 为当前镜像引入新的组件管理员

• publish: 向当前镜像推送新的组件

• modify: 修改当前镜像中的组件属性，主要是启用 / 禁用某个组件或它的某个版本

• rotate: 更新当前镜像中的根证书

• clone: 从已有镜像克隆一个新的镜像

• merge: 合并镜像

下面主要介绍通过 publish, clone, merge 这几个子命令，进行离线镜像的管理。

创建新镜像

命令 tiup mirror clone 从当前镜像中克隆出一个新的镜像，可以指定自己需要的版本，组件，平台等信息。新旧镜像的组件相同，但使用的签名密钥不同。

语法参考https://docs.pingcap.com/zh/tidb/dev/tiup-command-mirror-clone#tiup-mirror-clone

tiup mirror clone <target-dir> [global version] [flags]

下面举例说明如何创建自定义镜像

示例一：从官方镜像中克隆 v7.5.0 版本的镜像，包括所有组件以及 arm64 和 amd64 两个架构

1. 在一个可连接互联网的机器上安装 tiup

2. 执行以下命令 clone 镜像

以上命令将从官方镜像中下载所有组件的 v7.5.0 版本和两个架构的包到目录 /data/tidb-community-server-v7.5.0-linux 中，其中如果组件没有 v7.5.0 版本，将会下载该组件的最新版本。其中，离线镜像包中包括了 tiup 组件，将该离线镜像包上传到离线环境，直接执行 local_install.sh 即可离线安装 tiup。该镜像可以部署 arm64 和 amd64 两种架构的集群。

示例二：从示例一的离线镜像中分离出 amd64 架构的镜像

1. 将当前 tiup 镜像目录设置为示例一的镜像目录

2. 从离线镜像中克隆出 amd64 架构的镜像

执行完了之后 /data/tidb-community-server-v7.5.0-linux-amd64 中将只包括 amd64 架构的组件包

合并镜像

命令 tiup mirror merge 用于合并一个或多个镜像到当前镜像

执行此命令需要满足几个条件：

• 目标镜像的所有组件的管理员 ID 必须在当前镜像中存在。

• 执行该命令用户的 ${TIUP_HOME}/keys 目录中有上述管理员 ID 在当前镜像中对应的所有私钥（可以使用命令 tiup mirror set 将当前镜像切换成目前有权限修改的镜像）。

也就是将当前镜像中的 keys 目录中的内容复制到~/.tiup/keys 中

语法参考https://docs.pingcap.com/zh/tidb/dev/tiup-command-mirror-merge#tiup-mirror-merge

tiup mirror merge <mirror-dir-1> [mirror-dir-N] [flags]

下面通过举例介绍如何合并镜像

示例三：将 v7.5.0 版本和 v7.1.3 版本的镜像合并，创建包括这两个版本的离线镜像

1. v7.5.0 版本的镜像目录：/data/tidb-community-server-v7.5.0-linux，v7.1.3 版本的镜像：/data/tidb-community-server-v7.1.3-linux，将当前镜像设置为 v7.5.0

2. 查看当前镜像中 tidb-server 的版本

3. 将当前镜像的 keys 目录复制到~/.tiup/ 中

4. 将 7.1.3 版本的镜像合并到当前镜像

5. 查看当前镜像中的 tidb-server 版本

执行以上命令后，/data/tidb-community-server-v7.5.0-linux 镜像包可同时部署和管理 v7.1.3 和 v7.5.0 版本的集群。

修改镜像

若需要将离线镜像中的某个组件替换为我们自己编译的包，不能直接通过替换镜像中的 tar 包来实现，因为每个组件的包在镜像中都有对应的校验值，直接替换 tar 包会导致校验失败，需要通过tiup mirror publish命令来修改镜像中的组件包。

语法参考https://docs.pingcap.com/zh/tidb/dev/tiup-command-mirror-publish#tiup-mirror-publish

tiup mirror publish <comp-name> <version> <tarball> <entry> [flags]

使用 tiup mirror publish 时其中需要指定 key，如果需要修改官方的组件包，需要将 key 指定为 pingcap 官方的 key, 即{mirror}/keys/xxxx-pingcap.json，其中{mirror}为镜像包的路径，每个包中的 keys 的文件名是不一样的，我们需要使用的 key 是 pingcap.json 结尾。

下面通过举例来说明如何修改镜像

示例四：将当前镜像中的 v7.5.0 版本的 tidb-server 替换为自己编译的 tidb-server

1. 将自己编译的 tidb-server 打包进一个 tar 包中

2. 查看当前镜像中的 keys

3. 执行 tiup mirror publish 命令修改替换 tidb-server 包

执行以上命令部署集群时将会自动部署自己编译的 tidb-server

总结

本文档通过举例的方式来说明如果创建和管理离线镜像包，为需要离线环境部署 tidb 的场景提供参考。