يشرح هذا الدليل نشر PmaControl لمراقبة خوادم MariaDB / MySQL، ثم التحقق من عمل الواجهة وقاعدة البيانات المحلية وجمع البيانات.

طريقة التثبيت الحالية هي حزمة pmacontrol التي يوزعها مستودع APT الموقّع للمشروع. تثبّت MariaDB وإضافة RocksDB وPHP CLI وFrankenPHP واعتماديات التطبيق، وتهيّئ أيضاً قاعدة البيانات والحسابات والمهام المجدولة وإعدادات الويب. استخدام جهاز مخصص أو آلة افتراضية يجنب التعارض مع الخدمات الموجودة.

التثبيت بأمر واحد

على جهاز مخصص بمعمارية amd64 يعمل بنظام Debian 12/13 أو Ubuntu 24.04/26.04، نفّذ هذا الأمر في الطرفية. يتحقق السكربت من النظام ومفتاح المستودع الموقّع، ثم يثبّت حزمة PmaControl واعتمادياتها. يطلب صلاحيات المسؤول عبر sudo.

curl -fsSL https://pmacontrol.com/install.sh | sudo bash

إذا كنت تعمل بالفعل بصلاحيات root، فاستبدل sudo bash بـ bash. عرض السكربت. بعد التثبيت، تابع خطوات التحقق وإعداد HTTPS وتسجيل الدخول الأول الموضحة أدناه.

1. اختيار نظام التشغيل

النظام	فرع APT	المعمارية	الطريقة
Debian 12	`bookworm`	`amd64`	حزمة APT
Debian 13	`trixie`	`amd64`	حزمة APT
Ubuntu 24.04 LTS	`noble`	`amd64`	حزمة APT
Ubuntu 26.04 LTS	`resolute`	`amd64`	حزمة APT
Docker	—	—	انظر قسم Docker

في 26 سبتمبر 2026، توفر الفروع الأربعة الحزمة 5.4.36-1. يبقى الأمر apt-cache policy pmacontrol المرجع لمعرفة الإصدار المتاح عند التثبيت. قد يكون فرع التطوير أحدث من الحزمة المنشورة. لا تشمل هذه الإجراءات حزم ARM64 أو إصدارات Ubuntu القديمة.

2. تجهيز الجهاز والشبكة

جهّز صلاحيات المسؤول وDNS يعمل بصورة صحيحة وساعة متزامنة وتخزيناً دائماً. لبنية صغيرة، تشكل 2 إلى 4 وحدات vCPU و4 إلى 8 GiB من الذاكرة و40 GiB من تخزين SSD نقطة بداية تقديرية وليست حداً أدنى مضموناً. يعتمد حجم البيانات على عدد الخوادم والمقاييس وفترة الاحتفاظ والنسخ الاحتياطية. خصّص تخزيناً منفصلاً للنسخ الاحتياطية عند تفعيل هذه الميزة.

اسمح باتصالات TCP الواردة على 443 للمستخدمين المخولين، وعلى 80 لإعادة التوجيه ولـ ACME عند الحاجة. يستخدم HTTP/3 منفذ UDP 443، وهو اختياري للعملاء. وفّر HTTPS الصادر إلى المستودعات، وDNS/NTP إلى خدماتك، واتصالات SQL إلى الخوادم المراقبة على منافذها الفعلية، وSSH 22 فقط للميزات التي تستخدمه. لا تحتاج قاعدة البيانات المحلية إلى إتاحتها على الإنترنت.

نفّذ هذه الفحوص قبل التثبيت. إذا لم يكن /var/lib/mysql موجوداً بعد، افحص المساحة المتاحة في نظام الملفات الذي سيحتويه. يجب أن تكون منافذ الويب متاحة: ترفض الحزمة أي عملية أخرى تستمع عليها، ولا تعطل Apache أو Nginx أو Caddy تلقائياً.

cat /etc/os-release
dpkg --print-architecture
df -h / /var/lib/mysql
free -h
timedatectl status
ss -ltnp '( sport = :80 or sport = :443 )'
ss -lunp 'sport = :443'

3. التثبيت على Debian 12 أو Debian 13

استخدم الأوامر التالية على جهاز Debian مخصص. تختار تلقائياً bookworm أو trixie، وتتحقق من amd64، وتضيف مفتاحاً خاصاً بهذا المستودع عبر signed-by، وتعرض الإصدار المرشح، وتحاكي التثبيت قبل تنفيذه. راجع الحزم المضافة وأي تغييرات أثناء المحاكاة. تُنفذ الأوامر اللاحقة في صدفة root التي يفتحها sudo -i.

بصمة المفتاح التي تم التحقق منها في 26 سبتمبر 2026 هي CAFD ABF8 7717 CC60 291E 68E4 D56A 0ADA AB5F 97E2. إذا تغيرت، تأكد من تبديل المفتاح لدى المشروع قبل المتابعة. لا تستخدم trusted=yes لتجاوز خطأ في التوقيع.

sudo -i
set -eu
. /etc/os-release
case "$ID:$VERSION_CODENAME" in
  debian:bookworm|debian:trixie|ubuntu:noble|ubuntu:resolute) ;;
  *) echo "Unsupported distribution: $ID:$VERSION_CODENAME" >&2; exit 1 ;;
esac
test "$(dpkg --print-architecture)" = amd64
apt-get update
apt-get install -y ca-certificates curl gnupg
install -d -m 0755 /etc/apt/keyrings
curl -fsSL --retry 3   https://repo.pmacontrol.com/debian/pmacontrol-archive-keyring.gpg   -o /etc/apt/keyrings/pmacontrol-archive-keyring.gpg
chmod 0644 /etc/apt/keyrings/pmacontrol-archive-keyring.gpg
gpg --show-keys --with-fingerprint   /etc/apt/keyrings/pmacontrol-archive-keyring.gpg
printf 'deb [arch=amd64 signed-by=/etc/apt/keyrings/pmacontrol-archive-keyring.gpg] https://repo.pmacontrol.com/debian %s main\n'   "$VERSION_CODENAME" > /etc/apt/sources.list.d/pmacontrol.list
apt-get update
apt-cache policy pmacontrol
apt-get -s install pmacontrol
apt-get install pmacontrol

4. التثبيت على Ubuntu 24.04 أو Ubuntu 26.04

على Ubuntu، نفّذ كتلة أوامر APT نفسها من القسم السابق: تختار noble للإصدار 24.04 وresolute للإصدار 26.04. احتفظ بمستودعات Ubuntu الرسمية المعدّة مسبقاً وبفرعها الصحيح. يوفر مستودع PmaControl الحزمة والاعتماديات المطلوبة؛ لا تستبدل noble بـ trixie على جهاز Ubuntu.

بعد apt-get install pmacontrol، لا تعاود تشغيل install.sh، ولا تنشئ قاعدة البيانات يدوياً، ولا تضف منظومة ثانية من Apache/PHP-FPM. ينفذ سكربت ما بعد تثبيت الحزمة التهيئة بالفعل. PHP في سطر الأوامر وPHP المضمّن في FrankenPHP بيئتا تشغيل مختلفتان: لا يكفي php -v وحده للتحقق من بيئة الويب.

5. التحقق من التثبيت والحصول على بيانات الدخول

يجب أن تكون حالة الحزمة install ok installed، وألا يبلغ dpkg --audit عن إعداد غير مكتمل، وأن تكون MariaDB وFrankenPHP وcron نشطة. يجب أن يحتوي مؤشر بيئة التشغيل على frankenphp. تحقق أيضاً من تحميل RocksDB. ينبغي أن يُعاد توجيه HTTP إلى HTTPS، وأن يستجيب مسار تسجيل الدخول عبر HTTPS دون خطأ من الخادم.

يُستخدم الخيار -k في هذا الفحص المحلي لاختبار الشهادة الداخلية الأولية فقط. للوصول الاعتيادي للمستخدمين، اضبط الشهادة وفق القسم التالي وتحقق من الاتصال دون -k.

dpkg-query -W -f='${Status} ${Version}\n' pmacontrol
dpkg --audit
systemctl is-active mariadb frankenphp cron
systemctl is-enabled mariadb frankenphp cron
cat /etc/pmacontrol/active-runtime
mariadb -N -e "SELECT VERSION(); SELECT 1;"
mariadb -e "SHOW PLUGINS;" | awk 'NR == 1 || /ROCKSDB/'
curl -q --noproxy '*' -I http://127.0.0.1/
curl -q --noproxy '*' -k -I https://localhost/fr/user/connection/

تُحفظ بيانات الدخول المولدة في /root/pmacontrol-install.env، الذي يستطيع root وحده الوصول إليه، وعادة بصلاحيات 0600. اعرضه في طرفية خاصة: يقدّم PMACTRL_ADMIN_LOGIN وPMACTRL_ADMIN_PASSWORD دخول المسؤول، بينما تخص متغيرات webservice واجهة API. لا ترسل هذا الملف في تذكرة دعم أو مستودع أو لقطة شاشة.

افتح https://YOUR-HOST/fr/user/connection/، وسجّل الدخول، ثم عيّن كلمة مرور شخصية من ملفك الشخصي. احتفظ بملف الاسترداد في نسخة احتياطية مشفرة، وحدّثه عند تبديل بيانات الدخول التي يسجلها. بعد نجاح التهيئة، يجب أن يختفي الملف المؤقت /root/pmacontrol-install.json. قد يدل بقاؤه على تهيئة غير مكتملة: ابحث عن الخطأ قبل حذفه.

sudo stat -c '%a %U %G %n' /root/pmacontrol-install.env
sudo less /root/pmacontrol-install.env
sudo test ! -e /root/pmacontrol-install.json

6. إعداد اسم DNS فعلي وHTTPS

يستخدم FrankenPHP افتراضياً شهادة داخلية لـ localhost. لذلك قد يظهر تحذير ثقة أو عدم تطابق اسم عند الاتصال عبر عنوان IP أو اسم غير معدّ. لاستخدام اسم عام، أنشئ سجل DNS يشير إلى المثيل، واستبدل كل ظهور لـ pmacontrol.example.com أدناه باسمك.

تستورد الكتلة مقطع الإعداد المقدم من PmaControl. يستطيع Caddy الحصول تلقائياً على شهادة عامة إذا كان الاسم وتحديات ACME قابلين للوصول. في شبكة خاصة، استخدم جهة إصدار تثق بها أجهزتك أو ملفاتك الخاصة عبر tls /path/fullchain.pem /path/private.key. اسمح للخدمة بقراءة المفتاح دون جعله متاحاً للعامة. تبقى الملفات في /etc/pmacontrol/frankenphp.d/ محفوظة عند التحديث؛ أما ملفات Caddy المولدة من الحزمة فقد تُعاد توليدها.

sudo install -d -m 0755 /etc/pmacontrol/frankenphp.d
sudo tee /etc/pmacontrol/frankenphp.d/pmacontrol.example.com.caddyfile >/dev/null <<'CADDY'
pmacontrol.example.com {
    import pmacontrol_app
}
CADDY
(
  set -eu
  validation_dir="$(mktemp -d /tmp/pmacontrol-validation.XXXXXX)"
  trap 'sudo rm -rf -- "$validation_dir"' EXIT
  sudo env HOME="$validation_dir" frankenphp validate     --adapter caddyfile --config /etc/frankenphp/Caddyfile
)
sudo systemctl reload frankenphp
curl -I https://pmacontrol.example.com/fr/user/connection/

7. استخدام وكيل عكسي

فضّل HTTPS مع التحقق من الشهادة بين الوكيل وFrankenPHP. احتفظ بترويسة Host العامة الأصلية، واستبدل X-Forwarded-Proto الواردة بقيمة يحددها الوكيل بنفسه.

إذا كانت البنية تتطلب HTTP نحو الخادم الخلفي، أضف إلى /etc/pmacontrol/trusted-proxies عنوان IP للوكيل المتصل مباشرة فقط. استبدل 192.0.2.10 في المثال، ولا تسمح للإنترنت كله. لا تقدم الحزمة التطبيق عبر HTTP إلا لطرف مسموح له وبقيمة مطابقة تماماً لـ X-Forwarded-Proto: https. تُعاد توجيه الطلبات الأخرى. أعد إعداد الحزمة لتطبيق هذه السياسة.

sudo tee /etc/pmacontrol/trusted-proxies >/dev/null <<'PROXY'
192.0.2.10
PROXY
sudo chown root:root /etc/pmacontrol/trusted-proxies
sudo chmod 0644 /etc/pmacontrol/trusted-proxies
sudo apt-get install --reinstall pmacontrol

8. إضافة أول خوادم MariaDB / MySQL

أضف من الواجهة عنوان الخادم المراد مراقبته ومنفذه وبيانات SQL، ثم اختبر الاتصال. قاعدة MariaDB المحلية الخاصة بـ PmaControl منفصلة عن الخوادم المراقبة: لا تحتاج إلى نقل قواعد بيانات تطبيقاتك.

أنشئ حساب مراقبة مخصصاً ومقيداً بعنوان PmaControl، وامنحه الصلاحيات اللازمة للميزات المختارة. تختلف صلاحيات قراءة المقاييس والنسخ المتماثل والتحليل والنسخ الاحتياطي والإدارة بين MariaDB وMySQL وإصداراتهما؛ لا تستبدلها بحساب root بعيد ذي صلاحيات شاملة. فعّل Performance Schema على الخوادم إذا تطلبته الصفحات المختارة. SSH اختياري، ويخص ميزات جمع معلومات النظام والسجلات والنسخ الاحتياطي التي تحتاجه.

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

PmaControl بالصور

عشرة عروض للتعرف على المراقبة والطوبولوجيا وأدوات PmaControl. انقر على لقطة الشاشة لفتحها بحجمها الأصلي. التُقطت الصور في 26 سبتمبر 2026.

1. قائمة الخوادم

جرد الخوادم وتوافرها وإصداراتها ووقت آخر جمع للبيانات.

2. بنية Galera + ProxySQL

عرض عناوين VIP ومجموعات ProxySQL وأعضاء عناقيد Galera.

3. التنبيهات والحوادث

الحوادث المفتوحة والمحلولة ومستويات الخطورة والتصفية حسب الخادم.

4. حالة عقد Galera

أعضاء العناقيد وحالة المزامنة والقطاعات والإصدارات.

5. مجموعات المضيفين والتوجيه في ProxySQL

مجموعات writer وreader والخوادم الخلفية وحالة الاتصالات.

6. ذاكرة قواعد البيانات

مقارنة المخازن المؤقتة وإعدادات الذاكرة لكل خادم.

7. سعة PmaControl

رسوم بيانية للاتصالات والذاكرة وتنبيهات السعة.

8. النسخ المتماثل في MariaDB

المصادر وسلاسل النسخ المتماثل والإصدارات واتصالات SSL.

9. النسخ الاحتياطي والجدولة

سجل التنفيذ ومساحة التخزين وجدولة النسخ الاحتياطية.

10. استخدام الفهارس

عدادات القراءة ونسبة القراءات التي تخدمها الفهارس.

9. الملفات والبيانات والنسخ الاحتياطية

تنطبق المسارات أدناه على النشر بالحزمة. انسخ قاعدة البيانات المحلية و/etc/pmacontrol/ وبيانات التطبيق والشهادات وبيانات الاسترداد. مفتاح تشفير التطبيق جزء من الإعدادات: نسخة SQL وحدها لا تكفي لاستعادة بيانات الدخول المشفرة.

استخدم نسخة MariaDB تضمن الاتساق مع محركات التخزين الموجودة. تصدير --single-transaction وحده لا يضمن اتساق جميع الجداول عند استخدام عدة محركات. لنسخ الملفات أو أخذ لقطة، أوقف جمع البيانات وMariaDB ضمن نافذة مخططة، أو استخدم آلية نسخ احتياطي مجربة لمحركك وإصدارك. اختبر الاستعادة على مثيل معزول قبل الاعتماد على النسخة.

/usr/share/pmacontrol/                 application
/usr/bin/pmacontrol                    CLI
/etc/pmacontrol/                       configuration
/etc/pmacontrol/frankenphp.d/           operator TLS policy
/etc/pmacontrol/trusted-proxies         immediate trusted proxy peers
/var/lib/pmacontrol/                   persistent application data
/var/lib/mysql/                        local MariaDB data
/var/cache/pmacontrol/tmp/              application cache and logs
/etc/frankenphp/php.d/pmacontrol.ini    packaged PHP settings
/root/pmacontrol-install.env            bootstrap recovery credentials

10. تحديث PmaControl

قبل التحديث، حضّر نسخة قابلة للاستعادة من البيانات والإعدادات، واقرأ ملاحظات الإصدار المرشح. يطبق سكربت ما بعد التثبيت عمليات الترحيل ويعيد الخدمات الخلفية إلى حالتها المقصودة؛ يجب أن تبقى المهام الموقوفة عمداً متوقفة. الإجراء المعتاد هو تحديث الحزمة، وليس تشغيل git pull داخل /usr/share/pmacontrol.

بعد التحديث، أعد فحوص القسم 5، واختبر تسجيل دخول مستخدم وحداثة البيانات المجمعة. قد يتطلب التراجع بسبب خلل استعادة منسقة للكود وقاعدة البيانات: إعادة تثبيت حزمة قديمة لا تعيد مخطط قاعدة البيانات إلى حالته السابقة.

sudo apt-get update
apt-cache policy pmacontrol
sudo apt-get -s install --only-upgrade pmacontrol
sudo apt-get install --only-upgrade pmacontrol
sudo dpkg --audit
systemctl is-active mariadb frankenphp cron

11. Docker: الحالة الحالية وخيارات النشر

الحالة التي تم التحقق منها في 26 سبتمبر 2026: لا يقدم المستودع الحالي Dockerfile أو Compose أو مرجع صورة PmaControl لتثبيت كامل مدعوم. تخص ملفات Docker الموجودة أدوات أو قواعد اختبار. سيكون اقتراح docker pull pmacontrol/pmacontrol دون صورة منشورة ومتحقق منها مضللاً.

تستخدم حزمة APT نظام systemd وMariaDB محلية وcron وصلاحيات الملفات وفحوص منافذ الاستماع عند بدء التشغيل. وضعها في صورة PHP عامة لا يعيد إنتاج هذا التثبيت. يجب أن تتولى نسخة Docker التهيئة وإعادة المحاولة والمجلدات الدائمة والأسرار وعمليات الترحيل والخدمات الخلفية وفحوص الصحة واستعادة تم اختبارها.

يمكن الآن تثبيت PmaControl في آلة افتراضية Debian أو Ubuntu وفق هذا الدليل، ومراقبة خوادم MariaDB / MySQL التي تعمل في Docker، بشرط إمكانية الوصول إلى عناوين SQL الخاصة بها. يشير localhost داخل الحاوية إلى الحاوية نفسها، لا إلى آلة PmaControl الافتراضية. ستُضاف إجراءات تثبيت PmaControl نفسه في Docker مع صورة واختبارات قابلة لإعادة التنفيذ؛ ولا ينبغي الخلط بينها وبين مراقبة قواعد البيانات داخل الحاويات.

12. تشخيص تثبيت غير مكتمل

ابدأ بالسجلات وحالة الحزم. عند خطأ APT، افحص الفرع والمعمارية والوقت والمفتاح والشبكة. عند تعارض المنافذ، حدد الخدمة واختر مكان استضافة PmaControl؛ ينبغي ألا توقف الحزمة موقعاً آخر. عند خطأ TLS، افحص DNS والتحديات والشهادة والصلاحيات. إذا عمل الويب لكن بقيت الرسوم قديمة، افحص SQL/SSH والخدمات الخلفية وأخطاء الجمع.

sudo journalctl -u frankenphp -u mariadb -u cron --since '-30 min' --no-pager
sudo tail -n 100 /var/cache/pmacontrol/tmp/log/error_php.log
sudo tail -n 100 /var/log/apt/term.log
sudo dpkg --audit
sudo ss -ltnp '( sport = :80 or sport = :443 )'
sudo ss -lunp 'sport = :443'

بعد تصحيح السبب المبلغ عنه، أعد الإعداد بالأوامر التالية. قد يتطلب فشل تدوير الخدمات الخلفية أيضاً sudo runuser -u www-data -- pmacontrol Daemon startAll، لكن فقط لاستئناف الحالة المحفوظة لهذه العملية والتحقق من نتيجة JSON واحدة تتضمن ok: true. لا تحذف مفتاح التشفير أو ملف الدخول لفرض تهيئة جديدة.

sudo dpkg --configure -a
sudo apt-get -f install

13. إزالة الحزمة

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

sudo apt-get -s remove pmacontrol
sudo apt-get remove pmacontrol

14. قائمة التحقق عند بدء الخدمة

تم إعداد الحزمة والخدمات اللازمة نشطة.
يتطابق DNS مع الشهادة ويعمل الوصول المعتاد دون -k.
بيانات المسؤول وwebservice محفوظة بأمان.
ينجح خادم MariaDB / MySQL في اختبار الاتصال.
ينتج جمع البيانات عينات حديثة ورسومًا متسقة.
تناسب الصلاحيات والاحتفاظ والتخزين الميزات المفعلة.
يمكن استعادة نسخة احتياطية كاملة على مثيل معزول.

المصادر ونطاق التحقق. يستند الدليل إلى سكربتات التثبيت ووثائق المستودع الرسمي وفهارس APT والحزمة 5.4.36-1 التي تمت مراجعتها في 26 سبتمبر 2026. تم التحقق من توقيع الفهرس. هذا التحقق الوثائقي ليس اختبار تثبيت جديداً على كل توزيع من التوزيعات الأربعة.

تثبيت PmaControl على Debian وUbuntu: دليل كامل وحالة Docker