telepush

Telepush

أرسل إشعارات Telegram بسهولة عبر HTTP

وصف

روبوت Telegram بسيط لترجمة طلبات POST مع حمولة JSON إلى رسائل دفع Telegram. مماثل لـ Gotify وntfy.sh، إلا أنه لا يحتوي على تطبيق إضافي. مفيد لمراقبة الخادم والتنبيه وأي شيء آخر.

كيفية الاستخدام؟

الخطوة 1: الحصول على رمز مميز

افتح Telegram، وابدأ محادثة مع TelepushBot (أو الروبوت الخاص بك، على التوالي) واكتب /start للحصول على رمز المستلم.

الخطوة 2: إرسال الرسائل

يتم إرسال الرسائل عبر POST إلى https://telepush.dev/api/[[inlets/<inlet_name>]|messages]/<recipient> .

 RECIPIENT_TONEN=... # الرمز المميز الذي تلقيته باستخدام /start.curl -XPOST
      -H "نوع المحتوى: تطبيق/json"
      -d '{ "text": "*Hello World!* (نعم، هذا تخفيض السعر)" }'
      "https://telepush.dev/api/messages/${RECIPIENT_TONEN}"

عند استضافة المثيل الخاص بك، استبدل عنوان URL على التوالي.

خيارات الرسالة

مفتاح	يكتب	وصف
text *	خيط	الرسالة الفعلية بنص عادي أو بتنسيق Markdown
origin	خيط	ما سيظهر كمرسل رسالتك
type	[ TEXT FILE ]	نوع الرسالة، أي لإرسال نص أو ملف (الافتراضي: TEXT )
file **	base64	محتوى الملف المشفر بـ Base64
filename **	خيط	اسم الملف المراد إرساله
options	هدف	خيارات إضافية للتمرير
options.disable_link_previews	منطقي	ما إذا كان سيتم عرض معاينات الروابط في الدردشة

* = مطلوب type: TEXT ، ** = مطلوب type: FILE

مزيد من التفاصيل يمكن العثور عليها هنا.

كيفية تشغيل؟

الخيار 1: telepush.dev

ما عليك سوى استخدام المثيل الرسمي المستضاف. يقتصر المعدل على 240 طلبًا لكل مستلم يوميًا.

الخيار 2: استضافة ذاتية

عند استضافة مثيل Telepush الخاص بك، فإنك تحتاج إلى إنشاء روبوت جديد باستخدام @BotFather أولاً. ونتيجة لذلك، سوف تحصل على رمز مميز تقوم بعد ذلك بتمريره إلى Telepush عند بدء تشغيل الخادم (انظر أدناه).

الخيار 2.1: مع عامل الميناء

 حجم عامل الإرساء $ إنشاء telepush_data
تشغيل عامل الإرساء $ -d
     -ص 8080:8080
     -v telepush_data:/srv/data
     --اسم telepush
     gcr.io/muety/telepush
     -وضع ربط الويب
     -الرمز المميز <YOUR_BOTFATHER_TOKEN>

الخيار 2.2: مع Kubernetes

انظر هنا.

الخيار 2.3: الترجمة من المصدر

 # تثبيت$ اذهب لتثبيت github.com/muety/telepush@latest# تشغيل (وضع webhook)$ ./telepush -token <YOUR_BOTFATHER_TOKEN> -mode webhook

Webhook مقابل الاقتراع الطويل

يمكنك إما تشغيل الروبوت في وضع الاقتراع الطويل أو وضع webhook ( -mode [webhook|poll] ). لاستخدام الإنتاج يوصى بالخيار الأخير لأسباب مختلفة. ومع ذلك، ستحتاج إلى خادم مزود بعنوان IP ثابت وشهادة TLS.

يمكن العثور على مزيد من التفاصيل حول إعداد webhook في Marvin's Marvelous Guide to All Things Webhook .

HTTPS

في وضع webhook، يتطلب Telegram نقطة نهاية التحديثات الخاصة بك لاستخدام HTTPS. لتمكين ذلك، قم إما بتشغيل Telepush خلف وكيل عكسي (مثل Caddy)، الذي ينهي TLS.

أو دع Telepush نفسه يتعامل مع TLS. ستحتاج إلى شهادة لذلك، لذا احصل على واحدة من Let's Encrypt أو قم بإنشاء شهادة موقعة ذاتيًا، ثم استخدم -useHttps مع -certPath و -keyPath يشيران إلى شهادتك وملفات المفتاح الخاص على التوالي.

بالنسبة للشهادات الموقعة ذاتيًا، ستحتاج إلى تمرير مفتاحك العام إلى طريقة setWebhook الخاصة بـ Telegram بالإضافة إلى ذلك، راجع هذه التعليمات.

خيارات التكوين

• -address ( string ) - عنوان الشبكة (IPv4) للربط به. الإعدادات الافتراضية هي 127.0.0.1 .

• -address6 ( string ) - عنوان الشبكة (IPv6) المراد الارتباط به. الافتراضي هو ::1 .

• -disableIPv6 ( bool ) - ما إذا كان سيتم تعطيل الاستماع على كل من واجهات IPv4 وIPv6. الافتراضيات false .

• -port ( int ) - منفذ TCP للاستماع إليه. الافتراضي هو 8080 .

• -proxy ( string ) - سلسلة اتصال الوكيل التي سيتم استخدامها في وضع الاستقصاء الطويل. الافتراضات إلى لا شيء.

• -urlSecret ( string ) - لاحقة عشوائية لإلحاق مسار التحديثات الخاص بك الذي تستدعيه خوادم Telegram لمنع البريد العشوائي. الافتراضات إلى لا شيء.

• -useHttps ( bool ) - ما إذا كنت تريد استخدام HTTPS أم لا. الافتراضيات false .

• -certPath ( string ) - مسار شهادة SSL الخاصة بك عند استخدام وضع webhook مع useHttp . الافتراضي إلى لا شيء.

• -keyPath ( string ) - مسار مفتاح SSL الخاص عند استخدام وضع webhook مع useHttp . الافتراضي إلى لا شيء.

• -dataDir ( string ) - موقع نظام الملفات حيث يتم تخزين البيانات الدائمة. الإعدادات الافتراضية ل . .

• -inlets ( string ) - المسار إلى المجلد الذي يحتوي على تعريفات المدخل المستندة إلى التكوين بتنسيق YAML. الإعدادات الافتراضية هي ./inlets.d .

• -blacklist ( string ) - المسار إلى ملف قائمة سوداء مفصولة الأسطر تحتوي على معرفات المستخدمين (أرسل /help للحصول على المعرف الخاص بك). الإعدادات الافتراضية هي blacklist.txt .

• -whitelist ( string ) - المسار إلى ملف القائمة البيضاء مفصول الأسطر والذي يحتوي على معرفات المستخدمين (أرسل /help للحصول على المعرف الخاص بك). الافتراضي هو whitelist.txt .

• -rateLimit ( int ) - الحد الأقصى لعدد الرسائل التي سيتم تسليمها إلى كل مستلم في الساعة. الافتراضيات إلى 100 .

• -truncateMsgs ( bool ) - اقتطاع الرسائل الطويلة جدًا إلى 4096 حرفًا بدلاً من رفضها. الافتراضيات false .

• -metrics ( bool ) – ما إذا كان سيتم عرض مقاييس Prometheus ضمن /metrics . الافتراضيات false .

عند استخدام صورة Docker، يمكنك بدلاً من ذلك تعيين معظم خيارات التكوين المذكورة أعلاه عبر متغيرات البيئة (يتم تمريرها إلى docker run باستخدام -e )، على سبيل المثال APP_USE_HTTPS=true و APP_CERT_PATH=/etc/telepush.crt وما إلى ذلك. للحصول على التفاصيل، راجع entrypoint.sh .

القائمة البيضاء مقابل القائمة السوداء

(ويعرف أيضًا باسم القائمة المسموح بها مقابل القائمة المحظورة)

مداخل

توفر المداخل آلية للمعالجة المسبقة للبيانات الواردة التي تأتي بتنسيق مختلف عما يتوقعه الروبوت عادةً.

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

على سبيل المثال، قد ترغب في إرسال تنبيهات من Prometheus' Alertmanager كإشعارات Telegram. ومع ذلك، تبدو طلبات webhook الخاصة بـ Alertmanager مختلفة كثيرًا عن تنسيق الإدخال الافتراضي لـ Telepush. ولجعلها مناسبة، يمكنك كتابة مدخل لتدليك البيانات وفقًا لذلك.

لمعالجة المدخل مباشرة، اطلب https://telepush.dev/api/inlets/<inlet_name> . لاحظ أن /api/inlets/default يعادل /api/messages .

المداخل التالية متاحة حاليا:

اسم	وصف	حالة
default	ما عليك سوى تمرير الطلب دون أي تغييرات	✅
alertmanager	يستهلك طلبات webhook Alertmanager	✅
grafana	يستهلك طلبات Grafana webhook	✅
webmentionio	يقبل طلبات Webhook Webmention.io للإبلاغ عن إشارة Webmention جديدة لإحدى مقالاتك	✅
stripe	يقبل خطافات الويب Stripe للإخطار بتغييرات حالة الاشتراك	✅
bitbucket	يقبل طلبات Bitbucket webhook للإعلام بتغيير حالة خط الأنابيب	⏳

يمكنك أيضًا تحديد المداخل المخصصة الخاصة بك في YAML. يتوفر المزيد من الوثائق حول هذا الأمر وحول المداخل الفردية الموجودة مسبقًا هنا.

بالنسبة لجميع المداخل، تتوفر الخيارات التالية لتمريرها كمعلمات استعلام:

المعلمة	وصف
disable_link_previews	قم بتعطيل نسخة المعاينة لروابط الويب المكتشفة في الرسالة. الافتراضي: false .
disable_markdown	قم بتعطيل الرسالة التي تتم محاولة تحليلها كـ Markdown. الافتراضي: false .

مثال: POST https://telepush.dev/api/inlets/default?disable_markdown=true&disable_link_previews=true .

المقاييس

يتم عرض مقاييس Prometheus الأساسية ضمن /metrics ، إذا تم تمرير علامة -metrics . وهي تشمل:

• telepush_messages_total{origin="string", type="string"}

• telepush_requests_total{success="string"}

استكشاف الأخطاء وإصلاحها

خطأ: panic: template: pattern matches no files: *.tpl.html

عند تشغيل Telepush كملف واحد قابل للتنفيذ، يجب ألا تستخدم وضع التطوير ما لم يكن كود مصدر Telepush موجودًا داخل نفس الدليل. تأكد من عدم اجتياز -env dev في هذه الحالة.

رخصة

معهد ماساتشوستس للتكنولوجيا @ فرديناند موتش