كيفية استضافة Umami على خادم VPS

‎Umami بديل خفيف لـ ‎Google Analytics: مفتوح المصدر، بدون ملفات تتبع، ودون نقل بيانات إلى جهات خارجية. على ‎VPS، تحتفظ بالتحكم الكامل — لا حساب ‎SaaS، ولا حدود على عدد المواقع، ولا بيانات مشتركة. حزمة ‎Docker بسيطة: حاوية ‎Node.js للتطبيق وحاوية ‎PostgreSQL لقاعدة البيانات. يكتمل الإعداد في أقل من عشر دقائق على ‎VM عادي بصلاحيات الجذر، وتبقى بياناتك على خادمك.

مقارنةً بـ ‎Google Analytics 4، لا تتطلب ‎Umami موافقة على الإحصاءات المجهولة في معظم الدول الأوروبية. ومقارنةً بـ ‎Matomo، فإن بصمتها في الذاكرة أقل بكثير، وإعداد ‎Docker لا يتجاوز ملف docker-compose.yml واحدًا. بالنسبة لوكالة تدير عشرة عملاء، تكفي نسخة ‎Umami واحدة بعشرة مواقع عوضًا عن اشتراك ‎SaaS مدفوع لكل مستخدم أو نطاق. أضاف الإصدار ‎2.14 (يوليو 2026) دعمًا أصليًا للأحداث المخصصة ولوحة تحكم قابلة للتصدير بتنسيق ‎CSV — ميزتان طال انتظارهما من فرق التسويق.

تعمل ‎Umami على أي ‎VPS مثبَّت عليه ‎Docker. الحد الأدنى الموصى به هو ‎1 vCPU و512 ميغابايت ذاكرة وصول عشوائي للاستخدام الشخصي أو للشركات الصغيرة؛ فوق ‎200,000 مشاهدة صفحة شهريًا، يتجنب ‎1 جيجابايت تباطؤ ‎PostgreSQL. ستحتاج إلى: ‎Docker Engine (≥‎ 20.10) وDocker Compose V2 (docker compose، وليس docker-compose)، ونطاق أو نطاق فرعي يشير إلى ‎VPS الخاص بك، وخادم وكيل عكسي (nginx أو Caddy) لتقديم ‎Umami عبر ‎HTTPS. ‎Debian 12 وUbuntu 22 هما التوزيعتان المرجعيتان؛ تفترض الأوامر التالية الوصول بصلاحيات الجذر.

على جانب الخادم، افتح المنفذين ‎80 و‎443 في جدار الحماية (ufw allow 80/tcp && ufw allow 443/tcp). تحتاج ‎Umami فقط إلى ‎HTTPS مكشوفًا للخارج؛ منفذ التطبيق (‎3000 افتراضيًا) يبقى داخليًا ولا يُفتح مباشرةً. إذا كنت تستخدم ‎VPS من ‎ServOrbit، فإن مجموعة الأمان الافتراضية تسمح بالفعل بـ ‎80 و‎443.

‏ثلاثة أسباب رئيسية تُفسّر الغالبية العظمى من حالات الفشل المُبلَّغ عنها في أدلة المجتمع لعام 2026. إليك التشخيص والحل لكل منها.

‏1. حلقة إعادة تشغيل «Can't reach database server» — DATABASE_URL لا يطابق POSTGRES_PASSWORD

‏هذا هو الفخ الأكثر شيوعًا عند النسخ واللصق: تحتوي DATABASE_URL على كلمة المرور بنص صريح ضمن سلسلة الاتصال، ويجب أن تكون هذه الكلمة مطابقة تمامًا لقيمة POSTGRES_PASSWORD في خدمة db. إذا غيّرت إحداهما دون الأخرى، يبدأ Umami، ويفشل في الوصول إلى قاعدة البيانات، ويُعيد التشغيل في حلقة لا نهاية لها — دون رسالة خطأ واضحة في سجلات Docker.

‏تحقّق من تطابق المتغيّرين:

# في .env أو في ملف الـ compose
POSTGRES_PASSWORD=كلمة_مرور_قوية

# في DATABASE_URL، نفس كلمة المرور في الموضع الثالث
DATABASE_URL=postgresql://umami:كلمة_مرور_قوية@db:5432/umami

‏إذا كنت تستخدم متغيّر الاستيفاء (${POSTGRES_PASSWORD})، تأكّد من أن Docker Compose يُحمّل ملف .env فعلًا.

‏2. توقّف Umami بعد 5 إلى 10 ثوانٍ من التشغيل — depends_on بدون healthcheck

‏بشكل افتراضي، لا ينتظر depends_on: db سوى بدء حاوية PostgreSQL، وليس استعدادها لقبول الاتصالات. يحاول Umami الاتصال بينما تزال PostgreSQL تُهيّئ ملفات بياناتها، فيفشل ويتوقّف.

‏أضف healthcheck على خدمة db وشرطًا condition: service_healthy في depends_on الخاص بـ Umami:

services:
  db:
    image: postgres:15-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami"]
      interval: 10s
      timeout: 5s
      retries: 5
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    depends_on:
      db:
        condition: service_healthy

‏بهذا الإعداد، لن يبدأ Umami إلا بعد أن يستجيب PostgreSQL على المنفذ الخاص به.

‏3. خطأ 502 بعد docker compose pull — تغيّر المنفذ المنشور

‏بعد التحديث (docker compose pull ثم docker compose up -d)، قد يُعيد nginx خطأ 502 إذا تغيّرت الإعدادات بين إصدارات الصورة: قد يُعاد تعيين المنفذ الداخلي أو يتغيّر ارتباط المضيف. تحقّق أولًا من الحالة الفعلية للحاويات:

docker compose ps

‏انظر إلى عمود PORTS للتأكد من أن حاوية Umami تنشر على المنفذ المتوقع (3000 افتراضيًا). إذا تغيّر المنفذ، حدّث توجيه proxy_pass (أو reverse_proxy) في nginx أو Caddy ليعكس المنفذ الجديد، ثم أعد تحميل الخدمة (nginx -s reload أو systemctl reload caddy).

4. ‎docker-compose (v1) مقابل docker compose (v2) — صمت بدون رسالة خطأ

كثير من الأدلة المنشورة قبل ‎2025 تستخدم docker-compose (بشرطة)، وهو عميل ‎Python القديم غير المُصان. على تثبيت جديد لـ ‎Docker Engine، هذا الأمر غير موجود: يرجع الطرفية command not found ببساطة دون أن تشير إلى أن الإصدار ‎v2 يُسمّى docker compose (بمسافة). تحقق بـ docker compose version — إذا استجابت، فأنت تستخدم ‎v2. جميع الأمثلة في هذا الدليل تستخدم docker compose (v2).