الحفاظ على الفرع التجاري PmaControl: الترقية والتراجع وأفضل الممارسات

PmaControl هو نشر Git

لا يتم توزيع PmaControl كحزمة .deb أو .rpm. إنه نشر يستند إلى Git: يمكنك استنساخ المستودع، وتثبيت تبعيات Composer، وتشغيل البرنامج النصي للتثبيت، وهو قيد الإنتاج.

git clone -b commercial https://github.com/pmacontrol/pmacontrol.git /srv/www/pmacontrol
cd /srv/www/pmacontrol
composer install --no-dev
./install.sh

يتمتع هذا النموذج بمزايا (تحديث سريع، واستعادة سهلة، وعدم وجود مدير للحزم) وعيوب (لا توجد إدارة تلقائية لتبعيات النظام، ولا توجد برامج نصية موحدة بعد التثبيت). يغطي هذا الدليل الصيانة اليومية.

تتبع الإصدار

يخزن PmaControl نسخته في ملف تكوين الموقع:

// configuration/site.config.php
define('SITE_VERSION', '3.2.1');
define('SITE_LAST_UPDATE', '2026-04-01 14:30:00');

يتم تحديث هذه الثوابت تلقائيًا أثناء التثبيت (install.sh). يمكنك استشارتهم:

• عبر واجهة الويب: صفحة أو تذييل "حول".
• عبر واجهة سطر الأوامر: grep SITE_VERSION configuration/site.config.php
• عبر API: GET /api/v1/status يقوم بإرجاع الإصدار

قبل أي تحديث، لاحظ الإصدار الحالي:

cd /srv/www/pmacontrol
grep -E 'SITE_VERSION|SITE_LAST_UPDATE' configuration/site.config.php

قائمة التحقق قبل الترقية

قبل بدء التحديث، قم بتشغيل قائمة التحقق الكاملة هذه:

1. قم بعمل نسخة احتياطية لقاعدة البيانات

mysqldump --single-transaction --routines --triggers \
  -u pmacontrol -p pmacontrol > /backup/pmacontrol_$(date +%Y%m%d_%H%M%S).sql

تعتبر العلامة --single-transaction ضرورية: فهي تضمن إجراء نسخة احتياطية متسقة دون قفل الجداول (InnoDB/RocksDB).

التحقق من حجم التفريغ:

ls -lh /backup/pmacontrol_*.sql

يشير التفريغ الفارغ أو الصغير بشكل غير طبيعي إلى وجود مشكلة.

2. حفظ التكوين

cp -r /srv/www/pmacontrol/configuration/ /backup/pmacontrol_config_$(date +%Y%m%d)/

ملفات التكوين هي الأكثر أهمية: db.config.ini.php (بيانات الاعتماد)، telegram.php، acl.config.ini، site.config.php. لا ينبغي أن تؤدي الترقية إلى تعديلها، ولكن حدث خطأ بشري بسرعة.

3. لاحظ الإصدار الحالي والتزم به

cd /srv/www/pmacontrol
git log --oneline -1
# fe0911d (HEAD -> commercial) Fix: replication display for MySQL 8.4

grep SITE_VERSION configuration/site.config.php
# define('SITE_VERSION', '3.2.1');

احتفظ بتجزئة الالتزام (هنا fe0911d) - هذه هي نقطة التراجع.

4. تحقق من حالة Git

git status

إذا كانت هناك تغييرات محلية غير ملتزم بها، قرر الآن: الالتزام بها، أو تخزينها، أو إحباطها. يمكن أن يؤدي git pull مع التعديلات المحلية إلى حدوث تعارضات.

# Si des modifications doivent être conservées
git stash save "pre-upgrade $(date +%Y%m%d)"

# Si elles doivent être abandonnées
git checkout -- .

5. تحقق من مساحة القرص

df -h /srv/www/pmacontrol/
df -h /var/lib/mysql/

قد تتطلب الترقية والترحيل مساحة مؤقتة. تأكد من أن لديك مساحة خالية تبلغ 20% على الأقل على كلا القسمين.

إجراء الترقية

الخطوة 1: استرجاع التغييرات

cd /srv/www/pmacontrol
git fetch origin commercial

قبل الدمج، راجع ما تغير:

git log --oneline HEAD..origin/commercial

يسرد هذا جميع الالتزامات بين الإصدار الخاص بك والأحدث. اقرأ رسائل الالتزام لتحديد:

• تغييرات مخطط قاعدة البيانات
• تغييرات التكوين
• تمت إضافة أو تعديل تبعيات الملحن
• كسر التغييرات المبلغ عنها

الخطوة الثانية: تطبيق التحديث

git pull origin commercial

إذا ظهرت تعارضات، فهي موجودة دائمًا تقريبًا في ملفات التكوين. لا تحل أبدًا أي صراع من خلال القبول الأعمى لـ "صراعهم" - تحقق يدويًا.

الخطوة 3: تحديث التبعيات

composer install --no-dev

يستخدم composer install (بدون update) composer.lock من المستودع، والذي يضمن نفس الإصدارات التي يستخدمها فريق التطوير. لا تستخدم أبدًا composer update في الإنتاج، فقد يؤدي ذلك إلى سحب الإصدارات غير المختبرة.

تأكد من أن التثبيت سار بشكل جيد:

# Vérifier qu'il n'y a pas d'erreur
echo $?
# Doit retourner 0

# Vérifier le dossier vendor
ls -la vendor/autoload.php

الخطوة 4: التحقق من تغييرات التكوين

قارن نماذج الملفات بالتكوين الحالي لديك:

diff -r config_sample/ configuration/ --brief

إذا ظهرت ملفات جديدة في config_sample/ وهي غير موجودة في configuration/، فهذه تكوينات جديدة يجب دمجها:

# Lister les fichiers nouveaux dans config_sample
for f in config_sample/*; do
    base=$(basename "$f")
    if [ ! -f "configuration/$base" ]; then
        echo "NEW: $base — needs to be copied and configured"
    fi
done

لكل ملف جديد:

cp config_sample/new_config.php configuration/new_config.php
# Éditer et adapter les valeurs à votre environnement

الخطوة 5: تشغيل عمليات الترحيل

./install.sh

يعالج البرنامج النصي install.sh عمليات ترحيل مخطط قاعدة البيانات. هو:

1. يكتشف إصدار المخطط الحالي
2. قم بتطبيق عمليات الترحيل المفقودة بالترتيب
3. التحديثات SITE_VERSION وSITE_LAST_UPDATE

المراجعة اليدوية الموصى بها: قبل تشغيل install.sh، قم بمراجعة عمليات الترحيل:

# Lister les fichiers de migration
ls -la data/migrations/ 2>/dev/null || ls -la install/migrations/ 2>/dev/null

إذا كانت عملية الترحيل تحتوي على ALTER TABLE على جداول كبيرة (مثل ts_value_general_int)، فخطط لوقت صيانة أطول.

قائمة مراجعة ما بعد الترقية

1. أعد تشغيل الخدمات

./glial control service

يقوم هذا الأمر بإعادة تشغيل دورة التجميع والمعالجة. تأكد من أنه لا يرجع خطأ.

2. التحقق من crons

crontab -l -u www-data

تحقق من وجود الكرونز الثلاثة الأساسية:

crontab
* * * * * cd /srv/www/pmacontrol && ./glial agent check_daemon >> /tmp/pmacontrol_agent.log 2>&1
* * * * * cd /srv/www/pmacontrol && ./monitor_mysql.sh >> /tmp/pmacontrol_monitor.log 2>&1
0 */4 * * * cd /srv/www/pmacontrol && ./glial control service >> /tmp/pmacontrol_control.log 2>&1

3. تحقق من سجلات الأخطاء

# Logs PHP
tail -20 /var/log/apache2/error.log

# Logs PmaControl
tail -20 /tmp/pmacontrol_agent.log
tail -20 /tmp/pmacontrol_monitor.log
tail -20 /tmp/pmacontrol_control.log

تحقق من وجود أخطاء فادحة، وتحذيرات الفئة المفقودة، وأخطاء قاعدة البيانات. يجب ألا تؤدي الترقية الناجحة إلى أي أخطاء جديدة.

4. تحقق من الوصول إلى الويب

افتح PmaControl في المتصفح وتحقق من:

• صفحة تسجيل الدخول تعمل
• يتم تحميل لوحة القيادة الرئيسية
• يتم عرض قائمة الخوادم
• يمكن الوصول إلى خادم فردي
• الصفحة التابعة تعمل (إن وجدت)
• الأحمال طوبولوجيا Dot3

5. التحقق من المقاييس

انتظر 5 دقائق (دورة تجميع كاملة) ثم تحقق مما يلي:

# Les agents collectent-ils ?
./glial agent check_daemon

# Les données arrivent-elles ?
mysql -u pmacontrol -p pmacontrol -e "
SELECT server_id, MAX(timestamp) as last_data
FROM ts_value_general_int
GROUP BY server_id
HAVING last_data < NOW() - INTERVAL 5 MINUTE;
"

إذا أدى هذا الاستعلام إلى ظهور نتائج، فهذا يعني أن بعض الخوادم لم تعد تتلقى البيانات - تحقق من ذلك.

6. تحقق من Dot3 والطوبولوجيا

./glial dot3 generate

تأكد من إعادة إنشاء الهيكل بدون أخطاء ومن اتساق الرسم البياني في واجهة الويب.

إجراء الاستعادة

إذا حدث خطأ ما، فإليك كيفية عكسه.

التراجع عن الكود

cd /srv/www/pmacontrol
git checkout <previous-commit-hash>
composer install --no-dev

على سبيل المثال، إذا كان التزام ما قبل الترقية هو fe0911d:

git checkout fe0911d
composer install --no-dev

التراجع عن قاعدة البيانات (إذا تغير المخطط)

إذا قام install.sh بتعديل المخطط، فيجب استعادة النسخة الاحتياطية:

mysql -u root -p pmacontrol < /backup/pmacontrol_20260413_143000.sql

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

التراجع عن التكوين

cp /backup/pmacontrol_config_20260413/* /srv/www/pmacontrol/configuration/

بعد التراجع

./glial control service
# Vérifier les logs
tail -20 /tmp/pmacontrol_agent.log
# Vérifier l'accès web
curl -s -o /dev/null -w "%{http_code}" https://pmacontrol.example.com/
# Devrait retourner 200

إدارة تبعية الملحن

فهم ملف القفل

تم إصدار الملف composer.lock في المستودع. إنه يضمن أن الجميع يستخدم نفس إصدارات التبعية تمامًا. عندما يتغير composer.lock في السترة:

# Voir les changements de dépendances
git diff HEAD~1 composer.lock | grep '"name"'

التحقق من التغييرات العاجلة

إذا تغيرت تبعية رئيسية (على سبيل المثال، إطار العمل الدبقي من 2.x إلى 3.x)، فهذا تغيير محفوف بالمخاطر. تحقق من سجل التغيير للتبعية:

# Lister les dépendances mises à jour
composer show --latest --outdated

لا تقم أبدًا بإنشاء تحديث في الإنتاج

# NON — tire les dernières versions possibles
composer update

# OUI — installe exactement les versions du lock file
composer install --no-dev

عمليات ترحيل قاعدة البيانات

طريقة عملهم

install.sh ينفذ عمليات الترحيل بشكل تسلسلي. تكون كل عملية ترحيل غير فعالة — فهي تتحقق أولاً مما إذا كان التغيير قد تم تطبيقه بالفعل:

-- Exemple de migration typique
-- Vérifie si la colonne existe avant de l'ajouter
SET @exist := (SELECT COUNT(*) FROM information_schema.COLUMNS
               WHERE TABLE_SCHEMA = 'pmacontrol'
               AND TABLE_NAME = 'mysql_server'
               AND COLUMN_NAME = 'new_column');

SET @sql = IF(@exist = 0,
    'ALTER TABLE mysql_server ADD COLUMN new_column VARCHAR(255) DEFAULT NULL',
    'SELECT "Column already exists"');
PREPARE stmt FROM @sql;
EXECUTE stmt;

هجرات محفوفة بالمخاطر

بعض الهجرات أكثر خطورة من غيرها:

بالنسبة للجداول الكبيرة (مثل ts_value_general_int والتي يمكن أن تصل مساحتها إلى عدة غيغابايت)، يمكن أن يستغرق ADD INDEX دقائق أو حتى ساعات. خطط وفقًا لذلك.

يوصى بالمراجعة اليدوية

قبل تشغيل install.sh، اقرأ ملفات الترحيل لفهم ما سيتم تغييره. إذا كانت عملية الترحيل تبدو محفوفة بالمخاطر بالنسبة لك (ALTER TABLE على جدول مساحته عدة جيجابايت)، فاختبرها أولاً في بيئة مرحلية.

أفضل الممارسات

1. بيئة التدريج

حافظ على بيئة مرحلية تحاكي إنتاجك. يتم اختبار الترقية هناك قبل تطبيقها في الإنتاج:

1. Staging: git pull → composer install → install.sh → vérification
2. Attendre 24h — observer les logs
3. Production: même procédure

لا يحتاج التدريج إلى مراقبة عدد كبير من الخوادم مثل الإنتاج. 5-10 خوادم MariaDB / MySQL كافية للتحقق من صحة التشغيل.

2. نافذة الصيانة المجدولة

لا تقم أبدًا بالترقية يوم الجمعة الساعة 5 مساءً. الخطة:

• الثلاثاء أو الأربعاء: منتصف الأسبوع، الفريق متواجد
• الصباح: أن يكون لديك يوم كامل لاكتشاف المشاكل
• خارج أوقات الذروة: ليس أثناء نشر التطبيق أو دفعة ليلية

3. التواصل

قم بإخطار الفريق قبل الترقية:

Objet : Maintenance PmaControl — Mar 13 avril 09:00-10:00

L'instance PmaControl sera mise à jour de la version 3.2.1 à 3.3.0.
Pendant la maintenance (environ 30 minutes) :
- Les dashboards peuvent être temporairement indisponibles
- La collecte de métriques sera interrompue (rattrapage automatique)
- Les alertes Telegram seront suspendues puis reprises

Contact : dba@company.com

4. تحقق من مقاييس Dot3+ بعد الترقية

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

5. احتفظ بسجل للترقيات

احتفظ بملف بسيط يسرد الترقيات التي تم إجراؤها:

2026-04-13 09:15 | 3.2.1 → 3.3.0 | fe0911d → a1b2c3d | OK
2026-03-15 10:00 | 3.1.0 → 3.2.1 | 1234abc → fe0911d | OK — migration ts_value lente (45min)
2026-02-01 08:30 | 3.0.5 → 3.1.0 | 9876def → 1234abc | ROLLBACK — bug #342 dans Listener

6. قم بالتشغيل التلقائي عندما ينضج

بمجرد الانتهاء من 5 إلى 10 ترقيات يدوية دون وقوع أي حادث، يمكنك التشغيل تلقائيًا باستخدام برنامج نصي:

#!/bin/bash
# upgrade_pmacontrol.sh
set -euo pipefail

BACKUP_DIR="/backup/pmacontrol/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

# Backup
mysqldump --single-transaction -u pmacontrol -p"$DB_PASS" pmacontrol > "$BACKUP_DIR/db.sql"
cp -r /srv/www/pmacontrol/configuration/ "$BACKUP_DIR/config/"
git -C /srv/www/pmacontrol log --oneline -1 > "$BACKUP_DIR/version.txt"

# Upgrade
cd /srv/www/pmacontrol
git pull origin commercial
composer install --no-dev
./install.sh

# Verify
./glial control service
curl -s -o /dev/null -w "%{http_code}" https://pmacontrol.example.com/ | grep -q 200

echo "Upgrade successful"

لكن احتفظ دائمًا بإمكانية التراجع اليدوي.

أخطاء شائعة

"لم يتم العثور على الفئة" بعد الترقية

العرَض: خطأ PHP Class 'Xyz' not found في السجلات.

السبب: لم يتم تنفيذ composer install بعد السحب، أو لم يتم إعادة إنشاء أداة التحميل التلقائي.

حل :

composer install --no-dev
composer dump-autoload

خطأ في الترحيل "الجدول موجود بالفعل"

العرَض: فشل install.sh مع Table 'xyz' already exists.

السبب: الترحيل ليس فعالاً (خطأ في البرنامج النصي للترحيل).

الحل: تحقق يدويًا من وجود الجدول/العمود وتخطي الترحيل إذا لزم الأمر. أبلغ عن الخطأ إلى فريق PmaControl.

تعارضات Git في التكوين

العرَض: فشل git pull بسبب وجود تعارضات في configuration/.

السبب: قمت بتعديل ملف التكوين الذي تم تعديله أيضًا في البداية.

حل :

# Sauvegarder votre version
cp configuration/problematic_file.php /tmp/

# Accepter la version upstream
git checkout --theirs configuration/problematic_file.php
git add configuration/problematic_file.php

# Ré-appliquer vos modifications manuellement
# Comparer /tmp/problematic_file.php avec la version upstream

ضاع المخبأ

العَرَض: لقد فعلت git stash قبل الترقية ولم يعد بإمكانك العثور على تعديلاتك.

حل :

git stash list
# stash@{0}: On commercial: pre-upgrade 20260413

git stash pop stash@{0}

الخلاصة

تعد المحافظة على PmaControl في الإنتاج عملية يمكن التنبؤ بها إذا اتبعت الإجراء: النسخ الاحتياطي، والسحب، وتثبيت الملحن، وتثبيت.sh، والتحقق. يجعل نموذج Git الترقيات والتراجعات سريعة، ولكنه يتطلب الدقة في التكوين وإدارة النسخ الاحتياطي.

مفاتيح النجاح: بيئة مرحلية، ونافذة صيانة مخططة، وتواصل واضح مع الفريق، والتحقق المنهجي بعد كل ترقية. باتباع هذه الممارسات، تصبح ترقيات PmaControl عملية روتينية - وليست مصدرًا للتوتر.