تشغيل الخادم
الإدارة والإعدادات
صفحة الإدارة، وإيصال رموز التسجيل (SMS والبريد الإلكتروني)، وقيم إعدادات الخادم، والنسخ الاحتياطي والأمان — مرجع للمشغّلين.
يحتوي الخادم على صفحة إدارة تُفتح في المتصفح. ترى فيها حالة الخادم، وتحدد كيف تُوصَل رموز التسجيل وتسجيل الدخول، وتدير المستخدمين والبوتات. وهذا المستند مرجع يجمع في مكان واحد صفحةَ الإدارة وقيمَ إعدادات الخادم. وإن كان التثبيت هو خطوتك الأولى فراجع تثبيت الخادم. وبما أن واجهة صفحة الإدارة باللغة الكورية حالياً، نذكر بجانب أسماء التبويبات والأزرار والإعدادات اسمها الكوري كما يظهر على الشاشة.
فتح صفحة الإدارة
صفحة الإدارة هي /admin/ على منفذ HTTP الإداري (8080 في تكوين الإنتاج)، ولا تُفتح إلا من الخادم نفسه (127.0.0.1). ويدخل المشغّل إليها عبر نفق SSH.
# على حاسوبك (اتركه يعمل)
ssh -N -L 8080:127.0.0.1:8080 <user>@<server>
# في المتصفح: http://localhost:8080/admin/
# الرمز المميّز (على الخادم)
sudo cat /srv/pabal/pabal_server/data/admin-tokenأدخل الرمز المميّز واضغط فتح (열기). يتذكر المتصفح الرمز، ويمكنك مسحه بزر مسح الرمز المميّز (토큰 지우기) أعلى اليمين. ولتحديد الرمز بنفسك مرّر TELEGRAM_ADMIN_TOKEN (16 حرفاً على الأقل) — وعندها لا يُكتب الملف.
ما يظهر في كل تبويب
| التبويب | المحتوى | التحديث |
|---|---|---|
| لوحة المعلومات (대시보드) | الأشخاص والجلسات والاتصالات النشطة الآن، وعدد الأشخاص والبوتات والمجموعات والرسائل والصور، ومدة التشغيل والمنافذ وقاعدة البيانات، وJVM، وفحص الحالة. وإذا كانت أرقام الاختبار مفعّلة يظهر شريط تحذير | 5 ثوانٍ |
| رموز التسجيل (가입 코드) | الرموز المنتظرة (الرقم، وطريقة الإيصال، وحالة الإرسال، والرمز، والوقت المتبقي، وعدد المحاولات الخاطئة) والسجل الأخير. نسخ الرمز وإلغاؤه | 3 ثوانٍ |
| المستخدمون (사용자) | كل الحسابات — رقم الهاتف، وبريد تسجيل الدخول (قابل للتعديل)، وحالة الاتصال، وعدد الأجهزة المسجّل دخولها، وعدد الرسائل. تسجيل الخروج من جميع الأجهزة (모든 기기 로그아웃)، وحظر الرقم (번호 차단) | 10 ثوانٍ |
| البوتات (봇) | البوتات المنشأة عبر BotFather — منشئها، وقائمة أوامرها، وطريقة اتصالها (MTProto · استطلاع HTTP · عنوان webhook وسبب الفشل)، وعدد التحديثات المنتظرة | 10 ثوانٍ |
| الإعدادات (설정) | قواعد التسجيل وتسجيل الدخول، وSMS، والبريد الإلكتروني (SMTP)، وحظر أرقام الهواتف | حفظ يدوي |
| التخزين (저장소) | مجلد البيانات وعنوان قاعدة البيانات (مع إخفاء كلمة المرور)، وعدد الصور وحجمها، وعدد تدفقات التخزين (streams) حسب النوع | 10 ثوانٍ |
الإجراءات الخطرة (تسجيل الخروج والحظر وإلغاء الرمز) لا تُنفَّذ إلا بالضغط مرتين.
رموز التسجيل وتسجيل الدخول
عندما يُدخل شخص رقم هاتفه في التطبيق، ينشئ الخادم رمزاً ويرسله بالطريقة المختارة في تبويب الإعدادات (설정).
| طريقة الإيصال | إلى أين يذهب الرمز | شاشة التطبيق |
|---|---|---|
| صفحة الإدارة (관리 화면) | تبويب رموز التسجيل (가입 코드). ينسخه المشغّل ويبلّغه بنفسه | الرقم ← «أرسلنا الرمز» ← الرمز (والاسم إذا كان الرقم جديداً) |
| SMS | رسالة نصية عبر أحد الخيارات: Twilio · Solapi · webhook | مثل صفحة الإدارة |
| البريد الإلكتروني (이메일) | رسالة بريد عبر SMTP | الرقم ← إدخال البريد الإلكتروني ← «أرسلنا الرمز إلى بريدك الإلكتروني» ← الرمز |
- في طريقة البريد الإلكتروني يمكن للتسجيل الجديد استخدام أي عنوان، ويصبح ذلك العنوان بريد تسجيل الدخول للحساب. أما الحسابات الموجودة فلا تستلم الرمز إلا على بريد تسجيل الدخول المسجّل لها — وهذا يمنع أحداً من إدخال عنوانه مع رقم غيره والدخول. والحسابات الموجودة التي ليس لها بريد تسجيل دخول يُرسل إليها الرمز بدلاً من ذلك عبر SMS (إن كان مضبوطاً) أو عبر صفحة الإدارة. ويمكنك إضافة بريد تسجيل الدخول من تبويب المستخدمين (사용자).
- يتم الإرسال في الخلفية، فينتقل التطبيق فوراً إلى شاشة الرمز. وتظهر نتيجة الإرسال (النجاح أو الفشل وسببه) في تبويب رموز التسجيل.
- لا يتم التسجيل (إدخال الاسم) إلا بعد إدخال الرمز الصحيح. والرموز الخاطئة لا تُقبل إلا بعدد المحاولات المسموح، وبعدها يُرفض حتى الرمز الصحيح.
الإعدادات — التسجيل وتسجيل الدخول
| البند | المعنى | الافتراضي |
|---|---|---|
| السماح بالتسجيلات الجديدة (새 가입 허용) | إذا عُطّل فلا يسجّل الدخول إلا أصحاب الحسابات الموجودة، وتُرفض الأرقام الجديدة بـ«رقم غير صالح» | مفعّل |
| طريقة إيصال الرمز (코드 전달 방식) | صفحة الإدارة / SMS / البريد الإلكتروني | صفحة الإدارة |
| عرض الرمز في صفحة الإدارة (관리 화면에 코드 표시) | يعرض الرمز في تبويب رموز التسجيل حتى في طريقتي SMS والبريد الإلكتروني (احتياطاً لفشل الإرسال) | مفعّل |
| أرقام الاختبار (+99966…) (테스트 번호) | حسب إعداد الخادم / تفعيل / تعطيل. عطّلها في الإنتاج | حسب إعداد الخادم |
| عدد خانات الرمز · مدة الصلاحية (코드 자릿수 · 유효 시간) | 5 أو 6 خانات · من 1 إلى 60 دقيقة | 5 خانات · 5 دقائق |
| الفاصل بين الطلبات · الحد اليومي (재요청 간격 · 하루 최대) | عدد الثواني قبل أن يستطيع الرقم نفسه استلام رمز جديد (من 0 إلى 3600) · أقصى عدد من الطلبات خلال 24 ساعة (من 1 إلى 1000) | 60 ثانية · 10 مرات |
| عدد المحاولات الخاطئة المسموح (틀린 입력 허용 횟수) | إذا تجاوزها المستخدم يُقفل ذلك الرمز (من 1 إلى 20) | 5 مرات |
الإعدادات — SMS
| المزوّد | القيم المطلوبة | ملاحظات |
|---|---|---|
| Webhook (웹훅) | عنوان الاستلام (https://…)، وترويسة Authorization (اختيارية) | يرسل الخادم POST {"phone":"+8210…","code":"12345","text":"…"}، والاستجابة 2xx تعني النجاح. لتوصيله بخادم رسائل خاص بك أو بخدمة أخرى |
| Twilio | Account SID، وAuth Token، ورقم المُرسِل أو Messaging Service SID | العالم كله، بما في ذلك الأرقام الدولية |
| Solapi (CoolSMS سابقاً) | API Key، وAPI Secret، ورقم المُرسِل | رسائل داخل كوريا. ورقم المُرسِل يجب أن يكون مسجّلاً مسبقاً في Solapi. وتُرسل أرقام +82 بالصيغة 010… |
يمكنك وضع {code} (الرمز) و{minutes} (مدة الصلاحية) في نص الرسالة. والنص الافتراضي: [파발] 인증 코드: {code} (أي «[Pabal] رمز التحقق: {code}»). وبعد الحفظ تحقق منه بـالإرسال التجريبي (테스트 발송).
الإعدادات — البريد الإلكتروني (SMTP)
| الخدمة | الخادم · المنفذ · الأمان | اسم المستخدم · كلمة المرور |
|---|---|---|
| Gmail | smtp.gmail.com · 587 · STARTTLS | عنوان Gmail · كلمة مرور التطبيق (حساب Google ← الأمان ← التحقق بخطوتين ← كلمات مرور التطبيقات) |
| Naver | smtp.naver.com · 587 · STARTTLS | المعرّف · كلمة المرور (فعّل استخدام POP3/SMTP من إعدادات البريد) |
| مُرحِّل البريد الداخلي في المؤسسة | عنوان المُرحِّل · 25 · بلا | فارغ |
يجب أن يكون عنوان المُرسِل عنواناً يسمح حساب SMTP بالإرسال منه. ويُستخدم {code} و{minutes} في الموضوع والنص أيضاً.
إدارة المستخدمين
- تسجيل الخروج من جميع الأجهزة (모든 기기 로그아웃): يقطع كل تسجيلات الدخول (مفاتيح المصادقة) لذلك الحساب. ويُستخدم مع المستخدمين الذين فقدوا أجهزتهم.
- حظر الرقم (번호 차단): لا يستطيع ذلك الرقم استلام الرموز، ويُسجَّل خروج حسابه من جميع الأجهزة فوراً. وهو مطابق لقائمة حظر أرقام الهواتف في تبويب الإعدادات.
- بريد تسجيل الدخول (로그인 이메일): ضروري في طريقة البريد الإلكتروني كي يسجّل الحساب الموجود دخوله عبر البريد.
- @BotFather بوت موجود داخل الخادم، فلا يخضع لتسجيل الخروج.
إدارة البوتات
في تبويب البوتات (봇) ترى طريقة اتصال كل بوت — هل هو متصل عبر MTProto، وهل استدعى getUpdates عبر HTTP خلال الدقيقة الأخيرة، وما عنوان webhook الخاص به، وهل يفشل الآن (مع السبب). وإذا ظلّ عدد التحديثات المنتظرة يزداد، فبرنامج البوت متوقف أو أن webhook يفشل. أما حذف البوت وإعادة إصدار رمزه المميّز فيقوم بهما منشئ البوت لدى @BotFather.
متغيرات البيئة
يقرأ الخادم ملف الإعدادات (server-config.json) ثم يستبدل قيمه بقيم متغيرات البيئة. وبما أن ملف Compose الخاص بالإنتاج يحدد القيم أدناه، يكفي عادةً تعديل .env وحده.
| المتغير | المعنى | القيمة في Compose الإنتاج |
|---|---|---|
TELEGRAM_PORT | منفذ MTProto | MTPROTO_PORT (8443) |
TELEGRAM_HOST | العنوان الذي يستمع عليه MTProto | 0.0.0.0 |
TELEGRAM_PUBLIC_HOST | عنوان الخادم الذي يُبلَّغ به التطبيق (help.getConfig) | PUBLIC_IP |
TELEGRAM_WEB_PORT | منفذ الموقع والوثائق وBot API وصفحة الإدارة | 8080 |
TELEGRAM_WEB_HOST | العنوان الذي يستمع عليه ذلك المنفذ. الافتراضي 127.0.0.1 | 0.0.0.0 (داخل الحاوية، ولا يُنشر على المضيف إلا على 127.0.0.1) |
TELEGRAM_PUBLIC_URL | عنوان الموقع. يُستخدم للروابط (me_url_prefix) وروابط الدعوة وأمثلة الوثائق وصور المعاينة | https://DOMAIN/ |
TELEGRAM_DATA_DIR | مكان الصور وadmin-token وoperations.json | /app/data |
TELEGRAM_RSA_KEY | مسار مفتاح RSA الخاص بالخادم (إن لم يوجد يُنشأ في البداية، والمفتاح العام في .pub) | /app/keys/private.pem |
TELEGRAM_DC_ID | رقم DC لهذا الخادم | (الافتراضي في الصورة 1) |
TELEGRAM_DB_TYPE | memory · h2 · postgresql | postgresql |
TELEGRAM_DB_URL، TELEGRAM_DB_USERNAME، TELEGRAM_DB_PASSWORD | اتصال JDBC | jdbc:postgresql://pabal-postgres:5432/pabal، pabal، POSTGRES_PASSWORD |
TELEGRAM_DB_MAX_POOL_SIZE | عدد اتصالات قاعدة البيانات | 20 |
TELEGRAM_ADMIN_TOKEN | الرمز المميّز لصفحة الإدارة (إذا تُرك فارغاً يُنشأ في data/admin-token) | ADMIN_TOKEN |
TELEGRAM_TEST_NUMBERS | أرقام الاختبار +99966…. للتطوير فقط | false |
TELEGRAM_WEBHOOK_ALLOW_LOCAL | يسمح لـ webhook البوتات باستخدام http:// والعناوين الداخلية. للتطوير فقط | (غير محدد = false) |
JAVA_OPTS | خيارات JVM (الذاكرة) | القيمة من .env |
ملفات البيانات
| الملف | المحتوى | الصلاحيات |
|---|---|---|
keys/private.pem | مفتاح RSA الخاص بالخادم. لا يُخرج إلى أي مكان أبداً | 600 |
keys/private.pem.pub | المفتاح العام. يُستخدم في بناء التطبيق وفي /docs/server-key.pem | — |
data/admin-token | الرمز المميّز لصفحة الإدارة | 600 |
data/operations.json | قيم تبويب الإعدادات (설정) — قواعد التسجيل، والقيم السرية لـ SMS وSMTP، والأرقام المحظورة | 600 |
data/media/ | الصور الأصلية | — |
جدول events في PostgreSQL | الحسابات والمحادثات والرسائل وتسجيلات الدخول والبوتات وإعدادات webhook — سجل كل التغييرات | — |
ملاحظات أمنية
- لا تفتح منفذ الإدارة مباشرة على الإنترنت. وفي تكوين الإنتاج يحجب Caddy مسارات الإدارة مثل
/adminو/healthو/metricsبإعادة 404. - كل طلبات بيانات الإدارة تتطلب
Authorization: Bearer <token>، ولا تستطيع صفحات المواقع الأخرى قراءتها. - القيم السرية لـ SMS وSMTP موجودة في
operations.jsonفقط، ولا تُظهر الشاشة وواجهة API إلا أنها «محفوظة». وإذا تركت خانة القيمة السرية فارغة وحفظت تبقى القيمة السابقة كما هي. - لا تُطبع الرموز المميّزة والقيم السرية في السجلات، وتُسجَّل أرقام الهواتف مع إخفاء جزء منها. ولا تُسجَّل أيضاً عناوين Bot API (التي تتضمن الرمز المميّز).
- بما أن مفاتيح المصادقة موجودة في قاعدة البيانات، فمن يستطيع الوصول إلى قاعدة البيانات يستطيع فك تشفير حركة المستخدمين. فاحمِ قاعدة البيانات والنسخ الاحتياطية بقدر ما تحمي مفتاح RSA.
القيود
- الرموز المنتظرة والسجل الأخير موجودة في الذاكرة، فتضيع عند إعادة تشغيل الخادم (ويكفي أن يطلب المستخدم الرمز من جديد في التطبيق).
- يجب التحقق من الإرسال الفعلي لكل مزوّد SMS بحسابك لديه. فالخادم يبني الطلبات وفق وثائق كل مزوّد.
- ما ليس متاحاً بعد: حذف الحسابات، وحذف البوتات قسراً، والاطلاع على الرسائل، وعرض السجلات، والرسوم البيانية.