تشغيل الخادم

تثبيت الخادم

كيف تثبّت خادم Pabal وتشغّله باستخدام Docker Compose على خادم واحد متاح على الإنترنت.

هذه طريقة تثبيت خادم Pabal على خادم واحد متاح على الإنترنت. تشغّل باستخدام Docker Compose ثلاث حاويات هي خادم Pabal · PostgreSQL · Caddy (HTTPS)، وتربط كل البيانات التي يجب ألا تضيع بمجلدات على المضيف (bind mount). اتبع الخطوات بالترتيب من الأعلى إلى الأسفل.

نظرة سريعة

المتطلبات

المنافذ

1. تجهيز الخادم

sudo apt update && sudo apt -y upgrade
timedatectl                      # تحقق من ظهور "System clock synchronized: yes"

مزامنة الوقت ضرورية. فأرقام رسائل MTProto مشتقة من الوقت، وإذا انحرفت ساعة الخادم يكرّر التطبيق محاولات الاتصال. وإذا ظهرت no فنفّذ sudo timedatectl set-ntp true.

# جدار الحماية
sudo ufw allow OpenSSH           # إن أمكن: sudo ufw allow from <IP المشغّل> to any port 22
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw allow 8443/tcp
sudo ufw enable

# Docker (سكربت التثبيت الرسمي)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER     # بعد إعادة تسجيل الدخول يعمل docker دون sudo
docker compose version            # الإصدار v2 أو أحدث

2. جلب الشيفرة المصدرية

sudo mkdir -p /opt/pabal && sudo chown $USER: /opt/pabal
git clone <عنوان المستودع> /opt/pabal

إذا كنت تنسخ من حاسوب التطوير فلا ترسل المفاتيح والبيانات والسجلات (rsync --exclude 'keys/' --exclude 'data/' --exclude 'logs/' --exclude '**/target/'). فمفتاح RSA لخادم الإنتاج يُنشئه خادم الإنتاج بنفسه عند أول تشغيل — وإذا استخدمت مفتاح التطوير في الإنتاج يصبح حاسوب التطوير ذاك مكاناً قادراً على فك تشفير حركة الإنتاج.

3. مجلدات البيانات (bind mount)

sudo mkdir -p /srv/pabal/{postgres_data,pabal_server/keys,pabal_server/data,pabal_server/logs,caddy/data,caddy/config,backups}
sudo chown -R 1000:1000 /srv/pabal/pabal_server        # تعمل حاوية الخادم بالمعرّف uid 1000
sudo chown -R $USER: /srv/pabal/backups
sudo chmod 700 /srv/pabal/pabal_server/keys /srv/pabal/backups

4. ملف الإعدادات ‎.env

cd /opt/pabal/deploy
cp .env.example .env
chmod 600 .env
openssl rand -base64 30 | tr -d '/+=' | cut -c1-32     # ضع القيمة الناتجة في POSTGRES_PASSWORD
nano .env

DOMAIN=pabal.me
PUBLIC_IP=203.0.113.10
POSTGRES_PASSWORD=(القيمة التي أنشأتها أعلاه)
PABAL_HOME=/srv/pabal
PABAL_SOURCE=..
PABAL_NETWORK=ssemiya-net
MTPROTO_PORT=8443
HTTP_PORT=80
HTTPS_PORT=443
ADMIN_PORT=8080
ADMIN_TOKEN=
JAVA_OPTS="-Xms512m -Xmx2g -XX:+UseG1GC -XX:MaxGCPauseMillis=100"

يشغّل ملف Compose الخاص بالإنتاج الخادمَ وأرقام الاختبار معطّلة (TELEGRAM_TEST_NUMBERS=false). والقائمة الكاملة لقيم الإعدادات التي يقرؤها الخادم موجودة في الإدارة والإعدادات — متغيرات البيئة.

5. DNS

dig +short pabal.me        # يجب أن يظهر 203.0.113.10 (قد يستغرق سريان التغيير من دقائق إلى ساعات)

يمكنك التشغيل قبل أن يشير DNS إلى الخادم، فسيعيد Caddy المحاولة تلقائياً حتى يحصل على الشهادة.

6. البناء والتشغيل

cd /opt/pabal/deploy
docker network inspect ssemiya-net >/dev/null 2>&1 || docker network create ssemiya-net   # مرة واحدة فقط
docker compose up -d --build       # في المرة الأولى بضع دقائق (ينزّل Maven المكتبات)
docker compose ps                  # تظهر pabal-server وpabal-postgres وpabal-caddy بحالة running (healthy)
docker compose logs -f pabal-server      # للخروج اضغط Ctrl+C

عند التشغيل الأول تظهر في السجل أسطر مثل هذه.

WARN  ServerKeys - Generated a new RSA key at /app/keys/private.pem (fingerprint -3898654385185406269). Clients must embed /app/keys/private.pem.pub
INFO  TelegramServer - JDBC persistence active (jdbc:postgresql://pabal-postgres:5432/pabal)
INFO  BotFather - BotFather is user 100000
INFO  AdminToken - Created the admin token in /app/data/admin-token
INFO  TelegramServer - Website: http://0.0.0.0:8080/ (published at https://pabal.me/)

• السطر الأول بمستوى WARN لكنه طبيعي (تنبيه بأن المفتاح يُنشأ مرة واحدة فقط). وفي المرات التالية يظهر Loaded RSA key … (fingerprint …). والبصمة تختلف من خادم إلى آخر.
• ينشئ الخادم الجداول بنفسه عند التشغيل.

7. التحقق

# من الخارج (من حاسوبك)
curl -sI https://pabal.me/ | head -1                              # HTTP/2 200
curl -s -o /dev/null -w '%{http_code}\n' https://pabal.me/docs/    # 200 — هذه الوثائق
curl -s -o /dev/null -w '%{http_code}\n' https://pabal.me/admin/   # 404 — صفحة الإدارة غير منشورة
curl -s https://pabal.me/docs/server-key.pem | head -1             # -----BEGIN RSA PUBLIC KEY-----
nc -vz 203.0.113.10 8443                                          # succeeded — منفذ التطبيق

# على الخادم
curl -s http://127.0.0.1:8080/health          # {"status":"UP",…}
ls -l /srv/pabal/pabal_server/keys                  # private.pem(600), private.pem.pub

8. صفحة الإدارة والإعدادات الأولى

# على حاسوبك (اتركه يعمل)
ssh -N -L 8080:127.0.0.1:8080 <user>@203.0.113.10

# الرمز المميّز للإدارة تجده على الخادم
sudo cat /srv/pabal/pabal_server/data/admin-token

افتح http://localhost:8080/admin/ في المتصفح وأدخل الرمز المميّز. الإعدادات التي يجب ضبطها قبل التشغيل الفعلي (التفاصيل في الإدارة والإعدادات):

1. اجعل طريقة إيصال الرمز (코드 전달 방식) هي SMS أو البريد الإلكتروني. ففي طريقة «صفحة الإدارة» (관리 화면) على المشغّل أن يبلّغ الرموز واحداً واحداً.
2. أدخل قيم SMS أو البريد الإلكتروني (SMTP) (이메일 (SMTP)) واحفظها ← ثم تحقق بـالإرسال التجريبي (테스트 발송) من أنها تصل فعلاً.
3. تأكد من أن أرقام الاختبار (테스트 번호) معطّلة. فإذا فُعّلت يستطيع أي شخص تسجيل الدخول بأرقام +99966….
4. وإن لزم الأمر، عطّل السماح بالتسجيلات الجديدة (새 가입 허용) عند البدء، واستقبل أولاً من تدعوهم فقط.

9. توصيل التطبيق بهذا الخادم

يُبنى التطبيق وعنوان IP الخادم ومنفذه ومفتاحه العام مضمّنة فيه. لذا يجب إعادة بنائه بالمفتاح العام لهذا الخادم كي يتصل به. على جهاز Mac:

# 1. المفتاح العام لهذا الخادم (العام لا الخاص — ويمكن تنزيله من موقع الوثائق)
curl -s -o keys/production.pem.pub https://pabal.me/docs/server-key.pem

# 2. توجيه شيفرة التطبيق إلى هذا الخادم + تطبيق العلامة التجارية
python3 scripts/tdesktop/point_to_server.py ~/Developer/tdesktop \
    --host 203.0.113.10 --port 8443 --key keys/production.pem.pub
python3 scripts/tdesktop/apply_branding.py ~/Developer/tdesktop

بعد ذلك نفّذ الخطوتين 5 (configure) و6 (البناء) من docs/tdesktop-build-guide.md في المستودع. وانسخ الناتج out/Debug/Pabal.app باسم آخر — لأنك إذا أعدت بناء الشيفرة نفسها لخادم آخر فسيُستبدل.

التشغيل

الحالة والسجلات

cd /opt/pabal/deploy
docker compose ps
docker compose logs --since 1h pabal-server
tail -f /srv/pabal/pabal_server/logs/telegram-server.log

التحديث

cd /opt/pabal && git pull
cd deploy
./backup.sh                                     # نسخة احتياطية أولاً
docker compose up -d --build pabal-server             # استبدال الخادم وحده بالصورة الجديدة
docker compose logs --since 5m pabal-server | grep -E "Website|ERROR"

خلال عشرات الثواني التي يُعاد فيها تشغيل الخادم ينقطع التطبيق، ثم يعيد الاتصال بنفسه دون تسجيل دخول جديد. ويطبّق الخادم تغييرات الجداول تلقائياً عند التشغيل. والمجلدات المربوطة مستقلة عن الصورة، فلا تُحذف البيانات بـ docker compose down أو بحذف الصورة — فقط لا تحذف /srv/pabal.

النسخ الاحتياطي

./backup.sh            # → /srv/pabal/backups/<التاريخ-الوقت>/{pabal.dump, server-keys-data.tar.gz}
crontab -e             # يومياً في الساعة 03:00:
# 0 3 * * * /opt/pabal/deploy/backup.sh >> /srv/pabal/backups/backup.log 2>&1

• تُحذف تلقائياً النسخ الاحتياطية التي مضى عليها 14 يوماً (ويمكن تغيير ذلك، مثل KEEP_DAYS=30 ./backup.sh).
• انسخها إلى مكان آخر أيضاً. فالنسخة الاحتياطية على القرص نفسه لا تصمد أمام تعطّل القرص.
• تحتوي النسخ الاحتياطية على مفتاح RSA الخاص والقيم السرية لـ SMS وSMTP. فاحمِ مكان حفظها بقدر ما تحمي الخادم.

الاستعادة

cd /opt/pabal/deploy
B=/srv/pabal/backups/20260920-030000            # النسخة الاحتياطية المراد استعادتها
docker compose stop pabal-server pabal-caddy
docker compose exec -T pabal-postgres dropdb -U pabal pabal
docker compose exec -T pabal-postgres createdb -U pabal pabal
docker compose exec -T pabal-postgres pg_restore -U pabal -d pabal --no-owner < $B/pabal.dump
sudo tar -C /srv/pabal/pabal_server -xzf $B/server-keys-data.tar.gz
sudo chown -R 1000:1000 /srv/pabal/pabal_server
docker compose up -d

والأمر نفسه عند الانتقال إلى خادم جديد: نفّذ الخطوات من 1 إلى 5، ثم نفّذ الاستعادة أعلاه بدلاً من الخطوة 6، وشغّل. إذا استعدت المفتاح نفسه فلا حاجة إلى إعادة بناء التطبيق (إلا إذا تغيّر عنوان IP الخادم، فعندها أعد البناء).

التشغيل والإيقاف

docker compose restart pabal-server       # إعادة تشغيل الخادم وحده
docker compose stop                 # إيقاف الكل (تبقى البيانات كما هي)
docker compose up -d                # التشغيل من جديد

حتى لو أعدت تشغيل جهاز الخادم، تعمل الحاويات من جديد تلقائياً لأنها مضبوطة على restart: unless-stopped.

قائمة التحقق الأمني

• صلاحيات .env هي 600، وPOSTGRES_PASSWORD قيمة عشوائية
• صلاحيات /srv/pabal/pabal_server/keys هي 700، ولا يوجد المفتاح الخاص في أي مكان آخر غير النسخ الاحتياطية
• جدار الحماية: 22 (لعنوان IP المشغّل فقط إن أمكن) و80 و443 و8443 فقط
• من الخارج يعيد https://النطاق/admin/ الرمز 404
• صفحة الإدارة: أرقام الاختبار (테스트 번호) معطّلة، وطريقة إيصال الرمز (코드 전달 방식) هي SMS أو البريد الإلكتروني، والإرسال التجريبي (테스트 발송) ناجح
• لم تفعّل TELEGRAM_WEBHOOK_ALLOW_LOCAL (كي لا تصل طلبات webhook الخاصة بالبوتات إلى الشبكة الداخلية)
• SSH: عطّل تسجيل الدخول بكلمة المرور، واسمح بالمفاتيح فقط
• تحقق من مهمة cron للنسخ الاحتياطي ومن النسخ إلى مكان خارجي، وتدرّب على الاستعادة مرة واحدة
• التحديثات الأمنية التلقائية لنظام تشغيل الخادم (unattended-upgrades)

حل المشكلات

القيود المعروفة

• تكوين بخادم واحد. عند التشغيل تُحمَّل كل الحسابات والمحادثات والرسائل في الذاكرة. والتوسع الأفقي بتوزيعها على عدة خوادم غير ممكن بعد، فمع ازدياد البيانات يجب زيادة الذاكرة.
• رموز التسجيل المنتظرة وتحديثات البوتات التي لم تُجلب موجودة في الذاكرة، فتضيع عند إعادة تشغيل الخادم.
• لطلبات رموز التسجيل فاصل زمني وحد يومي، لكن لا يوجد بعد حد لمعدل سائر الطلبات. فراقب السجلات ولوحة المعلومات (대시보드) كثيراً بعد الإطلاق مباشرة.
• لا يوجد تطبيق للهاتف ولا إشعارات فورية. ومرفقات الرسائل مقتصرة على الصور. والقنوات والمجموعات الخارقة والتحقق بخطوتين غير متاحة بعد.
• مفاتيح المصادقة محفوظة في قاعدة البيانات نصاً صريحاً (يحتاج إليها الخادم لفك التشفير). فاحمِ قاعدة البيانات والنسخ الاحتياطية بقدر ما تحمي مفتاح RSA.

الملفات