لماذا تستضيف أداة اختصار الروابط بنفسك
أداة الاختصار العامة تقرر نيابة عنك: قد تغيّر شروطها، أو تحدّ عدد الروابط، أو تضيف صفحة وسيطة، أو تتوقف، فتتعطل روابطك المطبوعة. إحصاءاتها ملك لها، ونطاقها المشترك يُحجب بانتظام من مرشحات مكافحة التصيّد لأن آخرين يسيئون استخدامه.
مع Kutt على خادمك يبقى الرابط go.your-domain.ma/offre ملكك دائمًا: يمكنك تغيير وجهته دون إعادة طباعة الملصق، ومعرفة من نقر ومن أين، ولا يرى أي طرف ثالث حملاتك. وبالنسبة إلى الوكالة فهي أيضًا خدمة تقدّمها لكل عميل على نطاقه الخاص.
ما يقدّمه Kutt
- روابط على نطاقك — كل رابط قصير يحمل علامتك ويبقى صالحًا حتى لو غيّرت الأداة لاحقًا.
- عناوين مخصّصة —
/rentreeأو/webinar، أو رمز من ستة أحرف يُولَّد دون أحرف ملتبسة. - كلمة مرور وتاريخ انتهاء — رابط محمي لمستند عميل، ورابط يتوقف عن التحويل بانتهاء العرض.
- إحصاءات خاصة — الزيارات عبر الزمن، والمتصفحات، والأنظمة، والبلدان، والمواقع المُحيلة، ولا يراها إلا المالك.
- واجهة REST — مفتاح لكل مستخدم لإنشاء الروابط وتعديلها وحذفها من سكربتاتك وأدواتك.
- الإدارة — إنشاء حسابات الفريق، ومراجعة كل الروابط، وحظر رابط أو نطاق مسيء.
Kutt وShlink وخدمة عامة
مرّر الجدول أفقيًا
| Kutt | Shlink | خدمة عامة (bit.ly…) | |
|---|---|---|---|
| واجهة الويب | مدمجة | عميل ويب منفصل | نعم |
| واجهة REST | نعم، مفتاح لكل مستخدم | نعم، مفاتيح تُدار من سطر الأوامر | نعم، غالبًا مدفوعة |
| نطاقك الخاص | نعم، مضمَّن | نعم، مضمَّن | خيار مدفوع |
| الإحصاءات | في قاعدتك | في قاعدتك | لدى المزوّد |
| حسابات الفريق | نعم، ينشئها المسؤول | لا، الدخول بمفتاح API | حسب الباقة |
| التخزين | SQLite أو PostgreSQL أو MySQL | SQLite أو PostgreSQL أو MySQL أو SQL Server | يديره المزوّد |
المتطلبات
يكفي خادم VPS بنظام Ubuntu 24.04 وذاكرة 512 ميغابايت وقرص 5 غيغابايت: يعمل Kutt في حاوية Node.js واحدة ويستهلك نحو 200 ميغابايت من الذاكرة. تحتاج إلى Docker مع إضافة Compose، وإلى nginx وcertbot من أجل HTTPS، وإلى اسم DNS يشير إلى الخادم.
اختر هذا الاسم بعناية لأنه يكوّن كل رابط: كلما كان أقصر قصرت روابطك. يصلح جيدًا نطاق فرعي مثل go.your-domain.ma أو نطاق صغير مخصّص. يكتب Kutt الاسم في كل رابط ينشئه، لذا فإن تغييره لاحقًا لا يعيد كتابة الروابط التي شاركتها.
تثبيت Kutt باستخدام Docker Compose
تحضير المجلد والأسرار
أنشئ مجلد التطبيق وملف
.envيحمل المفتاح السري (الذي يوقّع الجلسات) ونطاق الروابط القصيرة. استبدلgo.example.comباسمك.mkdir -p /opt/kutt && cd /opt/kutt printf 'SECRET_KEY=%s\nDOMAIN=go.example.com\n' "$(openssl rand -hex 32)" > .env chmod 600 .envكتابة ملف compose
أنشئ
compose.yaml. لا يُنشر المنفذ إلا على الواجهة المحلية: لا يصل إليه إلا nginx. يبقى التسجيل العام والروابط المجهولة مغلقين، وتعيش قاعدة SQLite في وحدة تخزين مسمّاة.services: kutt: image: kutt/kutt:v3.2.6 restart: unless-stopped ports: - "127.0.0.1:8107:3000" environment: JWT_SECRET: ${SECRET_KEY:?SECRET_KEY requis} DEFAULT_DOMAIN: ${DOMAIN:?DOMAIN requis} DB_CLIENT: better-sqlite3 DB_FILENAME: /var/lib/kutt/data.sqlite TRUST_PROXY: "true" DISALLOW_REGISTRATION: "true" DISALLOW_ANONYMOUS_LINKS: "true" volumes: - kutt-data:/var/lib/kutt - kutt-custom:/kutt/custom volumes: kutt-data: {} kutt-custom: {}التشغيل والتحقق
شغّل الحزمة. يطبّق Kutt عمليات الترحيل عند الإقلاع، ثم يجب أن يجيب فحص الصحة بالرمز 200.
docker compose up -d docker compose ps curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8107/api/v2/healthنشر Kutt عبر HTTPS
عرّف مضيفًا افتراضيًا في nginx يمرّر الطلبات إلى المنفذ المحلي، ثم اطلب الشهادة باستخدام certbot. تتيح الترويسة
X-Forwarded-Forلـ Kutt تسجيل العنوان الحقيقي للزائر (TRUST_PROXY).server { server_name go.example.com; location / { proxy_pass http://127.0.0.1:8107; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }certbot --nginx -d go.example.com
أنشئ حساب المسؤول دون تأخير
لا ينشئ Kutt أي حساب مسبقًا: ما دام لا يوجد مستخدم، تحوّل الصفحة الرئيسية إلى نموذج create admin، ويصبح أول زائر هو المسؤول. افتح نطاقك فور عمل HTTPS وأنشئ حسابك بكلمة مرور قوية. بعد ذلك يرفض النموذج أي إنشاء جديد.
إنشاء الروابط عبر الواجهة البرمجية
من إعدادات حسابك ولّد مفتاح API، ثم أرسله في الترويسة X-API-KEY. يقبل جسم JSON الحقل target (العنوان الطويل) واختياريًا customurl وpassword وdescription وexpire_in (مدة مثل 7 days).
curl -s -X POST https://go.example.com/api/v2/links \
-H "X-API-KEY: $KUTT_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"target": "https://example.com/une/adresse/tres/longue", "customurl": "promo", "expire_in": "7 days"}'يحتوي الرد على الحقل link، أي الرابط القصير كاملًا. ونقطة الوصول نفسها بطلب GET تعرض روابطك مع عدد زياراتها، ويعيد /api/v2/links/<id>/stats الإحصاءات المفصّلة لرابط واحد. وبهذا تربط Kutt بنظام إدارة العملاء أو بسكربت الفوترة أو بحملة بريدية: يُختصر كل رابط صادر ويُقاس دون تدخل.
العمل ضمن فريق
التسجيل مغلق: المسؤول هو من ينشئ الحسابات من صفحة الإدارة. لكل عضو روابطه وإحصاءاته الخاصة ومفتاحه، ويُلغى المفتاح بتوليد مفتاح جديد. يرى المسؤول كل روابط الخادم ويمكنه حظر رابط مسيء؛ وهذا مهم لأن أداة اختصار تحمل نطاقك تضع سمعته على المحك.
يقبل Kutt أيضًا نطاقات إضافية تُضاف من الإعدادات. يجب أن يشير كل منها إلى الخادم وأن يملك شهادته الخاصة: ابدأ بنطاق واحد ثم أضف الباقي واحدًا تلو الآخر.
تفعيل البريد الإلكتروني
يُثبَّت Kutt والبريد معطّل: لا إعادة تعيين لكلمة المرور بالبريد ولا تحقق من العناوين. لتفعيلها أضف إلى بيئة الحاوية MAIL_ENABLED: "true" والمتغيرات MAIL_HOST وMAIL_PORT وMAIL_USER وMAIL_PASSWORD وMAIL_FROM الخاصة بخادم SMTP، ثم أعد التشغيل بالأمر docker compose up -d. واحتفظ بكلمة مرور المسؤول في مكان آمن حتى ذلك الحين: بدون بريد يُعالَج فقدانها في قاعدة البيانات.
تحديد حجم الخادم
لفريق وبضعة آلاف من الروابط تكفي ذاكرة 512 ميغابايت ومعالج vCPU واحد: التحويل مجرد قراءة من القاعدة. تكبر قاعدة SQLite مع الزيارات المسجلة، بمعدل بضع مئات من البايتات لكل نقرة. وبعد مئات الآلاف من النقرات يوميًا انتقل إلى PostgreSQL (DB_CLIENT: pg) وفعّل Redis (REDIS_ENABLED) للتخزين المؤقت.
النسخ الاحتياطي والتحديث
كل البيانات في وحدة التخزين kutt-data: تحتوي قاعدة SQLite على الحسابات والروابط والإحصاءات. أوقف الحاوية لحظة للحصول على نسخة متسقة، ثم أرشف وحدة التخزين.
docker compose stop kutt
docker run --rm -v kutt_kutt-data:/data -v "$PWD":/backup alpine \
tar czf /backup/kutt-$(date +%F).tar.gz -C /data .
docker compose start kuttللتحديث اقرأ ملاحظات الإصدار في المشروع، وغيّر وسم الصورة، ثم اسحب الصورة الجديدة: تُطبَّق عمليات الترحيل عند الإقلاع. خذ دائمًا نسخة احتياطية قبل ذلك مباشرة.
# changer l'étiquette de l'image dans compose.yaml, puis :
docker compose pull && docker compose up -dالتثبيت بنقرة واحدة من متجر ServOrbit
على خادم VPS من ServOrbit يُثبَّت Kutt من المتجر في مساحة العميل: اختر العنوان — نطاقًا فرعيًا قصيرًا من أحد نطاقاتك أو النطاق الفرعي المجاني للخادم مع HTTPS — ثم انقر «تثبيت». ينشر السكربت الحاوية، ويولّد المفتاح السري، ويضبط نطاق الروابط، ويهيّئ nginx. لا يبقى عليك إلا فتح نطاقك لإنشاء حساب المسؤول، ثم أول مفتاح API.
