# Telegram · راه‌اندازی

Canonical page: https://phishdestroy.io/tgwitness/fa/docs/reference/deployment/

TgWitness را به‌عنوان یک سرویس روی ویندوز، لینوکس، macOS یا Docker اجرا کنید، پشت HTTPS، همراه با پشتیبان‌گیری و به‌روزرسانی‌ها.

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/fa/llms.txt)

TgWitness را به‌عنوان یک سرویس روی ویندوز، لینوکس، macOS یا Docker اجرا کنید، پشت HTTPS، همراه با پشتیبان‌گیری و به‌روزرسانی‌ها.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [مستندسازی](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![راه‌اندازی و بازیابی](https://phishdestroy.io/tgwitness/assets/chapter-operate.svg?v=7039a376d47f)

**انگلیسی** · [روسی](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-<version>-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://phishdestroy.io/tgwitness/fa/docs/reference/high-assurance/) مراجعه کنید.

راه‌اندازی بومی یک `.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 باید از کانتینرهای لینوکس روی ویندوز استفاده کند. کانتینر وابستگی‌های پایتون خود را نصب می‌کند؛ میزبان نیازی به نصب جداگانه پایتون ندارد.

## کامپیوتر محلی

از `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 حالت کلید خارجی را برای نصب جدید انتخاب می‌کند؛ به [کلید اصلی خارجی](https://phishdestroy.io/tgwitness/fa/docs/reference/security/#external-master-key) مراجعه کنید. TGWITNESS_TOKEN، در صورت ارائه، باید حاوی حداقل 24 کاراکتر باشد؛ از یک مقدار تصادفی و رمزنگاری‌شده استفاده کنید. بدون آن، برنامه یک توکن تصادفی 256 بیتی در فایل panel-token.txt تولید می‌کند. تعریف مجدد محیطی، آن فایل را بازنویسی نمی‌کند. برای چرخاندن اعتبارنامه‌ها، برنامه را مجدداً راه‌اندازی کنید.

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

## بسته قابل حمل ویندوز

هر نسخه گیت‌هاب حاوی `TgWitness-<version>-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` | بدون راه‌اندازی، بررسی آمادگی را اجرا کنید |

واژه‌نامه مورفولوژی روسی سنجاق‌شده و پروفایل‌های رنگی PDF برای استفاده آفلاین بسته‌بندی شده‌اند. بسته‌بندی تنها مسیرهای فایل شناخته‌شده آن‌ها را در دایرکتوری‌های وابستگی `data` مجاز می‌داند؛ فایل‌های غیرمنتظره در آن دایرکتوری‌ها باعث شکست ساخت می‌شوند.

کل آرشیو را در یک پوشه قابل نوشتن مانند `Documents\TgWitness` استخراج کنید؛ آن را از داخل فایل ZIP یا پوشه Program Files اجرا نکنید. محیط اجرای برنامه از یک مسیر ماژول ایزوله استفاده می‌کند، بنابراین نصب‌های دیگر پایتون و `PYTHONPATH` بر آن تأثیری ندارند. داده‌ها در پوشه `data` این بسته باقی می‌مانند. برای به‌روزرسانی، TgWitness را متوقف کنید، نسخه جدید را در یک پوشه جدید استخراج کرده و پوشه `data` را کپی کنید.

خودتان آن را روی ویندوز ۶۴ بیتی با پایتون ۳.۱۲ بسازید:

```
python tools/build_portable.py
```

## کانتینر

```
docker compose up -d --build --wait
```

این کار یک حجم پایدار نام‌گذاری‌شده برای /data ایجاد می‌کند. پورت وب به 127.0.0.1:8787 نگاشت می‌شود. این فرآیند با UID 10001 و با قابلیت‌های محدودشده، یک سیستم فایل ریشه فقط-خواندنی، و دایرکتوری‌های قابل نوشتن /data و /tmp اجرا می‌شود. پارامتر `--wait` قبل از بازگشت، سلامت وب‌سرور را بررسی می‌کند؛ مجوزدهی و تحویل تلگرام در پنل نمایش داده می‌شوند. ابزارهای کمکی ارائه‌شده پس از ساخت، از یک تایم‌اوت آمادگی 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 daemon، گردآورنده را مجدداً راه‌اندازی می‌کند. در یک سرور لینوکس، Docker را با استفاده از مدیر سرویس توزیع خود، که معمولاً `sudo systemctl enable --now docker` است، در هنگام بوت فعال کنید. در ویندوز/macOS، گزینه «شروع به محض ورود» (start-at-sign-in) در Docker Desktop را فعال کنید. خروج از حساب کاربری دسکتاپ، حالت خواب، یا یک وضعیت متوقف‌شده دمون داکر می‌تواند فرآیند جمع‌آوری را قطع کند. یک کانتینر که به صراحت متوقف شده باشد، تا زمانی که آن را دوباره راه‌اندازی نکنید، متوقف باقی می‌ماند.

حجم /tmp در پیکربندی نمونه به ۵۱۲ مگابایت محدود شده است. ساخت export به جای آن از پوشه `temporary-exports/` در هر workspace روی فضای پایدار /data استفاده می‌کند. فضایی را در آنجا برای exportهای همزمان، رشد journal/WAL، رسانه‌ها و پشتیبان‌ها رزرو کنید. راه‌انداز از فایل deploy/constraints.txt برای ثابت کردن نسخه‌های وابستگی‌های زمان اجرا (runtime) واجد شرایط استفاده می‌کند. داکر و سرورهای با تضمین بالا از deploy/requirements.lock و deploy/build.lock با pip --require-hashes نصب می‌شوند: هر فایل بسته باید با یک رکورد SHA-256 که در کامیت ثبت شده مطابقت داشته باشد، بنابراین جایگزینی یک فایل در PyPI یا یک آینه‌بان رد می‌شود. پکیج‌هایی که فقط سورس را ارائه می‌کنند (jieba, pyaes) با setuptools پین‌شده در deploy/build.lock (`--no-build-isolation`) توسط لانچر، سازنده قابل حمل ویندوز و Dockerfile ساخته می‌شوند، بنابراین pip یک محیط ساخت جداگانه و بدون پین را حل نمی‌کند. تصویر پایه پایتون و بسته‌های سیستم‌عامل همچنان به تأیید مستقل نسخه نیاز دارند.

از دستور docker compose down -v استفاده نکنید، مگر اینکه قصد دارید دفترچه شواهد و کلیدها را نابود کنید. گزارش وضعیت کانتینر، در دسترس بودن وب‌سرور را نشان می‌دهد، نه ضبط موفقیت‌آمیز تلگرام. وضعیت کالکتور پنل، ضربان قلب، خطاها و رویدادهای پوشش را بررسی کنید.

### پروفایل شاهد مستقل

سرویس اختیاری `witness` یک [شاهد مستقل](https://phishdestroy.io/tgwitness/fa/docs/reference/witness/)را در کانتینر خود، با کلید و ژورنال مخصوص به خود در حجم `witness-data` اجرا می‌کند و فقط یک توکن شاهد فقط-خواندنی برای گردآورنده فراهم می‌آورد. توکن را در پنل زیر **More tools → Extras → Independent 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 کالکتور تنظیم کنید؛ آن فایل فقط شامل شاهد است.

## نصب یک تصویر منتشرشده

محتویات `deploy/env.example` را به `.env` کپی کنید. `TGWITNESS_IMAGE` را با استفاده از نسخه منتشرشده و مسیر مخزن **با حروف کوچک** تنظیم کنید، برای مثال:

```
TGWITNESS_IMAGE=ghcr.io/your-owner/your-repository:0.9.3
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` را باز کنید و توکن پنل را وارد کنید. آماده‌سازی شامل کانتینرها می‌شود؛ صدور گواهی‌نامه و دسترسی خارجی به DNS و فایروال بستگی دارد. اگر 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` را اجرا کنید.

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

## سرور از راه دور

سرویس را محدود به لوپ‌بک نگه دارید و از تونل 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 در هر دو حالت غیرفعال است. لاگ‌ها را با دایرکتوری داده محافظت کرده و قبل از اشتراک‌گذاری آنها را بررسی کنید.

## راه‌اندازی مجدد و فواصل

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

TgWitness موقعیت به‌روزرسانی تلگرام را برای حساب کاربری و برای هر کانال (pts, qts, seq و تاریخ) در گاوصندوق فضای کاری ذخیره می‌کند و در شروع بعدی آن را بازیابی می‌کند. سپس کلاینت، به‌روزرسانی‌های از دست رفته در زمانی که فرآیند متوقف بود را درخواست می‌کند و بازبینی دوره‌ای، پیام‌های از دست رفته را بازیابی کرده و پیام‌های ضبط‌شده‌ای را که تلگرام دیگر بازنمی‌گرداند، ثبت می‌کند. دیالوگ‌ها در هنگام شروع دوباره بارگذاری می‌شوند. هر بار راه‌اندازی، سرآیند ژورنال قبلی، مرز آفلاین و موقعیت به‌روزرسانی که از آن از سر گرفته شده را ثبت می‌کند. مانیتور هر 10 ثانیه اتصال را بررسی می‌کند و هر دقیقه یک ضربه قلب (heartbeat) اضافه می‌کند (**ابزارهای بیشتر → پارامترها → ثبت زنده هر**). قطع اتصالات و دوره‌های بی‌صدا به عنوان شکاف‌های پوشش به همراه دلیلشان ثبت می‌شوند. اسنپ‌شات‌های تاریخچه به عنوان مشاهدات جداگانه تاریخچه-جاری در کنار رکوردهای زنده ذخیره می‌شوند.

صف رسانه در پایگاه داده SQLite هر فضای کاری ذخیره می‌شود. یک پیام و وظیفه آن به‌صورت اتمی commit می‌شوند. وظایف در حال اجرا که متوقف شده‌اند برای اجرا مجدد در هنگام راه‌اندازی بازیابی می‌شوند. هر دانلود دارای یک زمان‌انتظار پایه 120 ثانیه‌ای به‌علاوه زمان لازم با سرعت 256 کیلوبایت بر ثانیه برای اندازه‌اش است، و یک محدودیت 1 تا 2,000 مگابایت برای هر نوع پیوست؛ تایم‌اوت، سرعت و تلاش‌های مجدد در بخش **ابزارهای بیشتر → پارامترها** قرار دارند. جمع‌کننده فایل‌هایی را که اندازه‌شان نامشخص است نادیده می‌گیرد. توقف، کارهای صف‌شده را حفظ می‌کند. تلاش مجدد از دسکتریپتور فایل اصلی مشاهده‌شده استفاده می‌کند، نه هرگز از آخرین نسخه یک پیام که بعداً ویرایش شده است. خطاهای موقت تلاش‌های مجدد محدودی دارند؛ توقف‌های حالت سیل (FloodWait) رسانه پس از راه‌اندازی مجدد نیز ادامه می‌یابند. بازیابی رسانه از بازیابی به‌روزرسانی تلگرام جدا است و نمی‌تواند فایل‌های ناپدیدشده را بازسازی کند.

## پشتیبان‌گیری، بازیابی و ظرفیت

پوشه `tgwitness backup FOLDER` در حالی که پنل همچنان در حال اجراست، از دایرکتوری داده کپی می‌گیرد: ابتدا چک‌پوینت‌ها، سپس فایل‌های SQLite از طریق API پشتیبان آنلاین، و در ادامه کلیدها، رسانه‌ها و پروفایل‌ها، بنابراین هیچ چک‌پوینت کپی‌شده‌ای جدیدتر از ژورنال کپی‌شده نیست. فایل `backup-manifest.json` ، SHA-256 هر فایل و سرهای ژورنال را فهرست می‌کند. برای بازیابی، TgWitness را متوقف کرده و کل دایرکتوری داده را با آن پوشه جایگزین کنید. راه‌اندازی بعدی ثبت می‌کند که ژورنال از یک نسخه قدیمی‌تر بازیابی شده است. این رکورد، ژورنال را با هد (سر) موجود در `TGWITNESS_STATE_DIR` ، پوشه‌ای خارج از دایرکتوری داده، مقایسه می‌کند: حجم `tgwitness-state` در برای Compose، در واحدهای systemd، `/var/lib/tgwitness-state` و در غیر این صورت پوشه وضعیت محلی کاربر. بدون یک پوشه وضعیت قابل نوشتن، بازیابی تشخیص داده نمی‌شود و لاگ یک بار این موضوع را اعلام می‌کند.

بدون این دستور، قبل از کپی کردن **کل دایرکتوری داده**، شامل vault.key، signing.enc، credentials.enc، پایگاه داده SQLite/فایل‌های WAL، media، token، checkpoints و تمام پروفایل‌ها/زیرپوشه‌ها، فرآیند را متوقف کنید. نسخه کامل را در حالی که سرویس مقصد متوقف شده است، بازیابی کنید. کلیدهای vault گم‌شده یا عدم تطابق signing-key باعث عدم موفقیت در راه‌اندازی می‌شوند؛ برای دسترسی اجباری، کلیدها را دوباره تولید نکنید.

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

تأیید راه‌اندازی و ثبت سوابق جریان خروجی به جای بارگذاری کل دفترچه. یک خروجی، یک نمای خواندنی را ثابت نگه می‌دارد در حالی که نوشتن‌های جدید WAL می‌توانند ادامه یابند؛ خروجی‌های طولانی‌مدت می‌توانند صفحات WAL را حفظ کنند، بنابراین ظرفیت دیسک همچنان اهمیت دارد. فایل‌های ZIP به ۴ گیگابایت (4) محدود شده‌اند تا با مقدار پیش‌فرض اعتبارسنج مستقل مطابقت داشته باشند؛ **ابزارهای بیشتر → پارامترها → بزرگترین فایل ZIP امضا شده (Largest signed ZIP**) محدودیت را افزایش می‌دهد، و چنین آرشیوهایی با دستور `verify.py --max-gib N` اعتبارسنجی می‌شوند. سایر فرمت‌ها محدودیت تعداد رویداد ندارند. مرورگرهای پشتیبانی‌شده، بلوک‌های پاسخ را به فایلی که کاربر انتخاب کرده است، استریم می‌کنند. سایر مرورگرها حداکثر ۱۲۸ مگابایت (128) بافر می‌کنند و انتقال‌های بزرگتر را به 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 امضا شده را به طور مستقل تأیید کنید.

پنل، رسانه‌های صف‌شده/ناموفق، قدیمی‌ترین رسانه در انتظار، فضای آزاد دیسک، مکث‌های درخواست تلگرام و منابعی را که دسترسی‌شان تأیید نشده است، نمایش می‌دهد. این تشخیص‌ها یک مانیتور تحویل کامل از ابتدا تا انتها نیستند. فضاهای کاری یک فرآیند را به اشتراک می‌گذارند؛ یک حساب پر سر و صدا همچنان می‌تواند بر دیگران تأثیر بگذارد. فرآیندهای کارگر جداگانه، نگهداری/گردش، بازیابی به‌روزرسانی پایدار و صلاحیت کامل استقرار همچنان باقی می‌مانند. دسترسی محدود به پنل در [بخش دسترسی و مجوزها](https://phishdestroy.io/tgwitness/fa/docs/reference/access/) مستندسازی شده است؛ نقاط کنترل مستقل در [راهنمای شاهد](https://phishdestroy.io/tgwitness/fa/docs/reference/witness/) پوشش داده شده‌اند.

روندهای دقیق: [اتصال/امنیت](https://phishdestroy.io/tgwitness/fa/docs/reference/connection/) و [حالت‌های عملیاتی](https://phishdestroy.io/tgwitness/fa/docs/reference/operations/).
