النسخ الاحتياطية
حالة وكيل النسخ الاحتياطي المدمج، وخطته، وعمليات تشغيله، ونقاطه، والتحقق، والاحتفاظ.
عمليات هذه المجموعة مع قاعدة الوصول وقاعدة إعادة المحاولة والمعلمات والاستجابات. يحمل كل طلب مفتاحًا: Authorization: Bearer <key> (راجع «المصادقة»).
العمليات
الحصول على حالة النسخ الاحتياطي
GET HEAD /api/v1/backup/status
الوصول: إذن النظام backup.read · إعادة المحاولة: آمن للتكرار (قراءة)
يلخّص نظام النسخ الاحتياطي: مخزن النسخ الاحتياطية (configured وavailable والبايتات الحرة والكلية)، ووكيل النسخ الاحتياطي (online وآخر نبضة (heartbeat) وإصداره)، والخطة، وأحدث نقطة مكتملة، والتشغيل المجدول التالي، والمهمة الجارية، و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
مثال
curl -X GET "$ARKVORY_URL/api/v1/backup/status" \
-H "Authorization: Bearer $ARKVORY_TOKEN"الحصول على خطة النسخ الاحتياطي
GET HEAD /api/v1/backup/plan
الوصول: إذن النظام backup.read · إعادة المحاولة: آمن للتكرار (قراءة)
يعيد الجدول اليومي (enabled وhour وminute في المنطقة الزمنية IANA timezone) وسياسة الاحتفاظ (نقاط daily وweekly وmonthly المراد الاحتفاظ بها) مع revision التي تُرسل مرة أخرى إلى updateBackupPlan. وما لم تتغير الخطة تكون معطّلة، بجدول 02:00 UTC و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
مثال
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 مع JSON Pointer في details. ويتبع الوكيل الجدول الجديد من فحصه التالي.
نص الطلب (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
مثال
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 نفسه
يضع في الطابور عملية التقاط (capture) للوكيل خارج الجدول ويردّ بـ 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
مثال
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
مثال
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
مثال
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
مثال
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 · إعادة المحاولة: آمن للتكرار: الطلب نفسه يُحدث الأثر نفسه
يعيّن pinned للنقطة id؛ وتبقى النقطة المثبّتة محفوظة خارج حدود سياسة الاحتفاظ إلى أن يُلغى تثبيتها. وتعيين القيمة نفسها مرة أخرى لا يغيّر شيئًا، والردّ هو النقطة المحدَّثة. والنقطة غير المعروفة أو التي نُسيت بالفعل هي 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
مثال
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
مثال
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
مثال
curl -X POST "$ARKVORY_URL/api/v1/backup/retention/apply" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"