# راه‌اندازی Canonical page: https://phishdestroy.github.io/TgWitness/fa/docs/reference/deployment/ TgWitness را به‌عنوان یک سرویس روی ویندوز، لینوکس، macOS یا Docker اجرا کنید، پشت HTTPS، همراه با پشتیبان‌گیری و به‌روزرسانی‌ها. **انگلیسی** · [روسی](https://github.com/phishdestroy/TgWitness/blob/main/docs/ru/DEPLOYMENT.md) · [اوکراینی](https://github.com/phishdestroy/TgWitness/blob/main/docs/uk/DEPLOYMENT.md) · [اسپانیایی](https://github.com/phishdestroy/TgWitness/blob/main/docs/es/DEPLOYMENT.md) · [پرتغالی (برزیل)](https://github.com/phishdestroy/TgWitness/blob/main/docs/pt/DEPLOYMENT.md) · [ترکی](https://github.com/phishdestroy/TgWitness/blob/main/docs/tr/DEPLOYMENT.md) · [عربی](https://github.com/phishdestroy/TgWitness/blob/main/docs/ar/DEPLOYMENT.md) · [فارسی](https://github.com/phishdestroy/TgWitness/blob/main/docs/fa/DEPLOYMENT.md) · [اردو](https://github.com/phishdestroy/TgWitness/blob/main/docs/ur/DEPLOYMENT.md) · [هندی](https://github.com/phishdestroy/TgWitness/blob/main/docs/hi/DEPLOYMENT.md) · [بهاسا اندونزی](https://github.com/phishdestroy/TgWitness/blob/main/docs/id/DEPLOYMENT.md) · [تایلندی](https://github.com/phishdestroy/TgWitness/blob/main/docs/vi/DEPLOYMENT.md) · [فونت ساده‌شدهٔ چینی](https://github.com/phishdestroy/TgWitness/blob/main/docs/zh/DEPLOYMENT.md) ## انتخاب نصب برای بسته قابل حمل، فایل `TgWitness--windows-amd64-portable.zip` را از GitHub Releases استخراج کنید. برای سایر روش‌ها، فایل ZIP منبع را دانلود و استخراج کنید یا مخزن را کلون کنید، سپس دستور زیر را از دایرکتوری پروژه اجرا کنید: | نصب | شروع | آیا در پس‌زمینه اجرا می‌شود؟ | | --- | --- | --- | | بسته قابل حمل ویندوز | `TgWitness.cmd` | نه؛ پنجره را باز نگه دارید. | | بومی ویندوز | `Start.cmd` | خیر؛ از وظیفهٔ اختیاری لاگین برای استفاده در پس‌زمینه استفاده کنید. | | بومی لینوکس/macOS | `sh start.sh` | خیر؛ برای استفاده در پس‌زمینه از systemd/launchd استفاده کنید. | | داکر روی هر میزبان پشتیبانی‌شده | `docker compose up -d --build --wait` | بله، در حالی که دیمون Docker در حال اجراست. | | راهنمای داکر در ویندوز | `scripts\Docker.cmd` | بله؛ دستیار منتظر سلامت وب‌سرور می‌ماند. | | راهنمای داکر در لینوکس/macOS | `sh scripts/docker-start.sh` | بله؛ دستیار منتظر سلامت وب‌سرور می‌ماند. | برای یک سرور ابری که شخص ثالث باید بتواند آن را بررسی کند — ایجاد شده از طریق API ارائه‌دهنده، بدون SSH، و تنها از طریق تونل کلودفلر قابل دسترسی است — به [استقرار با تضمین بالا](https://github.com/phishdestroy/TgWitness/blob/main/docs/HIGH-ASSURANCE.md) مراجعه کنید. راه‌اندازی بومی یک `.venv` خصوصی ایجاد می‌کند و وابستگی‌های پین‌شده را نصب می‌کند. داکر آن‌ها را داخل ایمیج می‌سازد، بدون اینکه به پایتون میزبان نیاز داشته باشد. راه‌اندازی اولیه نیاز به دسترسی به اینترنت دارد. هنگامی که هیچ Python 3.11+ یافت نشود، `Start.cmd` قبل از نصب Python 3.12 برای کاربر فعلی ویندوز (با استفاده از winget، در غیر این صورت با نصب‌کننده python.org پس از بررسی امضای بنیاد نرم‌افزار پایتون) سؤال می‌کند؛ این ابزار هرگز درخواست امتیازات ادمین نمی‌کند. Docker و سرویس‌های سیستم‌عامل همچنان از پیش‌نیازها هستند. نصب‌های بومی و قابل حمل از `data/live` در داخل پوشه خود استفاده می‌کنند. داکر از حجمی به نام `tgwitness-data` در `/data` استفاده می‌کند. این‌ها نصب‌های جداگانه‌ای هستند تا زمانی که شما عمداً دایرکتوری کامل داده را مهاجرت ندهید. انتظار نداشته باشید که یک کانتینر داکر جدید به طور خودکار حساب‌های بومی را کشف کند. ## نیازمندی‌های نصب نصب بومی به پایتون ۳.۱۱ یا جدیدتر با `venv` و `ensurepip`، دسترسی به اینترنت برای نصب اولین وابستگی، و یک دایرکتوری پروژه قابل نوشتن برای `.venv` نیاز دارد. پنل همراه نیازی به Node.js یا ساخت فرانت‌اند ندارد. لانچر را از حساب کاربری معمولی سیستم‌عامل خود اجرا کنید؛ TgWitness به امتیازات ادمین/روت نیاز ندارد. - **ویندوز:** `Start.cmd`، `py -3`، سپس `python` و سپس پوشه‌های نصب پیش‌فرض هر کاربر و Program Files را بررسی می‌کند و به نسخه ۳.۱۱ یا جدیدتر نیاز دارد. اگر هیچ‌کدام کار نکند، نصب خودکار بر اساس کاربر را که در بالا توضیح داده شد، ارائه می‌دهد. `py -3 start.py` نیز کار می‌کند. بسته قابل حمل به هیچ وجه به پایتون نیاز ندارد. - **لینوکس:** `start.sh` را امتحان می‌کند `python3.13`, `python3.12`, `python3.11`, `python3` و `python`, و زمانی که هیچ‌کدام مناسب نباشد، دستور نصب برای apt, dnf, pacman, zypper, apk یا Homebrew را چاپ می‌کند. نصب در دبیان/اوبونتو ممکن است به بسته `python3-venv` متناسب با تفسیرگر انتخاب‌شده نیاز داشته باشد. پایتون پیش‌فرض قدیمی‌تر توزیع باید با پایتون ۳.۱۱+ جایگزین یا تکمیل شود. - **macOS:** یک توزیعٔ جاریٔ Python 3.11+ را نصب کنید؛ فرض نکنید که یک مفسر ارائه‌شده توسط سیستم‌عامل این نیاز را برآورده می‌کند. از `python3 start.py` در دایرکتوری پروژه استفاده کنید. - **داکر:** از Docker Engine/Desktop با Compose نسخه 2.20 یا جدیدتر استفاده کنید. Docker Desktop باید از کانتینرهای لینوکس روی ویندوز استفاده کند. کانتینر وابستگی‌های پایتون خود را نصب می‌کند؛ میزبان نیازی به نصب جداگانه پایتون ندارد. از ذخیره‌سازی محلی پایدار برای دایرکتوری داده استفاده کنید. ظرفیت را بر اساس پیام‌ها، رسانه‌ها، رشد WAL، خروجی‌ها و پشتیبان‌ها برنامه‌ریزی کنید؛ هیچ مشخصات حداقلی جهانی مبتنی بر شواهد برای دیسک/RAM برای هر بار کاری وجود ندارد. معماری‌های CPU و نسخه‌های Python بدون چرخ‌های وابستگی سازگار ممکن است به ابزارهای ساخت اضافی و صلاحیت‌سنجی خاص خود نیاز داشته باشند. «قابل حمل» به معنای پشتیبانی جهانی از سیستم‌عامل یا سخت‌افزار نیست. ویندوز ۱۱/پایتون ۳.۱۲ به‌صورت محلی تأیید شده است. تعاریف لینوکس/macOS/کانتینر و CI ارائه شده‌اند اما روی این میزبان توسعه اجرا نشده‌اند. برای اطلاع از دامنه دقیق، به [فایل VERIFICATION.md](https://phishdestroy.github.io/TgWitness/fa/docs/reference/verification/) مراجعه کنید. ## کامپیوتر محلی از `Start.cmd` در ویندوز یا `sh start.sh` در لینوکس/مک‌او‌اس استفاده کنید. `scripts\Setup.cmd` یا `sh start.sh --setup-only` محیط را آماده می‌کند. لانچر در اولین استفاده وابستگی‌ها را نصب می‌کند؛ راه‌اندازی‌های بعدی از محیط موجود استفاده مجدد می‌کنند. برای راه‌اندازی و جمع‌آوری تلگرام به دسترسی به اینترنت نیاز است، اما مرور سوابق موجود و ایجاد خروجی‌ها به صورت آفلاین انجام می‌شود. پس از راه‌اندازی، دستور `python start.py --check` را اجرا کنید تا وابستگی‌های محلی، Ed25519، ذخیره‌سازی، پیکربندی کلید و آدرس گوش‌دادن را بدون راه‌اندازی یک گردآورنده بررسی کنید. برای خروجی ساختاریافته از `--json` استفاده کنید. پارامترهای مورد نظر `--data-dir`، `--host` و `--port` را ارسال کنید. این بررسی، بسته‌ها را نصب، دفترچه یادداشتی ایجاد یا تلگرام را متصل نمی‌کند؛ این یک گواهی یکپارچگی یا پوشش نیست. دستور شروع به صورت جداگانه دفترچه‌های یادداشت موجود را تأیید می‌کند. `python start.py --help` نیز از نصب جلوگیری می‌کند. گزینه‌ها: پس از استفاده از start.py، دستورات کمکی را با `.venv\Scripts\python.exe` در ویندوز یا `.venv/bin/python` در لینوکس/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، در صورت ارائه، باید حاوی حداقل ۲۴ کاراکتر باشد؛ از یک مقدار تصادفی و رمزنگاری‌شده استفاده کنید. بدون آن، برنامه یک توکن تصادفی ۲۵۶ بیتی در فایل panel-token.txt ایجاد می‌کند. نابودی محیطی آن فایل را بازنویسی نمی‌کند. برای چرخاندن اعتبارنامه‌ها، برنامه را مجدداً راه‌اندازی کنید. دقیقاً یک فرآیند می‌تواند مالک یک دایرکتوری داده باشد. یک قفل فایل سیستم‌عاملی چندسکویی از نوشتار همزمان تصادفی جلوگیری می‌کند. از یک کارگر Uvicorn استفاده کنید. پنل می‌تواند هر تعداد فضای کاری را مدیریت کند، با دایرکتوری‌های فضای کاری اضافی در زیر profiles//. برای نمونه‌های مجزای سرویس، از دایرکتوری‌ها و پورت‌های مجزا استفاده کنید. فایل‌های WAL در SQLite باید در حافظه دائمی محلی ذخیره شوند، نه در یک سیستم فایل شبکه‌ای. یک حجم را بین نسخه‌ها (replicas) مشترک نکنید. ## بسته قابل حمل ویندوز هر نسخه گیت‌هاب حاوی `TgWitness--windows-amd64-portable.zip` و `.sha256` آن است. این نسخه شامل محیط اجرایی رسمی و قابل جاسازی پایتون ۳.۱۲ از python.org (با چک‌سام ثابت‌شده در `tools/build_portable.py`)، TgWitness و وابستگی‌های ثابت‌شده آن، و سه لانچر است: | فایل | هدف | | --- | --- | | `TgWitness.cmd` | پنل را راه‌اندازی کنید؛ گزینه‌های اضافی ارسال می‌شوند، مثلاً `TgWitness.cmd --port 8790` | | `TgWitness-Demo.cmd` | دموی مصنوعی را در `data\demo` آغاز کنید | | `TgWitness-Check.cmd` | بدون راه‌اندازی، بررسی آمادگی را اجرا کنید | کل آرشیو را در یک پوشه قابل نوشتن مانند `Documents\TgWitness` استخراج کنید؛ آن را از داخل فایل ZIP یا پوشه Program Files اجرا نکنید. محیط اجرای برنامه از یک مسیر ماژول ایزوله استفاده می‌کند، بنابراین نصب‌های دیگر پایتون و `PYTHONPATH` بر آن تأثیری ندارند. داده‌ها در پوشه `data` این بسته باقی می‌مانند. برای به‌روزرسانی، TgWitness را متوقف کنید، نسخه جدید را در یک پوشه جدید استخراج کرده و پوشه `data` را کپی کنید. خودتان آن را روی ویندوز ۶۴ بیتی با پایتون ۳.۱۲ بسازید: ``` python tools/build_portable.py ``` سازنده، چک‌سام زمان اجرا را تأیید می‌کند، وابستگی‌های محدود را در بسته نصب می‌کند، بررسی آمادگی را با مفسر تعبیه‌شده اجرا می‌کند و فایل ZIP و چک‌سام را در `dist/` می‌نویسد. ## کانتینر ``` docker compose up -d --build --wait ``` این کار یک حجم دائمی با نام برای /data ایجاد می‌کند. پورت وب به 127.0.0.1:8787 نگاشت شده است. این فرآیند با UID 10001 و با قابلیت‌های محدودشده، یک سیستم فایل ریشه فقط-خواندنی، و دایرکتوری‌های قابل نوشتن /data و /tmp اجرا می‌شود. `--wait` قبل از بازگشت، سلامت وب‌سرور را بررسی می‌کند؛ این ابزار هیچ‌گونه تأیید اعتبار یا تحویل پیام تلگرام را انجام نمی‌دهد. کمک‌کننده‌های ارائه‌شده پس از ساخت، از یک تایم‌اوت آمادگی ۱۸۰ ثانیه‌ای استفاده می‌کنند. دانلودهای وابستگی اولیه ممکن است بیشتر از این زمان طول بکشد. هر دو فایل پایه 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 daemon، گردآورنده را مجدداً راه‌اندازی می‌کند. در یک سرور لینوکس، Docker را با استفاده از مدیر سرویس توزیع خود، که معمولاً `sudo systemctl enable --now docker` است، در هنگام بوت فعال کنید. در ویندوز/macOS، گزینه «شروع به محض ورود» (start-at-sign-in) در Docker Desktop را فعال کنید. خروج از حساب کاربری دسکتاپ، حالت خواب، یا یک وضعیت متوقف‌شده دمون داکر می‌تواند فرآیند جمع‌آوری را قطع کند. یک کانتینر که به صراحت متوقف شده باشد، تا زمانی که آن را دوباره راه‌اندازی نکنید، متوقف باقی می‌ماند. حجم /tmp در پیکربندی نمونه به ۵۱۲ مگابایت محدود شده است. ساخت خروجی به جای آن از فضای `temporary-exports/` هر workspace روی /data دائمی استفاده می‌کند. فضایی را در آنجا برای خروجی‌های همزمان، رشد ژورنال/WAL، رسانه‌ها و پشتیبان‌ها رزرو کنید. راه‌انداز از deploy/constraints.txt برای ثابت کردن نسخه‌های وابستگی زمان اجرا استفاده می‌کند. داکر و سرورهای با تضمین بالا از روی deploy/requirements.lock و deploy/build.lock با pip --require-hashes نصب می‌شوند: هر فایل پکیج باید با یک رکورد SHA-256 که در کامیت ثبت شده مطابقت داشته باشد، بنابراین جایگزینی یک فایل در PyPI یا یک آینه‌ی دیگر رد می‌شود. تصویر پایه پایتون و بسته‌های سیستم‌عامل همچنان به تأیید مستقل نسخه نیاز دارند. از دستور docker compose down -v استفاده نکنید، مگر اینکه قصد دارید دفترچه شواهد و کلیدها را نابود کنید. گزارش وضعیت کانتینر، در دسترس بودن وب‌سرور را نشان می‌دهد، نه ضبط موفقیت‌آمیز تلگرام. وضعیت کالکتور پنل، ضربان قلب، خطاها و رویدادهای پوشش را بررسی کنید. ### پروفایل شاهد مستقل سرویس اختیاری `witness` یک [شاهد مستقل](https://phishdestroy.github.io/TgWitness/fa/docs/reference/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/` برای یک فضای کاری دیگر). برای یک شاهد روی سرور جداگانه که توسط شخص دیگری اجرا می‌شود، از `deploy/compose/compose.witness.yaml` در آنجا استفاده کنید و `TGWITNESS_WITNESS_COLLECTOR` را روی آدرس HTTPS کالکتور تنظیم کنید؛ آن فایل فقط شامل شاهد است. ## نصب یک تصویر منتشرشده این قابلیت پس از یک [گردش کار انتشار](https://phishdestroy.github.io/TgWitness/fa/docs/reference/deployment/#automated-github-releases) موفق و پیکربندی بسته عمومی 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 ``` نیازی به نصب سورس، پایتون یا کامپایلر روی میزبان نیست. گردش کار انتشار، کانتینرهای لینوکس AMD64 و ARM64، از جمله ماشین مجازی لینوکس Docker Desktop را هدف قرار می‌دهد. از یک تگ نسخه یا `ghcr.io/owner/repository@sha256:...` از خلاصه گردش کار استفاده کنید. هیچ تگ متحرک `latest` یا ارتقای خودکار برنامه پیکربندی نشده است. نسخه‌های image و source هنگامی که نام پروژه آنها یکسان باشد، از همان حجم داده استفاده می‌کنند. ## HTTPS خودکار روی یک سرور از یک سرور با داکر، دامنه‌ای که شما کنترل می‌کنید، و ذخیره‌سازی محلی پایدار استفاده کنید. رکوردهای 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` را برای دستورات وضعیت، لاگ، به‌روزرسانی و توقف بعدی نگه دارید. کدی گواهی‌نامه را دریافت و تمدید می‌کند، HTTP را به HTTPS هدایت مجدد می‌کند و درخواست‌ها را به جمع‌آورنده در شبکه خصوصی Compose فوروارد می‌کند. وضعیت گواهی‌نامه دارای حجم پایدار خود است. پورت میزبان مستقیم جمع‌آورنده فقط برای لوپ‌بک باقی می‌ماند. پیکربندی ارائه‌شده کدی، ثبت دسترسی را فعال نمی‌کند. `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` خود دنبال می‌شود. فراخوانی (Pull) آن تصویر را تازه می‌کند؛ اگر به نسخه‌های ثابت زیرساخت نیاز دارید، یک هش آزمایش‌شده را در استقرار خود پین کنید. ## به‌روزرسانی‌ها و پشتیبان‌گیری‌ها حفظ نام پروژه Compose و حجم داده‌ها در طول به‌روزرسانی‌ها. ابتدا گردآورنده را متوقف کرده و یک نسخه پشتیبان کامل تهیه کنید. برای استقرار پیش‌فرض مبتنی بر منبع: ``` docker compose stop docker compose cp tgwitness:/data ../tgwitness-backup-before-update ``` هر بار از یک مقصد پشتیبان جدید، خارج از مخزن، استفاده کنید و آن را به عنوان ماده قابل دسترسی با حساب کاربری محافظت کنید. مسیر مثال صرفاً جهت نمایش است؛ از مکان پشتیبان خصوصی خود استفاده کنید. کل دایرکتوری، از جمله فایل‌های پنهان، تمام فضاهای کاری، کلیدها، ژورنال‌ها و رسانه‌ها را کپی کنید. در صورت پیکربندی، کلید اصلی گاوصندوق خارجی را به طور جداگانه پشتیبان‌گیری کنید. یک فایل ZIP مدرک، یک نسخه پشتیبان قابل بازیابی از برنامه نیست. برای HTTPS، همچنین در صورتی که نیاز به حفظ وضعیت گواهی/حساب دارید، حجم‌های Caddy را نیز حفظ کنید. برای استقرار در محیط تولید، فایل‌های نسخه جدید را تهیه کرده و اجرا کنید: ``` docker compose up -d --build --wait ``` برای استقرار با استفاده از image، `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` را بین سیستم‌عامل‌ها یا نسخه‌های پایتون کپی نکنید. برای به‌روزرسانی نصب مستقیم، TgWitness را متوقف کنید، از تمام پوشهٔ دادهٔ آن نسخهٔ پشتیبان بگیرید، فایل‌های کد منبع را جایگزین کنید و پیش از اجرا فرمان `python start.py --setup-only` را اجرا کنید. دسترسی پنل، هویت حساب، وضعیت مشاهده و پوشش را پس از یک به‌روزرسانی بررسی کنید. راه‌اندازی مجدد، به‌روزرسانی‌های از دست رفته تلگرام را بازسازی نمی‌کند. در صورتی که یک نسخه آینده فرمت‌های ذخیره‌سازی را تغییر دهد، بازگشت به نسخه قبلی ممکن است به نسخه پشتیبان پیش از به‌روزرسانی نیاز داشته باشد. ## انتشارهای خودکار گیت‌هاب [روند انتشار](https://github.com/phishdestroy/TgWitness/blob/main/.github/workflows/release.yml) پس از ارسال این پروژه به یک مخزن گیت‌هاب با اکشن‌های فعال، آماده استفاده است. این روند هنگام **انتشار** یک نسخه گیت‌هاب، از جمله نسخه‌های پیش‌انتشار، اجرا می‌شود. پیش‌نویس‌ها و ارسال تگ‌ها به تنهایی، بسته‌ها را منتشر نمی‌کنند. 1. نسخهٔ بسته و گزارش تغییرات را تنظیم کنید، سپس یک نسخه را با برچسب `v` منتشر کنید به‌علاوه نسخهٔ دقیق `pyproject.toml`، مانند `v0.7.0`. 2. جریان کاری تگ را اعتبارسنجی می‌کند و بررسی‌های مشترک پایتون ویندوز/لینوکس/macOS، مرورگر QR عمومی/واردات حساب، بستهٔ منبع و داکر را اجرا می‌کند. نصب بومی تازه نیز روی هر سه سیستم‌عامل با استفاده از پایتون ۳.۱۲ انجام می‌شود. 3. پس از موفقیت این بررسی‌ها، یک ایمیج ARM64 را تحت QEMU به صورت تست دودی اجرا می‌کند، ایمیج‌های AMD64/ARM64 را در `ghcr.io//:` منتشر می‌نماید و فایل ZIP منبع، چک‌سام و چرخ (wheel) پایتون را به نسخه منتشرشده ضمیمه می‌کند. یک وظیفه جداگانه در ویندوز، فایل ZIP قابل حمل و چک‌سام آن را ساخته و ضمیمه می‌نماید. 4. پس از اولین انتشار، تنظیمات بسته GHCR را باز کرده و در صورتی که قصد دریافت تصاویر ناشناس را دارید، گزینه «Visibility» را روی **«Public»** تنظیم کنید. یک مخزن سورس عمومی به تنهایی انتشار یک بسته کانتینری عمومی را تضمین نمی‌کند. سیاست‌های سازمان باید انتشار بسته را مجاز بدانند. این گردش کار از `GITHUB_TOKEN` استفاده می‌کند؛ هیچ رمز عبور رجیستری یا اعتبارنامه‌های VPS نباید در مخزن قرار داده شوند. موفقیت گردش کار از راه دور با این آماده‌سازی محلی تضمین نشده است. شبیه‌سازی ARM64 یک بررسی مقدماتی است، نه صلاحیت سخت‌افزار بومی یا تلگرام زنده. این کار بسته‌بندی نسخه را خودکار می‌کند؛ راه‌اندازی یک سرور همچنان به دستور Compose و پیش‌نیازهای دامنه/میزبان آن نیاز دارد. سرورها موجود هنگام انتشار یک نسخه به‌صورت بی‌صدا ارتقا یا مجدداً راه‌اندازی نمی‌شوند. ## سرور از راه دور سرویس را محدود به لوپ‌بک نگه دارید و از تونل SSH استفاده کنید، یا HTTPS را در یک پروکسی معکوس پایان دهید. فایل پایه Compose فقط برای استفاده محلی است؛ لایه اختیاری `deploy/compose/compose.https.yaml`، Caddy را برای یک دامنه پیکربندی‌شده فراهم می‌کند. توکن حامل را از URLها و لاگ‌های پروکسی دور نگه دارید. یک پروکسی معکوس باید اندازه درخواست و نرخ اتصال را محدود کند. HTTP ساده را در معرض اینترنت قرار ندهید. نمونه‌هایی برای systemd، یک وظیفه ورود به سیستم ویندوز، یک عامل کاربری macOS و Caddy در [پوشه deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md) ارائه شده‌اند. مسیرهای آن‌ها را قبل از نصب بررسی/تطبیق دهید. آن‌ها قالب‌هایی هستند که ارائه شده‌اند، نه واجد شرایط بودن پلتفرم که به صورت محلی اجرا شوند. هیچ سرویس یا وظیفه پس‌زمینه‌ای توسط راه‌انداز عادی ثبت نمی‌شود. در ویندوز، اجرای بدون پنجره `pythonw.exe`، تشخیص‌های راه‌اندازی/سرور را در `logs/server.log` زیر دایرکتوری داده (۵ مگابایت برای هر فایل، دو نسخه پشتیبان چرخشی) ذخیره می‌کند. اجرای کنسول، ثبت کنسول را حفظ می‌کند. ثبت دسترسی HTTP در هر دو حالت غیرفعال است. لاگ‌ها را با دایرکتوری داده محافظت کرده و قبل از اشتراک‌گذاری آنها را بررسی کنید. ## راه‌اندازی مجدد و فواصل آخرین وضعیت مشاهده‌ی درخواستی حفظ می‌شود. اگر مشاهده فعال بود، راه‌اندازی مجدد تلاش می‌کند تا منابع انتخاب‌شده را دوباره متصل کرده و از سر بگیرد. توقف دستی آن نیت را لغو می‌کند. یک راه‌اندازی مجدد ناموفق ثبت شده و در پنل نمایش داده می‌شود. StringSession مجوز را حفظ می‌کند اما وضعیت پایدار به‌روزرسانی/واحد تل‌هون را نه. دیالوگ‌ها در هنگام راه‌اندازی مجدد بارگذاری می‌شوند. تلگرام/تل‌هون می‌تواند برخی از وقفه‌های ارتباطی را در حین اجرا بازیابی کند، اما TgWitness ادعای بازپخش پایدار در سراسر راه‌اندازی مجدد فرآیندها را ندارد. هر بار راه‌اندازی، سرآیند ژورنال قبلی و مرز آفلاین را ثبت می‌کند. نظارتگر هر ۱۰ ثانیه اتصال را بررسی می‌کند و هر دقیقه یک تپش قلب اضافه می‌کند (**پارامترها → رکورد زنده بودن هر بار**). وقفه های کوتاه ممکن است از دست بروند؛ یک انتقال متصل، تحویل کامل به‌روزرسانی را تضمین نمی‌کند. اسنپ‌شات‌ها مشاهدات صریح تاریخچه فعلی هستند، نه ترمیم شکاف. صف رسانه در پایگاه داده SQLite هر فضای کاری ذخیره می‌شود. یک پیام و کار آن به‌صورت اتمیک ثبت می‌شوند. کارهای در حال اجرا که متوقف شده‌اند، در شروع مجدد برای تلاش دوباره بازیابی می‌شوند. هر دانلود دارای یک زمان انتظار پایه ۱۲۰ ثانیه‌ای به علاوه زمان لازم با سرعت ۲۵۶ کیلوبایت بر ثانیه برای اندازه‌اش، و یک محدودیت ۱ تا ۲۰۰۰ مگابایت برای هر نوع پیوست است؛ زمان انتظار، سرعت و تلاش‌های مجدد در **بخش پارامترها** قرار دارند. گردآورنده فایل‌هایی را که اندازه‌شان نامشخص است نادیده می‌گیرد. توقف، کارهای صف‌شده را حفظ می‌کند. امکان تکرار دانلود از توصیف‌گر فایل مشاهده‌شده اصلی استفاده می‌کند، نه از آخرین نسخه یک پیام که بعداً ویرایش شده است. خطاهای موقت دارای تعداد تکرار محدودی هستند؛ توقف حالت FloodWait رسانه‌ای پس از راه‌اندازی مجدد نیز ادامه می‌یابد. بازیابی رسانه از بازیابی به‌روزرسانی تلگرام جداست و نمی‌تواند فایل‌های ناپدیدشده را بازسازی کند. ## پشتیبان‌گیری، بازیابی و ظرفیت فرآیند را قبل از کپی کردن **کل دایرکتوری داده**، شامل vault.key، signing.enc، credentials.enc، فایل‌های پایگاه داده/WAL SQLite، رسانه، توکن، نقاط کنترل، و تمام پروفایل‌ها/زیرپوشه‌ها متوقف کنید. نسخه کامل را در حالی که سرویس مقصد متوقف شده است، بازیابی کنید. کلیدهای گنجینه (vault keys) گم‌شده یا عدم تطابق کلید امضا (signing-key) باعث عدم راه‌اندازی می‌شود؛ برای دسترسی اجباری، کلیدها را دوباره تولید نکنید. نسخه‌های پشتیبان مخفی را رمزگذاری‌شده و با کنترل دسترسی نگه دارید. فایل‌های فشرده مدرک قابل حمل هستند؛ بر روی آثار بررسی کنید، نه نسخه‌های پشتیبان اپلیکیشن یا نسخه‌های پشتیبان جلسه تلگرام. هیچ حذف خودکار مبتنی بر نگهداری وجود ندارد. فضای دیسک را برای تمام پیام‌ها، متادیتای خام، رسانه‌ها، خروجی‌های موقت و نسخه‌های پشتیبان برنامه‌ریزی کنید. تأیید راه‌اندازی و خروجی گرفتن سوابق جریان به جای بارگذاری کل دفترچه. یک خروجی، یک نمای کلی خواندنی را ثابت می‌کند در حالی که نوشته‌های جدید WAL می‌توانند ادامه یابند؛ خروجی‌های طولانی‌مدت می‌توانند صفحات WAL را حفظ کنند، بنابراین ظرفیت دیسک همچنان اهمیت دارد. فایل‌های ZIP به ۴ گیگابایت بدون فشرده‌سازی محدود می‌شوند تا با پیش‌فرض اعتبارسنج مستقل مطابقت داشته باشند؛ **پارامترها → بزرگترین ZIP امضا شده** محدودیت را افزایش می‌دهد، و چنین آرشیوهایی با `verify.py --max-gib N` تأیید می‌شوند. سایر فرمت‌ها محدودیت تعداد رویداد ندارند. مرورگرهای پشتیبانی‌شده، بلوک‌های پاسخ را به فایلی که کاربر انتخاب کرده است، استریم می‌کنند. سایر مرورگرها حداکثر ۱۲۸ مگابایت (MiB) را در بافر نگه می‌دارند و انتقال‌های بزرگتر را به CLI احراز هویت‌شده هدایت می‌کنند: ``` python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip ``` برای یک فضای کاری دیگر از `--profile ID` در **بخش «صادرات → شناسه فضای کاری» (Exports → Workspace ID)**، برای یک سرور راه دور از `--format zip|jsonl|csv|html`، `--url https://your-server`، یا برای تغییر محدودیت انتقال ۵ گیگابایتی از `--max-mib` استفاده کنید. HTTP ساده فقط برای لوپ‌بک مجاز است. توکن‌ها در هدرها جابجا می‌شوند، هدایت‌ها (redirects) رد می‌شوند، فایل‌های موجود بازنویسی نمی‌شوند و دانلودهای ناقص به عنوان فایل‌های کامل منتشر نمی‌شوند. اگر TGWITNESS_TOKEN توکن تولید شده را بازنویسی کند، از یک فایل جداگانه محافظت‌شده که حاوی آن مقدار فعال است استفاده کنید: panel-token.txt توسط این بازنویسی دوباره نوشته نمی‌شود. SHA-256 دستور فقط یک چک‌سام انتقال است؛ فایل ZIP امضا شده را به طور مستقل تأیید کنید. فایل‌های خروجی سرور در داخل فضای خصوصی هر workspace در `temporary-exports/` باقی می‌مانند. پاسخ‌های موفق فایل‌های خود را پاک می‌کنند. خروجی‌گیری‌های متوقف‌شده در شروع به کار بعدی فضای کاری، با قفل نمونه انحصاری خود، حذف می‌شوند. این دایرکتوری بخشی از مدل تهدید/ظرفیت ذخیره‌سازی است؛ از یک حجم داده رمزگذاری‌شده استفاده کنید. انتقال‌های چند گیگابایتی در مقیاس تولید همچنان به اعتبارسنجی روی سیستم مقصد شما نیاز دارند. پنل، رسانه‌های صف‌شده/ناموفق، قدیمی‌ترین رسانه در انتظار، فضای آزاد دیسک، مکث‌های درخواست تلگرام و منابعی را که دسترسی‌شان تأیید نشده است، نمایش می‌دهد. این تشخیص‌ها یک مانیتور تحویل کامل از ابتدا تا انتها نیستند. فضاهای کاری یک فرآیند را به اشتراک می‌گذارند؛ یک حساب پر سر و صدا همچنان می‌تواند بر دیگران تأثیر بگذارد. فرآیندهای کارگر جداگانه، نگهداری/گردش، بازیابی به‌روزرسانی پایدار و صلاحیت کامل استقرار همچنان باقی می‌مانند. دسترسی محدود به پنل در [بخش دسترسی و مجوزها](https://phishdestroy.github.io/TgWitness/fa/docs/reference/access/) مستندسازی شده است؛ نقاط کنترل مستقل در [راهنمای شاهد](https://phishdestroy.github.io/TgWitness/fa/docs/reference/witness/) پوشش داده شده‌اند. ## گزینه‌های اتصال و محافظت مسیرهای اتصال به ازای هر فضای کاری هستند و باید قبل از اعطای مجوز پیکربندی شوند. SOCKS5/HTTP CONNECT از وابستگی ثابت python-socks استفاده می‌کنند. MTProxy از حمل‌ونقل واسط تصادفی آزمایشی Telethon استفاده می‌کند؛ رازهای TLS جعلی پشتیبانی نمی‌شوند. بازگشت مستقیم به مسیر پشتیبان به [حالت IP](https://phishdestroy.github.io/TgWitness/fa/docs/reference/connection/#ip-modes) انتخاب‌شده بستگی دارد: حالت «پنهان کردن IP» (Hide IP) آن را رد می‌کند؛ حالت صریح بازگشت به پشتیبان پس از یک تأخیر آن را مجاز می‌سازد. حالت تونل/VPN مسیرهای مستقیم را مجاز می‌کند اما VPN ایجاد نمی‌کند. این یک سیاست شبکه در سطح کل سیستم نیست. برای نصب‌های جدید، TGWITNESS_VAULT_KEY_FILE به یک فایل کلید اصلی تصادفی اشاره می‌کند که به طور جداگانه محافظت می‌شود. آن را به صورت فقط-خواندنی خارج از /data در یک کانتینر مونت کنید. متادیتای نمک public vault.external.json را به همراه هر فضای کاری و کلید اصلی به صورت جداگانه حفظ کنید. گنجینه‌های محلی موجود به یک مهاجرت برنامه‌ریزی‌شده نیاز دارند؛ تنظیم این متغیر آنها را به صورت خودکار و بی‌صدا تبدیل نمی‌کند. ذخیره‌سازی و صادرات پیام/رسانه به صورت رمزگذاری‌شده توسط برنامه نیست. از حجم‌های رمزگذاری‌شده و ذخیره‌سازی موقت خصوصی کافی در صورت لزوم استفاده کنید. روندهای دقیق: [اتصال/امنیت](https://phishdestroy.github.io/TgWitness/fa/docs/reference/connection/) و [حالت‌های عملیاتی](https://phishdestroy.github.io/TgWitness/fa/docs/reference/operations/).