راه‌اندازی سریع

انگلیسی · روسی · اوکراینی · اسپانیایی · پرتغالی (برزیل) · ترکی · عربی · فارسی · اردو · هندی · بهاسا اندونزی · تایلندی · فونت ساده‌شدهٔ چینی

TgWitness یک برنامه مستقل برای مشاهده گروه‌ها و کانال‌های تلگرامی است که حساب‌های کاربری شما به آن‌ها دسترسی دارند. این برنامه به صورت محلی و با دایرکتوری داده اختصاصی خود اجرا می‌شود.

اولین بازدید؟ پیش از اتصال حساب، نسخهٔ نمایشی را امتحان کنید. برای پراکسی‌ها، شاهدان، خروجی‌ها یا راه‌اندازی سرور، راهنمای مناسب را انتخاب کنید.

نصب و راه‌اندازی#

ثبت با GitHub Actions (پیش‌نمایش)

یک روش را انتخاب کنید. دانلودهای قابل حمل پس از انتشار نسخهٔ نهایی در دسترس قرار می‌گیرند:

برای روش‌های مبتنی بر سورس، شاخهٔ main فعلی را دانلود و استخراج کنید یا مخزن را کلون کنید:

git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness

سورس فعلی شامل وارد کردن دسته‌ای حساب‌ها، داشبورد MTProxy و بارگذاری تاریخچه با قابلیت ادامه است. نسخهٔ پیش‌نمایش قابل حمل 0.7.0 و آرشیو سورس انتشار آن مربوط به پیش از این قابلیت‌ها هستند. برای مشاهدهٔ مرز نسخه‌ها به فهرست تغییرات مراجعه کنید.

در صورت یافت نشدن Python مناسب، Start.cmd پیشنهاد نصب Python 3.12 را برای کاربر ویندوز شما می‌دهد (از طریق winget یا نصب‌کنندهٔ امضاشدهٔ python.org). در صورت نبود Python، اسکریپت start.sh دستور دقیق نصب را برای توزیع لینوکس یا macOS شما چاپ می‌کند. اولین اجرا از طریق سورس، محیط .venv را ایجاد کرده و وابستگی‌ها را به‌طور خودکار نصب می‌کند.

Docker برنامه را می‌سازد و آن را در پس‌زمینه راه‌اندازی می‌کند؛ پایتون میزبان غیرضروری است. scripts\Docker.cmd و scripts/docker-start.sh آدرس پنل و توکن را زمانی که کانتینر سالم است چاپ می‌کنند. دستورات معادل Docker در هر میزبان پشتیبانی‌شده عبارتند از:

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

http://127.0.0.1:8787 را باز کنید. از توکنی که توسط دستیار Docker یا دستور دوم Docker چاپ شده است استفاده کنید، یا برای نصب قابل حمل یا سورس، فایل data/live/panel-token.txt را بخوانید. در بخش «اتصال تلگرام» در زیر ادامه دهید. نصب‌های بومی و داکر از ذخیره‌سازی جداگانه‌ای استفاده می‌کنند؛ راه‌اندازی داکر، ژورنال بومی موجود را وارد نمی‌کند.

برای یک سرور، استقرار شامل HTTPS خودکار، راه‌اندازی مجدد، تصاویر منتشرشده، به‌روزرسانی‌ها و پشتیبان‌گیری‌ها است.

رابط کاربری را کاوش کنید#

1. دستور TgWitness-Demo.cmd را در بستهٔ قابل حمل، scripts\Demo.cmd را در یک پوشهٔ منبع ویندوز، یا sh start.sh --demo را در لینوکس/macOS اجرا کنید. اجرای سورس ابتدا .venv را ایجاد کرده و وابستگی‌ها را نصب می‌کند.
2. http://127.0.0.1:8787 را باز کنید.
3. دموی محلی به‌طور خودکار دفترچه نمونه را باز می‌کند. برای دسترسی مستقیم محلی نیازی به کپی توکن نیست.

پیام‌های دمو خیالی هستند. حالت دمو نمی‌تواند به یک حساب واقعی تلگرام متصل شود.

اتصال تلگرام#

[!هشدار] از هر چیزی که تحمل از دست دادنش را ندارید، استفاده نکنید. ما قویاً توصیه می‌کنیم که حساب‌های شخصی یا باارزش خود را متصل نکنید و روی حسابی که برایتان ارزش دارد، شناسه/هش API ایجاد نکنید. تلگرام حساب‌ها را به طور غیرقابل پیش‌بینی و اغلب به صورت دائم، صرف‌نظر از کلاینت، مسدود می‌کند. یک اجرای آزمایشی موفقیت‌آمیز به تلگرام بستگی دارد، نه به TgWitness، و هیچ تضمینی برای آینده ندارد.

1. اگر دموی بومی در حال اجرا باشد، آن را متوقف کرده و Start.cmd یا sh start.sh را اجرا کنید. در غیر این صورت، نصب زندهٔ بالا را همچنان در حال اجرا نگه دارید.
2. برای باز کردن پنل، از توکن پنل مربوط به روش نصب خود استفاده کنید.
3. اگر به پروکسی نیاز دارید، آن را در مسیر حساب کاربری → تنظیمات → تنظیمات اتصال → تغییر مسیر اتصال ذخیره کنید.
4. در بخش «حساب» (Account)، شماره تلفن خود را وارد کرده و دکمه «ادامه» (Continue) را فشار دهید، سپس «کد QR» (QR code) → «نمایش کد QR» (Show QR code) را انتخاب کنید، یا فایل‌ها را انتخاب کرده و دکمه «اتصال حساب» (Connect account) را فشار دهید. «شناسه API + هش» (API ID + Hash) اختیاری است: فضای کاری از جفت ذخیره شده یا وارد شده خود، یا یک جفت فعال از مجموعه داخلی استفاده می‌کند. برای استفاده از اپلیکیشن خود، یک جفت API ID:API Hash را در بخش «شناسه API» (API ID) جای‌گذاری کنید. برای یک کلید احراز هویت کامل، «کلید احراز هویت» (Auth key) را انتخاب کنید، تمام ۵۱۲ کاراکتر هگزادسیمال را الصاق کنید و شناسه DC ارائه‌شده را انتخاب کنید. شناسه کاربر اختیاری است و در صورت وارد کردن، تیک آن زده می‌شود.
5. روش ورود انتخابی خود را تکمیل کنید: تلفن/کد/2FA، تأیید از طریق اپلیکیشن تلگرام واردشده برای QR، یا وارد کردن یک جلسه مجاز پشتیبانی‌شده.
6. شناسه حساب نمایش‌داده‌شده را بررسی کنید. منابع آزاد: چت‌های شما به‌طور خودکار بارگذاری می‌شوند؛ گروه‌های خود را اضافه کنید.
7. در بخش «انتخاب تغییرات قابل نگهداری»، دسته‌بندی‌های رویداد یا پیش‌تنظیم «پیام‌ها، ویرایش‌ها و حذف‌ها» را انتخاب کرده، سپس تنظیمات پایش را ذخیره کنید.
8. تنظیمات پیوست را به‌طور جداگانه انتخاب کنید، سپس دکمهٔ «شروع مشاهده» را فشار دهید.

اطلاعات اعتبارنامه API، برنامه شما را شناسایی می‌کنند؛ آن‌ها به خودی خود، حساب کاربری را مجاز نمی‌سازند. گروه‌های خصوصی به نام کاربری عمومی نیازی ندارند، اما حساب کاربری شما باید دسترسی داشته باشد.

برای حساب‌های موجود، حساب‌ها و قالب‌های نشست را ببینید: پنل از Telethon StringSession، فایل‌های SQLite مربوط به Telethon/Pyrogram، فایل ZIP تک‌حسابی TData و فایل‌های JSON پشتیبانی‌شدهٔ حساب پشتیبانی می‌کند. یک نشست و فایل JSON همراه آن را با هم انتخاب کرده و اتصال حساب را بزنید. ورود با کد QR نیز با همان تنظیمات اختیاری API در دسترس است. نشست‌های TDLib، نشست‌های ربات و فهرست‌های حساب CSV/JSON پشتیبانی نمی‌شوند.

برای چندین حساب، از حساب‌ها → وارد کردن حساب‌ها استفاده کنید و فایل‌های نشست پشتیبانی‌شدهٔ آن‌ها را انتخاب نمایید. فایل‌های JSON همراه بر اساس نام پایهٔ فایل جفت می‌شوند؛ هر حساب واردشده فضای کاری مخصوص به خود را دریافت می‌کند. بخش وارد کردن دسته‌ای و گروه‌های حساب را ببینید.

برای افزودن حساب کاربری دیگر، دکمه + را در کنار انتخابگر حساب کاربری فشار دهید یا به مسیر حساب کاربری → تنظیمات → تنظیمات اتصال → فضاهای کاری بروید، یا از بخش حساب‌ها استفاده کنید. فضاهای کاری دارای جلسات، دفترچه‌های ثبت، کلیدها، منابع و صف‌های مجزا هستند. تغییر نماها باعث توقف سایر گردآورنده‌ها نمی‌شود. یک حساب تلگرام نمی‌تواند در این نصب به دو فضای کاری اختصاص داده شود. تعداد ثابتی از فضاهای کاری وجود ندارد؛ آنها یک فرآیند را به اشتراک می‌گذارند، بنابراین ظرفیت به ماشین بستگی دارد.

توکن پنل زنده از دسترسی به مجوزهای تلگرام و مطالب ذخیره‌شده شما محافظت می‌کند؛ این توکن از اعتبارنامه‌های API تلگرام جداست. تنها یک دمو محلی که صراحتاً راه‌اندازی شده و مستقیماً به آن دسترسی پیدا شده باشد، ورود خودکار خواهد داشت. یک دمو از راه دور/پروکسی همچنان از data/demo/panel-token.txt استفاده می‌کند.

بازبینی و صدور#

• مجله: جستجو و فیلتر کردن مشاهدات بر اساس منبع و نوع رویداد.
• یک رویداد را انتخاب کنید تا رکورد اصلی، انتساب و نسخه‌های ذخیره‌شده آن را بررسی کنید.
• جزئیات ویرایش محتوای موجود قبل و بعد را نشان می‌دهند. جزئیات حذف، در صورت وجود، آخرین محتوای ضبط‌شده را نشان می‌دهند؛ عامل ناشناس همچنان ناشناس باقی می‌ماند.
• خروجی‌ها: ZIP امضا‌شده، JSONL، CSV و HTML آفلاین.
• خروجی کامل چت (منابع → خروجی کامل چت): دانلود کل تاریخچه قابل مشاهده یک چت به صورت یک بسته امضا شده با chat.json (سبک خروجی تلگرام) و یک chat.html قابل خواندن. چت‌های خصوصی زمانی کار می‌کنند که حساب کاربری عضو باشد. این یک نسخهٔ لحظه‌ای فعلی است، نه بازسازی پیام‌های حذف‌شده یا ویرایش‌شده در گذشته. نسخه را با python verify.py chat-export.zip --fingerprint TRUSTED_SHA256 تأیید کنید.
• ذخیره نقطه کنترل: مرز دفترچهٔ امضا شده را خارج از جمع‌کننده نگه دارید.
• دانلود رسید اجرای امضا شده: حفظ سوابق برنامه/نسخهٔ گردآورنده.
• درخواست مهر زمانی را آماده کنید: یک درخواست آفلاین برای یک مرجع مهر زمانی آماده کنید؛ برای دریافت و تأیید پاسخ، به فایل TIMESTAMP.md مراجعه کنید.
• تأیید دفترچه: بررسی امضاهای رویداد و پیوندهای زنجیره. خروجی ZIP همچنین رسانه‌ها را بررسی می‌کند.

مرورگرهای پشتیبانی‌شده خروجی‌های حجیم را مستقیماً در یک فایل انتخاب‌شده ذخیره می‌کنند. سایر مرورگرها حداکثر ۱۲۸ مگابایت را در بافر نگه می‌دارند. در حالی که سرور در حال اجراست، CLI پخش (streaming) دانلودهای بزرگ‌تر را بدون بافر کردن کل پاسخ پشتیبانی می‌کند:

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

برای یک فضای کاری دیگر، با استفاده از «صادرات → شناسه فضای کاری» (Exports → Workspace ID)، --profile ID را اضافه کنید. برای یک سرور از راه دور، --url https://your-server را اضافه کنید. محدودیت پیش‌فرض انتقال ۵ گیگابایت است؛ --max-mib آن را تغییر می‌دهد. محتوای ZIP امضا شده به طور پیش‌فرض دارای محدودیت تأیید اعتبار جداگانه ۴ گیگابایتی برای فایل‌های فشرده نشده است (پارامترها آن را افزایش می‌دهند؛ چنین آرشیوهایی را با verify.py --max-gib N تأیید کنید). آرشیو را با استفاده از یک نسخه مورد اعتماد از اعتبارسنج و یک اثر انگشت/نقطه کنترل کلیدی که به طور مستقل نگهداری شده است، تأیید اعتبار کنید.

نصب را بررسی کنید#

python start.py --setup-only
python start.py --check
python start.py --check --json

ابزار --check وابستگی‌های محلی، پشتیبانی از امضا، ذخیره‌سازی، پیکربندی کلید و آدرس گوش دادن را بررسی می‌کند. این ابزار هیچ چیزی نصب نمی‌کند و به تلگرام متصل نمی‌شود. یک پورت شلوغ ممکن است به این معنی باشد که یک نمونه دیگر در حال اجرا است. از یک --port دیگر استفاده کنید یا ابتدا آن را متوقف کنید.

راه‌انداز در .venv نصب می‌شود. دستورات کمکی python -m tgwitness... باید از .venv\Scripts\python.exe در ویندوز یا .venv/bin/python در لینوکس/macOS استفاده کنند، مگر اینکه آن محیط از قبل فعال باشد.

جلسات، حفاظت و عملکرد#

یک پایگاه داده SQLite بسته و یکپارچه .session می‌تواند به صورت محلی با python -m tgwitness.sessions account.session --out account.tgwitness-session تبدیل شده و سپس در حساب کاربری بارگذاری شود. وارد کردن مستقیم فایل و ورود با QR نیز در دسترس است. برای مشاهده فرمت‌های ورود، SOCKS5، HTTP CONNECT، MTProxy و کلیدهای اصلی خارجی به CONNECTION-SECURITY.md مراجعه کنید.

توقف مشاهده جمع‌آوری را متوقف می‌کند. قفل کردن فقط دسترسی از طریق مرورگر را می‌بندد. با بستن زبانه، فرایند جمع‌آوری همچنان اجرا می‌شود. متوقف کردن فرایند، جمع‌آوری را قطع می‌کند؛ ثبت تاریخچه نمی‌تواند تمام ویرایش‌ها یا حذف‌های ازدست‌رفته را بازسازی کند. برای سیاست‌های رویدادها، صف‌های پیوست، جداسازی حساب‌ها و رفتار هنگام راه‌اندازی مجدد، نحوهٔ کار جمع‌آوری را ببینید.

جلسات و اسرار رمزگذاری می‌شوند. محتوای پیام، رسانه‌ها و خروجی‌ها به یک دیسک یا حجم رمزگذاری‌شده نیاز دارند. امضاها یکپارچگی را نسبت به یک کلید مورد اعتماد برقرار می‌کنند؛ آن‌ها اصالت تلگرام را اثبات نمی‌کنند و از جعل توسط اپراتوری که گردآورنده و کلید آن را کنترل می‌کند، جلوگیری نمی‌کنند.

برای پشتیبان‌گیری/بازیابی فایل OPERATIONS.md، برای میزبانی فایل DEPLOYMENT.md و برای نمونه‌های سرویس به deploy/ مراجعه کنید. پنل نصب‌شده همچنین شامل یک راهنمای راه‌اندازی آفلاین در آدرس /guide.html است.

تأیید واقعی و محدودیت‌های باقی‌مانده در فایل‌های VERIFICATION.md و READINESS.md ثبت شده‌اند.