العملاء والبروتوكولات

لدى Arkvory تخزين واحد ونموذج وصول واحد، لكن بطرق عدة للوصول إليه. كل طريقة عميل أو بروتوكول تتحدثه أداة موجودة. وكلها تخزّن البيانات في صورة مُخرَجات (artifacts) في Arkvory. لذا تنطبق الأذونات والحصص وعمليات التحقق من SHA-256 وقواعد الاحتفاظ والنسخ الاحتياطية والمرايا نفسها، أيًّا كانت الطريقة التي تستخدمها.

تسرد هذه الصفحة كل طرق التواصل مع Arkvory، وما تصلح له كل طريقة، وبيانات الاعتماد التي تقبلها. استخدمها لاختيار الأداة المناسبة للمهمة.

نظرة عامة

الطريقة	العنوان	تصلح لـ	بيانات الاعتماد
وحدة التحكم على الويب	https://arkvory.example/console/	تصفح المستودعات، والرفع والتنزيل في المتصفح، وإدارة المستخدمين والمفاتيح والنسخ الاحتياطية	تسجيل الدخول باسم مستخدم وكلمة مرور، أو بمفتاح خدمة
سطر الأوامر arkvoryctl	/api/v1	نصوص CI البرمجية، والرفع والتنزيل القابلان للاستئناف، والملفات حسب المسار، والترقية، والنسخ الاحتياطية	مفتاح من ملف أو من متغير بيئة (يُرسل بصيغة Bearer)
TypeScript SDK	/api/v1	أدواتك الخاصة بـ TypeScript أو JavaScript، في Node.js أو في المتصفح	مفتاح من دالة استدعاء (callback) (يُرسل بصيغة Bearer)
REST API	/api/v1/...	التكاملات بأي لغة	Authorization: Bearer <key> فقط
سجل الحاويات (OCI)	/v2/	Docker وPodman وBuildx وcontainerd ومخططات Helm ومُخرَجات ORAS	Basic مع المفتاح ككلمة مرور (docker login)، أو Bearer
Git LFS	/lfs/<repository>	الملفات الكبيرة لمستودع git، وقفل الملفات لـ Unity وUnreal	Basic مع المفتاح ككلمة مرور (git credential helper)، أو Bearer
سجل npm	/npm/<repository>/	السجلات محددة النطاق (scoped registries) في Unity Package Manager، وnpm publish وnpm install	Bearer (_authToken في .npmrc، وtoken في .upmconfig.toml)، أو Basic _auth
الملفات الخام حسب المسار	/api/v1/repositories/<repository>/raw/<path>	طلب واحد بـ curl -T أو PowerShell	Authorization: Bearer <key> فقط
Webhook	عنوان URL للمستقبِل لديك	بدء نشر أو مهمة عندما يتغير مستودع	توقيع HMAC لكل طلب

تتبع المسارات تحت /v2 و/lfs و/npm مواصفات بروتوكولاتها. وهي ليست جزءًا من وثيقة OpenAPI الخاصة بـ /api/v1، وتبلّغ عن الأخطاء بالصيغة التي يتوقعها عملاؤها.

بيانات الاعتماد

يحتاج كل طلب إلى بيانات اعتماد، عدا فحوص السلامة العامة. ويقبل Arkvory الأنواع التالية:

النوع	يبدو هكذا	مصدره	الاستخدام المعتاد
رمز وصول شخصي	pat_...	ينشئه مستخدم في وحدة التحكم. النطاق read أو read-write. ينتهي (بعد 90 يومًا افتراضيًا، وبحد أقصى 365).	المطورون: Unity وgit وDocker على محطة عمل
مفتاح خدمة	arkvory_...	يصدره مسؤول لحساب خدمة، بإجراءات محددة لكل مستودع	CI/CD ووكلاء النشر وخوادم البناء
مفتاح ملف	أي سر	ملف مفاتيح الخادم (ARKVORY_KEYS_FILE)، مع read أو write لكل مستودع؛ ويدير مفتاح المالك أيضًا	مالك التثبيت والتكاملات القديمة
جلسة	dps_...	تسجيل الدخول إلى وحدة التحكم؛ صالحة 12 ساعة	العمل التفاعلي في وحدة التحكم
رابط تنزيل	عنوان URL مع ?token=	يُنشأ لمُخرَج واحد؛ من 60 ثانية إلى 24 ساعة	تسليم ملف واحد لشخص لا يملك مفتاحًا

تختلف البروتوكولات فقط في طريقة إرسال المفتاح:

• يستخدم /api/v1 وCLI وSDK والملفات الخام Authorization: Bearer <key>.
• يقبل /v2 و/lfs و/npm أيضًا HTTP Basic. ولا يُتحقق من اسم المستخدم. وكلمة المرور هي مفتاح Arkvory. وبهذه الطريقة يرسل docker login وgit credential helpers وnpm _auth بيانات الاعتماد.
• الرمز الشخصي للقراءة فقط لا يغيّر البيانات أبدًا. لكنه يستطيع تنزيل كائنات Git LFS، لأن طلب الدفعة (batch) في Git LFS هو POST للتنزيل أيضًا.

لمعرفة كيفية إنشاء الرموز والمفاتيح: الحسابات والمفاتيح. وتفاصيل الترويسة: المصادقة.

ما الطريقة التي أستخدمها؟

المهمة	الطريقة الموصى بها
رفع مُخرَج بناء من CI واستئنافه بعد انقطاع الشبكة	arkvoryctl upload أو arkvoryctl put
نشر حزمة UPack من CI	arkvoryctl packages publish
نشر «أحدث إصدار 1.4» على خادم	arkvoryctl packages download --range ^1.4 --stage release
وضع ملف صغير أو متوسط حسب المسار من نص shell برمجي دون تثبيت أي شيء	الملفات الخام مع curl -T أو PowerShell
تخزين صور الحاويات أو مخططات Helm	صور الحاويات
إبقاء خامات (textures) ونماذج ومراحل (levels) لعبة خارج مضيف git	Git LFS
مشاركة حزم Unity بين المشاريع	حزم Unity وnpm
بناء أداتك الخاصة أو واجهتك على الويب	TypeScript SDK
التكامل من Python أو Go أو C# أو لغة أخرى	REST API
الاطلاع على المحتوى وإدارة المستخدمين والمفاتيح والنسخ الاحتياطية	وحدة التحكم على الويب

قواعد عملية:

• الملفات الكبيرة (غيغابايتات كثيرة): استخدم arkvoryctl أو SDK. فهما يرفعان على أجزاء ويتابعان بعد الانقطاع. أما طلب PUT واحد (الملفات الخام، وكائنات Git LFS، ونشر npm، وطبقة Docker) فيبدأ من البايت صفر بعد الفشل.
• أداة تتحدث بروتوكولًا بالفعل: استخدم ذلك البروتوكول. فلا يحتاج Docker وgit وUnity إلى برنامج إضافي.
• جهاز يقرأ فقط: امنحه رمزًا للقراءة فقط أو مفتاح خدمة بإجراءات قراءة فقط.

القواعد المشتركة

HTTPS. استخدم HTTPS مع كل العملاء. يرفض CLI وSDK HTTP العادي إلا على الحلقة المحلية (localhost و127.0.0.1 و[::1]). ويحتاج Docker إلى شهادة موثوقة. ويرسل Git المفتاح مع كل طلب. راجع HTTPS.

التخزين نفسه. طبقة الصورة وكائن Git LFS وأرشيف npm tarball والملف الخام كلها مُخرَجات. وتُحتسب ضمن حصص المستودع وسعة التثبيت. ويُتحقق منها بـ SHA-256 عند تخزينها. وتدخل في النسخ الاحتياطية.

بوابات القراءة والمرايا. لا تقبل بوابة القراءة سوى GET وHEAD. والمرآة نسخة للقراءة فقط من مستودع على تثبيت آخر.

الطريقة	على بوابة قراءة	على مرآة
/api/v1 وCLI وSDK	قراءة فقط	قراءة؛ وتُرفض التغييرات (409 mirror_read_only)
سجل الحاويات	السحب (pull)	السحب؛ ويُرفض الدفع (push)
Git LFS	غير مدعوم (طلب الدفعة هو POST)	الاستنساخ (clone) والجلب (fetch)؛ ويُرفض الدفع والأقفال
سجل npm	التثبيت والبحث	التثبيت والبحث؛ ويُرفض النشر
الملفات الخام	GET وHEAD	GET وHEAD

راجع بوابات القراءة والمرايا.

صفحات ذات صلة

• سطر الأوامر (arkvoryctl)
• TypeScript SDK
• صور الحاويات
• Git LFS
• حزم Unity وnpm
• الملفات الخام
• Webhook
• نظرة عامة على API والأخطاء