title: TiUP 镜像参考指南

TiUP 镜像参考指南

TiUP 镜像是 TiUP 的组件仓库,存放了一些列的组件和这些组件的元信息。镜像有两种存在形式:

  • 本地磁盘上的目录:用于服务本地的 TiUP 客户端,文档中将称之为本地镜像
  • 基于远程的磁盘目录启动的 HTTP 镜像:服务远程的 TiUP 客户端,文档中将称之为远程镜像

镜像的创建与更新

镜像可以通过以下两种方式创建:

  • 通过命令 tiup mirror init 从零生成
  • 通过命令 tiup mirrir clone 从已有镜像克隆

在创建镜像之后,可以通过 tiup mirror 相关命令来给镜像添加组件或删除组件,无论是通过何种方式更新镜像,TiUP 都不会从镜像中删除任何文件,而是通过增加文件并分配新版本号的方式更新。

镜像结构

一个典型的镜像目录结构如下:

  1. + <mirror-dir> # 镜像根目录
  2. |-- root.json # 镜像根证书
  3. |-- {2..N}.root.json # 镜像根证书
  4. |-- {1..N}.index.json # 组件/用户索引
  5. |-- {1..N}.{component}.json # 组件元信息
  6. |-- {component}-{version}-{os}-{arch}.tar.gz # 组件二进制包
  7. |-- snapshot.json # 镜像最新快照
  8. |-- timestamp.json # 镜像最新时间戳
  9. |--+ commits # 镜像更新日志(可删除)
  10. |--+ commit-{ts1..tsN}
  11. |-- {N}.root.json
  12. |-- {N}.{component}.json
  13. |-- {N}.index.json
  14. |-- {component}-{version}-{os}-{arch}.tar.gz
  15. |-- snapshot.json
  16. |-- timestamp.json
  17. |--+ keys # 镜像私钥(可移动到其他位置)
  18. |-- {hash1..hashN}-root.json # 根证书私钥
  19. |-- {hash}-index.json # 索引私钥
  20. |-- {hash}-snapshot.json # 快照私钥
  21. |-- {hash}-timestamp.json # 时间戳私钥

注意:

  • commits 目录是在更新镜像过程中产生的日志,用于回滚镜像,磁盘空间不足时可以定期删除旧的文件夹
  • keys 文件夹中存放的私钥较敏感,建议单独妥善保管

根证书

在 TiUP 镜像中,根证书用于存放其他元信息文件的公钥,每次获取到任何元信息文件(*.json)都需要根据其文件类型(root,index,snapshot,timestamp)在当前已安装的 root.json 中找到对应的公钥,然后用公钥验证其签名是否合法。

根证书文件格式如下:

  1. {
  2. "signatures": [ # 每个元信息文件有一些列的签名,签名由该文件对应的几个私钥签出
  3. {
  4. "keyid": "{id-of-root-key-1}", # 第一个参与签名私钥的 ID,该 ID 由私钥对应的公钥内容哈希得到
  5. "sig": "{signature-by-root-key-1}" # 该私钥对此文件 signed 部分签名的结果
  6. },
  7. ...
  8. {
  9. "keyid": "{id-of-root-key-N}", # 第 N 个参与签名私钥的 ID
  10. "sig": "{signature-by-root-key-N}" # 该私钥对此文件 signed 部分签名的结果
  11. }
  12. ],
  13. "signed": { # 被签名的部分
  14. "_type": "root", # 该字段说明本文件的类型,root.json 的类型就是 root
  15. "expires": "{expiration-date-of-this-file}", # 该文件的过期时间,过期后客户端会拒绝此文件
  16. "roles": { # root.json 中的 roles 用来记录对各个元文件签名的密钥
  17. "{role:index,root,snapshot,timestamp}": { # 涉及的元文件类型包括 index, root, snapshot, timestamp
  18. "keys": { # 只有 keys 中记录的密钥签名才是合法的
  19. "{id-of-the-key-1}": { # 用于签名 {role} 的第 1 个密钥 ID
  20. "keytype": "rsa", # 密钥类型,目前固定为 rsa
  21. "keyval": { # 密钥的 payload
  22. "public": "{public-key-content}" # 表示公钥内容
  23. },
  24. "scheme": "rsassa-pss-sha256" # 目前固定为 rsassa-pss-sha256
  25. },
  26. "{id-of-the-key-N}": { # 用于签名 {role} 的第 N 个密钥 ID
  27. "keytype": "rsa",
  28. "keyval": {
  29. "public": "{public-key-content}"
  30. },
  31. "scheme": "rsassa-pss-sha256"
  32. }
  33. },
  34. "threshold": {N}, # threshold 指示该元文件需要至少 N 个密钥签名
  35. "url": "/{role}.json" # url 是指该文件的获取地址,对于 index 文件,需要在前面加上版本号,即 /{N}.index.json
  36. }
  37. },
  38. "spec_version": "0.1.0", # 本文件遵循的规范版本,未来变更文件结构需要升级版本号,目前为 0.1.0
  39. "version": {N} # 本文件的版本号,每次更新文件需要创建一个新的 {N+1}.root.json,并将其 version 设置为 N + 1
  40. }
  41. }

索引

索引文件记录了镜像中所有的组件以及组件的所有者信息。

其格式如下:

  1. {
  2. "signatures": [ # 该文件的签名
  3. {
  4. "keyid": "{id-of-index-key-1}", # 第一个参与签名的 key 的 ID
  5. "sig": "{signature-by-index-key-1}", # 该私钥对此文件 signed 部分签名的结果
  6. },
  7. ...
  8. {
  9. "keyid": "{id-of-root-key-N}", # 第 N 个参与签名私钥的 ID
  10. "sig": "{signature-by-root-key-N}" # 该私钥对此文件 signed 部分签名的结果
  11. }
  12. ],
  13. "signed": {
  14. "_type": "index", # 指示该文件类型
  15. "components": { # 组件列表
  16. "{component1}": { # 第一个组件的名称
  17. "hidden": {bool}, # 是否是隐藏组件
  18. "owner": "{owner-id}", # 组件管理员 ID
  19. "standalone": {bool}, # 该组件是否可独立运行
  20. "url": "/{component}.json", # 获取组件的地址,需要加上版本号:/{N}.{component}.json
  21. "yanked": {bool} # 该组件是否已被标记为删除
  22. },
  23. ...
  24. "{componentN}": { # 第 N 个组件的名称
  25. ...
  26. },
  27. },
  28. "default_components": ["{component1}".."{componentN}"], # 镜像必须包含的默认组件,该字段目前固定为空(未启用)
  29. "expires": "{expiration-date-of-this-file}", # 该文件的过期时间,过期后客户端会拒绝此文件
  30. "owners": {
  31. "{owner1}": { # 第一个属主的 ID
  32. "keys": { # 只有 keys 中记录的密钥签名才是合法的
  33. "{id-of-the-key-1}": { # 该属主的第一个密钥
  34. "keytype": "rsa", # 密钥类型,目前固定为 rsa
  35. "keyval": { # 密钥的 payload
  36. "public": "{public-key-content}" # 表示公钥内容
  37. },
  38. "scheme": "rsassa-pss-sha256" # 目前固定为 rsassa-pss-sha256
  39. },
  40. ...
  41. "{id-of-the-key-N}": { # 该属主的第 N 个密钥
  42. ...
  43. }
  44. },
  45. "name": "{owner-name}", # 该属主的名字
  46. "threshod": {N} # 指示该属主拥有的组件必须含有至少 N 个合法签名
  47. },
  48. ...
  49. "{ownerN}": { # 第 N 个属主的 ID
  50. ...
  51. }
  52. }
  53. "spec_version": "0.1.0", # 本文件遵循的规范版本,未来变更文件结构需要升级版本号,目前为 0.1.0
  54. "version": {N} # 本文件的版本号,每次更新文件需要创建一个新的 {N+1}.index.json,并将其 version 设置为 N + 1
  55. }
  56. }

组件

组件元信息文件记录了特定组件的平台以及版本信息。

其格式如下:

  1. {
  2. "signatures": [ # 该文件的签名
  3. {
  4. "keyid": "{id-of-index-key-1}", # 第一个参与签名的 key 的 ID
  5. "sig": "{signature-by-index-key-1}", # 该私钥对此文件 signed 部分签名的结果
  6. },
  7. ...
  8. {
  9. "keyid": "{id-of-root-key-N}", # 第 N 个参与签名私钥的 ID
  10. "sig": "{signature-by-root-key-N}" # 该私钥对此文件 signed 部分签名的结果
  11. }
  12. ],
  13. "signed": {
  14. "_type": "component", # 指示该文件类型
  15. "description": "{description-of-the-component}", # 该组件的描述信息
  16. "expires": "{expiration-date-of-this-file}", # 该文件的过期时间,过期后客户端会拒绝此文件
  17. "id": "{component-id}", # 该组件的 id,具有全局唯一性
  18. "nightly": "{nightly-cursor}", # nightly 游标,值为最新的 nightly 的版本号(如 v5.0.0-nightly-20201209)
  19. "platforms": { # 该组件支持的平台(如 darwin/amd64,linux/arm64 等)
  20. "{platform-pair-1}": {
  21. "{version-1}": { # Semantic Version 版本号(如 v1.0.0 等)
  22. "dependencies": null, # 用于约定组件之间的依赖关系,该字段尚未使用,固定为 null
  23. "entry": "{entry}", # 入口二进制文件位于 tar 包的相对路径
  24. "hashs": { # tar 包的 checksum,我们使用 sha256 和 sha512
  25. "sha256": "{sum-of-sha256}",
  26. "sha512": "{sum-of-sha512}",
  27. },
  28. "length": {length-of-tar}, # tar 包的长度
  29. "released": "{release-time}", # 该版本的 release 时间
  30. "url": "{url-of-tar}", # tar 包的下载地址
  31. "yanked": {bool} # 该版本是否已被禁用
  32. }
  33. },
  34. ...
  35. "{platform-pair-N}": {
  36. ...
  37. }
  38. },
  39. "spec_version": "0.1.0", # 本文件遵循的规范版本,未来变更文件结构需要升级版本号,目前为 0.1.0
  40. "version": {N} # 本文件的版本号,每次更新文件需要创建一个新的 {N+1}.{component}.json,并将其 version 设置为 N + 1
  41. }

快照

快照文件记录了各个元文件当前的版本号。

其格式如下:

  1. {
  2. "signatures": [ # 该文件的签名
  3. {
  4. "keyid": "{id-of-index-key-1}", # 第一个参与签名的 key 的 ID
  5. "sig": "{signature-by-index-key-1}", # 该私钥对此文件 signed 部分签名的结果
  6. },
  7. ...
  8. {
  9. "keyid": "{id-of-root-key-N}", # 第 N 个参与签名私钥的 ID
  10. "sig": "{signature-by-root-key-N}" # 该私钥对此文件 signed 部分签名的结果
  11. }
  12. ],
  13. "signed": {
  14. "_type": "snapshot", # 指示该文件类型
  15. "expires": "{expiration-date-of-this-file}", # 该文件的过期时间,过期后客户端会拒绝此文件
  16. "meta": { # 其他元文件的信息
  17. "/root.json": {
  18. "length": {length-of-json-file}, # root.json 的长度
  19. "version": {version-of-json-file} # root.json 的 version
  20. },
  21. "/index.json": {
  22. "length": {length-of-json-file},
  23. "version": {version-of-json-file}
  24. },
  25. "/{component-1}.json": {
  26. "length": {length-of-json-file},
  27. "version": {version-of-json-file}
  28. },
  29. ...
  30. "/{component-N}.json": {
  31. ...
  32. }
  33. },
  34. "spec_version": "0.1.0", # 本文件遵循的规范版本,未来变更文件结构需要升级版本号,目前为 0.1.0
  35. "version": 0 # 本文件的版本号,固定为 0
  36. }

时间戳

时间戳文件记录了当前快照 checksum。

其文件格式如下:

  1. {
  2. "signatures": [ # 该文件的签名
  3. {
  4. "keyid": "{id-of-index-key-1}", # 第一个参与签名的 key 的 ID
  5. "sig": "{signature-by-index-key-1}", # 该私钥对此文件 signed 部分签名的结果
  6. },
  7. ...
  8. {
  9. "keyid": "{id-of-root-key-N}", # 第 N 个参与签名私钥的 ID
  10. "sig": "{signature-by-root-key-N}" # 该私钥对此文件 signed 部分签名的结果
  11. }
  12. ],
  13. "signed": {
  14. "_type": "timestamp", # 指示该文件类型
  15. "expires": "{expiration-date-of-this-file}", # 该文件的过期时间,过期后客户端会拒绝此文件
  16. "meta": { # snapshot.json 的信息
  17. "/snapshot.json": {
  18. "hashes": {
  19. "sha256": "{sum-of-sha256}" # snapshot.json 的 sha256
  20. },
  21. "length": {length-of-json-file} # snapshot.json 的长度
  22. }
  23. },
  24. "spec_version": "0.1.0", # 本文件遵循的规范版本,未来变更文件结构需要升级版本号,目前为 0.1.0
  25. "version": {N} # 本文件的版本号,每次更新文件需要覆盖 timestamp.json,并将其 version 设置为 N + 1

客户端工作流程

客户端通过以下逻辑保证从镜像下载到的文件是安全的:

  • 客户端安装时随 binary 附带了一个 root.json
  • 客户端运行时以已有的 root.json 为基础,做如下操作:
    1. 获取 root.json 中的 version,记为 N
    2. 向镜像请求 {N+1}.root.json,若成功,使用 root.json 中记录的公钥验证该文件是否合法
  • 向镜像请求 timestamp.json,并使用 root.json 中记录的公钥验证该文件是否合法
  • 检查 timestamp.json 中记录的 snapshot.json 的 checksum 和本地的 snapshot.json 的 checksum 是否吻合
    • 若不吻合,则向镜像请求最新的 snapshot.json 并使用 root.json 中记录的公钥验证该文件是否合法
  • 对于 index.json 文件,从 snapshot.json 中获取其版本号 N,并请求 {N}.index.json,然后使用 root.json 中记录的公钥验证该文件是否合法
  • 对于组件(如 tidb.json,tikv.json),从 snapshot.json 中获取其版本号 N,并请求 {N}.{component}.json,然后使用 index.json 中记录的公钥验证该文件是否合法
  • 对于组件 tar 文件,从 {component}.json 中获取其 url 及 checksum,请求 url 得到 tar 包,并验证 checksum 是否正确