系统与健康状况
存活状态、就绪状态、指标、OpenAPI 文档以及服务器的功能。
本组中的操作及其访问规则、重试规则、参数和响应。每个请求都需携带密钥：Authorization: Bearer <密钥>（参见“身份验证”）。
操作
检查详细就绪状态
GET HEAD /health/ready
访问: 任何有效的密钥或会话 · 重试: 可安全重试（读取）
当数据库和存储均有响应时返回 ready，同时给出本节点的 role（api 或 reader）、当前是否接受写入（在读取网关上，以及磁盘仅剩预留的可用空间期间，writable 为 false）、读取网关的共享下载槽位，以及上传和下载的准入与带宽汇总计数器。服务器正在排空请求或某个依赖项不可用时，返回 503 并带有 Retry-After。该请求不计入请求预算；无密钥的负载均衡器请使用 getReadinessStatus。
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
role | string | 是 | 取值之一：api, reader |
sharedDownloads | object | 是 | 可以为 null |
sharedDownloads.slot | integer | 是 | 不小于 0 |
sharedDownloads.slots | integer | 是 | 不小于 0 |
sharedDownloads.active | boolean | 是 | — |
sharedDownloads.leaseSeconds | integer | 是 | 不小于 0 |
status | string | 是 | 取值之一：ready |
writable | 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 | 是 | — |
transfers | object | 是 | — |
transfers.uploads | object | 是 | — |
transfers.uploads.admission | object | 是 | — |
transfers.uploads.bandwidth | object | 是 | — |
transfers.uploads.sessions | object | 否 | — |
transfers.downloads | object | 是 | — |
transfers.downloads.admission | object | 是 | — |
transfers.downloads.bandwidth | object | 是 | — |
transfers.downloads.sessions | object | 否 | — |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/health/ready" \
-H "Authorization: Bearer $ARKVORY_TOKEN"获取服务器能力与限制
GET HEAD /api/v1/capabilities
访问: 任何有效的密钥或会话 · 重试: 可安全重试（读取）
返回 API 版本、网关角色、功能开关（例如 selfRegistration 或 mirrorFeed），以及客户端需要适配的限制：最大对象大小（maxObjectBytes，十进制字符串）、分片上传的最小和最大分片大小、最大分片数和最大页面大小。客户端启动时读取一次即可；它不列出任何资源。
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
apiVersions | 数组（string） | 是 | — |
gatewayRole | string | 是 | 取值之一：api, reader |
features | 映射（boolean） | 是 | — |
limits | object | 是 | — |
limits.maxObjectBytes | string | 否 | 用十进制数字表示的整数，以字符串形式发送 |
limits.partBytes | integer | 否 | 分片上传的最小分片大小。 |
limits.maxPartBytes | integer | 否 | — |
limits.maxParts | integer | 否 | — |
limits.maxPageSize | integer | 否 | — |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/capabilities" \
-H "Authorization: Bearer $ARKVORY_TOKEN"检查负载均衡器就绪状态
GET HEAD /health/status
访问: 任何人，无需密钥 · 重试: 可安全重试（读取）
无需密钥，也不返回详情：返回 200 和 {"status":"ready"}，或返回 503（unavailable 或 draining）并带有 Retry-After。依赖项检查是共享的，并缓存一秒，因此频繁探测不会增加数据库负载，且该探测不计入请求预算。
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
status | string | 是 | 取值之一：ready, unavailable, draining |
响应: 200, 400, 403, 503
示例
curl -X GET "$ARKVORY_URL/health/status"检查进程是否存活
GET HEAD /health/live
访问: 任何人，无需密钥 · 重试: 可安全重试（读取）
只要进程能响应 HTTP，就返回 200 和 {"status":"ok"}。它不检查任何依赖项，因此用它决定是否重启，用 getReadinessStatus 决定是否导入流量。
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
status | string | 是 | 取值之一：ok |
响应: 200, 400, 403, 503
示例
curl -X GET "$ARKVORY_URL/health/live"获取 OpenAPI 文档
GET HEAD /api/v1/openapi.json
访问: 任何有效的密钥或会话 · 重试: 可安全重试（读取）
返回此部署的 OpenAPI 3.0 文档，其中的 x-arkvory-* 扩展描述每个操作的访问、重试和网关规则。surface（discovery、identity、catalog、transfers、administration 或 operations）只返回对应的范围；未知或重复的查询参数会返回 400。对所有调用方，该文档都相同，且不授予任何权限：要了解当前凭据可以调用什么，请使用 listVisibleOperations。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
surface | 查询 | string | 否 | 取值之一：discovery, identity, catalog, transfers, administration, operations; Documentation view only; not filtered by caller permissions. |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
openapi | string | 是 | 取值之一：3.0.3 |
info | object | 是 | — |
paths | object | 是 | — |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/openapi.json" \
-H "Authorization: Bearer $ARKVORY_TOKEN"获取 Prometheus 指标
GET HEAD /health/metrics
访问: 任何有效的密钥或会话 · 重试: 可安全重试（读取）
以 Prometheus 文本格式（text/plain; version=0.0.4）返回进程指标，供采集器抓取。计数器和直方图属于当前进程，重启后从零开始（参见 arkvory_process_start_time_seconds）；标签仅限路由模板、方法、状态类别和传输方向，从不包含制品、密钥或账户的名称。抓取不计入请求预算。
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/health/metrics" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o file列出当前凭据可调用的操作
GET HEAD /api/v1/operations
访问: 任何有效的密钥或会话 · 重试: 可安全重试（读取）
按 operationId 排序，列出当前凭据可在此网关上调用的操作，每项包含其所属范围、重试规则、所需操作权限，以及仅在调用时才检查的 conditions（例如 resource-state 或 upload-owner）。repository 会加入该仓库的操作（未知或无权访问的仓库返回 404），surface 将列表限定在一个范围；每页包含 limit 项（1–100，默认 50），将 after 设为 next 即可继续。该结果仅供参考：可据此构建菜单，但每个真实请求都会重新鉴权，读取网关不会列出会产生变更的方法。
参数
| 名称 | 位置 | 类型 | 必需 | 规则 |
|---|---|---|---|---|
repository | 查询 | string | 否 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$ |
surface | 查询 | string | 否 | 取值之一：discovery, identity, catalog, transfers, administration, operations |
after | 查询 | string | 否 | 匹配 ^[A-Za-z][A-Za-z0-9]{0,95}$ |
limit | 查询 | integer | 否 | 1–100; 默认值 50 |
响应 200
| 字段 | 类型 | 必需 | 规则 |
|---|---|---|---|
apiVersion | string | 是 | 取值之一：v1 |
documentVersion | string | 是 | 匹配 ^\d+\.\d+\.\d+$ |
gatewayRole | string | 是 | 取值之一：api, reader |
repository | string | 是 | 匹配 ^[a-z0-9][a-z0-9_-]{0,63}$; 可以为 null |
advisory | boolean | 是 | 取值之一：true |
items | 数组（object） | 是 | 最多 100 项 |
items[].operationId | string | 是 | 匹配 ^[A-Za-z][A-Za-z0-9]{0,95}$ |
items[].method | string | 是 | 取值之一：get, head, post, put, patch, delete |
items[].path | string | 是 | 匹配 ^/; 最多 512 个字符 |
items[].summary | string | 是 | 最多 1024 个字符 |
items[].surface | string | 是 | 取值之一：discovery, identity, catalog, transfers, administration, operations |
items[].visibility | string | 是 | 取值之一：public, authenticated, self, repository, owned-resource, delegated, bootstrap, administrator |
items[].retry | string | 是 | 取值之一：read, never-automatic, idempotent, idempotency-key, compare-and-swap, reconcile-upload, reconcile-job |
items[].requiredActions | 数组（string） | 是 | 最多 33 项; 不允许重复项; 每项：取值之一：repository.read, storage.read, storage.manage, diagnostics.read, artifact.read, artifact.list, artifact.delete, artifact.promote, content.read, upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.read, package.publish, asset.read, asset.write, asset.restore, annotation.read, annotation.write, reference.write, audit.read, service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read, backup.read, backup.manage |
items[].conditions | 数组（string） | 是 | 最多 6 项; 不允许重复项; 每项：取值之一：resource-state, upload-owner, job-owner, reference-owner, delegation-target-and-ceiling, own-key |
next | string | 是 | 匹配 ^[A-Za-z][A-Za-z0-9]{0,95}$; 可以为 null |
响应: 200, 400, 401, 403, 404, 409, 422, 503, 507
示例
curl -X GET "$ARKVORY_URL/api/v1/operations" \
-H "Authorization: Bearer $ARKVORY_TOKEN"