अवधारणाएँ

यह पृष्ठ उन शब्दों को समझाता है जो बाकी पृष्ठ इस्तेमाल करते हैं। हर अनुभाग छोटा है और उस पृष्ठ से लिंक करता है जो विषय को पूरा समझाता है। एक पंक्ति की परिभाषाओं के लिए शब्दावली देखें।

इंस्टॉलेशन और उसकी सेवाएँ

एक इंस्टॉलेशन एक सर्वर है। यह एक PostgreSQL डेटाबेस के साथ तीन Arkvory सेवाएँ चलाता है:

भाग	यह क्या करता है
API	HTTP सर्वर: HTTP API, वेब कंसोल, और कंटेनर, Git LFS व npm के लिए रजिस्ट्रियाँ। यह प्रतिधारण और भौतिक क्लीनअप भी चलाता है।
वर्कर	पृष्ठभूमि के काम: बड़े अपलोड पूरे करता है और मिरर सिंक्रनाइज़ करता है।
बैकअप एजेंट	बैकअप स्टोरेज (vault) में निर्धारित बैकअप।
PostgreSQL	कैटलॉग: आर्टिफ़ैक्ट, पैकेज, संशोधन, खाते, कुंजियाँ और जॉब।

फ़ाइल की सामग्री सर्वर की एक स्थानीय डायरेक्टरी में रहती है, डेटाबेस में नहीं। सभी भाग इंस्टॉलेशन रूट में रहते हैं (Windows पर C:\ProgramData\ProAnima\Arkvory, Linux पर /opt/proanima-arkvory)। सेवाएँ किसी साइन-इन किए हुए उपयोगकर्ता के बिना शुरू होती हैं और क्रैश या हैंग के बाद फिर से शुरू हो जाती हैं (स्वतः पुनर्प्राप्ति)।

एक इंस्टॉलेशन उच्च उपलब्धता (high availability) वाला क्लस्टर नहीं है। सर्वर रुक जाए तो क्लाइंट प्रतीक्षा करते हैं और फिर अपने ट्रांसफ़र जारी रखते हैं। इंस्टॉलेशन चुनें देखें। Linux पर दो या तीन सर्वर मिलकर उच्च उपलब्धता क्लस्टर बना सकते हैं।

रिपॉज़िटरी

एक रिपॉज़िटरी सामग्री के लिए एक नामित स्थान है। इसके अपने एक्सेस नियम, अपनी स्टोरेज नीति (कोटा और प्रतिधारण) और वैकल्पिक रूप से एक मिरर स्रोत होता है। रिपॉज़िटरी नाम में 1 से 64 अक्षर होते हैं: छोटे लैटिन अक्षर, अंक, - और _, जो किसी अक्षर या अंक से शुरू हो।

आप अलग कमांड से रिपॉज़िटरी नहीं बनाते। रिपॉज़िटरी तभी अस्तित्व में आती है जब किसी समूह को उसके नाम पर एक्सेस दिया जाता है या कोई सेवा खाता नीति उसका नाम लेती है। नए इंस्टॉलेशन में पहली रिपॉज़िटरी के लिए जगह होती है, releases। रिपॉज़िटरी देखें।

आर्टिफ़ैक्ट

एक आर्टिफ़ैक्ट एक सहेजी गई फ़ाइल है। यह अपरिवर्तनीय है: इसके बाइट कभी नहीं बदलते। इसका एक UUID, एक नाम (/ या \ के बिना, 240 अक्षर तक), एक आकार और एक SHA-256 चेकसम होता है। नई सामग्री एक नया आर्टिफ़ैक्ट बनाती है; यह पुराने को कभी नहीं बदलती।

कोई आर्टिफ़ैक्ट तभी दिखाई देता है जब सर्वर जाँच लेता है कि बाइट घोषित आकार और SHA-256 से मेल खाते हैं। डाउनलोड वही बाइट लौटाता है, साथ में मज़बूत ETag के रूप में चेकसम। Arkvory पर बाकी सब कुछ आर्टिफ़ैक्ट पर टिका है: एक पैकेज संस्करण, किसी पथ का संशोधन, एक कंटेनर लेयर और एक Git LFS ऑब्जेक्ट — सभी आर्टिफ़ैक्ट हैं।

अपलोड

एक अपलोड भविष्य के आर्टिफ़ैक्ट को आरक्षित करता है। आप फ़ाइल के नाम, आकार और SHA-256 के साथ, और एक Idempotency-Key के साथ एक अपलोड सत्र बनाते हैं जो अनुरोध को दोहराने के लिए सुरक्षित बनाता है। फिर आप बाइट भेजते हैं:

• छोटी और मध्यम फ़ाइलों के लिए एक ही अनुरोध में; या
• बड़ी फ़ाइलों के लिए भागों में। भाग का आकार सर्वर चुनता है: कम से कम 8 MiB, बहुत बड़ी फ़ाइलों के लिए दोगुना, ताकि अपलोड को कभी 10,000 से अधिक भागों की ज़रूरत न पड़े। एक भाग कभी 1 GiB से अधिक नहीं होता। हर भाग का अपना SHA-256 होता है, और दोहराया गया भाग नुकसानदेह नहीं है।

फिर आप अपलोड पूरा करते हैं। सर्वर पूरी फ़ाइल जाँचता है और उसे प्रकाशित करता है। बड़ी फ़ाइलों के लिए वर्कर अपलोड को एक पूर्णता जॉब में पूरा करता है जिसे क्लाइंट फ़ॉलो करता है; SDK और कमांड-लाइन क्लाइंट 16 GiB और उससे बड़ी फ़ाइलों के लिए इसे चुनते हैं। एक अपलोड सत्र 7 दिन तक रहता है। रुका हुआ अपलोड उन भागों से जारी रहता है जो सर्वर के पास पहले से हैं। सबसे बड़ा ऑब्जेक्ट 10,000 GiB है, जब तक व्यवस्थापक कम ARKVORY_MAX_OBJECT_BYTES सेट न करे।

कमांड-लाइन क्लाइंट और SDK यह सब आपके लिए करते हैं। ट्रांसफ़र और अपलोड संदर्भ देखें।

पैकेज

एक पैकेज एक UPack आर्काइव है जिसे Arkvory ने पंजीकृत किया है। इसकी पहचान एक समूह, एक नाम और एक SemVer संस्करण है, उदाहरण के लिए acme / game-server / 1.4.2। समूह पहचान का हिस्सा है: अलग-अलग समूहों में एक ही नाम वाले दो पैकेज अलग पैकेज हैं। प्रकाशित संस्करण कभी नहीं बदलता; उसी संस्करण को दूसरी सामग्री के साथ प्रकाशित करना अस्वीकार कर दिया जाता है।

एक डिप्लॉयमेंट एजेंट पैकेज को सटीक संस्करण से, ^1.4 जैसी संस्करण श्रेणी से, या किसी स्टेज पर सबसे नए संस्करण से माँगता है। प्री-रिलीज़ संस्करण तभी दिखते हैं जब आप उन्हें माँगते हैं। पैकेज देखें।

पथ वाली फ़ाइलें

एक पथ वाली फ़ाइल का पता builds/game/1.4/Setup.exe जैसा होता है और यह किसी आर्टिफ़ैक्ट की ओर इशारा करती है। जब आप उस पथ पर नई बाइट सहेजते हैं, तो पथ को एक नया संशोधन मिलता है (1, 2, 3 और आगे)। पिछले संशोधन इतिहास में रहते हैं, और आप किसी एक को पुनर्स्थापित कर सकते हैं: पुनर्स्थापित करने से पुरानी सामग्री वाला नया संशोधन जुड़ता है। वही बाइट फिर से सहेजने से कुछ नहीं जुड़ता।

एक पथ में अधिकतम 1,024 अक्षर होते हैं, विभाजक के रूप में / इस्तेमाल होता है, और उसमें कोई खाली, . या .. खंड और कोई : नहीं होता। कोई बदलाव उस संशोधन का नाम लेता है जिसकी वह अपेक्षा करता है; अगर कोई दूसरा बदलाव पहले आ गया, तो सर्वर 409 उत्तर देता है। ऐसे पथ के लिए 0 इस्तेमाल करें जो अभी मौजूद नहीं है। फ़ाइलें और पथ और रॉ फ़ाइलें देखें।

लेबल, मेटाडेटा, संग्रह और अटैचमेंट

आप किसी आर्टिफ़ैक्ट के बाइट को छुए बिना उसका वर्णन कर सकते हैं:

मद	नियम
लेबल	nightly या tested जैसे अधिकतम 32 छोटे टैग।
मेटाडेटा	अधिकतम 32 टेक्स्ट फ़ील्ड; एक कुंजी में अधिकतम 64 अक्षर, एक मान में अधिकतम 1,024।
संग्रह	आर्टिफ़ैक्ट को समूहित करने वाले नामित सेट।
अटैचमेंट	एक बिल्ड से उसी रिपॉज़िटरी के अन्य आर्टिफ़ैक्ट तक अधिकतम 32 लिंक: एक मैनिफ़ेस्ट, एक SBOM, एक हस्ताक्षर, एक रिपोर्ट या कोई अन्य फ़ाइल।

लेबल, मेटाडेटा और संग्रह एक संशोधित सेट के रूप में बदलते हैं। अटैचमेंट का अपना संशोधन और इतिहास होता है।

स्टेज और प्रमोशन

एक स्टेज किसी बिल्ड पर एक नियंत्रित चिह्न है, जैसे qa, release या prod। स्टेज नाम में छोटे अक्षर, अंक, ., _ और - (अधिकतम 32 अक्षर) इस्तेमाल होते हैं, और एक आर्टिफ़ैक्ट पर अधिकतम 16 स्टेज हो सकते हैं। स्टेज बदलने के लिए उसकी अपनी अनुमति artifact.promote चाहिए, और हर बदलाव अभिनेता, समय और टिप्पणी के साथ दर्ज होता है।

प्रमोशन किसी बिल्ड को बाइट दोबारा भेजे बिना किसी दूसरी रिपॉज़िटरी में प्रकाशित करता है। copy स्रोत रखता है; move बिल्ड को स्रोत रिपॉज़िटरी से हटा भी देता है। प्रमोशन दोहराने पर मौजूद प्रति लौटती है। Resolve वह बिल्ड ढूँढता है जिसकी ओर कोई स्टेज और संस्करण श्रेणी इशारा करते हैं। प्रमोशन देखें।

खाते, समूह और अनुमतियाँ

लोग खाते इस्तेमाल करते हैं। एक खाते का एक नाम (3 से 64 अक्षर) और एक पासवर्ड (12 से 128 अक्षर) होता है। एक व्यवस्थापक खाता खातों और समूहों का प्रबंधन करता है। खाते समूहों से संबंधित होते हैं, और किसी समूह को रिपॉज़िटरी पर read या write ("पढ़ें और लिखें") एक्सेस दिया जाता है। हर अनुरोध पर अधिकार फिर से गिने जाते हैं, इसलिए बदलाव तुरंत लागू होता है।

ऑटोमेशन इसके बजाय सेवा खाता इस्तेमाल करता है। इसकी नीति प्रति रिपॉज़िटरी सटीक कार्रवाइयाँ सूचीबद्ध करती है, जैसे upload.create या content.read, और इसकी कुंजियाँ उस नीति को केवल संकुचित कर सकती हैं। सर्वर हर कार्रवाई जाँचता है; कंसोल में कोई बटन छिपाना सुरक्षा नहीं है। खाते और एक्सेस और प्रमाणीकरण देखें।

कुंजियाँ और टोकन

हर अनुरोध के साथ एक क्रेडेंशियल होता है। चार प्रकार आप बनाते हैं, और एक अंतर्निहित है:

क्रेडेंशियल	किसके लिए	अवधि
कंसोल सत्र	नाम और पासवर्ड से साइन-इन किया हुआ व्यक्ति	12 घंटे
व्यक्तिगत एक्सेस टोकन	एक व्यक्ति की स्क्रिप्ट और टूल	डिफ़ॉल्ट रूप से 90 दिन, अधिकतम 365
सेवा कुंजी	CI/CD और डिप्लॉयमेंट एजेंट	डिफ़ॉल्ट रूप से 90 दिन, अधिकतम 365
डाउनलोड लिंक	बिना कुंजी वाले किसी व्यक्ति को एक आर्टिफ़ैक्ट सौंपना	60 सेकंड से 24 घंटे (डिफ़ॉल्ट रूप से 1 घंटा)
पुनर्प्राप्ति कुंजी	इंस्टॉलेशन स्वयं	समाप्त नहीं होती

एक सेवा कुंजी एक बार जारी होती है, एक बार दिखाई जाती है, और सक्रिय होने के बाद ही उपयोग योग्य बनती है। आप इसे रोटेट कर सकते हैं (नई जारी करें, फिर पुरानी सेवानिवृत्त करें) और हमेशा के लिए निरस्त कर सकते हैं। प्रमाणीकरण देखें।

स्वामी और पुनर्प्राप्ति कुंजी

स्वामी पहला खाता है। यह एक व्यवस्थापक है और समूह arkvory-owners का सदस्य है, जिसके पास releases पर write एक्सेस है। इसे Windows इंस्टॉलर बनाता है; Linux और Docker पर आप इसे कंसोल में पुनर्प्राप्ति कुंजी से बनाते हैं।

पुनर्प्राप्ति कुंजी एक सीक्रेट है जिसे इंस्टॉलर इंस्टॉलेशन रूट में config/bootstrap-token.txt में लिखता है। यह पहला स्वामी और खाते बना सकती है, सेवा खातों और उनके प्रत्यायोजनों का प्रबंधन कर सकती है, बैकअप चला सकती है, और अपडेट माँग सकती है। इंस्टॉलेशन टूल इसे सर्वर पर पढ़ते हैं। यह CI या रोज़ के काम के लिए नहीं है: इसे सर्वर पर रखें और इसकी प्रति न बनाएँ। इंस्टॉलेशन चुनें और सुरक्षा देखें।

प्रतिधारण, कोटा और क्लीनअप

एक स्टोरेज नीति किसी रिपॉज़िटरी की होती है। यह हर पैकेज के (या हर पैकेज और चैनल के) अंतिम N बिल्ड रख सकती है, लेबल और स्टेज को हटाने से बचा सकती है, कुछ भी हटाने से पहले न्यूनतम आयु प्रतीक्षा कर सकती है, और चेतावनी व गंभीर सीमाओं वाला कोटा तय कर सकती है। यह तब तक बंद रहती है जब तक व्यवस्थापक इसे चालू न करे। आर्टिफ़ैक्ट हटाना पहले तार्किक होता है: बाइट छूट अवधि (डिफ़ॉल्ट रूप से 24 घंटे) तक डिस्क पर रहते हैं और फिर भौतिक क्लीनअप पृष्ठभूमि में, छोटे बैचों में, सर्वर रोके बिना जगह खाली करता है।

सर्वर खाली डिस्क स्थान का एक रिज़र्व भी रखता है (डिफ़ॉल्ट रूप से 1 GiB) जिसका उपयोग अपलोड कभी नहीं करते। स्टोरेज देखें।

बैकअप

बैकअप एजेंट डेटाबेस और सारी प्रकाशित सामग्री को बैकअप स्टोरेज (vault) में कॉपी करता है, जो किसी दूसरी डिस्क या नेटवर्क शेयर पर एक फ़ोल्डर है। एक पूरी प्रति एक पुनर्स्थापना बिंदु है। एजेंट हर बिंदु की जाँच करता है, बिंदुओं पर प्रतिधारण लागू करता है (डिफ़ॉल्ट रूप से 7 दैनिक, 4 साप्ताहिक और 6 मासिक) और आपको किसी बिंदु को पिन करने देता है ताकि प्रतिधारण उसे रखे। दैनिक शेड्यूल तब तक बंद रहता है जब तक व्यवस्थापक इसे शेड्यूल और प्रतिधारण में चालू न करे।

पुनर्स्थापित करना सर्वर पर एक कमांड है। यह एक खाली डेटाबेस और एक खाली स्टोरेज डायरेक्टरी में लिखता है। बैकअप देखें।

मिरर और रीड गेटवे

एक मिरर किसी रिपॉज़िटरी की रीड-ओनली प्रति है जिसे दूसरा इंस्टॉलेशन पहले यानी स्रोत का अनुसरण करके रखता है। यह बदलाव अस्वीकार करता है और डाउनलोड परोसता है। अगर स्रोत खो जाए, तो एक ऑपरेटर मिरर को अलग कर देता है और वह एक साधारण रिपॉज़िटरी बन जाता है; यह स्विच हाथ से होता है और स्वचालित फ़ेलओवर नहीं है। मिरर देखें।

एक रीड गेटवे उसी स्टोरेज पर एक अतिरिक्त API प्रोसेस है जो केवल GET और HEAD का उत्तर देता है। राइटर और गेटवे एक ही डाउनलोड बैंडविड्थ बजट साझा करते हैं। रीड गेटवे देखें।

आगे कहाँ जाएँ

1. त्वरित शुरुआत: Arkvory इंस्टॉल करें और पहली फ़ाइल अपलोड करें।
2. खाते और एक्सेस: लोग, समूह, टोकन और सेवा कुंजियाँ।
3. HTTP API अवलोकन: वे नियम जो हर इंटीग्रेशन को चाहिए।
4. शब्दावली: हर शब्द की छोटी परिभाषा।