SSD Nodes Learn Hosting plans →
الأدلة Matt Connorبقلم Matt Connor · آخر تحديث في 2026-10-21

إنشاء أداة تقصير روابط مستضافة ذاتياً باستخدام Shlink

أنشئ أداة تقصير روابط على VPS باستخدام Shlink وDocker Compose، مع نطاق قصير وPostgres ومفاتيح API وعميل الويب ورموز QR وإحصاءات النقرات.

ما الذي ستبنيه

أداة تقصير روابط مستضافة ذاتياً هي خادم صغير يحوّل الرابط الطويل إلى رابط قصير تملكه، ويحصي كل نقرة عليه. الخيار المناسب هو Shlink: فهو مفتوح المصدر، ويتوفر على هيئة Docker image، وينفّذ المهمة كاملة داخل حاوية واحدة مع قاعدة بيانات. يضع هذا الدليل الأداة على VPS خلف نطاق قصير فعلي، مع HTTPS ومفتاح API ورموز QR وإحصاءات النقرات.

يتكوّن هذا الحل من جزأين يجعلان استخدامه شبيهاً بأدوات تقصير الروابط التجارية. يستجيب خادم API لعمليات إعادة التوجيه ويحتفظ بالبيانات. أما عميل الويب فهو تطبيق static منفصل يتصل بواجهة API من متصفحك. يمكنك تشغيل الجزأين معاً، أو تشغيل API فقط والتحكم بها من سطر الأوامر.

أرقام الإصدارات الواردة هنا هي الإصدارات الحالية حتى October 2026: Shlink 5.1 وshlink-web-client 4.8.

اجعل نطاقاً قصيراً يشير إلى الخادم أولاً

النطاق هو المنتج. يظهر s.example.com/abc123 في الروابط التي يراها المستخدمون، لذلك اختر اسماً قصيراً وحدده قبل تثبيت أي شيء. يخزّن Shlink النطاق مع كل عنوان URL مختصر، ويؤدي تغييره لاحقاً إلى توقف كل رابط سبق أن وزعته عن العمل.

أنشئ سجل DNS من نوع A للنطاق القصير، ووجّهه إلى عنوان IPv4 العام لخادم VPS. أضف أيضاً سجلاً من نوع AAAA إذا كان الخادم يدعم IPv6. ثم تأكد من أن النطاق يُحل قبل المتابعة.

dig +short s.example.com A

يجب أن يكون الناتج هو عنوان خادمك. إذا كان الناتج فارغاً، فهذا يعني أن السجل لم ينتشر بعد، وستفشل كل خطوة لاحقة بطريقة مربكة، لأن تعذر إصدار شهادة TLS (أمان طبقة النقل) لاسم لا يُحل.

ملف compose

يحتاج Shlink إلى قاعدة بيانات. يعمل SQLite للاختبار، لكن Postgres هو الخيار المناسب لأي بيانات تخطط للاحتفاظ بها، لأن سجلات الزيارات تتراكم ولأن Postgres يتعامل مع الفهارس والكتابات المتزامنة بصورة أفضل. ضع ما يلي في /opt/shlink/compose.yaml.

services:
  shlink:
    image: shlinkio/shlink:stable
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      DEFAULT_DOMAIN: s.example.com
      IS_HTTPS_ENABLED: "true"
      DB_DRIVER: postgres
      DB_HOST: database
      DB_NAME: shlink
      DB_USER: shlink
      DB_PASSWORD: ${DB_PASSWORD}
    depends_on:
      - database

  database:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: shlink
      POSTGRES_USER: shlink
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - shlink_db:/var/lib/postgresql/data

  web-client:
    image: shlinkio/shlink-web-client:stable
    restart: unless-stopped
    ports:
      - "127.0.0.1:8081:8080"

volumes:
  shlink_db:

يرتبط كلا المنفذين المنشورين بـ 127.0.0.1، لذلك لا يمكن الوصول إلى أي شيء من الإنترنت قبل إعداد reverse proxy في القسم التالي. يكتب Docker قواعد إعادة التوجيه الخاصة به قبل جدار حماية المضيف، ما يعني أن سطر 8080:8080 عادي سيعرّض التطبيق للوصول حتى على جهاز يبدو جدار حمايته مغلقاً. يؤدي الربط بعنوان loopback إلى تجنّب ذلك. ينطبق النمط نفسه على أي تطبيق تشغّله بهذه الطريقة، وترد تفاصيل إضافية عنه في دليل Docker Compose على VPS.

تأتي كلمة مرور قاعدة البيانات من ملف .env بجانب ملف compose، لذلك لا تُحفظ داخل YAML.

sudo mkdir -p /opt/shlink
printf 'DB_PASSWORD=%s\n' "$(openssl rand -base64 24)" | sudo tee /opt/shlink/.env
sudo chmod 600 /opt/shlink/.env

شغّله وراقب بدء تشغيل API.

cd /opt/shlink
sudo docker compose up -d
sudo docker compose logs -f shlink

ينفّذ التشغيل الأول عمليات ترحيل قاعدة البيانات، لذلك يستغرق وقتاً أطول من عمليات التشغيل اللاحقة. بعد استقرار الخدمة، تحقّق من أنها تستجيب محلياً.

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/rest/health

تعني 200 أن API يعمل وأن اتصال قاعدة البيانات سليم. وتعني 503 أن Shlink يعمل، لكن فحص قاعدة البيانات فشل. تستجيب نقطة health بـ 503 عند حدوث أي خطأ في قاعدة البيانات، ولا تستجيب أبداً بـ 500. إذا طبع curl بدلاً من ذلك 000، فلا توجد خدمة تستجيب على المنفذ: لقد توقفت الحاوية أثناء فحوص بدء التشغيل، ويعيد Docker تشغيلها، لذا راجع السجلات أعلاه. في كلتا الحالتين، يكون السبب المعتاد هو أن DB_PASSWORD في .env لا يطابق القيمة التي أُنشئت بها Postgres، لأن صورة Postgres تقرأ POSTGRES_PASSWORD فقط عند تهيئة دليل بيانات فارغ. لا يؤثر تعديل كلمة المرور لاحقاً حتى تزيل volume وتبدأ من جديد.

إنهاء HTTPS أمامه

يقدّم Shlink خدمة HTTP عادية على المنفذ 8080. يجب إنهاء TLS في reverse proxy، والإعداد الوحيد المهم هو تمرير اسم المضيف الأصلي. يحدد Shlink النطاق الذي ينتمي إليه الرمز المختصر بقراءة الرأس Host، لذلك فإن proxy يعيد كتابته ينتج استجابات 404 للروابط الموجودة، ويربط إحصاءات الزيارات بالنطاق الخطأ.

server {
    server_name s.example.com;
    listen 80;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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 على Ubuntu 24.04.

sudo certbot --nginx -d s.example.com

إنّ IS_HTTPS_ENABLED: "true" في ملف compose هو ما يجعل Shlink يطبع https:// في عناوين URL المختصرة التي يعيدها. لا يفعّل ذلك TLS بحد ذاته. اتركه false خلف HTTPS proxy، وستكون كل وصلة يعيدها API وصلة http:// ثم تعيد التوجيه، ما يضيف دورة ذهاب وإياب ويبدو غير صحيح في عميل الويب.

إنشاء مفتاح API

لا يمكن لأي جهة الاتصال بواجهة API من دون مفتاح. أنشئ مفتاحاً باستخدام CLI داخل الحاوية.

sudo docker compose exec shlink shlink api-key:generate --name "web client"

يعرض الأمر المفتاح مرة واحدة. انسخه الآن، لأنه يُخزَّن بصيغة تجزئة ولا يمكن عرضه مرة أخرى. يعرض shlink api-key:list أسماء المفاتيح وما إذا كان كل مفتاح مفعّلاً، لكنه لا يعرض المفتاح نفسه. أبطِل أحد المفاتيح باستخدام shlink api-key:disable واسمه.

تتضمن كل مكالمة REST المفتاح في رأس X-Api-Key.

curl -H "X-Api-Key: YOUR_KEY" https://s.example.com/rest/v3/short-urls

يعني كائن JSON يحتوي على مفتاح shortUrls أن المفتاح يعمل. ويعني 401 تكون قيمة type فيه هي https://shlink.io/api/error/invalid-api-key، مع العنوان Invalid API key، أن المفتاح غير صحيح أو معطّل أو انتهت مدة صلاحيته.

أنشئ روابط قصيرة من سطر الأوامر

يُعد CLI أسرع طريقة لإنشاء الروابط، كما أنه مناسب للبرامج النصية.

sudo docker compose exec shlink shlink short-url:create https://example.com/a/very/long/path
sudo docker compose exec shlink shlink short-url:create https://example.com/docs --custom-slug docs --tag reference

يمنحك --custom-slug رابطاً سهل القراءة بدلاً من رمز مُنشأ تلقائياً. تكون الأجزاء التعريفية فريدة لكل نطاق، لذلك تفشل المحاولة الثانية باستخدام جزء تعريفي مستخدم بدلاً من استبدال الرابط الأول بصمت. يمكنك تكرار --tag، وتُستخدم الوسوم لتجميع الروابط التي ستحتاج إلى إحصاءات مشتركة لها لاحقاً.

اعرض العناصر الموجودة، ثم اطّلع على حركة المرور الخاصة بأحد الروابط.

sudo docker compose exec shlink shlink short-url:list
sudo docker compose exec shlink shlink short-url:visits docs

يطبع short-url:visits صفاً واحداً لكل نقرة، متضمناً التاريخ، والمُحيل، ووكيل المستخدم. تبقى أعمدة الدولة والمدينة فارغة ما لم تضبط متغير البيئة GEOLITE_LICENSE_KEY، وهو مفتاح MaxMind مجاني يستخدمه Shlink لتنزيل قاعدة بيانات GeoLite2. من دونه، يستمر تسجيل الزيارات، لكن لا يجري تحديد مواقعها.

عميل الويب ورموز QR

أصبح عميل الويب الآن على 127.0.0.1:8081 ويحتاج إلى إدخال وكيل خاص به، أو نفق SSH إذا كنت تفضّل عدم نشره. يطلب عنوان الخادم ومفتاح API عند التحميل الأول. أدخل https://s.example.com والمفتاح الذي أنشأته. يحتفظ العميل بكليهما في مساحة تخزين المتصفح، ويتصل بواجهة API لديك مباشرةً، لذلك لا تمر أي بيانات عبر جهة أخرى. يستحق فصل الواجهة عن واجهة API الانتباه، لأنه النمط نفسه الذي يتيح لـHalcyon تحويل مكتبة Jellyfin إلى متجر تأجير من تسعينيات القرن الماضي دون تغيير خادم الوسائط الموجود خلفها.

تُنشأ رموز QR من عميل الويب، وليس من واجهة API. أزال Shlink 5 الحيلة القديمة المتمثلة في إلحاق /qr-code بعنوان URL المختصر، لذلك لم يعد هذا العنوان يعرض صورة. يرسم عميل الويب الرمز في متصفحك بدلاً من ذلك، دون إرسال طلب إلى Shlink. افتح خيار رمز QR لأي رابط في قائمة عناوين URL المختصرة، واضبط الحجم والتنسيق والهامش، ثم نزّل النتيجة. ارفع مستوى تصحيح الأخطاء لرمز يظل قابلاً للمسح عند طباعته بحجم صغير أو تغطية جزء منه. يتيح مربع الحوار نفسه أيضاً ضبط الألوان وإضافة شعار.

شغِّله باستمرار

قد يتعطل تطبيق اختصار الروابط بصمت. تتوقف الروابط عن إعادة التوجيه، ولا يخبرك أحد بذلك لأن الشخص الذي نقر عليها افترض أن الرابط غير صالح. وجّه فحص الجاهزية إلى عنوان URL مختصر فعلي، وليس إلى الصفحة الرئيسية، وأرسل تنبيهاً عند ظهور أي استجابة غير إعادة توجيه. تنفّذ نسخة Uptime Kuma المستضافة ذاتياً ذلك جيداً، ويمكنها التحقق من رمز حالة محدد.

أنشئ نسخة احتياطية من قاعدة البيانات، وليس من الحاوية. يفرغها أمر واحد.

sudo docker compose exec -T database pg_dump -U shlink shlink | gzip > shlink-$(date +%F).sql.gz

يعيد هذا الملف مع ملف compose الخدمة بالكامل على خادم جديد. يحتاج كل تطبيق على الخادم إلى نسخة مستقلة من هذين الملفين. وتُعد مكتبة الصور الحالة المعقدة، لأن PhotoPrism وImmich يحتفظان بالملفات الأصلية على القرص، إضافة إلى الصفوف في قاعدة البيانات. لذلك تعيد النسخة المفرغة الحسابات والإعدادات، لكنها لا تعيد صورة واحدة. تُنفّذ الترقيات عبر sudo docker compose pull ثم sudo docker compose up -d، ويشغّل Shlink أي عمليات ترحيل جديدة عند بدء التشغيل. أنشئ النسخة المفرغة قبل تنفيذ pull، لأن عملية الترحيل لا يمكن التراجع عنها.

FAQ

لماذا تُرجع الروابط المختصرة رمز 404 بعد إضافة Reverse Proxy؟

يطابق Shlink الرمز المختصر مع النطاق الموجود في الترويسة Host. إذا أرسل الـProxy اسمه الخاص أو عنواناً داخلياً، فسيبحث Shlink عن ذلك الرمز ضمن نطاق لا يحتوي على روابط، ولذلك يُرجع 404. اضبط proxy_set_header Host $host; في كتلة الموقع في nginx، ثم أعد تحميل الـProxy. ستعمل الروابط فوراً، من دون إعادة تشغيل الحاوية.

هل أحتاج إلى Postgres، أم تكفي SQLite؟

تكفي SQLite لتجربة Shlink، ولا تحتاج إلى حاوية ثانية. انتقل إلى Postgres قبل نشر روابط مهمة، لأن صفوف الزيارات تزداد مع كل نقرة، ولأن SQLite تجعل عمليات الكتابة متسلسلة. يتطلب التبديل لاحقاً تصدير الروابط وإعادة استيرادها، لذلك يوفّر اختيار Postgres من البداية عملية الترحيل هذه.

هل يمكنني استعادة مفتاح API نسيت نسخه؟

لا. يخزّن Shlink تجزئة المفتاح، لذلك يعرض api-key:list الأسماء والحالة، لكنه لا يعرض قيمة المفتاح مطلقاً. أنشئ بديلاً باستخدام shlink api-key:generate، والصقه في عميل الويب، ثم عطّل المفتاح القديم باستخدام shlink api-key:disable حتى يتوقف عن العمل.

لماذا تكون أعمدة البلدان فارغة في إحصاءات الزيارات؟

تحتاج خدمة تحديد الموقع الجغرافي إلى قاعدة بيانات GeoLite2، ولا ينزّلها Shlink إلا عند تزويده بـ GEOLITE_LICENSE_KEY. المفتاح مجاني من MaxMind. أضفه إلى قسم البيئة، ثم أعد إنشاء الحاوية، وستُحدَّد مواقع الزيارات الجديدة. ستبقى الزيارات المسجّلة قبل ذلك فارغة إلى أن تشغّل shlink visit:locate.

احتفظ بالنطاق وانقل البيانات. أنشئ نسخة تفريغ من قاعدة البيانات باستخدام pg_dump، وانسخ النسخة وملف compose إلى الخادم الجديد، ثم شغّل المكدس واستعد النسخة في قاعدة البيانات الفارغة قبل وصول حركة الشبكة الفعلية. غيّر سجل DNS أخيراً. ستبقى الرموز المختصرة وسجل زياراتها، لأن كل شيء مخزّن في قاعدة البيانات.

هل كان هذا المقال مفيدًا؟