متغيرات البيئة
يُضبط Arkvory بمتغيرات بيئة تبدأ أسماؤها بـ ARKVORY_. تسرد هذه الصفحة كل متغير تقرؤه عمليات الخادم وعميل سطر الأوامر ونصوص التثبيت البرمجية.
من أين تأتي القيم
تكتب برامج التثبيت إعدادات الخادم في ملف واحد، هو config/runtime.json، في جذر التثبيت. ويقرأ مشغّل (launcher) كل خدمة هذا الملف ويمرّر قيمه إلى API والعامل ووكيل النسخ الاحتياطي. يجب أن يبدأ كل مفتاح بـ ARKVORY_، وأن تكون كل قيمة نصًا.
json
{
"ARKVORY_HOST": "127.0.0.1",
"ARKVORY_PORT": "8080",
"ARKVORY_CAPACITY_BYTES": "10995116277760",
"ARKVORY_DATABASE_URL": "postgresql://arkvory:PASSWORD@127.0.0.1:54329/arkvory",
"ARKVORY_DATA_DIR": "/opt/proanima-arkvory/data",
"ARKVORY_KEYS_FILE": "/opt/proanima-arkvory/config/keys.json",
"ARKVORY_MAX_DOWNLOADS": "32"
}يحتوي الملف على كلمة مرور قاعدة البيانات. أبقِ صلاحيات الوصول إليه كما ضبطها برنامج التثبيت.
لتغيير إعداد، حرّر config/runtime.json وأعد تشغيل الخدمات. ويُفضَّل الأمر arkvory configure حيث يغطي الإعداد (HTTPS ومخزن النسخ الاحتياطية والمرايا والتحديثات). فهو يتحقق من التغيير ويستعيد الملف القديم إذا لم تبدأ الخدمات. راجع الإعداد.
bash
sudo systemctl restart arkvory-api arkvory-worker arkvory-backuppowershell
Restart-Service Arkvoryapi, Arkvoryworker, Arkvorybackupالقيمة خارج نطاقها المسموح توقف العملية عند البدء برسالة تسمّي المتغير. ولا يعود Arkvory إلى القيمة الافتراضية في هذه الحالة.
يستخدم العمود «يقرؤه» هذه الأسماء: API هو خادم HTTP (وبوابة القراءة أيضًا)، والعامل هو عامل الخلفية، والوكيل هو وكيل النسخ الاحتياطي، وCLI هو arkvoryctl.
الأساسيات
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_DATABASE_URL | API، العامل، الوكيل، الترحيل | مطلوب | عنوان اتصال PostgreSQL (postgres:// أو postgresql://). استخدم قاعدة بيانات منفصلة لكل تثبيت. |
ARKVORY_DATA_DIR | API، العامل، الوكيل | مطلوب | دليل التخزين المحلي: منطقة التجهيز (staging) والمحتوى وملف storage-id. لا تستخدم مشاركة شبكية. |
ARKVORY_HOST | API | 127.0.0.1 | العنوان الذي يُستمع إليه. تكتب برامج التثبيت 127.0.0.1؛ وفي Docker Compose يكون 0.0.0.0 داخل الحاوية، وينشر المنفذ على الحلقة المحلية للمضيف فقط. |
ARKVORY_PORT | API | 8080 | منفذ TCP، من 1 إلى 65535. |
ARKVORY_WEB_DIR | API | apps/web/public | دليل ملفات وحدة التحكم على الويب. يضبطه المشغّل على الإصدار الحالي عند كل بدء. |
ARKVORY_DATABASE_POOL_SIZE | API | 20 | حجم مجمّع استعلامات واجهة API، من 4 إلى 200. تستخدم الجلسات الطويلة مجمّعًا منفصلًا من 3 اتصالات. |
التخزين والحدود
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_CAPACITY_BYTES | API، العامل | 10 TiB | الحد الأعلى، بالبايت، لكل المحتوى المحجوز: المنشور وعمليات الرفع غير المكتملة والمحتوى الذي ينتظر التنظيف. وهو ليس فحصًا للقرص. ولا يقرؤه العامل إلا لنسخ المرايا. |
ARKVORY_STORAGE_RESERVE_BYTES | API، العامل، الوكيل | 1073741824 | المساحة الحرة، بالبايت، التي لا تستخدمها عمليات الرفع أبدًا. وتُحفظ لقاعدة البيانات والسجلات والنظام. و0 توقف الاحتياطي. |
ARKVORY_MAX_OBJECT_BYTES | API | نحو 10 TiB | أكبر كائن، بالبايت. أعلى قيمة مسموحة هي 10 000 جزء بحجم 1 GiB. اضبط قيمة أقل لتحديد حجم الملف. |
عمليات النقل وعرض النطاق
تنتمي هذه الحدود إلى عملية API واحدة. المعدلات بالبايت في الثانية: 0 تعني بلا حد، وأي قيمة أخرى يجب أن تكون من 65 536 إلى 1 TiB.
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_MAX_UPLOADS | API | 8 | عمليات الرفع التي تعمل في الوقت نفسه، من 1 إلى 32. |
ARKVORY_MAX_DOWNLOADS | API | 16 | عمليات التنزيل التي تعمل في الوقت نفسه، من 1 إلى 256. |
ARKVORY_MAX_UPLOADS_PER_PRINCIPAL | API | 4 | عمليات رفع حساب أو مفتاح واحد في الوقت نفسه، حتى حد الرفع الإجمالي. |
ARKVORY_MAX_DOWNLOADS_PER_PRINCIPAL | API | 4 | عمليات تنزيل حساب أو مفتاح واحد في الوقت نفسه، حتى حد التنزيل الإجمالي. |
ARKVORY_DOWNLOAD_STRATEGY | API | ordered | كيف يرتّب طابور التنزيل عمليات التنزيل الكاملة للكائنات الأكبر من ARKVORY_DOWNLOAD_SESSION_MIN_BYTES: ordered (فئات أولوية، والحسابات والمفاتيح بالتناوب)، أو smallest-first (الكائنات الصغيرة أولًا)، أو shared (بلا طابور: يُقبل كل طلب وحده). الافتراضي في بوابات القراءة shared. |
ARKVORY_MAX_DOWNLOAD_SESSIONS | API | ARKVORY_MAX_DOWNLOADS | عمليات التنزيل التي تشغل مكانًا في الوقت نفسه، من 1 إلى 1024. |
ARKVORY_DOWNLOAD_RESERVE | API | 1 | أماكن محجوزة للأشخاص (جلسات وحدة التحكم والرموز الشخصية) أثناء التحديث الجماعي. الافتراضي 0 إذا كانت الأماكن أقل من أربعة. |
ARKVORY_DOWNLOAD_WEIGHTS | API | interactive=8,release=4,bulk=2,background=1 | حصة الأماكن الشاغرة لكل فئة. اذكر الفئات التي تغيّرها فقط. |
ARKVORY_DOWNLOAD_SESSION_MIN_BYTES | API | 16777216 | الكائنات حتى هذا الحجم لا تدخل الطابور وتُقبل لكل طلب. |
ARKVORY_DOWNLOAD_IDLE_SECONDS | API | 30 | التوقف بين النطاقات لمدة أطول من هذه يحرّر المكان. يحتفظ التنزيل بدوره عشر دقائق. |
ARKVORY_DOWNLOAD_AGING_MINUTES | API | 15 | كل انتظار بهذه المدة يرفع التنزيل فئة واحدة حتى release كحد أقصى. القيمة 0 توقف التقادم. |
ARKVORY_DOWNLOAD_PREEMPT | API | true | عملاء بروتوكول الطابور (SDK وarkvoryctl) يتنازلون عن مكانهم عند حد نطاق لفئة أعلى أو لمفتاح دون حصته، بعد أن يشغلوه دقيقة. |
ARKVORY_DOWNLOAD_RANGES_PER_SESSION | API | 4 | الطلبات المتزامنة لتنزيل واحد: نطاقات متوازية، أو عملاء خلف عنوان واحد. |
ARKVORY_DOWNLOAD_QUEUE_LIMIT | API | 65536 | إجمالي التنزيلات النشطة والمنتظرة. بعد ذلك يُطلب من العميل العودة بعد دقيقة. |
ARKVORY_DOWNLOAD_QUEUE_PER_PRINCIPAL | API | 4096 | إجمالي تنزيلات حساب أو مفتاح أو رابط واحد. |
ARKVORY_DOWNLOAD_HOLD_SECONDS | API | 20 | مدة احتجاز طلب أداة خارج بروتوكول الطابور (docker وnpm وcurl والمتصفح) حتى يحين دورها قبل الرد 503. الافتراضي: ARKVORY_TRANSFER_QUEUE_TIMEOUT_MS. القيمة 0 ترد فورًا. |
ARKVORY_SITE_NAME | API | — | اسم هذا التثبيت في صفحة المواقع لدى التثبيتات الأخرى، من 1 إلى 63 حرفًا. |
ARKVORY_FLEET_KEY_FILE | API | fleet.key | المفتاح الذي يختم مفاتيح المواقع التي يديرها هذا التثبيت. تنشئه عملية الكتابة عند أول تشغيل؛ احمه كما تحمي دليل البيانات. ليس في قاعدة البيانات ولا في النسخ الاحتياطية. |
ARKVORY_TRANSFER_QUEUE_LIMIT | API | 64 | عمليات النقل التي يجوز أن تنتظر فتحة شاغرة، من 1 إلى 1024. |
ARKVORY_TRANSFER_QUEUE_PER_PRINCIPAL | API | 8 | عمليات النقل المنتظرة لحساب أو مفتاح واحد، حتى حد القائمة. |
ARKVORY_TRANSFER_QUEUE_TIMEOUT_MS | API | 20000 | المدة التي يجوز أن ينتظرها النقل في القائمة، من 1 إلى 120 000 مللي ثانية. |
ARKVORY_MAX_REQUESTS | API | 128 | الطلبات الموثَّقة في الوقت نفسه، من 1 إلى 4096. يجب أن يكون أكبر من مجموع عمليات الرفع والتنزيل. وعندما لا يُضبط وتكون حدود النقل مرتفعة، تكون القيمة الافتراضية مجموع عمليات الرفع والتنزيل زائد 64. |
ARKVORY_UPLOAD_BYTES_PER_SECOND | API | 0 | معدل الرفع الإجمالي للعملية. |
ARKVORY_DOWNLOAD_BYTES_PER_SECOND | API | 0 | معدل التنزيل الإجمالي للعملية. |
ARKVORY_UPLOAD_BYTES_PER_SECOND_PER_PRINCIPAL | API | 0 | معدل رفع حساب أو مفتاح واحد، عبر كل اتصالاته. |
ARKVORY_DOWNLOAD_BYTES_PER_SECOND_PER_PRINCIPAL | API | 0 | معدل تنزيل حساب أو مفتاح واحد، عبر كل اتصالاته. |
ARKVORY_UPLOAD_IDLE_TIMEOUT_MS | API | 30000 | يُوقَف طلب الرفع الذي لا يرسل بيانات خلال هذه المدة، من 1 إلى 1 800 000 مللي ثانية. |
ARKVORY_UPLOAD_DEADLINE_MS | API | 1800000 | أطول مدة لطلب رفع واحد، من 1 إلى 1 800 000 مللي ثانية. ولا يمكن أن تكون أقصر من مهلة الخمول. |
الشبكة وHTTPS والمتصفحات
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_TLS_CERT_FILE | API | غير مضبوط | شهادة PEM (مع سلسلتها) لـ HTTPS المضمَّن. اضبطها مع ملف المفتاح. |
ARKVORY_TLS_KEY_FILE | API | غير مضبوط | مفتاح خاص بصيغة PEM دون كلمة مرور. |
ARKVORY_TLS_MIN_VERSION | API | TLSv1.2 | TLSv1.2 أو TLSv1.3. |
ARKVORY_TLS_RELOAD_SECONDS | API | 300 | الفاصل بين قراءتين لملفات الشهادة المجدَّدة: من 30 إلى 86 400 ثانية، أو 0 لقراءتها عند البدء فقط. |
ARKVORY_CORS_ORIGINS | API | فارغ | قائمة مفصولة بفواصل تضم حتى 16 أصلًا (origin) للمتصفح، لوحدة تحكم على عنوان آخر. HTTPS فقط، أو HTTP على الحلقة المحلية. |
ARKVORY_TRUSTED_PROXIES | API | فارغ | حتى 32 عنوانًا لوكلاء عكسيين (IP أو CIDR). وهذه العناوين وحدها يجوز لها ضبط عنوان العميل عبر X-Forwarded-For. |
HTTPS المضمَّن مخصص للتثبيتات الأصلية. ومع Docker Compose استخدم وكيلًا عكسيًا. راجع HTTPS.
الهوية والمفاتيح
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_KEYS_FILE | API، العامل | مطلوب | ملف JSON فيه مفاتيح الملفات، مثل مفتاح الاسترداد ومفتاح فحص السلامة. يخزّن تجزئات SHA-256، ولا يخزّن المفاتيح أبدًا. |
ARKVORY_ALLOW_REGISTRATION | API | متوقف | true يتيح للناس إنشاء حساباتهم بأنفسهم في صفحة تسجيل الدخول. وأي قيمة أخرى تُبقيه متوقفًا. |
النسخ الاحتياطية
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_BACKUP_VAULT | الوكيل | غير مضبوط | دليل مخزن مهيَّأ. بدونه يعمل الوكيل ويبلّغ بأنه لا يوجد مخزن مضبوط. ويكتبه arkvory configure --backup-vault. |
ARKVORY_BACKUP_VAULT_KEY_FILE | الوكيل | غير مضبوط | ملف يحوي مفتاح الخدمة لـ vault مشفّر (AK1-…)، أو حزمة استرداد. تقبله الأوامر أيضًا بصيغة --key-file. يكتبه arkvory configure --vault-key-file. |
ARKVORY_BACKUP_BYTES_PER_SECOND | الوكيل | بلا حد | حد معدل النسخ في النسخة الاحتياطية، 65 536 على الأقل. |
ARKVORY_BACKUP_POLL_SECONDS | الوكيل | 15 | الفاصل الذي يتحقق فيه الوكيل من مهام النسخ الاحتياطي الجديدة، من 1 إلى 3600 ثانية. |
ARKVORY_BACKUP_LEASE_SECONDS | الوكيل | 60 | مدة الحجز (lease) التي تمنع وكيلًا ثانيًا من العمل في الوقت نفسه، من 2 إلى 3600 ثانية. |
ARKVORY_BACKUP_SNAPSHOT_SECONDS | الوكيل | 1800 | الحد الزمني لجزء لقطة قاعدة البيانات في النسخة الاحتياطية، من 60 إلى 86 400 ثانية. |
ARKVORY_BACKUP_BARRIER_SECONDS | الوكيل | 30 | المدة التي تنتظر فيها النسخة الاحتياطية خطوة تنظيف جارية، من 1 إلى 600 ثانية. |
ARKVORY_RESTORE_DATABASE_URL | أمر الاستعادة | غير مضبوط | قاعدة البيانات الهدف للاستعادة. وهو أكثر أمانًا من --database-url، لأن المستخدمين الآخرين لا يرونه في قائمة العمليات. |
راجع النسخ الاحتياطية.
المرايا
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_MIRRORS_FILE | API، العامل | غير مضبوط | ملف JSON يسرد المستودعات المنسوخة بمرآة (حتى 64). ويكتبه arkvory configure --mirror. |
ARKVORY_MIRRORS_CA_FILE | العامل | غير مضبوط | مسار مطلق إلى ملف PEM يضم جهات إصدار شهادات إضافية لخوادم المصدر. ويُتحقق من TLS دائمًا. |
راجع المرايا.
Webhook
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_WEBHOOKS_FILE | العامل | غير مضبوط | ملف JSON يسرد اشتراكات Webhook (حتى 16). من دونه لا تُرسَل أي Webhook. |
ARKVORY_WEBHOOKS_ALLOW_PRIVATE | العامل | غير مضبوط | شبكات بصيغة CIDR مفصولة بفواصل (حتى 32) يجوز أن تستقبل Webhook إضافة إلى العناوين العامة، مثل 10.20.0.0/16. |
ARKVORY_WEBHOOKS_CA_FILE | العامل | غير مضبوط | المسار المطلق لملف PEM يحوي سلطات شهادات إضافية للمستقبِلين. يُتحقَّق من TLS دائمًا. |
راجع Webhook.
عنقود عالي التوفر
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_REPLICA_SOCKET | API | غير معيّن | مقبس خدمة arkvory-replica. يعيّنه arkvory configure --cluster. عند تعيينه لا تحصل الكتابة على 2xx إلا عندما تكتمل النسخ المطلوبة. إن لم يُعيَّن فهو خادم مستقل. |
راجع High availability cluster.
التحديثات والمركز (hub)
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_HUB_URL | API | https://hub.proanima.net | عنوان مركز ProAnimaStudio، تستخدمه ملاحظات وحدة التحكم فقط (مركز التحديثات محفوظ في config/hub.json ويُغيَّر بالأمر arkvory configure). والقيمة الفارغة توقف الملاحظات. HTTPS فقط، أو HTTP على الحلقة المحلية. |
ARKVORY_HUB_PROJECT | API | arkvory | اسم المشروع في المركز. |
ARKVORY_UPDATE_CONTROL_DIR | API | غير مضبوط | الدليل الذي يشاركه API مع برنامج التحديث على المضيف. تضبطه برامج التثبيت. وبدونه لا تستطيع وحدة التحكم طلب التحديثات. |
راجع التحديثات.
السجلات والإيقاف
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_LOG_LEVEL | API، العامل، الوكيل | info | debug أو info أو warning أو error. |
ARKVORY_ACCESS_LOG | API | true | true يكتب سطر JSON واحدًا لكل طلب HTTP؛ وfalse يوقفه. |
ARKVORY_DRAIN_TIMEOUT_MS | API | 30000 | بعد إشارة الإيقاف، المدة المتاحة لانتهاء الطلبات الجارية، من 0 إلى 3 600 000 مللي ثانية. |
بوابات القراءة
عندما يُضبط أي من هذه المتغيرات، يصبح ضبط الفتحة (slot) وعدد الفتحات والمعدل المشترك مطلوبًا. يستخدم الكاتب الدور api والفتحة 0. وتستخدم كل بوابة قراءة الدور reader وفتحتها الخاصة. راجع بوابات القراءة.
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_ROLE | API | api | api (الكاتب) أو reader (بوابة قراءة). |
ARKVORY_GATEWAY_SLOTS | API | غير مضبوط | عدد العمليات التي تتقاسم ميزانية التنزيل، من 2 إلى 16. |
ARKVORY_GATEWAY_SLOT | API | غير مضبوط | فتحة هذه العملية، من 0 إلى عدد الفتحات ناقص واحد. |
ARKVORY_SHARED_DOWNLOAD_BYTES_PER_SECOND | API | غير مضبوط | معدل التنزيل الإجمالي لكل العمليات. تحصل كل فتحة على حصة متساوية، 65 536 بايت في الثانية على الأقل. |
ARKVORY_SHARED_DOWNLOAD_BYTES_PER_SECOND_PER_PRINCIPAL | API | 0 | معدل التنزيل الإجمالي لحساب أو مفتاح واحد عبر كل العمليات؛ و0 تعني بلا حد. |
المراقب الذاتي (Watchdog)
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_WATCHDOG_SECONDS | API، العامل، الوكيل | 60 | العملية التي تبقى محجوبة هذه المدة تنهي نفسها، ويبدأها مدير الخدمات مرة أخرى. و0 توقفه (لأجل مصحّح الأخطاء)؛ وإلا فالقيمة من 10 إلى 3600 ثانية. |
راجع الإصلاح الذاتي.
عميل سطر الأوامر
| المتغير | يقرؤه | الافتراضي | المعنى |
|---|---|---|---|
ARKVORY_BASE_URL | CLI | ملف التعريف، ثم http://127.0.0.1:8080 | عنوان الخادم. وعند ضبطه يجب أن يأتي المفتاح أيضًا من البيئة. |
ARKVORY_TOKEN | CLI | غير مضبوط | المفتاح نفسه. له الأولوية على ملف المفتاح. |
ARKVORY_TOKEN_FILE | CLI | ملف المفتاح في ملف التعريف | مسار ملف يحتوي على المفتاح. |
ARKVORY_CLI_HOME | CLI | ~/.config/arkvory | دليل الملف profiles.json. |
ARKVORY_CLI_VERSION | CLI | development | الإصدار الذي يطبعه --version. وتحتويه حزم الإصدار. |
راجع عميل سطر الأوامر.
نصوص التثبيت البرمجية
يقرأ install.sh على Linux هذه المتغيرات. أما على Windows فيستخدم install.ps1 معاملات مثل -Root و-Artifact بدلًا منها.
| المتغير | الافتراضي | المعنى |
|---|---|---|
ARKVORY_INSTALL_ROOT | /opt/proanima-arkvory | جذر التثبيت. لا تضع تثبيتًا أصليًا في دليل منزلي (home). |
ARKVORY_ARTIFACT_DIR | غير مضبوط | دليل إصدار مفكوك الضغط. يثبّته النص البرمجي بدلًا من تنزيل إصدار. |
ARKVORY_RELEASE_VERSION | أحدث إصدار مستقر | الإصدار المستقر المحدد الذي يُثبَّت، مثل 1.2.3. |
ما يضبطه برنامج التثبيت
يضبط برنامج التثبيت هذه المتغيرات لعملياته المساعدة. لا تضبطها بنفسك.
| المتغير | المعنى |
|---|---|
ARKVORY_IMAGE | صورة الحاوية للإصدار الحالي، في config/compose.env. |
ARKVORY_SERVICE_WRAPPER | مسار غلاف خدمة النسخ الاحتياطي في Windows، يُستخدم عندما تكون الخدمة متوقفة. |
ARKVORY_PROTECT_ROOT | جذر التثبيت الذي تُضبط قواعد الوصول إليه في Windows. |
ARKVORY_ENGINE_USER | على Windows مع Docker Desktop، يمنح المستخدم الحالي حق الوصول إلى الجذر. |