制品与目录
已发布的制品：列表、详细信息、内容、注解、引用、搜索、目录审计及其变更流。
本组中的操作及其访问规则、重试规则、参数和响应。每个请求都需携带密钥：Authorization: Bearer <密钥>（参见“身份验证”）。
操作
获取制品的注解
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/annotations
访问: 仓库权限：annotation.read; 文件密钥：read · 重试: 可安全重试（读取）
返回已发布制品当前的标签、元数据和集合及其 revision。修订版本 0 表示它们从未被替换过：标签和元数据是创建上传时给出的值，集合为空。将该修订版本作为 expectedRevision 传给 setAnnotations。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
revision | integer | 是 | 0–2147483647 |
labels | 数组（string） | 是 | 最多 32 项 |
metadata | 映射（string） | 是 | 最多 32 个条目 |
collections | 数组（string） | 是 | 最多 32 项 |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
-H "Authorization: Bearer $ARKVORY_TOKEN"替换制品的注解
PUT /api/v1/repositories/{repository}/artifacts/{id}/annotations
访问: 仓库权限：annotation.write, artifact.read; 文件密钥：read, write · 重试: 仅在携带预期修订版本时重试（compare-and-swap）
一次性替换已发布制品的 labels、metadata 和 collections；value 中省略的字段会变为空。expectedRevision 必须是当前修订版本（首次变更时为 0），否则返回 409 revision_mismatch：请重新读取注解，再重新应用变更。最多 32 个标签、32 个集合（每个 1–64 个字母、数字或 _.:-）和 32 个元数据条目（值最长 1024 个字符）；字节和原始描述符永远不会改变。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
请求正文 (application/json)
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
expectedRevision | integer | 是 | 0–2147483646 |
value | object | 是 | — |
value.labels | 数组（string） | 否 | 最多 32 项 |
value.metadata | 映射（string） | 否 | 最多 32 个条目 |
value.collections | 数组（string） | 否 | 最多 32 项 |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
revision | integer | 是 | 0–2147483647 |
labels | 数组（string） | 是 | 最多 32 项 |
metadata | 映射（string） | 是 | 最多 32 个条目 |
collections | 数组（string） | 是 | 最多 32 项 |
响应: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
示例
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"value":{}}'将制品注册为 UPack 包
POST /api/v1/repositories/{repository}/artifacts/{id}/package
访问: 仓库权限：package.publish, artifact.read; 文件密钥：read, write · 重试: 可安全重试：相同的请求效果相同
将已发布的制品作为 UPack ZIP 打开，读取根目录下的 upack.json（name、可选的 group、SemVer version），并为其注册该包版本；不安全或无效的归档会被拒绝并返回 400。版本不可变：再次注册同一个制品会返回相同的条目，而用另一个制品注册已存在的包组、名称和版本（比较时不区分大小写）则返回 409 version_exists。此后该版本会出现在 listPackages 中，并可按名称、版本范围和阶段解析。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
group | string | 否 | — |
name | string | 否 | — |
version | string | 否 | — |
artifactId | string (uuid) | 否 | — |
manifest | object | 否 | — |
响应: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
示例
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/package" \
-H "Authorization: Bearer $ARKVORY_TOKEN"搜索制品
GET HEAD /api/v1/repositories/{repository}/search
访问: 仓库权限：artifact.list; 文件密钥：read · 重试: 可安全重试（读取）
按以下条件查找已发布的制品：q（名称或当前元数据值的子串，不区分大小写）、精确匹配的当前 label、collection，以及精确匹配的 metadataKey/metadataValue 键值对（两者须同时提供）；所有给出的过滤条件必须同时满足。结果按每页 100 条、按 ID 排序，每项包含大小、创建和发布时间、当前标签和晋级阶段；将 after 设为 next 即可继续。不返回元数据和集合：请用 getAnnotations 读取。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
q | 查询 | string | 否 | — |
label | 查询 | string | 否 | — |
collection | 查询 | string | 否 | — |
after | 查询 | string | 否 | — |
metadataKey | 查询 | string | 否 | 匹配 ^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$; 最多 64 个字符; Exact metadata key; requires metadataValue. |
metadataValue | 查询 | string | 否 | 最多 1024 个字符; Exact case-sensitive value; requires metadataKey. Empty string is allowed. |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
items | 数组（object） | 是 | 最多 100 项 |
items[].id | string (uuid) | 是 | — |
items[].name | string | 是 | — |
items[].size | string | 是 | 用十进制数字表示的整数，以字符串形式发送; 字节大小，十进制字符串 |
items[].createdAt | string (date-time) | 是 | 上传预留时间 |
items[].publishedAt | string (date-time) | 是 | 可以为 null; 发布时间；仅在没有记录时为 null |
items[].labels | 数组（string） | 是 | 最多 32 项; 当前标签：已被替换时取自注解，否则取自上传描述符 |
items[].stages | 数组（string） | 是 | 最多 16 项; 每项：匹配 ^[a-z0-9][a-z0-9_.-]{0,31}$; 当前晋级阶段，按字节顺序排列 |
next | string (uuid) | 是 | 可以为 null; 满页时为最后一个 ID；作为 after 传入 |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/search" \
-H "Authorization: Bearer $ARKVORY_TOKEN"读取仓库的目录审计
GET HEAD /api/v1/repositories/{repository}/audit
访问: 仓库权限：audit.read; 文件密钥：write · 重试: 可安全重试（读取）
按从旧到新的顺序，返回仓库在序号 after（默认 0）之后的最多 100 条目录变更：发布、删除、注解和附件变更、包注册、文件路径变更、引用、阶段和晋级，每条包含操作者、操作、制品和时间。要继续读取，请将页面中最后一个 sequence 作为 after 传入；没有 next 字段。其中不含下载和登录；镜像使用 listCatalogChanges 来跟进变更，该接口省略操作者。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | 查询 | string | 否 | — |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
items | 数组（object） | 否 | — |
items[].sequence | string | 否 | — |
items[].actor | string | 否 | — |
items[].action | string | 否 | — |
items[].artifactId | string | 否 | — |
items[].occurredAt | string (date-time) | 否 | — |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/audit" \
-H "Authorization: Bearer $ARKVORY_TOKEN"为制品添加引用
POST /api/v1/repositories/{repository}/artifacts/{id}/references
访问: 仓库权限：reference.write, artifact.read; 文件密钥：read, write · 重试: 可安全重试：相同的请求效果相同
记录 Arkvory 之外的某个对象正在使用此制品，使用您自选的 key（1–256 个字母、数字或 _.:/-），例如某个部署的名称。被引用的制品在所有引用都被移除之前，不能被删除，也不会被保留规则移除。引用属于调用方；用相同的键再次添加不会产生任何变化。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
请求正文 (application/json)
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
key | string | 是 | 最多 256 个字符 |
响应: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
示例
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/references" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"key":"<key>"}'移除制品的引用
DELETE /api/v1/repositories/{repository}/artifacts/{id}/references
访问: 仓库权限：reference.write, artifact.read; 文件密钥：read, write · 重试: 可安全重试：相同的请求效果相同
从制品中移除调用方自己的引用 key；其他调用方的引用保持不变。移除不存在的键同样会成功。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
请求正文 (application/json)
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
key | string | 是 | 最多 256 个字符 |
响应: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
示例
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/references" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"key":"<key>"}'列出制品
GET HEAD /api/v1/repositories/{repository}/artifacts
访问: 仓库权限：artifact.list; 文件密钥：read · 重试: 可安全重试（读取）
按 ID 排序，列出仓库中已发布的制品，每页 limit 项（1–100，默认 50）；将 after 设为 next 即可继续。只要页面已满就会设置 next，因此最后一页可能为空。每项带有上传时给出的描述符；当前的标签和元数据见 getAnnotations。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | 查询 | string (uuid) | 否 | — |
limit | 查询 | integer | 否 | 1–100; 默认值 50 |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
items | 数组（object） | 否 | — |
items[].id | string (uuid) | 是 | — |
items[].repository | string | 是 | — |
items[].status | string | 是 | 取值之一：pending, available, cancelled |
items[].createdAt | string (date-time) | 是 | — |
items[].expiresAt | string (date-time) | 是 | — |
items[].descriptor | object | 是 | — |
items[].descriptor.name | string | 是 | 1–240 个字符 |
items[].descriptor.size | string | 是 | 用十进制数字表示的整数，以字符串形式发送 |
items[].descriptor.sha256 | string | 是 | SHA-256：64 位小写十六进制数字 |
items[].descriptor.labels | 数组（string） | 否 | 最多 32 项; 每项：最多 64 个字符 |
items[].descriptor.metadata | 映射（string） | 否 | 最多 32 个条目 |
next | string | 否 | 可以为 null |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts" \
-H "Authorization: Bearer $ARKVORY_TOKEN"获取制品
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}
访问: 仓库权限：artifact.read; 文件密钥：read · 重试: 可安全重试（读取）
返回已发布的制品：其 ID、仓库、状态、创建时间，以及上传时给出的描述符（名称、大小、SHA-256、原始标签和元数据）。待完成、已取消和已删除的制品返回 404。要读取字节，请使用 downloadArtifact。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
id | string (uuid) | 是 | — |
repository | string | 是 | — |
status | string | 是 | 取值之一：pending, available, cancelled |
createdAt | string (date-time) | 是 | — |
expiresAt | string (date-time) | 是 | — |
descriptor | object | 是 | — |
descriptor.name | string | 是 | 1–240 个字符 |
descriptor.size | string | 是 | 用十进制数字表示的整数，以字符串形式发送 |
descriptor.sha256 | string | 是 | SHA-256：64 位小写十六进制数字 |
descriptor.labels | 数组（string） | 否 | 最多 32 项; 每项：最多 64 个字符 |
descriptor.metadata | 映射（string） | 否 | 最多 32 个条目 |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"删除制品
DELETE /api/v1/repositories/{repository}/artifacts/{id}
访问: 仓库权限：artifact.delete · 重试: 可安全重试：相同的请求效果相同
逻辑删除已发布的制品：它会立即从列表、搜索和下载中消失，其字节在宽限期后由仓库的在线物理清理（setCleanup，默认关闭）回收。expectedAnnotationRevision 必须等于当前的注解修订版本。响应为 200，带有 outcome：deleted、already_deleted、changed（修订版本不同）、not_found，或 protected 并附带阻止删除的 blockers（引用、文件路径修订版本、构建附件或晋级阶段）。请事先用 inspectArtifactDeletion 检查。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
请求正文 (application/json)
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
expectedAnnotationRevision | integer | 是 | 0–2147483647 |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
id | string (uuid) | 是 | — |
outcome | string | 是 | 取值之一：deleted, already_deleted, protected, changed, not_eligible, not_found |
blockers | 数组（string） | 是 | 最多 4 项; 不允许重复项; 每项：取值之一：reference, asset_history, attachment_history, protected_label, promotion_stage |
响应: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
示例
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedAnnotationRevision":0}'下载制品
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/content
访问: 仓库权限：content.read; 文件密钥：read · 重试: 可安全重试（读取）
以流式返回原始字节，附带 Content-Length、Content-Disposition（制品名称）和强 ETag（"sha256:<hex>"）。单个 Range 返回 206（无法满足时返回 416）；带 ETag 的 If-Range 可安全续传，If-None-Match 返回 304。HEAD 返回相同的响应头但没有响应体，并忽略 Range。请求也可以不带 Authorization 头，而是把 createDownloadLink 生成的下载链接作为 token 携带；下载会等待服务器下载准入的空闲槽位。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
Range | 标头 | string | 否 | — |
If-Range | 标头 | string | 否 | — |
If-None-Match | 标头 | string | 否 | — |
Arkvory-Download-Id | 标头 | string | 否 | 匹配 ^[A-Za-z0-9_-]{16,64}$; The client own id of one download, the same on every range of it: the queue keys the session by it instead of the client address, answers a waiting request at once with 503 download_queued, and may ask it to yield its place at a range boundary. Without it, a waiting request is held until its turn for a bounded time. |
Arkvory-Queue-Ticket | 标头 | string | 否 | 最多 80 个字符; The last Arkvory-Queue-Ticket the server sent for this download: after a server restart the download takes its old turn. A ticket that is wrong, expired or of another download is ignored. |
Arkvory-Download-Class | 标头 | string | 否 | 取值之一：interactive, release, bulk, background; Queue class of the download. Only a class lower than the caller own one applies (people: interactive, services and links: release); an unknown value is 400. The response names the class applied. |
token | 查询 | string | 否 | 匹配 ^dtl_[A-Za-z0-9_-]{43}$; Download link from POST …/artifacts/{id}/links, instead of an Authorization header |
响应: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/content" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o file读取站点概览
GET HEAD /api/v1/fleet/overview
访问: 管理员 · 重试: 可安全重试（读取）
受管站点和本安装的告警，最严重的在前（critical、warning、info），以及它们之间的镜像关联。根据最近的后台读取构建，最多每 5 秒一次。没有受管站点在其地址上应答的源记为 external:<origin>；本安装为 self，只有设置了 ARKVORY_SITE_URL 时才会出现指向它的关联。仅由写入进程应答。
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
generatedAt | string (date-time) | 是 | — |
self | object | 是 | — |
self.name | string | 是 | — |
self.version | string | 是 | — |
self.url | string | 是 | 可以为 null |
alerts | 数组（object） | 是 | — |
alerts[].site | string | 是 | — |
alerts[].name | string | 是 | — |
alerts[].kind | string | 是 | 取值之一：unreachable, certificate, revoked, refused, invalid, stale, not-writable, copies, single-copy, mirror-failing, mirror-lag, updates-failed, version-skew |
alerts[].severity | string | 是 | 取值之一：critical, warning, info |
alerts[].subject | string | 是 | 可以为 null |
alerts[].since | string (date-time) | 是 | 可以为 null |
links | 数组（object） | 是 | — |
links[].from | string | 是 | — |
links[].to | string | 是 | — |
links[].repository | string | 是 | — |
links[].sourceRepository | string | 是 | — |
links[].mode | string | 是 | 取值之一：mirror, import |
links[].lagChanges | string | 是 | 用十进制数字表示的整数，以字符串形式发送; 可以为 null |
links[].failing | boolean | 是 | — |
links[].stale | boolean | 否 | — |
external | 数组（string） | 是 | — |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/fleet/overview" \
-H "Authorization: Bearer $ARKVORY_TOKEN"列出受管站点
GET HEAD /api/v1/fleet/sites
访问: 管理员 · 重试: 可安全重试（读取）
列出本安装管理的站点（ADR 0077）及每个站点最后报告的内容：state（ok，或未能读取的原因：unreachable、certificate、revoked、invalid、refused）、最后一次可见的时间以及最后的 topology。站点每 30 秒在后台读取一次。从不返回站点密钥。
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
items | 数组（object） | 是 | 最多 256 项 |
items[].id | string (uuid) | 是 | — |
items[].name | string | 是 | — |
items[].url | string | 是 | — |
items[].fingerprint | string | 是 | 匹配 ^[0-9a-f]{64}$; 可以为 null |
items[].addedBy | string | 是 | — |
items[].addedAt | string (date-time) | 是 | — |
items[].seenAt | string (date-time) | 是 | 可以为 null |
items[].state | string | 是 | 取值之一：pending, ok, unreachable, certificate, revoked, invalid, refused |
items[].error | string | 是 | 可以为 null |
items[].topology | object | 是 | 可以为 null |
items[].topology.collectedAt | string (date-time) | 是 | — |
items[].topology.site | object | 是 | — |
items[].topology.health | object | 是 | — |
items[].topology.replication | object | 是 | 可以为 null |
items[].topology.gateways | 数组（object） | 是 | 最多 16 项 |
items[].topology.mirrors | 数组（object） | 是 | 最多 64 项 |
items[].topology.updates | object | 是 | 可以为 null |
items[].topology.downloads | object | 是 | — |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites" \
-H "Authorization: Bearer $ARKVORY_TOKEN"与站点配对
POST /api/v1/fleet/sites
访问: 管理员 · 重试: 请勿自动重试
与站点配对：控制站点重新连接，证书必须仍具有管理员确认的 fingerprint（loopback 上的 HTTP 为 null），在站点上生成的配对 code 被换成密钥，密钥用 ARKVORY_FLEET_KEY_FILE 封存。应答前读取一次站点。没有密钥文件时应答 503。
请求正文 (application/json)
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
url | string | 是 | — |
fingerprint | string | 是 | 匹配 ^[0-9a-f]{64}$; 可以为 null |
code | string | 是 | 最多 32 个字符 |
响应 201
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
id | string (uuid) | 是 | — |
name | string | 是 | — |
url | string | 是 | — |
fingerprint | string | 是 | 匹配 ^[0-9a-f]{64}$; 可以为 null |
addedBy | string | 是 | — |
addedAt | string (date-time) | 是 | — |
seenAt | string (date-time) | 是 | 可以为 null |
state | string | 是 | 取值之一：pending, ok, unreachable, certificate, revoked, invalid, refused |
error | string | 是 | 可以为 null |
topology | object | 是 | 可以为 null |
topology.collectedAt | string (date-time) | 是 | — |
topology.site | object | 是 | — |
topology.site.name | string | 是 | — |
topology.site.version | string | 是 | — |
topology.site.schema | integer | 是 | 不小于 0 |
topology.site.role | string | 是 | 取值之一：api, reader |
topology.health | object | 是 | — |
topology.health.available | boolean | 是 | — |
topology.health.writable | boolean | 是 | — |
topology.health.draining | boolean | 是 | — |
topology.replication | object | 是 | 可以为 null |
topology.replication.copies | integer | 是 | 0–16 |
topology.replication.required | integer | 是 | 1–16 |
topology.replication.singleCopyUntil | string (date-time) | 是 | 可以为 null |
topology.replication.node | string | 否 | 最多 63 个字符 |
topology.replication.profile | string | 否 | 取值之一：ha-2, ha-3 |
topology.replication.peers | 数组（object） | 否 | 最多 16 项 |
topology.gateways | 数组（object） | 是 | 最多 16 项 |
topology.gateways[].slot | integer | 是 | 不小于 0 |
topology.gateways[].active | boolean | 是 | — |
topology.gateways[].expiresAt | string (date-time) | 是 | — |
topology.mirrors | 数组（object） | 是 | 最多 64 项 |
topology.mirrors[].repository | string | 是 | — |
topology.mirrors[].mode | string | 是 | 取值之一：mirror, import |
topology.mirrors[].upstream | string | 是 | — |
topology.mirrors[].sourceRepository | string | 是 | — |
topology.mirrors[].phase | string | 是 | — |
topology.mirrors[].errorCode | string | 是 | 可以为 null |
topology.mirrors[].checkedAt | string (date-time) | 是 | 可以为 null |
topology.mirrors[].syncedAt | string (date-time) | 是 | 可以为 null |
topology.mirrors[].lagChanges | string | 是 | 用十进制数字表示的整数，以字符串形式发送; 可以为 null |
topology.mirrors[].copiedArtifacts | integer | 是 | 不小于 0 |
topology.mirrors[].copiedBytes | string | 是 | 用十进制数字表示的整数，以字符串形式发送 |
topology.updates | object | 是 | 可以为 null |
topology.updates.currentVersion | string | 是 | — |
topology.updates.latest | string | 是 | 可以为 null |
topology.updates.phase | string | 是 | — |
topology.updates.error | string | 是 | 可以为 null |
topology.updates.automatic | boolean | 是 | — |
topology.updates.heartbeatAt | string (date-time) | 是 | — |
topology.downloads | object | 是 | — |
topology.downloads.strategy | string | 是 | 取值之一：ordered, smallest-first, shared |
topology.downloads.sessions | integer | 是 | 不小于 0 |
topology.downloads.active | integer | 是 | 不小于 0 |
topology.downloads.waiting | integer | 是 | 不小于 0 |
topology.downloads.oldestWaitSeconds | integer | 是 | 不小于 0 |
topology.downloads.bytesPerSecond | integer | 是 | 不小于 0 |
响应: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
示例
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"<url>","fingerprint":"<fingerprint>","code":"<code>"}'读取站点证书
POST /api/v1/fleet/sites/probe
访问: 管理员 · 重试: 可安全重试：相同的请求效果相同
连接到该地址并读取站点出示的证书，不发送任何内容：配对前将其 fingerprint 与站点管理员看到的指纹进行比较。
请求正文 (application/json)
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
url | string | 是 | — |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
url | string | 是 | — |
certificate | object | 是 | 可以为 null |
certificate.fingerprint | string | 是 | 匹配 ^[0-9a-f]{64}$ |
certificate.subject | string | 是 | — |
certificate.issuer | string | 是 | — |
certificate.validTo | string (date-time) | 是 | — |
响应: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
示例
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/probe" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"<url>"}'忘记站点
DELETE /api/v1/fleet/sites/{id}
访问: 管理员 · 重试: 可安全重试：相同的请求效果相同
在此处删除站点及其封存的密钥。也请在站点上撤销此控制站点；在此之前密钥在那里仍然有效。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
id | 路径 | string (uuid) | 是 | — |
响应: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
示例
curl -X DELETE "$ARKVORY_URL/api/v1/fleet/sites/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"读取站点目录
GET HEAD /api/v1/fleet/sites/{id}/read
访问: 管理员 · 重试: 可安全重试（读取）
将一次目录读取转发给受管站点，并原样返回其应答：仓库、搜索、制品、注释、阶段、包、文件页面和历史、存储用量、镜像状态。path 是站点路由及其查询。其他路由和文件字节以 400 拒绝。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
id | 路径 | string (uuid) | 是 | — |
path | 查询 | string | 是 | 匹配 ^/api/v1/; 最多 2048 个字符; A read route of the site with its query, from a fixed list: catalog metadata (repositories, search, artifacts, annotations, stages, packages, file pages and history, storage usage, mirror state), download queue settings and update state. Never file bytes. |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites/$ID/read?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"更改站点的设置
POST /api/v1/fleet/sites/{id}/change
访问: 管理员 · 重试: 请勿自动重试
将一次更改转发给受管站点，并原样返回其应答。path 为以下路由之一：/api/v1/system/downloads/settings（下载队列设置，以 PUT 发送）或 /api/v1/system/updates/requests（更新请求，以 POST 发送）。请求体原样发送到站点；站点检查修订号或请求 id，因此重复的更改不会应用两次。其他路径以 400 拒绝。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
id | 路径 | string (uuid) | 是 | — |
path | 查询 | string | 是 | 匹配 ^/api/v1/; 最多 2048 个字符; A change route of the site, from a fixed list: PUT /api/v1/system/downloads/settings, POST /api/v1/system/updates/requests. |
请求正文 (application/json)
响应: 200, 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
示例
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/change?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'立即读取站点
POST /api/v1/fleet/sites/{id}/refresh
访问: 管理员 · 重试: 可安全重试：相同的请求效果相同
立即读取站点而不等待下一轮，并返回其新状态。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
id | 路径 | string (uuid) | 是 | — |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
id | string (uuid) | 是 | — |
name | string | 是 | — |
url | string | 是 | — |
fingerprint | string | 是 | 匹配 ^[0-9a-f]{64}$; 可以为 null |
addedBy | string | 是 | — |
addedAt | string (date-time) | 是 | — |
seenAt | string (date-time) | 是 | 可以为 null |
state | string | 是 | 取值之一：pending, ok, unreachable, certificate, revoked, invalid, refused |
error | string | 是 | 可以为 null |
topology | object | 是 | 可以为 null |
topology.collectedAt | string (date-time) | 是 | — |
topology.site | object | 是 | — |
topology.site.name | string | 是 | — |
topology.site.version | string | 是 | — |
topology.site.schema | integer | 是 | 不小于 0 |
topology.site.role | string | 是 | 取值之一：api, reader |
topology.health | object | 是 | — |
topology.health.available | boolean | 是 | — |
topology.health.writable | boolean | 是 | — |
topology.health.draining | boolean | 是 | — |
topology.replication | object | 是 | 可以为 null |
topology.replication.copies | integer | 是 | 0–16 |
topology.replication.required | integer | 是 | 1–16 |
topology.replication.singleCopyUntil | string (date-time) | 是 | 可以为 null |
topology.replication.node | string | 否 | 最多 63 个字符 |
topology.replication.profile | string | 否 | 取值之一：ha-2, ha-3 |
topology.replication.peers | 数组（object） | 否 | 最多 16 项 |
topology.gateways | 数组（object） | 是 | 最多 16 项 |
topology.gateways[].slot | integer | 是 | 不小于 0 |
topology.gateways[].active | boolean | 是 | — |
topology.gateways[].expiresAt | string (date-time) | 是 | — |
topology.mirrors | 数组（object） | 是 | 最多 64 项 |
topology.mirrors[].repository | string | 是 | — |
topology.mirrors[].mode | string | 是 | 取值之一：mirror, import |
topology.mirrors[].upstream | string | 是 | — |
topology.mirrors[].sourceRepository | string | 是 | — |
topology.mirrors[].phase | string | 是 | — |
topology.mirrors[].errorCode | string | 是 | 可以为 null |
topology.mirrors[].checkedAt | string (date-time) | 是 | 可以为 null |
topology.mirrors[].syncedAt | string (date-time) | 是 | 可以为 null |
topology.mirrors[].lagChanges | string | 是 | 用十进制数字表示的整数，以字符串形式发送; 可以为 null |
topology.mirrors[].copiedArtifacts | integer | 是 | 不小于 0 |
topology.mirrors[].copiedBytes | string | 是 | 用十进制数字表示的整数，以字符串形式发送 |
topology.updates | object | 是 | 可以为 null |
topology.updates.currentVersion | string | 是 | — |
topology.updates.latest | string | 是 | 可以为 null |
topology.updates.phase | string | 是 | — |
topology.updates.error | string | 是 | 可以为 null |
topology.updates.automatic | boolean | 是 | — |
topology.updates.heartbeatAt | string (date-time) | 是 | — |
topology.downloads | object | 是 | — |
topology.downloads.strategy | string | 是 | 取值之一：ordered, smallest-first, shared |
topology.downloads.sessions | integer | 是 | 不小于 0 |
topology.downloads.active | integer | 是 | 不小于 0 |
topology.downloads.waiting | integer | 是 | 不小于 0 |
topology.downloads.oldestWaitSeconds | integer | 是 | 不小于 0 |
topology.downloads.bytesPerSecond | integer | 是 | 不小于 0 |
响应: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
示例
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/refresh" \
-H "Authorization: Bearer $ARKVORY_TOKEN"创建配对码
POST /api/v1/system/fleet/pairings
访问: 管理员 · 重试: 请勿自动重试
创建一个一次性、十分钟有效的代码，控制站点的管理员输入它即可管理本站点。代码只显示一次，只以哈希形式保存。只有站点的全局管理员可以创建。
响应 201
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
code | string | 是 | 匹配 ^[0-9A-Z]{4}-[0-9A-Z]{4}-[0-9A-Z]{4}$ |
expiresAt | string (date-time) | 是 | — |
fingerprint | string | 是 | 匹配 ^[0-9a-f]{64}$; 可以为 null |
响应: 201, 400, 401, 403, 404, 405, 409, 422, 503, 507
示例
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/pairings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"列出本站点的控制站点
GET HEAD /api/v1/system/fleet/controllers
访问: 管理员 · 重试: 可安全重试（读取）
列出可以管理本站点的控制站点：名称、由谁配对、何时配对，以及其密钥最后一次使用的时间。
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
items | 数组（object） | 是 | 最多 100 项 |
items[].id | string (uuid) | 是 | — |
items[].name | string | 是 | — |
items[].pairedBy | string | 是 | — |
items[].pairedAt | string (date-time) | 是 | — |
items[].usedAt | string (date-time) | 是 | 可以为 null |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/system/fleet/controllers" \
-H "Authorization: Bearer $ARKVORY_TOKEN"撤销控制站点
DELETE /api/v1/system/fleet/controllers/{id}
访问: 管理员 · 重试: 可安全重试：相同的请求效果相同
撤销一个控制站点：其集群密钥立即被拒绝。要再次管理本站点，必须用新代码重新配对。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
id | 路径 | string (uuid) | 是 | — |
响应: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
示例
curl -X DELETE "$ARKVORY_URL/api/v1/system/fleet/controllers/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"与控制站点配对
POST /api/v1/system/fleet/enrollment
访问: 任何人，无需密钥 · 重试: 请勿自动重试
用一个有效的配对码一次性换取集群密钥。控制站点通过固定在管理员确认的指纹上的 TLS 调用它。密钥只返回一次，只能访问控制站点所需的路由。
请求正文 (application/json)
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
code | string | 是 | 最多 32 个字符 |
name | string | 是 | 1–63 个字符 |
响应 201
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
key | string | 是 | 匹配 ^afk_[A-Za-z0-9_-]{43}$ |
site | object | 是 | — |
site.name | string | 是 | — |
site.version | string | 是 | — |
响应: 201, 400, 403, 405, 413, 415, 503
示例
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/enrollment" \
-H "Content-Type: application/json" \
-d '{"code":"<code>","name":"<name>"}'获取本站点供集群控制台使用
GET HEAD /api/v1/system/topology
访问: 管理员 · 重试: 可安全重试（读取）
把本安装作为集群中的一个站点返回（ADR 0077）：名称、版本、架构和角色，是否可用、是否可写，HA 副本和节点，按租约列出的只读网关，每个镜像和导入及其阶段、最后同步时间和 lagChanges（源中尚未应用的变更），更新代理状态和下载队列。只有站点的全局管理员或已配对的控制站点可以读取。
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
collectedAt | string (date-time) | 是 | — |
site | object | 是 | — |
site.name | string | 是 | — |
site.version | string | 是 | — |
site.schema | integer | 是 | 不小于 0 |
site.role | string | 是 | 取值之一：api, reader |
health | object | 是 | — |
health.available | boolean | 是 | — |
health.writable | boolean | 是 | — |
health.draining | boolean | 是 | — |
replication | object | 是 | 可以为 null |
replication.copies | integer | 是 | 0–16 |
replication.required | integer | 是 | 1–16 |
replication.singleCopyUntil | string (date-time) | 是 | 可以为 null |
replication.node | string | 否 | 最多 63 个字符 |
replication.profile | string | 否 | 取值之一：ha-2, ha-3 |
replication.peers | 数组（object） | 否 | 最多 16 项 |
replication.peers[].name | string | 是 | 最多 63 个字符 |
replication.peers[].connected | boolean | 是 | — |
replication.peers[].disk | string | 是 | 最多 24 个字符 |
replication.peers[].complete | boolean | 是 | — |
replication.peers[].witness | boolean | 是 | — |
gateways | 数组（object） | 是 | 最多 16 项 |
gateways[].slot | integer | 是 | 不小于 0 |
gateways[].active | boolean | 是 | — |
gateways[].expiresAt | string (date-time) | 是 | — |
mirrors | 数组（object） | 是 | 最多 64 项 |
mirrors[].repository | string | 是 | — |
mirrors[].mode | string | 是 | 取值之一：mirror, import |
mirrors[].upstream | string | 是 | — |
mirrors[].sourceRepository | string | 是 | — |
mirrors[].phase | string | 是 | — |
mirrors[].errorCode | string | 是 | 可以为 null |
mirrors[].checkedAt | string (date-time) | 是 | 可以为 null |
mirrors[].syncedAt | string (date-time) | 是 | 可以为 null |
mirrors[].lagChanges | string | 是 | 用十进制数字表示的整数，以字符串形式发送; 可以为 null |
mirrors[].copiedArtifacts | integer | 是 | 不小于 0 |
mirrors[].copiedBytes | string | 是 | 用十进制数字表示的整数，以字符串形式发送 |
updates | object | 是 | 可以为 null |
updates.currentVersion | string | 是 | — |
updates.latest | string | 是 | 可以为 null |
updates.phase | string | 是 | — |
updates.error | string | 是 | 可以为 null |
updates.automatic | boolean | 是 | — |
updates.heartbeatAt | string (date-time) | 是 | — |
downloads | object | 是 | — |
downloads.strategy | string | 是 | 取值之一：ordered, smallest-first, shared |
downloads.sessions | integer | 是 | 不小于 0 |
downloads.active | integer | 是 | 不小于 0 |
downloads.waiting | integer | 是 | 不小于 0 |
downloads.oldestWaitSeconds | integer | 是 | 不小于 0 |
downloads.bytesPerSecond | integer | 是 | 不小于 0 |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/system/topology" \
-H "Authorization: Bearer $ARKVORY_TOKEN"读取下载队列设置
GET HEAD /api/v1/system/downloads/settings
访问: 管理员 · 重试: 可安全重试（读取）
返回已更改的值（overrides）、服务器环境设定的值（defaults）以及队列当前使用的值（effective），并附带更改时需传回的修订号。problem 说明已保存的设置为何不适用于此服务器；此时队列按默认值运行。
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
revision | integer | 是 | 0–9007199254740991 |
overrides | object | 是 | — |
overrides.strategy | string | 否 | 取值之一：ordered, smallest-first, shared |
overrides.sessions | integer | 否 | 1–1024 |
overrides.reserve | integer | 否 | 0–1023 |
overrides.perPrincipal | integer | 否 | 1–1024 |
overrides.weights | object | 否 | — |
overrides.weights.interactive | integer | 是 | 1–1000 |
overrides.weights.release | integer | 是 | 1–1000 |
overrides.weights.bulk | integer | 是 | 1–1000 |
overrides.weights.background | integer | 是 | 1–1000 |
overrides.sessionMinBytes | integer | 否 | 0–9007199254740991 |
overrides.idleSeconds | integer | 否 | 1–3600 |
overrides.agingMinutes | integer | 否 | 0–10080 |
overrides.preempt | boolean | 否 | — |
overrides.rangesPerSession | integer | 否 | 1–64 |
defaults | object | 是 | — |
defaults.strategy | string | 是 | 取值之一：ordered, smallest-first, shared |
defaults.sessions | integer | 是 | 1–1024 |
defaults.reserve | integer | 是 | 0–1023 |
defaults.perPrincipal | integer | 是 | 1–1024 |
defaults.weights | object | 是 | — |
defaults.weights.interactive | integer | 是 | 1–1000 |
defaults.weights.release | integer | 是 | 1–1000 |
defaults.weights.bulk | integer | 是 | 1–1000 |
defaults.weights.background | integer | 是 | 1–1000 |
defaults.sessionMinBytes | integer | 是 | 0–9007199254740991 |
defaults.idleSeconds | integer | 是 | 1–3600 |
defaults.agingMinutes | integer | 是 | 0–10080 |
defaults.preempt | boolean | 是 | — |
defaults.rangesPerSession | integer | 是 | 1–64 |
effective | object | 是 | — |
effective.strategy | string | 是 | 取值之一：ordered, smallest-first, shared |
effective.sessions | integer | 是 | 1–1024 |
effective.reserve | integer | 是 | 0–1023 |
effective.perPrincipal | integer | 是 | 1–1024 |
effective.weights | object | 是 | — |
effective.weights.interactive | integer | 是 | 1–1000 |
effective.weights.release | integer | 是 | 1–1000 |
effective.weights.bulk | integer | 是 | 1–1000 |
effective.weights.background | integer | 是 | 1–1000 |
effective.sessionMinBytes | integer | 是 | 0–9007199254740991 |
effective.idleSeconds | integer | 是 | 1–3600 |
effective.agingMinutes | integer | 是 | 0–10080 |
effective.preempt | boolean | 是 | — |
effective.rangesPerSession | integer | 是 | 1–64 |
admission | string | 是 | 取值之一：sessions, per-request |
updatedAt | string (date-time) | 是 | 可以为 null |
updatedBy | string | 是 | 可以为 null |
actor | string | 是 | 可以为 null |
problem | string | 是 | 可以为 null |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"更改下载队列设置
PUT /api/v1/system/downloads/settings
访问: 管理员 · 重试: 仅在携带预期修订版本时重试（compare-and-swap）
将 overrides 保存在服务器环境之上，并在不重启的情况下应用：新的决策立即遵循它们，正在进行的下载保留其位置。所给的值替换之前的所有更改；{} 恢复为环境值。无法在此运行的设置以 400 拒绝并指出字段；过期的 expectedRevision 得到 409。只读网关保留其环境。
请求正文 (application/json)
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
expectedRevision | integer | 是 | 0–9007199254740991 |
overrides | object | 是 | — |
overrides.strategy | string | 否 | 取值之一：ordered, smallest-first, shared |
overrides.sessions | integer | 否 | 1–1024 |
overrides.reserve | integer | 否 | 0–1023 |
overrides.perPrincipal | integer | 否 | 1–1024 |
overrides.weights | object | 否 | — |
overrides.weights.interactive | integer | 是 | 1–1000 |
overrides.weights.release | integer | 是 | 1–1000 |
overrides.weights.bulk | integer | 是 | 1–1000 |
overrides.weights.background | integer | 是 | 1–1000 |
overrides.sessionMinBytes | integer | 否 | 0–9007199254740991 |
overrides.idleSeconds | integer | 否 | 1–3600 |
overrides.agingMinutes | integer | 否 | 0–10080 |
overrides.preempt | boolean | 否 | — |
overrides.rangesPerSession | integer | 否 | 1–64 |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
revision | integer | 是 | 0–9007199254740991 |
overrides | object | 是 | — |
overrides.strategy | string | 否 | 取值之一：ordered, smallest-first, shared |
overrides.sessions | integer | 否 | 1–1024 |
overrides.reserve | integer | 否 | 0–1023 |
overrides.perPrincipal | integer | 否 | 1–1024 |
overrides.weights | object | 否 | — |
overrides.weights.interactive | integer | 是 | 1–1000 |
overrides.weights.release | integer | 是 | 1–1000 |
overrides.weights.bulk | integer | 是 | 1–1000 |
overrides.weights.background | integer | 是 | 1–1000 |
overrides.sessionMinBytes | integer | 否 | 0–9007199254740991 |
overrides.idleSeconds | integer | 否 | 1–3600 |
overrides.agingMinutes | integer | 否 | 0–10080 |
overrides.preempt | boolean | 否 | — |
overrides.rangesPerSession | integer | 否 | 1–64 |
defaults | object | 是 | — |
defaults.strategy | string | 是 | 取值之一：ordered, smallest-first, shared |
defaults.sessions | integer | 是 | 1–1024 |
defaults.reserve | integer | 是 | 0–1023 |
defaults.perPrincipal | integer | 是 | 1–1024 |
defaults.weights | object | 是 | — |
defaults.weights.interactive | integer | 是 | 1–1000 |
defaults.weights.release | integer | 是 | 1–1000 |
defaults.weights.bulk | integer | 是 | 1–1000 |
defaults.weights.background | integer | 是 | 1–1000 |
defaults.sessionMinBytes | integer | 是 | 0–9007199254740991 |
defaults.idleSeconds | integer | 是 | 1–3600 |
defaults.agingMinutes | integer | 是 | 0–10080 |
defaults.preempt | boolean | 是 | — |
defaults.rangesPerSession | integer | 是 | 1–64 |
effective | object | 是 | — |
effective.strategy | string | 是 | 取值之一：ordered, smallest-first, shared |
effective.sessions | integer | 是 | 1–1024 |
effective.reserve | integer | 是 | 0–1023 |
effective.perPrincipal | integer | 是 | 1–1024 |
effective.weights | object | 是 | — |
effective.weights.interactive | integer | 是 | 1–1000 |
effective.weights.release | integer | 是 | 1–1000 |
effective.weights.bulk | integer | 是 | 1–1000 |
effective.weights.background | integer | 是 | 1–1000 |
effective.sessionMinBytes | integer | 是 | 0–9007199254740991 |
effective.idleSeconds | integer | 是 | 1–3600 |
effective.agingMinutes | integer | 是 | 0–10080 |
effective.preempt | boolean | 是 | — |
effective.rangesPerSession | integer | 是 | 1–64 |
admission | string | 是 | 取值之一：sessions, per-request |
updatedAt | string (date-time) | 是 | 可以为 null |
updatedBy | string | 是 | 可以为 null |
actor | string | 是 | 可以为 null |
problem | string | 是 | 可以为 null |
响应: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
示例
curl -X PUT "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"overrides":{}}'读取站点更改
GET HEAD /api/v1/system/changes
访问: 管理员 · 重试: 可安全重试（读取）
返回站点代理是否在报告（agent）、待处理的请求以及最近 20 个请求及其状态：pending、applying、done 或附带原因的 failed。源密钥从不出现在这里。
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
agent | boolean | 是 | — |
updating | boolean | 是 | — |
blocked | string | 是 | 取值之一：expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; 可以为 null |
pending | object | 是 | 可以为 null |
pending.id | string (uuid) | 是 | — |
pending.kind | string | 是 | 取值之一：mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy |
pending.actor | string | 是 | 最多 200 个字符 |
pending.requestedAt | string (date-time) | 是 | — |
recent | 数组（object） | 是 | 最多 20 项 |
recent[].id | string (uuid) | 是 | — |
recent[].digest | string | 是 | 匹配 ^[0-9a-f]{64}$ |
recent[].kind | string | 是 | 取值之一：mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy |
recent[].state | string | 是 | 取值之一：pending, applying, done, failed |
recent[].error | string | 是 | 取值之一：expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; 可以为 null |
recent[].actor | string | 是 | 最多 200 个字符 |
recent[].requestedAt | string (date-time) | 是 | — |
recent[].finishedAt | string (date-time) | 是 | 可以为 null |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/system/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"将站点更改加入队列
POST /api/v1/system/changes
访问: 管理员 · 重试: 可安全重试：相同的请求效果相同
为站点代理加入一项更改，代理在一分钟内以 arkvory configure 和 cluster-* 的检查与回滚应用它：连接镜像或导入、替换其源密钥、断开镜像、切换活动 HA 节点（节点名称输入两次）或决定单副本写入。id 由客户端选择；重复它不会再次加入队列。key 仅用于 mirror-attach 和 mirror-key 的源密钥：它以单独的 0600 文件交给代理，永不返回。202 表示已入队，而非已应用。
请求正文 (application/json)
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
id | string (uuid) | 是 | — |
change | object | 是 | — |
change.kind | string | 是 | 取值之一：mirror-attach |
change.repository | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.upstream | string | 是 | 最多 255 个字符 |
change.sourceRepository | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.stages | 数组（string） | 否 | 1–16 项; 每项：匹配 ^[a-z0-9][a-z0-9_.-]{0,31}$; 可以为 null |
change.repositories | 数组（string） | 是 | 1–64 项; 每项：匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.node | string | 是 | 匹配 ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$ |
change.confirm | string | 是 | 匹配 ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$ |
change.until | string (date-time) | 是 | 可以为 null |
change.reason | string | 是 | 1–200 个字符 |
key | string | 否 | 16–4000 个字符 |
响应 202
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
id | string (uuid) | 是 | — |
响应: 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
示例
curl -X POST "$ARKVORY_URL/api/v1/system/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":"00000000-0000-4000-8000-000000000000","change":{"kind":"mirror-attach","repository":"<repository>","upstream":"<upstream>","sourceRepository":"<sourceRepository>"}}'跟踪仓库的变更流
GET HEAD /api/v1/repositories/{repository}/changes
访问: 仓库权限：artifact.list; 文件密钥：read · 重试: 可安全重试（读取）
按提交顺序，返回序号 after（默认 0）之后的最多 limit 条变更（1–100，默认 100）：操作、制品，以及对文件路径和阶段而言，在 detail 中给出的路径或阶段；不包含操作者，因此有列出权限即可。head 是仓库最新的序号，next 是下一页的游标，页面到达 head 时为 null。镜像会保存它最后应用的序号并从那里开始轮询。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | 查询 | string | 否 | 用十进制数字表示的整数，以字符串形式发送; Sequence cursor, default 0 |
limit | 查询 | integer | 否 | 1–100 |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
items | 数组（object） | 是 | — |
items[].sequence | string | 是 | 用十进制数字表示的整数，以字符串形式发送 |
items[].action | string | 是 | — |
items[].artifactId | string (uuid) | 是 | — |
items[].detail | string | 是 | 可以为 null |
head | string | 是 | 用十进制数字表示的整数，以字符串形式发送 |
next | string | 是 | 用十进制数字表示的整数，以字符串形式发送; 可以为 null |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"创建下载链接
POST /api/v1/repositories/{repository}/artifacts/{id}/links
访问: 仓库权限：content.read; 文件密钥：read · 重试: 请勿自动重试
返回机密 token、相对于 API 源的 url 和 expiresAt，可在不带密钥的情况下对这一个制品调用 downloadArtifact；ttlSeconds 设置有效期（60 秒到一天，默认一小时）。令牌只在本次响应中显示，且无法撤销：它在过期或制品被删除后失效，通过它进行的下载计入创建者的传输限制。一个调用方最多可持有 1000 个有效链接（507 token_limit），下载链接不能再创建其他链接。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 路径 | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | 路径 | string (uuid) | 是 | — |
请求正文 (application/json)
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
ttlSeconds | integer | 否 | 60–86400; 默认值 3600 |
响应 201
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
token | string | 是 | 匹配 ^dtl_[A-Za-z0-9_-]{43}$ |
url | string | 是 | — |
expiresAt | string (date-time) | 是 | — |
响应: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
示例
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/links" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'