Adoptium® 市场发布者产品列表仓库

概述

Adoptium 推广在市场中列出的产品。每个发布者管理一个包含其产品结构化信息的位置。Adoptium 会定期使用您的产品列表中的信息更新市场。该位置指的是数据资源的"仓库"。这样的仓库可以实现为简单的文件系统、动态创建的数据流、版本控制存储、数据库或其他响应 HTTP 请求并返回以下所述信息的设施。

在以下描述和示例中，为简单起见，我们将使用"文件"和"目录"来指代仓库的实现。

术语

仓库由三种类型的文件组成，分别是索引文件、发布文件和签名文件。

索引文件：描述发布文件和索引文件的位置。
发布文件：包含市场产品列表。
签名文件：包含与索引或发布文件关联的数字签名。

所有文件均以 UTF-8 编码读取。

签名文件

签名文件用于确保索引和发布文件数据已正确接收，且在传输过程中未被修改。Adoptium 市场代理将读取文件并检查相关文件签名。文件的签名存储在与被签名文件同名的文件中，后缀为 .sha256.sign。

签名必须是对整个文件内容进行 Base64 编码的 RSA 加密 SHA-256 哈希值。签名将使用您在发布者信息中提供的公钥进行验证。

有许多工具和代码示例可帮助生成此类签名。

使用 OpenSSL 生成、验证和编码签名

# Generate signature
openssl dgst -sha256 -sign private.pem -out index.json.sig index.json

# Verify
openssl dgst -sha256 -verify public.pem -signature index.json.sig index.json

#Base64 encode for publishing
cat index.json.sig | base64 -w 0 > index.json.sha256.sign

简单产品列表仓库

最简单的产品列表仓库由一个索引文件和一个发布文件以及相关数字签名组成。

顶级索引文件必须出现在仓库位置的根目录，并且必须命名为 index.json。

以下是一个简单的列表仓库示例。

Example 1. 简单仓库布局

/index.json (1)
/index.json.sha256.sign (2)
/release.json (3)
/release.json.sha256.sign (4)

1	主产品仓库索引文件。
2	索引文件的数字签名。
3	产品发布列表文件。
4	发布列表文件的数字签名。

最简单的 index.json 文件仅包含对单个 releases.json 文件的引用。

{
  "schema_version": "1.0.0",
  "releases": [
    "example.json"
  ]
}

结构化仓库布局

产品列表仓库可以使用多个索引文件和发布文件进行结构化，以满足每个供应商的发布偏好。例如，发布者可以选择按 Java 版本、平台、日历发布等生成发布文件。Adoptium 市场将从根 index.json 开始，递归遍历每个索引文件以找到所有发布文件。

作为更复杂的示例，以下仓库展示了按 Java 版本和发布标识符组织的发布文件结构。

Example 2. 结构化仓库布局

.
├── 17
│   ├── index.json
│   ├── index.json.sha256.sign
│   ├── jdk_17_0_1_12.json
│   ├── jdk_17_0_1_12.json.sha256.sign
│   ├── jdk_17_0_2_8.json
│   └── jdk_17_0_2_8.json.sha256.sign
├── 8
│   ├── index.json
│   ├── index.json.sha256.sign
│   ├── jdk8u312_b07.json
│   └── jdk8u312_b07.json.sha256.sign
├── index.json
└── index.json.sha256.sign

在此仓库中，根 /index.json 将包含

{
  "schema_version": "1.0.0",
  "indexes": [
    "8/index.json",
    "17/index.json"
  ],
  "releases": [
  ]
}

而 17/index.json 将包含

{
  "schema_version": "1.0.0",
  "indexes": [
  ],
  "releases": [
    "jdk_17_0_1_12.json",
    "jdk_17_0_2_8.json"
  ]
}

请注意，虽然在此示例中我们为每个主要 Java 版本创建了一个索引文件，并为每个 Java 发布创建了一个发布文件，但这并非强制要求。一个索引可以包含多个索引和发布，一个发布文件也可以根据需要包含多个版本发布。

Tip

每个索引和发布文件引用均相对于索引文件路径，即如果 https://release.adoptium.net/repo/17/index.json 包含 jdk_17_0_2_8.json 的发布，则将检查路径 https://release.adoptium.net/repo/17/jdk_17_0_2_8.json。

发布文件

发布文件包含有关您产品的详细信息，包括 Java 版本、目标机器架构、下载位置、测试结果位置等。发布文件的名称与 Adoptium 市场无关，只需从上述索引文件中引用即可。

您的产品发布文件列表必须遵循市场产品 JSON 模式，Adoptium 提供了示例和代码以帮助以正确格式生成产品列表数据。

Temurin 的实时发布文件可在我们的公共市场数据仓库中获取，可作为预期格式的示例。

仓库读取与市场更新流程

Adoptium 通常每小时检索一次产品列表信息，但此周期无法保证，可能会有所变化。Adoptium 可能会考虑您的 HTTP 响应 cache-control HTTP 头（如 max-age）来确定获取产品列表的频率。反过来，Adoptium 请求可能会使用条件请求（如 If-Modified-Since 头）来帮助减少工作量。

如果产品列表文件不符合模式或签名无法验证内容，则该文件将被拒绝。如果列表文件反复验证失败，我们将与您联系。

成功读取后，新的市场信息将替换该供应商之前保存的所有信息。

总结来说，更新流程如下：

更新程序拉取根索引并对照签名进行验证。
从索引中递归提取更多索引（如有），直到所有索引均已读取和验证。
从所有索引中提取所有发布文件的位置。
拉取每个发布文件并对照相应签名进行验证。
根据模式对发布文件信息进行解析和验证。
该供应商在市场中的所有产品信息均被替换。