当需要在离线环境中部署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两个架构
- 在一个可连接互联网的机器上安装tiup
curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
- 执行以下命令clone镜像
tiup mirror clone /data/tidb-community-server-v7.5.0-linux v7.5.0 --arch amd64,arm64 --os linux
以上命令将从官方镜像中下载所有组件的v7.5.0版本和两个架构的包到目录/data/tidb-community-server-v7.5.0-linux中，其中如果组件没有v7.5.0版本，将会下载该组件的最新版本。其中，离线镜像包中包括了tiup组件，将该离线镜像包上传到离线环境，直接执行local_install.sh即可离线安装tiup。该镜像可以部署arm64和amd64两种架构的集群。
示例二：从示例一的离线镜像中分离出amd64架构的镜像
- 将当前tiup镜像目录设置为示例一的镜像目录
tiup mirror set /data/tidb-community-server-v7.5.0-linux
- 从离线镜像中克隆出amd64架构的镜像
tiup mirror clone /data/tidb-community-server-v7.5.0-linux-amd64 v7.5.0 --arch amd64 --os linux
执行完了之后/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版本的镜像合并，创建包括这两个版本的离线镜像
- 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
tiup mirror set /data/tidb-community-server-v7.5.0-linux
- 查看当前镜像中tidb-server的版本
$ tiup list tidb
Available versions for tidb:
Version Installed Release Platforms
------- --------- ------- ---------
v7.5.0 2024-01-15T07:06:27Z linux/amd64,linux/arm64
- 将当前镜像的keys目录复制到~/.tiup/中
cd /data/tidb-community-server-v7.5.0-linux
cp -r keys ~/.tiup/
- 将7.1.3版本的镜像合并到当前镜像
tiup mirror merge /data/tidb-community-server-v7.1.3-linux
- 查看当前镜像中的tidb-server版本
$ tiup list tidb
Available versions for tidb:
Version Installed Release Platforms
------- --------- ------- ---------
v7.1.3 2024-01-15T07:06:27Z linux/amd64,linux/arm64
v7.5.0 2024-01-15T07:06:27Z linux/amd64,linux/arm64
执行以上命令后，/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
- 将自己编译的tidb-server打包进一个tar包中
tar -zcf my-tidb-server.tar.gz tidb-server
- 查看当前镜像中的keys
$ ls /data/tidb-community-server-v7.5.0-linux/keys/
1c12ba5663b5b3ed-root.json 32762dfd5812ac40-timestamp.json 88c0aff47103fa21-root.json ed54a0bef7fa53fb-index.json
1f29fe4561a59dd0-pingcap.json 4ff9c9ada34ab32e-root.json c941efba22aac7eb-snapshot.json
- 执行tiup mirror publish命令修改替换tidb-server包
tiup mirror publish tidb v7.5.0 my-tidb-server.tar.gz tidb-server -k /data/tidb-community-server-v7.5.0-linux/keys/1f29fe4561a59dd0-pingcap.json --arch amd64
执行以上命令部署集群时将会自动部署自己编译的tidb-server
总结
本文档通过举例的方式来说明如果创建和管理离线镜像包，为需要离线环境部署tidb的场景提供参考。