SSD Nodes Learn Hosting plans →
الأدلة Matt Connorبقلم Matt Connor

استضافة LinkBreeze ذاتياً كبديل لـ Linktree

شغّل LinkBreeze على VPS باستخدام Docker Compose وCaddy، مع تثبيت وسوم الصور، وتتبع نقرات بلا ملفات تعريف ارتباط، ومعرفة المجلد الوحيد الذي يحفظ موقعك بالكامل.

ما هو LinkBreeze

LinkBreeze بديل مستضاف ذاتياً لخدمة Linktree. وهو حاوية Docker واحدة تعرض صفحة عامة للروابط في النبذة ولوحة تحكم إدارية، وتخزّن قاعدة بياناتها في ملف SQLite واحد. المشروع مرخّص بموجب MIT، ومكتوب بلغة TypeScript باستخدام Next.js، ومنشور كصورة حاوية على Docker Hub باسم omnirise/linkbreeze وعلى GHCR باسم ghcr.io/omnirise/linkbreeze؛ وكانت الإصدارات الأقدم تستخدم ghcr.io/manak-hash/linkbreeze. لتشغيله، تحتاج إلى VPS، ونطاق يحتوي على سجل A يشير إلى ذلك الـVPS، وفتح المنفذين 80 و443، وDocker Engine مع إضافة Compose.

يغطي هذا الدليل طريقة النشر التي يدعمها المستودع فعلياً: Docker Compose خلف Reverse Proxy يتولى جلب الشهادات بنفسه. كما يوضح أسباب الأعطال، لأن الرابط الموجود في النبذة هو عنوان URL عام ينقر عليه الآخرون، وتعطّله يعني فقدان النقرة.

قبل كل ذلك، انتبه إلى حداثة هذا المشروع.

هل LinkBreeze ناضج بما يكفي لاستخدامه كرابط ملف شخصي عام؟

يعود أول إصدار موسوم، v1.0.0، إلى 1 July 2026. هذا مشروع عمره بضعة أشهر، وليس بضع سنوات.

تشير سجلّات التغييرات إلى مشكلات في مستوى ظهور حساب GitHub. في 2 November 2026، أصبح مستودع GitHub الأساسي في github.com/OmniRise/LinkBreeze عاماً، إلى جانب نسخة GitLab الرسمية المطابقة للمشروع، gitlab.com/omnirise00/linkbreeze، مع صورة المشروع على Docker Hub.

رسم بيانيLinkBreeze tagged releases per week, v1.0.0 to v1.4.1
البيانات وراء هذا الرسم البياني
[
  {
    "week": "2026-06-29",
    "releases": 3,
    "cumulative": 3
  },
  {
    "week": "2026-07-06",
    "releases": 3,
    "cumulative": 6
  },
  {
    "week": "2026-07-13",
    "releases": 1,
    "cumulative": 7
  },
  {
    "week": "2026-07-20",
    "releases": 2,
    "cumulative": 9
  },
  {
    "week": "2026-07-27",
    "releases": 3,
    "cumulative": 12
  },
  {
    "week": "2026-08-03",
    "releases": 2,
    "cumulative": 14
  },
  {
    "week": "2026-08-10",
    "releases": 4,
    "cumulative": 18
  },
  {
    "week": "2026-08-17",
    "releases": 1,
    "cumulative": 19
  },
  {
    "week": "2026-08-24",
    "releases": 1,
    "cumulative": 20
  },
  {
    "week": "2026-08-31",
    "releases": 0,
    "cumulative": 20
  },
  {
    "week": "2026-09-07",
    "releases": 0,
    "cumulative": 20
  },
  {
    "week": "2026-09-14",
    "releases": 1,
    "cumulative": 21
  },
  {
    "week": "2026-09-21",
    "releases": 1,
    "cumulative": 22
  }
]

منذ v1.0.0، أصدر المشروع 22 إصداراً موسوماً عبر 13 أسابيع تقويمية، حتى الإصدار v1.4.1 في 23 September 2026. ينتهي هذا المخطط عند v1.4.1؛ ثم صدر v1.5.0 في 24 October، وv1.5.1 في 27 October 2026.

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

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

ثبّت وسم الصورة، ولا تستخدم latest

يدفع سير عمل الإصدار الحالي وسمين لكل إصدار إلى Docker Hub وGHCR: latest، ووسم Git كما دُفع تماماً، بما في ذلك v. لذلك يكون الوسم المثبّت للإصدار v1.4.1 هو docker.io/omnirise/linkbreeze:v1.4.1. كانت الإصدارات السابقة لـ v1.4.0 تستخدم وسوماً مختلفة: كان سير العمل يزيل v، ولا توجد هذه الإصدارات إلا على GHCR كأرقام مجردة مثل ghcr.io/manak-hash/linkbreeze:1.2.7. إذا كتبت الوسم بصيغة غير صحيحة للإصدار، فسيعرض Docker الخطأ manifest unknown، لأن هذا الوسم لم يُدفع قط. ويحتوي Docker Hub، الذي يستخدمه README الآن كمسار السحب الافتراضي، أيضاً على v1.5.1، وهو الوسم المحدد في حزمة Unraid الرسمية للمشروع.

ثبّت الوسم لأن latest يتغير. وفق الوتيرة الموضحة في المخطط أعلاه، فإن docker compose pull إلى latest يمثل ترقية غير خاضعة للمراجعة لصفحة يستخدمها جمهورك. عند تثبيت الوسم، تحدث الترقية عندما تعدّل الملف.

هناك نقطة أخرى بشأن الصورة. منذ v1.4.0، أصبحت الصورة قائمة manifest متعددة المعماريات لكل من linux/amd64 وlinux/arm64، وقد بُني كل منهما على runner أصلي. إذا كنت تستخدم خادماً افتراضياً ARM بدلاً من x86، فسيسحب الوسم نفسه نسخة arm64، ولن تحتاج إلى تجميع أي شيء على الخادم. نُشرت الإصدارات حتى v1.3.2 لـ linux/amd64 فقط، واستُبعدت لوحات arm/v7 ذات 32 بت عمداً، لذلك سيظل الوسم الأقدم أو اللوحة ذات 32 بت يفشلان مع خطأ no matching manifest.

نشر LinkBreeze خلف Caddy مع TLS تلقائي

يطلب Caddy الشهادات من Let's Encrypt ويجددها تلقائياً، لذلك لا تحتاج إلى خطوة منفصلة لإعداد شهادة TLS (أمان طبقة النقل). يتكوّن النشر بالكامل من ثلاثة ملفات في دليل واحد.

أنشئ السر أولاً:

mkdir -p ~/linkbreeze && cd ~/linkbreeze
printf 'SECRET_KEY=%s\n' "$(openssl rand -hex 32)" > .env
chmod 600 .env

يوقّع SECRET_KEY ملف تعريف ارتباط جلسة المسؤول، ويضيف قيمة عشوائية إلى تجزئة زائر التحليلات، ومنذ الإصدار v1.4.0 يشتق أيضاً المفتاح الذي يشفّر أسرار المصادقة الثنائية (TOTP) المخزنة. يضبط ملف Compose المنشور مع الإصدار v1.4.1 هذه القيمة افتراضياً على ${SECRET_KEY:-changeme-in-production}، لذلك تعمل النسخة التي تستخدم هذا الملف من دون ضبط السر بمفتاح توقيع جلسة مطبوع في المستودع العام للمشروع. اضبطه قبل التشغيل الأول، لأن تغييره لاحقاً يسجّل خروجك ويعيد ضبط قيمة التحليلات العشوائية.

اكتب docker-compose.yml:

services:
  linkbreeze:
    image: docker.io/omnirise/linkbreeze:v1.4.1
    restart: unless-stopped
    volumes:
      - linkbreeze-data:/app/data
    environment:
      - DATABASE_PATH=/app/data/linkbreeze.db
      - SECRET_KEY=${SECRET_KEY}
      - BASE_URL=https://links.example.com
    networks:
      - linkbreeze-net

  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    networks:
      - linkbreeze-net

networks:
  linkbreeze-net:

volumes:
  linkbreeze-data:
  caddy-data:
  caddy-config:

يُعد BASE_URL اختيارياً، لكن من المفيد ضبطه. فهو يعرّف التطبيق بعنوانه العام الحقيقي، وبذلك لا يستطيع طلب يصل مع ترويسة Host مزوّرة أن يجعل التطبيق ينشئ روابط إلى نطاق يخص شخصاً آخر.

اكتب Caddyfile بجانبه، باستخدام نطاقك الخاص:

links.example.com {
    encode zstd gzip
    reverse_proxy linkbreeze:3000
}

يضبط Caddy X-Forwarded-For وX-Forwarded-Proto في الطلبات الممررة افتراضياً. توفّر الأولى عنوان العميل للتحليلات، وتحدّد الثانية بروتوكول النقل المستخدم لتأمين ملف تعريف ارتباط الجلسة. شغّل الحاويات:

docker compose up -d
docker compose ps
docker compose logs -f caddy

يجب أن يعرض docker compose ps حاوية LinkBreeze بالحالة healthy. تتضمن الصورة فحص سلامة خاصاً بها، وهو wget --spider -q http://127.0.0.1:3000/api/health، لذلك لا تحتاج إلى إضافة فحص آخر. لا تنسخ فحص السلامة من مثال Caddy الموجود في المستودع نفسه. فهو يستدعي curl، بينما تُبنى الصورة على node:22-alpine، الذي يحتوي على busybox wget ولا يحتوي على curl. وتبلغ تلك الحاوية عن unhealthy رغم أنها تقدّم الصفحات بصورة سليمة.

افتح https://links.example.com في متصفح. تنقلك الزيارة الأولى إلى معالج الإعداد في /setup، الذي ينشئ حساب المسؤول الوحيد. بعد ذلك توجد لوحة المعلومات في /dashboard، ونموذج تسجيل الدخول في /login. في الإصدار المثبت v1.4.1، يكون هذا الحساب محلياً لهذه النسخة، ولا توجد نقطة ربط لتسجيل الدخول الأحادي. لذلك، إذا أردت حماية لوحة المعلومات بتسجيل الدخول نفسه المستخدم لحماية كل ما تستضيفه، فعليك تنفيذ ذلك عبر وكيل مصادقة أمامي مثل Authentik مستضاف ذاتياً. أُدرج تسجيل الدخول الأحادي الأصلي عبر OIDC ضمن الميزات غير المُصدرة حتى 2 November 2026.

لاحظ ما لا يفعله ملف Compose: فهو لا ينشر المنفذ 3000 مطلقاً. يستمع Caddy وحده على الواجهة العامة. إذا كانت صيغة ملفات Compose جديدة عليك، يشرح دليل أساسيات Docker Compose لخادم VPS الأجزاء التي يفترضها هذا الملف. وإذا كنت تشغّل خدمة أخرى أمامه، يشرح مقارنة بين Nginx وCaddy وTraefik التغييرات المطلوبة. يوفّر المستودع أمثلة جاهزة للعمل على Nginx مع Certbot، وعلى Traefik، وعلى نفق Cloudflare.

مكان وجود بياناتك وما يجب أن تتضمنه النسخة الاحتياطية

يشير DATABASE_PATH إلى /app/data/linkbreeze.db. تُكتب الصور الرمزية المرفوعة والصور المصغّرة للروابط بجانبه في /app/data/uploads. وكلاهما موجود في وحدة التخزين المسماة linkbreeze-data، لذلك تكون وحدة النسخ الاحتياطي هي وحدة التخزين، وليس ملف قاعدة البيانات وحده. إذا استعدت الملف من دون دليل uploads، فستُرجع كل صورة في الصفحة خطأ 404.

كل ما عدا ذلك موجود فعلاً في قاعدة البيانات الواحدة: الصفحات، والروابط، والإعدادات، والسمة، ومشتركو البريد الإلكتروني، وصفوف التحليلات.

أنشئ النسخة مع إيقاف الحاوية:

docker compose stop linkbreeze
docker compose cp linkbreeze:/app/data ./backup-$(date +%F)
docker compose start linkbreeze

أوقف الحاوية أولاً، لأن نسخ قاعدة بيانات SQLite أثناء كتابة عملية إليها قد يلتقط معاملة غير مكتملة، وعندها تُفتح النسخة كملف تالف. تصبح الصفحة غير متاحة أثناء إنشاء النسخة. وتتم الاستعادة بالطريقة نفسها مع عكس الاتجاه:

docker compose stop linkbreeze
docker compose cp ./backup-2026-08-14/. linkbreeze:/app/data
docker compose start linkbreeze
docker compose logs -f linkbreeze

توفّر لوحة التحكم أيضاً تصديراً بتنسيق JSON، ويُقدَّم من /api/backup على أنه linkbreeze-backup-YYYY-MM-DD.json. يتضمن ملف التصدير الملف الشخصي، والروابط وأقسامها، والإعدادات، والسمات المحفوظة، وإدخالات الخطوط المخصصة. ولا يتضمن سجل التحليلات، أو مشتركي البريد الإلكتروني، أو حساب المسؤول، أو الملفات المرفوعة. وعند استعادته، يحذف الصفوف الحالية في الجداول الستة التي يتضمنها، ثم يُدرج صفوف الملف. تعامل معه كلقطة لإعدادات النظام عند نقل الاستضافة أو التراجع عن خطأ في التحرير. أما نسخة وحدة التخزين فهي النسخة الاحتياطية.

تنطبق هنا قاعدتا التخزين نفسهما كما في أي مكان آخر عند تشغيل SQLite في بيئة إنتاج على VPS. احتفظ بقاعدة البيانات على قرص محلي، لأن آلية القفل في SQLite غير موثوقة على نظام ملفات شبكي، ولأنك قد لا تكتشف تلف الصفحة إلا بعد حدوثه. وإذا استبدلت وحدة التخزين المسماة بعملية bind mount إلى المضيف، فنفّذ chown على دليل المضيف أولاً: تعمل الحاوية كمستخدم non-root هو node، ومعرّفه uid 1000 في node:22-alpine، ولا يكون الدليل الذي أنشأه root قابلاً للكتابة من هذا المستخدم، لذلك لا يستطيع التطبيق فتح قاعدة البيانات وتخرج الحاوية عند بدء التشغيل. يشرح استخدام Bind mounts مع وحدات التخزين المسماة في Compose هذا المفاضلة بالكامل.

التحليلات، ولافتة الموافقة التي لا تحتاج إليها

هذه هي الميزة التي تبرر استضافة صفحة ذاتياً، رغم إمكانية الحصول عليها مجاناً من مكان آخر.

التحليلات لا تستخدم ملفات تعريف الارتباط. لا تنشئ التحليلات المضمّنة ملف تعريف ارتباط للزائر، ولا تحمّل أي script لتتبّع من طرف ثالث؛ أما التحليلات الخارجية وعمليات التضمين فهي ميزات اختيارية. يُحدَّد الزائر بواسطة تجزئة SHA-256 لعنوان IP وسلسلة user agent وsalt، ثم تُقتطع النتيجة إلى 16 محرفاً سداسياً عشرياً. وsalt نفسه عبارة عن تجزئة للتاريخ الحالي بتوقيت UTC ولـ SECRET_KEY، لذلك يتغير عند منتصف الليل بتوقيت UTC، ولا يمكن مطابقة تجزئات الأمس بتجزئات اليوم. لا يُكتب عنوان IP الخام في قاعدة البيانات مطلقاً.

تُحتسب النقرات على الخادم. يشير كل رابط http في الصفحة العامة إلى /go/<id> على نطاقك أنت، حيث تُسجَّل النقرة ثم يُرسَل رد بإعادة توجيه 302 إلى الوجهة الفعلية. لذلك يعمل العد مع القراء الذين عطّلوا JavaScript، وداخل المتصفحات المضمّنة في التطبيقات التي تحظر الطلبات في الخلفية. تُسجَّل مشاهدات الصفحة على الخادم عند عرض الصفحة العامة؛ ويتولى /api/track معالجة أحداث النقر وفتح النوافذ المنبثقة.

هناك استثناءان مهمان. يُتجاوز أي طلب يحمل جلسة admin صالحة، حتى لا يؤدي تعديل صفحتك إلى زيادة الأرقام. كما تُتجاوز أيضاً user agents المعروفة الخاصة بالزواحف.

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

هناك ملاحظة قد تفاجئ بعض المستخدمين: عند تدوير SECRET_KEY، يتغير salt اليومي معه، ولذلك يُحتسب كل زائر عائد على أنه زائر جديد منذ تلك اللحظة.

لماذا يكون عمود الدولة فارغاً في التحليلات؟

لأن أياً من مكوّنات الحزمة لا يعيّن ترويسة للدولة. يستخرج LinkBreeze الدولة من ترويسات الوكيل مثل cf-ipcountry وx-vercel-ip-country. عند تشغيل الخادم الافتراضي الخاص VPS خلف Caddy أو Nginx الخاص بك، لا توجد أي من هذه الترويسات، لذلك تُسجَّل الدولة بالقيمة null ويبقى التقسيم فارغاً. لا توجد قاعدة بيانات GeoIP داخل الحاوية.

هناك طريقتان لملء هذا العمود. ضع Cloudflare أمام النطاق وفعّل Managed Transform باسم Add visitor location headers لتوفير cf-ipcountry. أو عيّن إحدى هذه الترويسات في الـreverse proxy الخاص بك بالاعتماد على بحث GeoIP محلي.

المشكلة المرتبطة بذلك أخطر، لذا تحقّق منها أيضاً. تقرأ معالجات النقرات ومرات العرض عنوان العميل من X-Forwarded-For أولاً، ثم X-Real-IP، وتستخدم 0.0.0.0 كبديل عند غياب الترويستين. إذا نشرت المنفذ 3000 مباشرةً على الإنترنت من دون ترويسة عنوان، فسيشارك الزوار الذين يستخدمون وكيل المستخدم نفسه قيمة hash ضمن كل يوم UTC؛ بينما ينتج وكلاء المستخدم المختلفون قيماً مختلفة، وتتغير قيمة hash يومياً. بعد ذلك، تنطبق حدود المعدل لكل عنوان IP، وهي 60 حدثاً في الدقيقة على /api/track و/go/<id>، على جمهورك بأكمله باستخدام العنوان البديل. عند استخدام توجيه reverse_proxy أعلاه، يعيّن Caddy الترويسة نيابةً عنك وتختفي المشكلتان.

الاستيراد من Linktree وما لا ينتقل

يقبل معالج الترحيل في لوحة التحكم عنوان URL عاماً للملف الشخصي أو ملفاً مُصدَّراً. ويتعرّف على صفحات linktr.ee وbento.me وlnk.bio وtap.link وhopp.bio وbeacons.ai وsolo.to وlinkfly وmssg.me وLittleLink، إضافةً إلى صادرات HTML وJSON العامة. عند استخدام عنوان URL من Linktree أو Bento، يقرأ معالج الترحيل JSON ‏__NEXT_DATA__ الذي تضمّنه تلك الصفحات. أما في الصفحة الثابتة، فيقرأ وسوم الارتباط.

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

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

يجلب المستورد عنوان URL من خادمك بدلاً من متصفحك، لذلك يرفض العناوين غير العامة. يعني Private/local URLs are not allowed أنك قدّمت عنواناً داخل شبكتك الخاصة، وهذا الرفض مقصود: من دونه، يمكن لأي شخص يملك صلاحية الوصول إلى لوحة التحكم استخدام خادمك لفحص أجهزة لا يستطيع الوصول إليها إلا خادمك. والرسائل الأخرى التي قد تراها هي Only http and https URLs are allowed وRequest timed out وResponse too large.

يعتمد الاستخراج على بنية HTML التي يحددها طرف آخر. في الإصدار v1.5.1، يعالج المستورد خطأً في Linktree كان يجعله يجلب روابط الإحالة الخاصة بالمنصة بدلاً من الروابط الخاصة بالملف الشخصي. حدّث البرنامج قبل الاستيراد من Linktree؛ فالملفات الشخصية التي لا تُعرَض روابطها إلا في المتصفح تحتاج إلى استخدام علامة التبويب File أو إلى الإدخال اليدوي. إذا لم يعثر المعالج على شيء في صفحة تحتوي بوضوح على روابط، فأضف الروابط يدوياً بدلاً من انتظار إصلاح. إذا كان ما تريده فعلياً هو روابط قصيرة قابلة للقياس بدلاً من صفحة ملف شخصي، فإن مقصّر عناوين URL مستضاف ذاتياً مثل Shlink ينفّذ هذه المهمة ويعمل بسهولة على الخادم نفسه.

تحديث عملية نشر مثبتة

# edit the image tag in docker-compose.yml, then
docker compose pull
docker compose up -d
docker compose logs -f linkbreeze

تُجرى عمليات ترحيل المخطط تلقائياً عند بدء الحاوية. لا توجد طريقة موثقة لإجرائها بصورة عكسية، لذلك أنشئ نسخة من الـvolume أولاً. لا يكون التحديث الذي لا يمكنك التراجع عنه آمناً إلا إذا أمكنك استعادة الحالة السابقة.

من المفترض أن تعرض لوحة المعلومات شريطاً عند توفر إصدار أحدث. يتحقق الإصدار المثبت v1.4.1 من ملف إصدار صغير على GitHub؛ ومنذ الإصدار v1.5.0، الذي صدر في 24 October 2026، يجلب فحص الشريط linkbreeze.omnirise.dev/latest-version.json. تُخزَّن النتائج مؤقتاً لمدة 24 ساعة، لكن زر Check now اليدوي يتجاوز هذه الذاكرة المؤقتة، بما في ذلك في الإصدار v1.4.1. لا ترسل هذه الفحوصات أي بيانات عن النسخة في حمولة الطلب. يذكر سجل التغييرات أن الإصدارات من v1.2.0 إلى v1.4.0 كانت تستعلم عن عنوان يعيد الاستجابة 404، ولذلك لم تعرض الشريط مطلقاً. إلى أن تشغّل إصداراً يستخدم نقطة نهاية الموقع، لا تنتظر ظهور الشريط؛ راقب سجل التغييرات في linkbreeze.omnirise.dev/changelog بنفسك. في الإصدار v1.5.1، تحتوي Settings أيضاً على بطاقة لحالة التحديث تتحقق من GitHub ومن الموقع، مع زر Recheck يتجاوز الذاكرة المؤقتة. اقرأ ملاحظات الإصدار قبل نقل الوسم، لأن الإصدار الثانوي قد يغيّر في هذه المرحلة من المشروع الإعدادات الافتراضية التي تعتمد عليها.

حالات الفشل والنصوص التي ستظهر

manifest unknown عند السحب. كُتب الوسم بصيغة غير صحيحة لإصداره. ابتداءً من v1.4.0، تحتفظ الوسوم بـv، لذا استخدم :v1.4.1. تستخدم إصدارات GHCR حتى v1.3.2 أرقاماً مجردة مثل :1.2.7، كما يحتوي Docker Hub أيضاً على وسوم إصدارات أحدث مثل v1.5.1.

no matching manifest for linux/arm64/v8 in the manifest list entries. ثبّتَّ إصداراً أقدم من v1.4.0، وكان منشوراً لمعمارية amd64 فقط. انقل التثبيت إلى v1.4.1، فهو يتضمن بنية arm64. يحصل جهاز arm/v7 ذو 32-bit على النوع نفسه من الخطأ في كل إصدار، لأن هذه المنصة لا تُبنى عمداً.

يُبلغ الحاوي عن unhealthy بينما تُحمّل الصفحة دون مشكلة. يستدعي فحص السلامة في ملف compose لديك curl، لكن الصورة لا تتضمنه. احذفه ودَع فحص السلامة wget الخاص بالصورة يعمل.

يعرض Caddy خطأ في الشهادة، أو لا يعرض شيئاً إطلاقاً. تحقّق من docker compose logs caddy. تأكد من أن سجل A يشير إلى VPS هذا، وأن المنفذين 80 و443 قابلان للوصول. يستطيع Caddy إجراء التحقق عبر تحدي HTTP على المنفذ 80 أو تحدي TLS-ALPN على المنفذ 443.

تظل قيمة الزوار الفريدين عند 1. تحقّق مما إذا كان الـproxy يضبط X-Forwarded-For أو X-Real-IP. من دون أي من الرأسين، يتشارك الزوار الذين لديهم وكلاء مستخدم متطابقون قيمة hash واحدة خلال كل يوم UTC. تتضمن قيمة hash أيضاً salt يومياً، لذلك لا تؤدي الرؤوس المفقودة إلى جعل قيمة hash متطابقة لكل الزوار إلى الأبد.

تخرج الحاوية مباشرة بعد بدء التشغيل، رغم أنها كانت تعمل بالأمس. إذا انتقلت من volume مسمّى إلى bind mount من المضيف، فسيكون دليل البيانات مملوكاً للحساب root، بينما يعمل التطبيق بالمعرّف uid 1000، ولذلك يتعذر عليه فتح ملف قاعدة البيانات. sudo chown -R 1000:1000 دليل المضيف.

تُجاب طلبات التتبع بحالة HTTP 429. تم بلوغ حد الطلبات لكل IP على /api/track. أما الحد المنفصل على /go/<id>، فيتخطى تسجيل النقرة لكنه يعيد توجيه 302 إلى الوجهة.

FAQ

هل أصبح LinkBreeze جاهزاً لاستخدامه في رابط عام داخل النبذة؟

ما يزال المشروع حديثاً، ويعود تاريخ الإصدار الأول إلى 1 July 2026. أصدر 22 إصداراً موسوماً بين ذلك التاريخ والإصدار v1.4.1 في 23 September 2026، وكان معظمها قبل منتصف August، لذلك تغيّر سلوكه بسرعة. صدر الإصداران v1.5.0 وv1.5.1 في 24 و27 October 2026، وأصبح مستودع GitHub الأساسي عاماً في 2 November 2026. يتيح لك ترخيص MIT وملف SQLite المحلي الاحتفاظ بصفحة تعمل حتى إذا توقف التطوير، لكن تطبيق ويب عاماً من دون إصلاحات أمنية يتحول إلى مسؤولية، لذلك تعامل معه كبرنامج ستواصل تحديثه، وليس كبرنامج تثبّته مرة واحدة.

ما وسم صورة LinkBreeze الذي ينبغي تشغيله؟

شغّل وسم الإصدار، مثل docker.io/omnirise/linkbreeze:v1.4.1، وغيّره عمداً. منذ v1.4.0، تدفع عملية الإصدار latest ووسم git مسبوقاً بـ v، لذلك لا وجود لـ :1.4.1 من دون v، ويرد Docker بالرسالة manifest unknown. أما الإصدارات حتى v1.3.2 فتعمل بالعكس: لا توجد في GHCR إلا الأرقام المجردة. تُبنى الصورة لـ linux/amd64 وlinux/arm64 منذ v1.4.0، لذلك تسحبها VPS بمعمارية arm64 مباشرةً من دون بناء محلي.

لماذا يبقى توزيع البلدان فارغاً في تحليلات LinkBreeze؟

يقرأ LinkBreeze بلد الزائر من رؤوس Proxy مثل cf-ipcountry أو x-vercel-ip-country، ولا يتضمن قاعدة بيانات GeoIP خاصة به. لا يضبط VPS خلف Caddy أو Nginx مملوك لك أياً من هذه الرؤوس، لذلك يُخزَّن البلد بالقيمة null. ضع Cloudflare أمام النطاق وفعّل Managed Transform المسمى Add visitor location headers، أو اجعل Reverse Proxy يضبط أحد هذه الرؤوس اعتماداً على بحث GeoIP محلي.

ما الذي ينبغي نسخه احتياطياً تحديداً، وكيف أستعيده؟

انسخ volume linkbreeze-data بالكامل احتياطياً، وليس ملف قاعدة البيانات فقط. يحتوي /app/data/linkbreeze.db على كل صفوف الروابط والصفحة والإعدادات والمشتركين والتحليلات، بينما يحتوي /app/data/uploads على صور avatar وthumbnail التي تشير إليها الصفحة. أوقف الحاوية، وشغّل docker compose cp linkbreeze:/app/data ./backup-$(date +%F)، ثم شغّلها مجدداً. للاستعادة، انسخ الدليل مرة أخرى إلى الحاوية المتوقفة ثم شغّلها. تصدير JSON من لوحة التحكم هو لقطة لإعدادات الملف الشخصي والروابط والإعدادات والسمات وإدخالات الخطوط، ولا يتضمن التحليلات أو الصور.

هل يجلب الاستيراد من Linktree تحليلاتي وسمتي؟

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

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