# معماری

Canonical page: https://phishdestroy.github.io/TgWitness/fa/docs/reference/architecture/

اجزای جمع‌آورنده، پنل، دفترچه، کارگران و شاهد، و نحوهٔ جابجایی داده‌ها بین آن‌ها.

یک فرآیند پایتون میزبان پنل FastAPI و هر تعداد فضای کاری ایزوله است، که هر کدام دارای یک کلاینت حساب کاربری تل‌هان (Telethon) هستند. SQLite یک دفترچه وقایع امضا شده با قابلیت الحاق تنها و تنظیمات عملیاتی قابل تغییر را در خود جای می‌دهد. یک گاوصندوق رمزگذاری‌شده حاوی اعتبارنامه‌های API، StringSession و کلید امضا است. فرانت‌اند، HTML/CSS/JavaScript بسته‌بندی‌شده و ساده‌ای است: نیازی به ساخت با Node، CDNها یا دانلودهای فرانت‌اند در زمان اجرا نیست.

| ماژول | مسئولیت |
| --- | --- |
| collector.py | مجوز، انتخاب دیالوگ، به‌روزرسانی‌ها، اسنپ‌شات‌ها، صف رسانه‌ای، نظارت بر اتصال |
| interactions.py / telegram_client.py | اقدامات واضح پنل، رسیدهای امضا‌شده، شناسه‌های درخواست پایدار و سیاست تلاش مجدد فراخوانی/پیوست‌شدن محلی وظیفه |
| message_content.py | مقایسهٔ قابل مشاهدهٔ پیام‌ها، بدون در نظر گرفتن متادیتای دسترسی به انتقال |
| workers.py | منتظر کارگران فایل خروجی قبل از پاکسازی لغو باشید |
| store.py | معاملات WAL، زنجیره رویداد مرتب‌شده، فیلترهای پرس‌وجو، تنظیمات عملیاتی |
| security.py | ایجاد فایل خصوصی، گاوصندوق رمزگذاری‌شده، امضای Ed25519، قفل تک‌فرآیندی |
| evidence.py | خروجی کامل دفترچه، مشتقات، نقاط کنترل، تأیید پیوست |
| verify.py | راست‌آزماین مستقل و فقط-خواندنی ( stdlib + رمزنگاری): آرشیوها، پوشش، دفترچه‌های شاهدی و پست‌های کانال، فایل‌های پروفایل |
| app.py | API احرازشده، چرخهٔ عمر، اعتبارسنجی درخواست، پنل ایستا |
| profiles.py | گردآورنده‌های چندحساب، کنترل‌کننده دسترسی مشترک، چرخه عمر به‌ازای هر فضای کاری |
| access.py | مجوزهای محدود، بررسی‌های دسترسی، محدودیت‌های IP، محدودیت‌های جلسه و کنسول مدیر |
| proxy_catalog.py | اسکرین‌شات‌های فید عمومی، بررسی‌های انتقال، استخر پروکسی مشترک و انتخاب مبتنی بر سلامت |
| provenance.py | اندازه‌گیری‌های کد و وابستگی‌های هویت، اجراشده و امضا‌شده |
| network.py | مسیرهای تأییدشده برای هر فضای کاری؛ وضعیت و شواهد سانسور شده؛ گزینه‌های انتقال تله‌تون |
| sessions.py | تبدیل آفلاین فقط-خواندنی طرح‌های SQLite تله‌تون بررسی‌شده |
| import_حساب.py | تشخیص و نرمال‌سازی در حافظه‌ای فایل‌های حساب کاربری و JSON پشتیبانی‌شده |
| tdata.py | خوانندهٔ محدود مدرن TData ZIP، اعتبارسنجی چک‌سام/رمزگشایی، بدون استخراج |
| doctor.py | بررسی‌های آمادگی محلی بدون جمع‌آوری، ورود یا نصب بسته |
| download.py | دانلود خروجی استریمینگ احرازشده با خوانش‌های محدود و بدون بازنویسی |
| monitoring.py | سیاست رویداد تأییدشده برای هر فضای کاری و قواعد پیوست‌بندی بر اساس نوع، که توسط پردازشگرها، وضعیت و رسیدهای امضاشده به اشتراک گذاشته می‌شوند |
| scope.py | دامنهٔ مشاهده (گفت‌وگوهای انتخابی، پوشهٔ تلگرام، کل حساب)، انواع منابع، استثناها، سطوح بازبینی مجدد |
| dossier.py | پروفایل افراد در هر گفتگو بر اساس سوابق ذخیره شده ساخته شده است: حقایق با ارجاع به سوابق، SHA-256/pHash آواتار، استخراج ذکرها |
| witness_api.py | توکن‌های شاهد فقط-خواندنی و سرتیتر امضاشدهٔ دفترچهٔ یادداشت که ممکن است دریافت کنند |
| witness.py | فرآیند شاهد مستقل: کلید و دفترچه یادداشت اختصاصی، بررسی‌های سرانگشتی، پست‌های امضا‌شده کانال، خروجی‌گیری |
| alerts.py | اخطاریه‌های اپرایز و فهرست اعلان‌های پنل |
| logging_config.py | ثبت لاگ کنسول و تشخیص وضعیت سرورهای چرخشی برای راه‌اندازی‌های بدون پنجره |
| ایستا/ | رابط کاربری واکنش‌گرا، دروازه دسترسی محلی، فیلترها، جزئیات، خروجی‌ها، تنظیم حساب |
| demo.py | دفترچهٔ مصنوعی به‌وضوح برچسب‌گذاری‌شده، جدا از مجموعهٔ واقعی |

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

هر فضای کاری یک حساب کاربری را می‌پذیرد و دارای دایرکتوری و هویت امضای خود است. فضای کاری اصلی برای سازگاری در ریشه باقی می‌ماند؛ فضاهای کاری اضافی در profiles/<id>/ قرار دارند. یک توکن حامل کل نصب را کنترل می‌کند؛ فضاهای کاری اجزای مجزای مجوزدهی نیستند. قفل‌های فرآیند از دایرکتوری‌ها محافظت می‌کنند؛ قفل‌های پایگاه داده، درج رویدادها را به صورت سریالی انجام می‌دهند. هر افزودنی به طور همزمان در WAL (لاگ پیش‌رونده) SQLite با حالت همگام کامل commit می‌شود. رویدادهای به‌روزرسانی/حذف، ویرایش‌های عادی برنامه را متوقف می‌کنند؛ مدیران فایل‌سیستم در محدوده اعتماد باقی می‌مانند.

مجوز API یک توکن حمل‌کننده است. عملیات ورود به سیستم به صورت سریالی و با محدودیت زمانی هستند. بارگذاری‌ها در حساب کاربری از محدودیت اختصاصی ۱۲ مگابایت برای بدنه رمزگذاری‌شده و ۸ مگابایت برای فایل رمزگشایی‌شده استفاده می‌کنند؛ درخواست‌های عادی API به محدودیت ۱۶ کیلوبایت خود پایبند هستند. فرآیند تبدیل در یک نخ کاری (worker thread) اجرا می‌شود، بارگذاری‌ها را در حافظه نگه می‌دارد و ورودی نرمال‌شده را به مرورگر احراز هویت‌شده بازمی‌گرداند. ورود با QR دارای یک شناسه موقت به ازای هر فضای کاری، یک وظیفه منتظر (waiter task) و لغو صریح است. تنها مجوز پذیرفته‌شده به مشتری فعال تبدیل می‌شود. Telegram FloodWait با یک مقدار Retry-After بازگشته می‌شود؛ اعتبارنامه‌ها و پیام‌های خطای خام RPC در خطاهای API فاش نمی‌شوند. خروجی‌ها خارج از حلقه رویداد غیرهمزمان اجرا می‌شوند و به ازای هر فضای کاری سریالی‌سازی می‌شوند. آنها یک اسنپ‌شات خواندن پایدار را استریم می‌کنند و می‌توانند با نوشته‌های WAL در حال انجام هم‌زیست باشند. جمع‌کننده‌های فضای کاری حلقه فرآیند/رویداد را به اشتراک می‌گذارند.

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

برای توضیحات مربوط به اپراتور، [نحوه کارکرد جمع‌آوری](https://phishdestroy.github.io/TgWitness/fa/docs/reference/collection/) و [فرمت‌های حساب‌ها و جلسات](https://phishdestroy.github.io/TgWitness/fa/docs/reference/accounts/) را ببینید.

پیکربندی شبکه در گاوصندوق رمزگذاری‌شده نگهداری می‌شود. اعمال یک مسیر، کلاینت‌های قدیمی را می‌بندد و ورود ناکامل را لغو می‌کند؛ اتصالات بعدی از آن مسیر استفاده می‌کنند و به هیچ‌گونه بازگشت مستقیم (fallback) دسترسی ندارند. یک نصب جدید کلید خارجی، کلید فرنت (Fernet) هر فضای کاری را با HKDF-SHA256 از یک فایل کلید اصلی و یک شور تصادفی (salt) ذخیره‌شده استخراج می‌کند. این کار، اسرار را به‌طور جداگانه از دایرکتوری داده‌ها محافظت می‌کند، نه از محتوای متن ساده (plaintext) دفترچه یادداشت/رسانه‌ها.

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