作者: dengqee

当需要在离线环境中部署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
curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
  1. 执行以下命令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架构的镜像

  1. 将当前tiup镜像目录设置为示例一的镜像目录
tiup mirror set /data/tidb-community-server-v7.5.0-linux
  1. 从离线镜像中克隆出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版本的镜像合并,创建包括这两个版本的离线镜像

  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
tiup mirror set /data/tidb-community-server-v7.5.0-linux
  1. 查看当前镜像中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
  1. 将当前镜像的keys目录复制到~/.tiup/中
cd /data/tidb-community-server-v7.5.0-linux
cp -r keys ~/.tiup/
  1. 将7.1.3版本的镜像合并到当前镜像
tiup mirror merge /data/tidb-community-server-v7.1.3-linux
  1. 查看当前镜像中的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

  1. 将自己编译的tidb-server打包进一个tar包中
tar -zcf my-tidb-server.tar.gz tidb-server
  1. 查看当前镜像中的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
  1. 执行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的场景提供参考。