النشر

اللغة الإنجليزية · Русский · الأوكرانية · Español · البرتغالية (البرازيل) · Türkçe · العربية · فارسي · الأردو · الهندية · اللغة الإندونيسية · الفيتنامية · الصينية المبسطة

اختر طريقة التثبيت#

بالنسبة للحزمة المحمولة، قم باستخراج ملف TgWitness-<version>-windows-amd64-portable.zip من إصدارات GitHub. بالنسبة للطرق الأخرى، قم بتنزيل ملف ZIP المصدر واستخراجه أو انسخ المستودع، ثم قم بتشغيل الأمر التالي من دليل المشروع:

بالنسبة لخادم سحابي يمكن لطرف ثالث التحقق منه — تم إنشاؤه عبر واجهة برمجة تطبيقات (API) المزود، بدون SSH، ولا يمكن الوصول إليه إلا عبر نفق Cloudflare — انظر «النشر عالي الأمان».

تقوم عملية التشغيل الأصلية بإنشاء .venv خاص وتثبيت التبعيات المثبتة. يقوم Docker بإنشائها داخل الصورة، دون الحاجة إلى Python المضيف. يتطلب الإعداد للمرة الأولى اتصالاً بالإنترنت. عند عدم العثور على Python 3.11+، يسأل Start.cmd قبل تثبيت Python 3.12 للمستخدم الحالي لنظام Windows (winget، أو برنامج التثبيت الخاص بـ python.org بعد التحقق من توقيع مؤسسة برمجيات Python)؛ ولا يطلب أبدًا صلاحيات المسؤول. تظل خدمات Docker وخدمات نظام التشغيل متطلبات أساسية.

تستخدم التثبيتات الأصلية والقابلة للنقل data/live داخل مجلدها. بينما يستخدم Docker وحدة التخزين المسماة tgwitness-data في /data. وتُعتبر هذه تثبيتات منفصلة إلى أن تقوم عمداً بترحيل دليل البيانات بالكامل. لا تتوقع أن تكتشف حاوية Docker جديدة الحسابات الأصلية تلقائياً.

متطلبات التثبيت#

يتطلب التثبيت الأصلي Python 3.11 أو أحدث مع venv وensurepip، ووصولًا إلى الإنترنت لتثبيت التبعية الأولى، ودليل مشروع قابل للكتابة لـ .venv. لا تحتاج اللوحة المدمجة إلى Node.js أو بناء واجهة مستخدم. قم بتشغيل المشغل من حساب نظام التشغيل العادي الخاص بك؛ لا يتطلب TgWitness امتيازات المسؤول/الجذر.

• نظام Windows: يقوم Start.cmd بفحص py -3، ثم python، ثم المجلدات الافتراضية لكل مستخدم و مجلدات التثبيت في «Program Files»، ويتطلب الإصدار 3.11 أو أحدث. إذا لم ينجح أي منها، فإنه يقدم التثبيت التلقائي لكل مستخدم الموصوف أعلاه. يعمل py -3 start.py أيضًا. لا تحتاج الحزمة المحمولة إلى لغة Python على الإطلاق.
• Linux: يحاول start.sh استخدام python3.13 وpython3.12 وpython3.11 وpython3 و python، ويطبع أمر التثبيت لـ apt أو dnf أو pacman أو zypper أو apk أو Homebrew عندما لا يكون أي منها مناسبًا. قد تتطلب عمليات التثبيت على Debian/Ubuntu حزمة python3-venv المطابقة للمترجم المحدد. يجب استبدال إصدار Python الافتراضي الأقدم في التوزيعة أو استكماله بـ Python 3.11 أو أحدث.
• نظام macOS: قم بتثبيت إصدار حديث من Python 3.11+؛ لا تفترض أن المُترجم المُوفَّر من نظام التشغيل يفي بالمتطلبات. استخدم python3 start.py من دليل المشروع.
• Docker: استخدم Docker Engine/Desktop مع Compose الإصدار 2.20 أو أحدث. يجب أن يستخدم Docker Desktop حاويات Linux على نظام Windows. تقوم الحاوية بتثبيت تبعيات Python الخاصة بها؛ ولا يحتاج المضيف إلى تثبيت Python منفصل.

استخدم تخزينًا محليًّا دائمًا لدليل البيانات. خطط للسعة بناءً على عدد الرسائل، والملفات الوسائطية، ونمو سجل WAL، وعمليات التصدير والنسخ الاحتياطي؛ فلا توجد مواصفات دنيا عالمية قائمة على الأدلة للسعة القرصية/ذاكرة الوصول العشوائي لكل حمل عمل. قد تتطلب بنى وحدة المعالجة المركزية وإصدارات Python التي تفتقر إلى عجلات التبعية المتوافقة أدوات بناء إضافية و تأهيلها الخاص. كلمة «قابل للنقل» لا تعني دعمًا شاملاً لجميع أنظمة التشغيل أو الأجهزة.

تم التحقق محليًّا من Windows 11/Python 3.12. أما تعريفات Linux/macOS/الحاويات وCI فقد تم توفيرها ولكن لم يتم تنفيذها على مضيف التطوير هذا. انظر ملف VERIFICATION.md لمعرفة النطاق الدقيق.

جهاز كمبيوتر محلي#

استخدم Start.cmd على نظام Windows أو sh start.sh على أنظمة Linux/macOS. يقوم scripts\Setup.cmd أو sh start.sh --setup-only بإعداد البيئة. يقوم المشغل بتثبيت التبعيات عند الاستخدام الأول؛ أما عمليات التشغيل اللاحقة فتعيد استخدام البيئة. يلزم الاتصال بالإنترنت لإجراء الإعداد وجمع رسائل Telegram، ولكن تصفح السجلات الموجودة وإنشاء ملفات التصدير يعملان دون اتصال بالإنترنت.

قم بتشغيل python start.py --check بعد الإعداد لفحص التبعيات المحلية، و Ed25519، والتخزين، وتكوين المفتاح، وعنوان الاستماع دون تشغيل أداة التجميع. استخدم --json للحصول على مخرجات منظمة. قم بتمرير الأوامر المقصودة --data-dir و--host و --port. لا يقوم الفحص بتثبيت الحزم، أو إنشاء سجل، أو الاتصال بـ Telegram؛ وهو ليس تقييمًا للسلامة أو التغطية. يقوم برنامج Startup بالتحقق بشكل منفصل من السجلات الموجودة. كما يتجنب python start.py --help التثبيت.

الخيارات:

بعد استخدام start.py، قم بتشغيل الأوامر المساعدة باستخدام .venv\Scripts\python.exe في نظام Windows أو .venv/bin/python في Linux/macOS، أو قم بتنشيط تلك البيئة أولاً. تفترض الأمثلة python -m ... أدناه أن البيئة نشطة.

python -m tgwitness --data-dir /path/to/private/data --host 127.0.0.1 --port 8787

متغيرات البيئة: TGWITNESS_DATA، TGWITNESS_HOST، TGWITNESS_PORT، TGWITNESS_TOKEN. يحدد TGWITNESS_VAULT_KEY_FILE وضع المفتاح الخارجي للتثبيت الجديد؛ انظر أدناه. يجب أن يحتوي TGWITNESS_TOKEN، إذا تم توفيره، على 24 حرفًا على الأقل؛ استخدم قيمة عشوائية مشفرة. وبدونه، يقوم التطبيق بإنشاء رمز عشوائي 256 بت في ملف panel-token.txt. لا يؤدي تجاوز متغيرات البيئة إلى إعادة كتابة هذا الملف. أعد التشغيل لتغيير بيانات الاعتماد.

يمكن لعملية واحدة فقط أن تمتلك دليل البيانات. يمنع قفل الملفات عبر أنظمة التشغيل الكتابة المتزامنة غير المقصودة. استخدم عامل Uvicorn واحدًا. يمكن للوحة إدارة أي عدد من مساحات العمل، مع وجود أدلة إضافية لمساحات العمل ضمن profiles/<id>/. بالنسبة لمثيلات الخدمة المنفصلة، استخدم أدلة ومنافذ منفصلة. يجب أن تكون ملفات WAL الخاصة بـ SQLite موجودة في وحدة تخزين محلية دائمة، وليس في نظام ملفات شبكي. لا تشارك وحدة تخزين واحدة بين النسخ المتماثلة.

حزمة قابلة للتشغيل على نظام ويندوز#

يحتوي كل إصدار على GitHub على TgWitness-<version>-windows-amd64-portable.zip و .sha256. ويشتمل على بيئة التشغيل الرسمية القابلة للتضمين لـ Python 3.12 من python.org (مجموع التحقق مثبت في tools/build_portable.py)، وTgWitness وتبعياته المثبتة، وثلاثة مشغلات:

قم باستخراج الأرشيف بالكامل إلى مجلد قابل للكتابة مثل Documents\TgWitness؛ لا تقم بتشغيله من داخل ملف ZIP أو من مجلد Program Files. يستخدم وقت التشغيل مسار وحدة معزولة، لذلك لا تؤثر عليه تثبيتات Python الأخرى ولا PYTHONPATH. تبقى البيانات في مجلد data الخاص بالحزمة. للتحديث، أوقف تشغيل TgWitness، ثم قم باستخراج الإصدار الجديد إلى مجلد جديد وانسخ مجلد data إليه.

قم بتثبيتها بنفسك على نظام Windows 64 بت باستخدام Python 3.12:

python tools/build_portable.py

يقوم المُنشئ بالتحقق من المجموع الاختباري لوقت التشغيل، وتثبيت التبعيات المقيدة في الحزمة، وتشغيل فحص الجاهزية باستخدام المُترجم المدمج، وكتابة ملف ZIP والمجموع الاختباري إلى dist/.

الحاوية#

docker compose up -d --build --wait

يؤدي هذا إلى إنشاء وحدة تخزين دائمة ذات اسم لمجلد /data. يتم تعيين منفذ الويب إلى 127.0.0.1:8787. تعمل العملية برقم UID 10001 مع إمكانيات محدودة، ونظام ملفات جذر للقراءة فقط، ومجلدين /data و/tmp قابلين للكتابة. يقوم --wait بفحص حالة خادم الويب قبل العودة؛ ولا يقوم بإجراء تخويل أو تسليم Telegram. تستخدم الأدوات المساعدة المتوفرة مهلة استعداد مدتها 180 ثانية بعد الإنشاء. قد يستغرق تنزيل التبعيات الأولية وقتًا أطول من ذلك.

يستخدم كل من ملفَي Compose الأساسيين اسم المشروع tgwitness، لذا فإن استخراج إصدار جديد إلى دليل آخر لا يؤدي تلقائيًا إلى تحديد وحدة تخزين بيانات جديدة. احتفظ بنشر واحد فقط نشطًا لهذا المشروع. بالنسبة للتثبيتات المستقلة، استخدم docker compose -p NAME ... فريدًا ومنفذ مضيف مختلف، واحتفظ بكليهما عند التحديثات. بالنسبة لعملية نشر أقدم تستخدم اسم مشروع مختلف، استمر في استخدام اسمها الأصلي مع -p؛ حيث يسرد docker compose ls المشاريع الموجودة.

انسخ deploy/env.example إلى .env وقم بتغيير TGWITNESS_PORT لاستخدام منفذ لوبباك مختلف. على سبيل المثال، يعرض TGWITNESS_PORT=8788 اللوحة على http://127.0.0.1:8788؛ ولا يزال الحاوية تستمع على المنفذ 8787. يتم تجاهل .env في Git.

استرداد الرمز المميز الأولي:

docker compose exec tgwitness cat /data/panel-token.txt

الأوامر المفيدة:

docker compose ps
docker compose logs --tail 100 -f
docker compose stop
docker compose up -d --wait

restart: unless-stopped يعيد تشغيل أداة التجميع بعد حدوث عطل أو إعادة تشغيل خدمة Docker الخلفية . على خادم Linux، قم بتمكين Docker عند بدء التشغيل باستخدام مدير الخدمات الخاص بنظام التوزيع الخاص بك ، والذي يُعرف عادةً باسم sudo systemctl enable --now docker. على أنظمة Windows/macOS، قم بتمكين إعداد «التشغيل عند تسجيل الدخول» في Docker Desktop. قد يؤدي تسجيل الخروج من سطح المكتب أو وضع السكون أو توقف قد يؤدي إيقاف تشغيل خادم Docker إلى مقاطعة عملية التجميع. تظل الحاوية التي تم إيقافها بشكل صريح متوقفة حتى تقوم بتشغيلها مرة أخرى.

يبلغ الحد الأقصى لحجم وحدة التخزين /tmp 512 ميغابايت في التكوين المثال. يستخدم بناء التصدير temporary-exports/ لكل مساحة عمل على وحدة التخزين الدائمة /data بدلاً من ذلك. احجز مساحة هناك لعمليات التصدير المتزامنة، ونمو السجل/WAL، والوسائط، والنسخ الاحتياطية. يستخدم المشغل ملف deploy/constraints.txt لتثبيت إصدارات التبعيات المؤهلة لوقت التشغيل. يتم تثبيت Docker والخوادم عالية الأمان من ملفات deploy/requirements.lock و deploy/build.lock باستخدام pip --require-hashes: يجب أن يتطابق كل ملف حزمة مع قيمة SHA-256 مسجلة في الالتزام (commit)، وبالتالي يتم رفض أي ملف تم استبداله على PyPI أو على خادم مرآة. لا تزال الصورة الأساسية لـ Python وحزم نظام التشغيل تتطلب تأهيلًا مستقلًا للإصدار.

لا تستخدم الأمر docker compose down -v إلا إذا كنت تنوي إتلاف السجل والمفاتيح. تشير تقارير حالة الحاوية إلى توفر خادم الويب، وليس إلى نجاح عملية التقاط رسائل Telegram. افحص حالة المجمع في اللوحة، ونبضه، والأخطاء، وأحداث التغطية.

ملف تعريفي للشاهد المستقل#

تقوم خدمة witness الاختيارية بتشغيل شاهد مستقل في حاوية خاصة بها، مع مفتاحها الخاص وسجلها في وحدة التخزين witness-data، مع وجود رمز شاهد للقارئ فقط للمجمع. قم بإنشاء الرمز على صفحة «Witness» (الشاهد) في اللوحة، وأضفه مع رمز بوت وقناة إلى .env، ثم ابدأ الملف الشخصي:

docker compose --profile witness up -d          # deploy/compose/compose.image.yaml: same flag
docker compose logs witness                     # witness key fingerprint

تصل الخدمة إلى أداة التجميع داخل شبكة Compose على http://tgwitness:8787 (TGWITNESS_WITNESS_COLLECTOR يتجاوزها، على سبيل المثال /profiles/<workspace ID> لمساحة عمل أخرى). بالنسبة لـ«شاهد» على خادم منفصل، يديره شخص آخر، استخدم deploy/compose/compose.witness.yaml هناك مع تعيين TGWITNESS_WITNESS_COLLECTOR على عنوان HTTPS لأداة التجميع؛ لا يحتوي هذا الملف سوى على «الشاهد».

تثبيت صورة منشورة#

يصبح هذا متاحًا بعد إتمام سير عمل الإصدار بنجاح وتكوين حزمة GHCR العامة. لا يتم ترميز اسم/مالك المستودع بشكل ثابت في شجرة المصدر هذه. استخدم الصورة الموضحة في ملخص سير عمل ذلك الإصدار.

انسخ deploy/env.example إلى .env. اضبط TGWITNESS_IMAGE على الإصدار المنشور، باستخدام مسار المستودع بالأحرف الصغيرة، على سبيل المثال:

TGWITNESS_IMAGE=ghcr.io/your-owner/your-repository:0.7.0
TGWITNESS_PORT=8787

قم بتشغيل هذا الملف بمفرده، بدلاً من compose.yaml:

docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait
docker compose --project-directory . -f deploy/compose/compose.image.yaml exec tgwitness cat /data/panel-token.txt

لا حاجة إلى بناء المصدر أو لغة Python أو مُجمِّع على المضيف. يستهدف سير عمل الإصدار حاويات Linux AMD64 وARM64، بما في ذلك الآلة الافتراضية Linux في Docker Desktop. استخدم علامة الإصدار أو ghcr.io/owner/repository@sha256:... من ملخص سير العمل. لم يتم تكوين علامة latest المتحركة أو ترقية التطبيق غير المراقبة. تستخدم الصورة ومتغيرات المصدر نفس حجم البيانات عندما يتطابق اسم المشروع.

تشغيل HTTPS تلقائيًا على الخادم#

استخدم خادمًا مزودًا بـ Docker، ونطاقًا تحت سيطرتك، وتخزينًا محليًّا دائمًا. قم بتوجيه سجلات A/AAAA للنطاق إلى الخادم؛ وانشر سجل AAAA فقط إذا وصل IPv6 إليه. اسمح بالاتصالات الواردة عبر TCP 80 و443 والاتصالات الصادرة عبر DNS/HTTPS لإصدار الشهادات. يجب ألا تكون هذه المنافذ مخصصة بالفعل لخدمات أخرى.

انسخ deploy/env.example إلى .env وقم بتعيين اسم مضيف، بدون مخطط أو مسار:

TGWITNESS_DOMAIN=watch.your-domain.org

ابدأ بناء المصدر باستخدام طبقة HTTPS:

docker compose -f compose.yaml -f deploy/compose/compose.https.yaml up -d --build --wait
docker compose -f compose.yaml -f deploy/compose/compose.https.yaml exec tgwitness cat /data/panel-token.txt

docker compose --project-directory . -f deploy/compose/compose.image.yaml -f deploy/compose/compose.https.yaml up -d --wait

بالنسبة للصورة المنشورة، استخدم deploy/compose/compose.image.yaml كملف أول بدلاً من ذلك. احتفظ بكل من معلمتي -f لاستخدامهما لاحقًا في أوامر الحالة والسجلات والتحديث والإيقاف.

يقوم Caddy بالحصول على شهادة وتجديدها، وإعادة توجيه HTTP إلى HTTPS، وإعادة توجيه الطلبات إلى المجمع على شبكة Compose الخاصة. حالة الشهادة لها وحدة تخزين دائمة خاصة بها. يظل منفذ المضيف المباشر للمجمع مخصصًا للارتداد الداخلي فقط. لا تتيح تهيئة Caddy المُقدمة تسجيل الوصول.

افتح https://watch.your-domain.org وأدخل رمز اللوحة. الاستعداد للكتابة لا يؤكد إصدار الشهادة أو إمكانية الوصول الخارجي. إذا لم يكن HTTPS جاهزًا، فافحص DNS وقواعد جدار الحماية، بالإضافة إلى:

docker compose -f compose.yaml -f deploy/compose/compose.https.yaml logs --tail 100 caddy

صورة Caddy المرفقة تتبع علامة 2-alpine الخاصة بها. يؤدي سحب الصورة إلى تحديثها؛ قم بتثبيت ملخص تم اختباره في بيئتك إذا كنت بحاجة إلى إصدارات ثابتة من البنية التحتية.

التحديثات والنسخ الاحتياطية#

الحفاظ على اسم مشروع Compose وحجم البيانات عبر التحديثات. قم أولاً بإيقاف أداة التجميع (collector) وعمل نسخة احتياطية كاملة. بالنسبة للنشر الافتراضي القائم على المصدر:

docker compose stop
docker compose cp tgwitness:/data ../tgwitness-backup-before-update

استخدم وجهة نسخ احتياطي جديدة في كل مرة، خارج المستودع، وقم بحمايتها باعتبارها مواد تتطلب وصولاً إلى الحساب. المسار الموضح في المثال هو لأغراض التوضيح فقط؛ استخدم موقع النسخ الاحتياطي الخاص بك. انسخ الدليل بأكمله، بما في ذلك الملفات المخفية، وجميع مساحات العمل، والمفاتيح، والسجلات، والملفات الوسائطية. قم بعمل نسخة احتياطية من المفتاح الرئيسي للخزينة الخارجية بشكل منفصل إذا تم تكوينه. ملف ZIP الخاص بالأدلة ليس نسخة احتياطية قابلة للاستعادة للتطبيق. بالنسبة لـ HTTPS، احتفظ أيضًا بمجلدات Caddy إذا كنت بحاجة إلى الاحتفاظ بحالة الشهادة/الحساب.

لنشر المصدر، احصل على ملفات الإصدار الجديد وقم بتشغيل:

docker compose up -d --build --wait

لنشر الصورة، قم بتغيير TGWITNESS_IMAGE إلى الإصدار المطلوب، ثم قم بتشغيل:

docker compose --project-directory . -f deploy/compose/compose.image.yaml pull
docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait

استخدم ملف (ملفات) Compose الخاص بتثبيتك لأوامر الإيقاف/النسخ السابقة أيضًا. احتفظ بـ .env، والتكوين المخصص، واسم المشروع نفسه. يحافظ down على المجلدات المسماة؛ بينما يحذفها down -v. لا تنسخ .venv بين أنظمة التشغيل أو إصدارات Python. للتحديثات الأصلية، أوقف TgWitness، وقم بعمل نسخة احتياطية من دليل البيانات الكامل الخاص به، واستبدل الملفات المصدرية، وقم بتشغيل python start.py --setup-only قبل التشغيل.

تحقق من الوصول إلى اللوحة، وهوية الحساب، وحالة المراقبة، والتغطية بعد إجراء تحديث. لا تؤدي إعادة التشغيل إلى استعادة تحديثات Telegram الفائتة. قد يتطلب التراجع النسخة الاحتياطية السابقة للتحديث إذا غيرت إصدارات مستقبلية تنسيقات التخزين.

إصدارات GitHub الآلية#

يصبح سير عمل الإصدار جاهزًا للاستخدام بعد نقل هذا المشروع إلى مستودع GitHub مع تمكين ميزة Actions. ويتم تشغيله عند نشر إصدار GitHub، بما في ذلك الإصدارات التمهيدية. ولا تؤدي المسودات وعمليات دفع العلامات بحد ذاتها إلى نشر الحزم.

1. قم بتعيين إصدار الحزمة وسجل التغييرات، ثم انشر إصدارًا مُعلَّمًا بـ v بالإضافة إلى الإصدار الدقيق من pyproject.toml، مثل v0.7.0.
2. يقوم سير العمل بالتحقق من صحة العلامة وتشغيل فحوصات Python المشتركة بين أنظمة التشغيل Windows/Linux/macOS، وكذلك فحوصات general/account-import/QR browser، و source-package، و Docker. كما يتم إجراء تثبيت أصلي جديد على جميع أنظمة التشغيل الثلاثة باستخدام Python 3.12.
3. بعد اجتياز تلك الفحوصات، تُجرى اختبارات أولية لصورة ARM64 تحت بيئة QEMU، ويتم نشر صور AMD64/ARM64 على ghcr.io/<lowercase-owner>/<lowercase-repository>:<version>، ويتم إرفاق ملف ZIP المصدر، ومجموع التحقق، وملف Python wheel بالإصدار. وتقوم مهمة منفصلة على نظام Windows بإنشاء ملف ZIP القابل للنقل وإرفاقه مع مجموع التحقق الخاص به.
4. بعد النشر الأول، افتح إعدادات حزمة GHCR واضبط الرؤية على «عام» إذا كان المقصود هو سحب الصور بشكل مجهول. لا يضمن مستودع المصدر العام بمفرده أن تكون حزمة الحاوية عامة. يجب أن تسمح سياسات المؤسسة بنشر الحزمة. يستخدم سير العمل GITHUB_TOKEN؛ ولا ينبغي أن يتضمن المستودع كلمة مرور التسجيل أو بيانات اعتماد VPS.

لم يتم إثبات نجاح سير العمل عن بُعد من خلال هذا الإعداد المحلي. محاكاة ARM64 هي مجرد اختبار أولي، وليست تأهيلًا للأجهزة الأصلية أو لتطبيق Telegram في الوقت الفعلي. يؤدي هذا إلى أتمتة عملية تجميع الإصدارات؛ ولا يزال تشغيل الخادم يتطلب الأمر Compose ومتطلباته الأساسية المتعلقة بالمجال/المضيف. لا يتم ترقية الخوادم الحالية أو إعادة تشغيلها تلقائيًا عند نشر إصدار جديد.

خادم بعيد#

حافظ على ربط الخدمة بـ loopback واستخدم نفق SSH، أو قم بإنهاء HTTPS عند بروكسي عكسي. ملف Compose الأساسي محلي فقط؛ بينما توفر طبقة deploy/compose/compose.https.yaml الاختيارية Caddy لنطاق تم تكوينه. احرص على عدم ظهور رمز الحامل في عناوين URL وسجلات الوكيل. يجب أن يحد الوكيل العكسي من حجم الطلبات ومعدلات الاتصال. لا تكشف بروتوكول HTTP العادي للإنترنت.

تتوفر أمثلة لـ systemd، ومهمة تسجيل الدخول إلى Windows، ووكيل مستخدم macOS، و Caddy في مجلد deploy/. قم بمراجعة/تعديل مساراتها قبل التثبيت. هذه نماذج مقدمة، وليست إعدادات منصة يتم تنفيذها محليًّا. لا يتم تسجيل أي خدمة أو مهمة في الخلفية بواسطة المشغل العادي.

في نظام Windows، يؤدي تشغيل pythonw.exe بدون نافذة إلى تخزين تشخيصات بدء التشغيل/الخادم في logs/server.log ضمن دليل البيانات (5 ميغابايت لكل ملف، ونسختان احتياطيتان يتم تناوبهما). يحتفظ تشغيل وحدة التحكم بسجلات وحدة التحكم. يتم تعطيل تسجيل الوصول عبر HTTP في كلا الوضعين. قم بحماية السجلات باستخدام دليل البيانات وراجعها قبل مشاركتها.

إعادة التشغيل والثغرات#

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

يحتفظ StringSession بالترخيص ولكنه لا يحتفظ بحالة التحديث/الكيان الدائمة لـ Telethon. يتم إعادة تحميل الحوارات عند البدء. يمكن لـ Telegram/Telethon استعادة بعض انقطاعات النقل أثناء التشغيل، لكن TgWitness لا يدعي إمكانية إعادة التشغيل الدائمة عبر عمليات إعادة تشغيل العملية. يتم عند كل عملية بدء تشغيل تسجيل رأس السجل السابق وحدود وضع عدم الاتصال. يقوم جهاز المراقبة بفحص الاتصال كل 10 ثوانٍ وإضافة إشارة نبض كل دقيقة (المعلمات → تسجيل النشاط كل). قد يتم تفويت الانقطاعات القصيرة؛ ولا يضمن الاتصال المستمر تسليم التحديثات بالكامل. اللقطات هي ملاحظات صريحة للتاريخ الحالي، وليست أبدًا إصلاحًا للفجوات.

يتم تخزين قائمة انتظار الوسائط في قاعدة بيانات SQLite الخاصة بكل مساحة عمل. يتم تسجيل الرسالة ومهمتها بشكل متكامل. يتم استرداد المهام قيد التشغيل التي تمت مقاطعتها لإعادة المحاولة عند البدء. يتمتع كل تنزيل بمهلة انتظار أساسية مدتها 120 ثانية بالإضافة إلى الوقت اللازم لحجم الملف بمعدل 256 كيلوبايت في الثانية، و حد أقصى يتراوح بين 1 و2,000 ميغابايت لكل نوع مرفق؛ وتوجد إعدادات المهلة والسرعة والمحاولات المتكررة ضمن قسم «المعلمات». يقوم المجمع بتخطي الملفات التي يكون حجمها غير معروف. ويؤدي الإيقاف المؤقت إلى الاحتفاظ بالأعمال الموجودة في قائمة الانتظار. تستخدم إعادة المحاولة وصف الملف الأصلي الذي تمت ملاحظته، ولا تستخدم أبدًا أحدث إصدار من رسالة تم تعديلها لاحقًا. يتم تحديد عدد محاولات إعادة المحاولة في حالات الفشل المؤقت؛ وتبقى فترات توقف «FloodWait» للوسائط سارية بعد إعادة التشغيل. يتم استرداد الوسائط بشكل منفصل عن استرداد تحديثات Telegram ولا يمكن إعادة إنشاء الملفات المفقودة.

النسخ الاحتياطي والاستعادة والسعة#

أوقف العملية قبل نسخ دليل البيانات بالكامل، بما في ذلك ملفات vault.key و signing.enc و credentials.enc وقاعدة بيانات SQLite وملفات WAL والوسائط والرمز المميز ونقاط الفحص، وجميع الملفات الشخصية/الدلائل الفرعية. استعد النسخة الكاملة أثناء توقف الخدمة الوجهة. يؤدي فقدان مفاتيح الخزينة أو عدم تطابق مفتاح التوقيع إلى فشل بدء التشغيل؛ لا تقم بإعادة إنشاء المفاتيح لفرض الوصول.

احتفظ بالنسخ الاحتياطية السرية مشفرة وخاضعة للتحكم في الوصول. ملفات ZIP الخاصة بالأدلة قابلة للنقل وهي عبارة عن عناصر قابلة للمراجعة، وليست نسخًا احتياطية للتطبيق أو لجلسات Telegram. لا يوجد حذف تلقائي للبيانات المحتفظ بها. خصص مساحة على القرص لجميع الرسائل، والبيانات الوصفية الأولية، والملفات الوسائطية، وعمليات التصدير المؤقتة، والنسخ الاحتياطية.

تقوم الأداة الناشئة بالتحقق وتصدير سجلات التدفق بدلاً من تحميل السجل بأكمله. يؤدي التصدير إلى تثبيت لقطة قراءة بينما يمكن أن تستمر عمليات الكتابة الجديدة في WAL؛ ويمكن أن تحتفظ عمليات التصدير طويلة الأمد بصفحات WAL، لذا تظل سعة القرص مهمة. يبلغ الحد الأقصى لملفات ZIP 4 جيجابايت غير مضغوطة لتتوافق مع الإعداد الافتراضي للمحقق المستقل؛ المعلمات → أكبر ملف ZIP موقّع يرفع الحد الأقصى، ويتم التحقق من هذه الأرشيفات باستخدام verify.py --max-gib N. لا يوجد حد أقصى لعدد الأحداث في التنسيقات الأخرى. تقوم المتصفحات المدعومة ببث أجزاء الاستجابة إلى ملف يختاره المستخدم. أما المتصفحات الأخرى فتخزن مؤقتًا 128 ميغابايت كحد أقصى وتوجه عمليات النقل الأكبر حجمًا إلى واجهة سطر الأوامر (CLI) المصادق عليها:

python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip

استخدم --profile ID من «التصدير» → «معرف مساحة العمل» لمساحة عمل أخرى، أو --format zip|jsonl|csv|html و--url https://your-server لخادم بعيد، أو --max-mib لتغيير حد النقل البالغ 5 جيجابايت. يُسمح باستخدام بروتوكول HTTP العادي فقط من أجل الارتداد الداخلي. تنتقل الرموز في الرؤوس، ويتم رفض عمليات إعادة التوجيه، ولا يتم الكتابة فوق الملفات الموجودة، ولا يتم نشر التنزيلات غير المكتملة كملفات مكتملة. إذا تجاوز TGWITNESS_TOKEN الرمز المميز الذي تم إنشاؤه، فاستخدم ملفًا محميًّا بشكل منفصل يحتوي على تلك القيمة النشطة: لا يتم إعادة كتابة ملف panel-token.txt بواسطة التجاوز. يُعد SHA-256 الخاص بالأمر مجرد مجموع اختباري للنقل؛ قم بالتحقق بشكل مستقل من ملف ZIP الموقّع.

تظل ملفات التصدير من الخادم داخل مجلد temporary-exports/ الخاص بكل مساحة عمل. تقوم العمليات الناجحة بمسح ملفاتها. أما عمليات التصدير المتوقفة فيتم إزالتها عند التشغيل التالي لمساحة العمل مع الاحتفاظ بقفل المثيل الحصري الخاص بها. هذا الدليل جزء من نموذج التهديدات/السعة التخزينية؛ استخدم وحدة تخزين بيانات مشفرة. عمليات النقل على نطاق الإنتاج التي تصل إلى عدة غيغابايت لا تزال تتطلب تأهيلًا على نظامك المستهدف.

تعرض اللوحة الوسائط الموضوعة في قائمة الانتظار/التي فشلت، وأقدم الوسائط المعلقة، ومساحة القرص المتوفرة، و عمليات إيقاف طلبات Telegram مؤقتًا، والمصادر التي لم يتم تأكيد الوصول إليها. هذه التشخيصات ليست مراقبة كاملة للتسليم من البداية إلى النهاية. تشترك مساحات العمل في عملية واحدة؛ لذا يمكن للحساب المثير للضوضاء أن يؤثر على الآخرين. لا تزال عمليات العمال المنفصلة، والاحتفاظ/التناوب، واستعادة التحديثات الدائمة والتأهيل الكامل للنشر قائمة. يتم توثيق الوصول المحدود إلى اللوحة في قسم الوصول والأذونات؛ بينما يتم تغطية نقاط الفحص المستقلة في دليل الشهود.

خيارات الاتصال والحماية#

مسارات الاتصال خاصة بكل مساحة عمل ويجب تهيئتها قبل منح الصلاحيات. يستخدم SOCKS5/HTTP CONNECT التبعية المثبتة python-socks. يستخدم MTProxy نظام النقل الوسيط العشوائي التجريبي من Telethon؛ ولا يتم دعم أسرار TLS ee المزيفة. يعتمد التراجع المباشر على وضع IP المحدد: يرفضه وضع «إخفاء IP»؛ بينما يسمح به وضع التراجع الصريح بعد فترة تأخير. يسمح وضع «النفق/VPN» بالمسارات المباشرة ولكنه لا ينشئ شبكة VPN. هذه ليست سياسة شبكة على مستوى النظام بأكمله.

بالنسبة للتثبيتات الجديدة، يشير TGWITNESS_VAULT_KEY_FILE إلى ملف مفتاح رئيسي عشوائي محمي بشكل منفصل. قم بتركيبه على أنه للقراءة فقط خارج /data في حاوية. احتفظ ببيانات التعريف العامة لملف salt الخاص بـ vault.external.json مع كل مساحة عمل والمفتاح الرئيسي بشكل منفصل. تتطلب الخزائن المحلية الحالية عملية ترحيل مخطط لها؛ ولا يؤدي تعيين هذا المتغير إلى تحويلها تلقائيًّا. لا يتم تشفير تخزين الرسائل/الوسائط وعمليات التصدير بواسطة التطبيق. استخدم وحدات تخزين مشفرة ومساحة تخزين مؤقتة خاصة كافية عند الحاجة.

إجراءات تفصيلية: الاتصال/الأمان و أوضاع التشغيل.