لماذا تستضيف مسجّل npm خاصاً على VPS
ثلاثة سيناريوهات تجعل مسجّل npm الخاص ضرورياً للفرق البرمجية. الأول: إدارة المكتبات الداخلية — إذا طوّرت نظام تصميم، أدوات مساعدة خاصة بمنظمتك، أو عملاء API داخليين، فإن نشر هذه الحزم على npmjs.org يعرّضها للعموم. مسجّل خاص يبقيها خلف بنيتك التحتية، مُعرَّفة بالإصدار ومتاحة فقط لمطوّريك وخطوط أنابيب CI الخاصة بك.
الثاني: استقرار خطوط أنابيب CI — يتعطّل npmjs.org عدة مرات في السنة، وكل عطل قد يوقف عمليات النشر لساعات. Verdaccio يخزّن كل حزمة عامة محمَّلة محلياً: التثبيت الثاني عبر npm install — سواء في CI أو محلياً — لا يصل إلى الشبكة أبداً. تتسارع بنياتك وتصبح مستقلة عن توافر السجل العام.
الثالث: العمل في بيئات معزولة أو بدون إنترنت — بعد تسخين الذاكرة المؤقتة، يخدم Verdaccio جميع الحزم المُشاهَدة سابقاً دون اتصال بالإنترنت. هذا مفيد لبيئات الامتثال الصارمة أو خطوط الأنابيب الداخلية أو العروض التوضيحية بدون Wi-Fi. كل هذا في حاوية Docker واحدة خفيفة (أقل من 128 ميغابايت RAM)، بلا قاعدة بيانات خارجية ولا إعداد معقّد.
مزايا Verdaccio المستضاف ذاتياً
- حزم خاصة تحت نطاقك — انشر مكتباتك الداخلية دون كشفها للعموم.
- تخزين مؤقت محلي لـnpmjs.org — بنيات CI تستمر حتى عند تعطّل السجل العام.
- صفر تبعيات خارجية — حاوية Docker واحدة وحجم واحد، بلا قاعدة بيانات.
- أقل من 128 ميغابايت RAM — يعمل على أصغر VPS دون تأثير على الخدمات الأخرى.
- متوافق مع npm وYarn وpnpm — فقط غيّر URL السجل.
- وضع بلا إنترنت — سخّن الذاكرة مرة واقطع الاتصال: بنياتك تبقى قابلة للاستنساخ.
المتطلبات
Verdaccio أحد أخف الخدمات التي يمكن نشرها على VPS. قائمة المتطلبات قصيرة عمداً: VPS بـ1 vCPU و512 ميغابايت RAM (Verdaccio يستخدم أقل من 128 ميغابايت في التشغيل العادي) وDocker مثبَّت. لا يلزم أي نطاق للبدء — يمكنك الوصول إلى السجل عبر نفق SSH من محطة عملك أو من runner CI.
للوصول الدائم من قِبَل الفريق أو خطوط أنابيب CI المستضافة في مكان آخر، أضف نطاقاً من لوحة تحكم ServOrbit: سيوكّله nginx تلقائياً عبر HTTPS، وتُدار شهادة TLS بواسطة ServOrbit دون أي تدخل منك. للتخزين، خطّط مساحة القرص بما يتناسب مع الاستخدام — الحزم العامة المخزَّنة مؤقتاً والحزم الخاصة تتراكم في حجم Docker مستمر.
نشر Verdaccio على VPS ServOrbit
الطلب من Marketplace ServOrbit
من منطقة عملاء ServOrbit، ثبّت Verdaccio بنقرة واحدة من Marketplace: اختر فئة التطوير، حدّد Verdaccio، وأكّد طلبك. تُنشر الحاوية Docker تلقائياً على VPS الخاص بك مع healthcheck مدمج يتحقق من استجابة السجل كل 30 ثانية. ستتلقى إشعاراً فور جاهزية الخدمة مع المنفذ المُخصَّص لها.
الاتصال عبر نفق SSH
افتح نفق SSH من جهازك المحلي:
ssh -L 4873:127.0.0.1:<port> root@<ip-vps>. ثم وجّه npm نحو النفق:npm set registry http://localhost:4873. لـYarn 2+ (Berry)، أضفnpmRegistryServer: "http://localhost:4873"إلى.yarnrc.yml. لـpnpm:pnpm config set registry http://localhost:4873. تُطبَّق هذه الإعدادات على مستوى النظام في~/.npmrcأو على مستوى المشروع في.npmrcعند جذر المستودع.إنشاء أول حساب
نفّذ
npm adduser --registry http://localhost:4873. أدخل اسم المستخدم وكلمة المرور والبريد الإلكتروني. يصبح هذا المستخدم مدير السجل بصلاحيات القراءة والنشر الكاملة. يمكنك إنشاء حسابات إضافية بالأمر ذاته — كل مطوّر يحصل على بياناته الخاصة ورمز وصول مستقل يمكن إلغاؤه بشكل منفرد.نشر أول حزمة خاصة
في مجلد الحزمة، نفّذ
npm publish --registry http://localhost:4873. تأكد من أن حقلnameفيpackage.jsonيتضمن نطاقك الخاص (مثل@org/package) للتمييز عن الحزم العامة. تحقق من نجاح النشر على واجهة Verdaccio: تظهر حزمتك في القائمة مع رقم إصدارها، وهي الآن متاحة لأي مطوّر أو pipeline CI مصادَق على سجّلك.إضافة نطاق للوصول الدائم
من منطقة عملاء ServOrbit، أضف نطاقاً أو نطاقاً فرعياً إلى VPS الخاص بك. سيوكّل nginx Verdaccio تلقائياً عبر HTTPS. حدّث
.npmrcالعام (registry=https://verdaccio.your-domain.com) أو متغير البيئةNPM_CONFIG_REGISTRYفي إعدادات CI. يمكن لعدّائي GitHub Actions وGitLab CI وغيرهم الوصول إلى السجل الآن دون الحاجة إلى نفق SSH.
للوصول الدائم من قِبَل الفريق، أضف نطاقاً من لوحة ServOrbit. سيوكّل nginx Verdaccio عبر HTTPS تلقائياً — اضبط .npmrc العام (registry=https://verdaccio.your-domain.com) أو عرّف NPM_CONFIG_REGISTRY في متغيرات CI لربط عدّائي GitHub Actions وGitLab CI وأدوات pnpm.
ضبط النطاقات وقواعد الوكالة
افتراضياً، يبحث Verdaccio أولاً عن الحزمة في التخزين المحلي ثم يوكّل طلب التنزيل إلى npmjs.org في حال غيابها. هذا السلوك مناسب للبدء، لكن معظم الفرق تريد ضبطاً دقيقاً حسب النطاق.
التهيئة تعيش في config.yaml، يمكن الوصول إليه من حجم Docker (verdaccio-storage). قسم packages: يعرّف القواعد بأنماط الأسماء. لنطاق خاص (@acme/*)، يمكنك تعطيل الوكالة إلى npmjs.org وتقييد الوصول للمستخدمين المصادق عليهم فقط.
مثال بسيط:
packages:
'@acme/*':
access: $authenticated
publish: $authenticated
'**':
access: $all
proxy: npmjsبعد التعديل، أعد تشغيل الحاوية: docker compose restart verdaccio. تُطبَّق التهيئة دون إعادة تحميل قاعدة الحزم. يضمن هذا النهج أن حزمك الخاصة لن تصل أبداً إلى npmjs.org، حتى في حال خطأ في التهيئة.
التكامل مع CI/CD
لاستخدام Verdaccio في GitHub Actions، عيّن متغير البيئة NPM_CONFIG_REGISTRY ورمز المصادقة ${{ secrets.VERDACCIO_TOKEN }} في سير العمل. احصل على الرمز المميز بـ npm token create --registry https://verdaccio.your-domain.com من أي حساب Verdaccio:
jobs:
build:
env:
NPM_CONFIG_REGISTRY: https://verdaccio.your-domain.com
NPM_CONFIG_//verdaccio.your-domain.com/:_authToken: ${{ secrets.VERDACCIO_TOKEN }}لـGitLab CI، استخدم قسم variables: في .gitlab-ci.yml مع نفس متغيرات البيئة. كلا المنصتين يدعمان متغيرات CI الآمنة المشفرة — لا تضع رمز Verdaccio في ملف .npmrc مباشرةً في المستودع.
يُقلّص التخزين المؤقت مدة تثبيت node_modules من 30–60 ثانية إلى 2–5 ثوانٍ في البنيات المتكررة، لأن الحزم العامة تُخدَم من ذاكرة Verdaccio المؤقتة بدلاً من الشبكة. لتحقيق أقصى فائدة في CI، شغّل خطوة التسخين (npm install على فرع رئيسي) قبل اختبار فروع الميزات.
الأمان والتحكم في الوصول
يستخدم Verdaccio افتراضياً مصادقة htpasswd مع تشفير bcrypt — آمن لفريق صغير. للتوسع، يدعم Verdaccio مكونات إضافية للمصادقة: LDAP، GitLab، GitHub OAuth، وKeycloak.
لرموز وصول CI: استخدم npm token create --registry https://verdaccio.your-domain.com بدلاً من تخزين كلمة مرور نصية. يمكن إلغاء أي رمز بشكل مستقل دون التأثير على المستخدمين الآخرين. خزّن الرمز في أسرار CI (${{ secrets.VERDACCIO_TOKEN }} في GitHub Actions) وليس في ملفات المستودع.
على ServOrbit، Verdaccio مرتبط بـ127.0.0.1 ومعرّض فقط عبر وكيل nginx العكسي. المنفذ 4873 غير مكشوف مباشرة على الإنترنت — nginx يضيف TLS، والنطاق الموكّل فقط يستجيب على المنفذ 443. للأمان الأقصى، فعّل المصادقة الإجبارية للقراءة (access: $authenticated في config.yaml) إذا كان سجّلك يحتوي على حزم حساسة. افتراضياً، يسمح Verdaccio بالقراءة المجهولة — مناسب لذاكرة الحزم العامة، لكن ينبغي تقييده للحزم الخاصة والملكية.
