备份

内置备份代理的状态、计划、运行、恢复点、验证和保留。

本组中的操作及其访问规则、重试规则、参数和响应。每个请求都需携带密钥：Authorization: Bearer <密钥>（参见“身份验证”）。

操作

获取备份状态

GET HEAD /api/v1/backup/status

访问: 系统权限 backup.read · 重试: 可安全重试（读取）

汇总备份系统：备份存储（configured、available、可用和总字节数）、备份代理（online、上次心跳、版本）、计划、最新完成的恢复点、下一次计划运行、正在运行的作业，以及 warnings，每项是形如 agent_offline 或 backup_stale 的代码，严重程度为 warning 或 critical。代理离线时，备份存储被报告为不可用。其中不含路径或机密值。

响应 200

字段	类型	必需	规则
`vault`	object	是	—
`vault.configured`	boolean	是	—
`vault.id`	string (uuid)	是	可以为 null
`vault.available`	boolean	是	—
`vault.encrypted`	boolean	是	可以为 null; 保管库是否已加密；未知或未连接时为 null。
`vault.freeBytes`	string	是	用十进制数字表示的整数，以字符串形式发送; 可以为 null
`vault.totalBytes`	string	是	用十进制数字表示的整数，以字符串形式发送; 可以为 null
`agent`	object	是	—
`agent.online`	boolean	是	—
`agent.lastSeenAt`	string (date-time)	是	可以为 null
`agent.version`	string	是	最多 64 个字符; 可以为 null
`plan`	object	是	—
`plan.enabled`	boolean	是	—
`plan.hour`	integer	是	0–23
`plan.minute`	integer	是	0–59
`plan.timezone`	string	是	1–64 个字符; 明确指定的 IANA 时区，例如 Europe/Moscow；由服务器校验。
`plan.retention`	object	是	—
`plan.retention.daily`	integer	是	0–366
`plan.retention.weekly`	integer	是	0–260
`plan.retention.monthly`	integer	是	0–120
`plan.revision`	integer	是	0–2147483647
`lastCompleted`	object	是	可以为 null
`lastCompleted.id`	string (uuid)	是	—
`lastCompleted.snapshotAt`	string (date-time)	是	快照时间 T；恢复点的存续时间从 T 起算。
`lastCompleted.completedAt`	string (date-time)	是	—
`lastCompleted.blobs`	integer	是	不小于 0
`lastCompleted.contentBytes`	string	是	用十进制数字表示的整数，以字符串形式发送
`lastCompleted.newBytes`	string	是	用十进制数字表示的整数，以字符串形式发送; 此恢复点加入备份存储的字节数。
`lastCompleted.tables`	integer	是	不小于 0
`lastCompleted.rows`	integer	是	不小于 0
`lastCompleted.pinned`	boolean	是	—
`lastCompleted.verifiedAt`	string (date-time)	是	可以为 null
`lastCompleted.verifyDepth`	string	是	取值之一：`structural`, `deep`, `null`; 可以为 null
`lastCompleted.verifyError`	string	是	匹配 `^[a-z][a-z0-9_]{0,63}$`; 可以为 null
`nextRunAt`	string (date-time)	是	可以为 null
`running`	object	是	可以为 null
`running.id`	string (uuid)	是	—
`running.kind`	string	是	取值之一：`capture`, `verify`, `retention`
`running.state`	string	是	取值之一：`queued`, `running`, `committing`, `completed`, `failed`, `interrupted`
`running.phase`	string	是	匹配 `^[a-z][a-z0-9_]{0,63}$`; 可以为 null
`running.startedAt`	string (date-time)	是	开始执行的时间，排队期间则为请求时间。
`running.finishedAt`	string (date-time)	是	可以为 null
`running.errorCode`	string	是	匹配 `^[a-z][a-z0-9_]{0,63}$`; 可以为 null
`running.pointId`	string (uuid)	是	可以为 null
`running.progress`	object	是	—
`running.progress.bytesCopied`	string	是	用十进制数字表示的整数，以字符串形式发送; 已处理的字节数：已复制的，或已在备份存储中的。
`running.progress.bytesTotal`	string	是	用十进制数字表示的整数，以字符串形式发送
`running.progress.blobsCopied`	integer	是	不小于 0
`running.progress.blobsTotal`	integer	是	不小于 0
`warnings`	数组（object）	是	最多 10 项
`warnings[].code`	string	是	取值之一：`vault_not_configured`, `agent_offline`, `schedule_disabled`, `no_backup_yet`, `backup_stale`, `last_run_failed`, `vault_unavailable`, `vault_low_space`, `verify_failed`, `never_deep_verified`
`warnings[].severity`	string	是	取值之一：`warning`, `critical`

响应: 200, 400, 401, 403, 404, 409, 422, 503, 507

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/backup/status" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

获取备份计划

GET HEAD /api/v1/backup/plan

访问: 系统权限 backup.read · 重试: 可安全重试（读取）

返回每日计划（enabled，IANA timezone 中的 hour 和 minute）和保留策略（要保留的 daily、weekly、monthly 恢复点数），以及要回传给 updateBackupPlan 的 revision。未更改之前，计划处于禁用状态，计划时间为 UTC 02:00，保留 7 个每日、4 个每周和 6 个每月的恢复点。

响应 200

字段	类型	必需	规则
`enabled`	boolean	是	—
`hour`	integer	是	0–23
`minute`	integer	是	0–59
`timezone`	string	是	1–64 个字符; 明确指定的 IANA 时区，例如 Europe/Moscow；由服务器校验。
`retention`	object	是	—
`retention.daily`	integer	是	0–366
`retention.weekly`	integer	是	0–260
`retention.monthly`	integer	是	0–120
`revision`	integer	是	0–2147483647

响应: 200, 400, 401, 403, 404, 409, 422, 503, 507

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/backup/plan" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

替换备份计划

PUT /api/v1/backup/plan

访问: 系统权限 backup.manage · 重试: 仅在携带预期修订版本时重试（compare-and-swap）

替换整个计划：enabled、hour（0–23）、minute（0–59）、timezone 和 retention（最多 366 个每日、260 个每周、120 个每月）必须全部提供。expectedRevision 必须是当前修订版本，否则返回 409 revision_mismatch；无效字段返回 400，并在 details 中给出 JSON Pointer。代理从下一次检查起遵循新计划。

请求正文 (application/json)

字段	类型	必需	规则
`expectedRevision`	integer	是	0–2147483647
`enabled`	boolean	是	—
`hour`	integer	是	0–23
`minute`	integer	是	0–59
`timezone`	string	是	1–64 个字符; 明确指定的 IANA 时区，例如 Europe/Moscow；由服务器校验。
`retention`	object	是	—
`retention.daily`	integer	是	0–366
`retention.weekly`	integer	是	0–260
`retention.monthly`	integer	是	0–120

响应 200

字段	类型	必需	规则
`enabled`	boolean	是	—
`hour`	integer	是	0–23
`minute`	integer	是	0–59
`timezone`	string	是	1–64 个字符; 明确指定的 IANA 时区，例如 Europe/Moscow；由服务器校验。
`retention`	object	是	—
`retention.daily`	integer	是	0–366
`retention.weekly`	integer	是	0–260
`retention.monthly`	integer	是	0–120
`revision`	integer	是	0–2147483647

响应: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

示例

bash

curl -X PUT "$ARKVORY_URL/api/v1/backup/plan" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0,"enabled":false,"hour":0,"minute":0,"timezone":"<timezone>","retention":{"daily":0,"weekly":0,"monthly":0}}'

立即请求备份

POST /api/v1/backup/runs

访问: 系统权限 backup.manage · 重试: 使用相同的 Idempotency-Key 可安全重试

在计划之外为备份代理排队一次捕获，并返回 202 和该作业（kind 为 capture）；代理先执行它，随后进行验证和保留。必须提供 Idempotency-Key：同一调用方重复使用它会返回同一个作业。在 listBackupJobs 中跟踪该作业。最多可同时有 100 个未完成的备份请求（507 queue_full）；没有代理在线时，作业会等待。

参数

名称	位置	类型	必需	规则
`Idempotency-Key`	标头	string	是	匹配 `^[A-Za-z0-9_.:-]{1,128}$`; Repeat returns the same job; per caller and operation kind.

响应 202

字段	类型	必需	规则
`id`	string (uuid)	是	—
`kind`	string	是	取值之一：`capture`, `verify`, `retention`
`state`	string	是	取值之一：`queued`, `running`, `committing`, `completed`, `failed`, `interrupted`

响应: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

示例

bash

curl -X POST "$ARKVORY_URL/api/v1/backup/runs" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

列出备份作业

GET HEAD /api/v1/backup/jobs

访问: 系统权限 backup.read · 重试: 可安全重试（读取）

按从新到旧的顺序，列出捕获、验证和保留作业，每个包含其 state（queued、running、committing、completed、failed、interrupted）、phase、时间、errorCode、生成的恢复点以及 progress（已处理的字节数和对象数）。每页包含 limit 个作业（1–100，默认 50）；将 after 设为 next 即可继续。

参数

名称	位置	类型	必需	规则
`after`	查询	string	否	匹配 `^[0-9]{1,17}_[0-9a-f-]{36}$`; next of the previous page
`limit`	查询	integer	否	1–100; 默认值 `50`

响应 200

字段	类型	必需	规则
`items`	数组（object）	是	最多 100 项
`items[].id`	string (uuid)	是	—
`items[].kind`	string	是	取值之一：`capture`, `verify`, `retention`
`items[].state`	string	是	取值之一：`queued`, `running`, `committing`, `completed`, `failed`, `interrupted`
`items[].phase`	string	是	匹配 `^[a-z][a-z0-9_]{0,63}$`; 可以为 null
`items[].startedAt`	string (date-time)	是	开始执行的时间，排队期间则为请求时间。
`items[].finishedAt`	string (date-time)	是	可以为 null
`items[].errorCode`	string	是	匹配 `^[a-z][a-z0-9_]{0,63}$`; 可以为 null
`items[].pointId`	string (uuid)	是	可以为 null
`items[].progress`	object	是	—
`items[].progress.bytesCopied`	string	是	用十进制数字表示的整数，以字符串形式发送; 已处理的字节数：已复制的，或已在备份存储中的。
`items[].progress.bytesTotal`	string	是	用十进制数字表示的整数，以字符串形式发送
`items[].progress.blobsCopied`	integer	是	不小于 0
`items[].progress.blobsTotal`	integer	是	不小于 0
`next`	string	是	匹配 `^[0-9]{1,17}_[0-9a-f-]{36}$`; 可以为 null

响应: 200, 400, 401, 403, 404, 409, 422, 503, 507

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/backup/jobs" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

列出备份恢复点

GET HEAD /api/v1/backup/points

访问: 系统权限 backup.read · 重试: 可安全重试（读取）

列出当前备份存储中已完成的恢复点，快照最新的排在前面，每个包含快照时间 T、大小、加入备份存储的字节数、是否已固定（pinned）以及最近一次验证（verifiedAt、verifyDepth 为 structural 或 deep、verifyError）。每页包含 limit 个恢复点（1–100，默认 50）；将 after 设为 next 即可继续。被替换的备份存储只显示它自己的恢复点。

参数

名称	位置	类型	必需	规则
`after`	查询	string	否	匹配 `^[0-9]{1,17}_[0-9a-f-]{36}$`; next of the previous page
`limit`	查询	integer	否	1–100; 默认值 `50`

响应 200

字段	类型	必需	规则
`items`	数组（object）	是	最多 100 项
`items[].id`	string (uuid)	是	—
`items[].snapshotAt`	string (date-time)	是	快照时间 T；恢复点的存续时间从 T 起算。
`items[].completedAt`	string (date-time)	是	—
`items[].blobs`	integer	是	不小于 0
`items[].contentBytes`	string	是	用十进制数字表示的整数，以字符串形式发送
`items[].newBytes`	string	是	用十进制数字表示的整数，以字符串形式发送; 此恢复点加入备份存储的字节数。
`items[].tables`	integer	是	不小于 0
`items[].rows`	integer	是	不小于 0
`items[].pinned`	boolean	是	—
`items[].verifiedAt`	string (date-time)	是	可以为 null
`items[].verifyDepth`	string	是	取值之一：`structural`, `deep`, `null`; 可以为 null
`items[].verifyError`	string	是	匹配 `^[a-z][a-z0-9_]{0,63}$`; 可以为 null
`next`	string	是	匹配 `^[0-9]{1,17}_[0-9a-f-]{36}$`; 可以为 null

响应: 200, 400, 401, 403, 404, 409, 422, 503, 507

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/backup/points" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

请求对备份恢复点进行深度检查

POST /api/v1/backup/points/{id}/verify

访问: 系统权限 backup.manage · 重试: 使用相同的 Idempotency-Key 可安全重试

为恢复点 id 排队一次验证，它会读取该恢复点存储的每一个字节；响应为 202 和该作业，结果会出现在该恢复点的 verifiedAt、verifyDepth 和 verifyError 中。必须提供 Idempotency-Key，将它用于另一个恢复点会返回 409 idempotency_mismatch。未知的恢复点返回 404。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—
`Idempotency-Key`	标头	string	是	匹配 `^[A-Za-z0-9_.:-]{1,128}$`; Repeat returns the same job; per caller and operation kind.

响应 202

字段	类型	必需	规则
`id`	string (uuid)	是	—
`kind`	string	是	取值之一：`capture`, `verify`, `retention`
`state`	string	是	取值之一：`queued`, `running`, `committing`, `completed`, `failed`, `interrupted`

响应: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

示例

bash

curl -X POST "$ARKVORY_URL/api/v1/backup/points/$ID/verify" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

固定或取消固定备份恢复点

PUT /api/v1/backup/points/{id}/pin

访问: 系统权限 backup.manage · 重试: 可安全重试：相同的请求效果相同

设置恢复点 id 的 pinned；被固定的恢复点会超出策略范围被保留规则保留，直到取消固定。再次设置相同的值不会产生任何变化，响应为更新后的恢复点。未知或已被移除的恢复点返回 404。

参数

名称	位置	类型	必需	规则
`id`	路径	string (uuid)	是	—

请求正文 (application/json)

字段	类型	必需	规则
`pinned`	boolean	是	—

响应 200

字段	类型	必需	规则
`id`	string (uuid)	是	—
`snapshotAt`	string (date-time)	是	快照时间 T；恢复点的存续时间从 T 起算。
`completedAt`	string (date-time)	是	—
`blobs`	integer	是	不小于 0
`contentBytes`	string	是	用十进制数字表示的整数，以字符串形式发送
`newBytes`	string	是	用十进制数字表示的整数，以字符串形式发送; 此恢复点加入备份存储的字节数。
`tables`	integer	是	不小于 0
`rows`	integer	是	不小于 0
`pinned`	boolean	是	—
`verifiedAt`	string (date-time)	是	可以为 null
`verifyDepth`	string	是	取值之一：`structural`, `deep`, `null`; 可以为 null
`verifyError`	string	是	匹配 `^[a-z][a-z0-9_]{0,63}$`; 可以为 null

响应: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

示例

bash

curl -X PUT "$ARKVORY_URL/api/v1/backup/points/$ID/pin" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pinned":false}'

预览备份保留规则会保留什么

GET HEAD /api/v1/backup/retention/preview

访问: 系统权限 backup.read · 重试: 可安全重试（读取）

显示保留策略会保留哪些恢复点，每个附带原因（daily、weekly、monthly、pinned、newest），以及现在会删除哪些。验证失败的恢复点不在考虑之列。该预览仅供参考：requestBackupRetention 运行时会根据备份存储重新决定。

响应 200

字段	类型	必需	规则
`keep`	数组（object）	是	—
`keep[].id`	string (uuid)	是	—
`keep[].reasons`	数组（string）	是	每项：取值之一：`daily`, `weekly`, `monthly`, `pinned`, `newest`
`delete`	数组（object）	是	—
`delete[].id`	string (uuid)	是	—

响应: 200, 400, 401, 403, 404, 409, 422, 503, 507

示例

bash

curl -X GET "$ARKVORY_URL/api/v1/backup/retention/preview" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

请求备份保留

POST /api/v1/backup/retention/apply

访问: 系统权限 backup.manage · 重试: 使用相同的 Idempotency-Key 可安全重试

排队一个保留作业：代理移除策略之外的恢复点，然后删除不再被任何剩余恢复点使用的内容，因此只有作业完成后，空间才会回到备份存储。返回 202 和该作业；必须提供 Idempotency-Key，重复使用它会返回同一个作业。请先查看 previewBackupRetention。

参数

名称	位置	类型	必需	规则
`Idempotency-Key`	标头	string	是	匹配 `^[A-Za-z0-9_.:-]{1,128}$`; Repeat returns the same job; per caller and operation kind.

响应 202

字段	类型	必需	规则
`id`	string (uuid)	是	—
`kind`	string	是	取值之一：`capture`, `verify`, `retention`
`state`	string	是	取值之一：`queued`, `running`, `committing`, `completed`, `failed`, `interrupted`

响应: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

示例

bash

curl -X POST "$ARKVORY_URL/api/v1/backup/retention/apply" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

备份 ​

操作 ​

获取备份状态 ​

获取备份计划 ​

替换备份计划 ​

立即请求备份 ​

列出备份作业 ​

列出备份恢复点 ​

请求对备份恢复点进行深度检查 ​

固定或取消固定备份恢复点 ​

预览备份保留规则会保留什么 ​

请求备份保留 ​

备份

操作

获取备份状态

获取备份计划

替换备份计划

立即请求备份

列出备份作业

列出备份恢复点

请求对备份恢复点进行深度检查

固定或取消固定备份恢复点

预览备份保留规则会保留什么

请求备份保留