# راهنمای استفاده تفصیلی

این راهنما جریان‌های کاری معمول رابط سطر فرمان (CLI) را پوشش می‌دهد. برای دستورالعمل‌های داکر به `docs/docker.md` و برای قالب‌های اعلامیه موجود به `docs/templates.md` مراجعه کنید.

## پیش‌نیازها

ووکس‌ورا (VoxVera) به گونه‌ای طراحی شده است که بسیار قابل حمل باشد و به حداقل وابستگی‌های سیستم نیاز داشته باشد.

### ۱. فایل‌های اجرایی مستقل (توصیه شده)
می‌توانید فایل‌های اجرایی (Binary) مستقل و بدون نیاز به وابستگی را برای سیستم‌عامل خود دانلود کنید:
- **لینوکس:** `voxvera-linux`
- **ویندوز:** `voxvera-windows.exe`
- **مک:** `voxvera-macos`

این فایل‌ها شامل تمام موارد لازم برای اجرای ووکس‌ورا هستند (به جز `onionshare-cli`).

### ۲. نصب‌کننده تک‌خطی
همچنین می‌توانید از طریق اسکریپت خودکار ما نصب را انجام دهید:

```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```

### ۳. نصب دستی پایتون
اگر ترجیح می‌دهید از سورس کد استفاده کنید:

```bash
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli   # دبیان/اوبونتو
```

## گام به گام

۱. **راه‌اندازی:** دستور `voxvera init` را اجرا کرده و مراحل را دنبال کنید. در ابتدا از شما خواسته می‌شود زبان خود را انتخاب کنید.
۲. **ساخت:** دارایی‌های اعلامیه را ایجاد کنید. هر بار که عملیات ساخت انجام می‌شود، یک فایل `voxvera-portable.zip` به طور خودکار در پوشه اعلامیه ساخته می‌شود که به دیگران اجازه می‌دهد ابزار کامل را مستقیماً از اعلامیه شما دانلود کنند.
   ```bash
   voxvera build
   ```
۳. **میزبانی:** اعلامیه را روی شبکه تور منتشر کنید:
   ```bash
   voxvera serve
   ```
   این دستور به طور خودکار تور شما را شناسایی کرده، OnionShare را راه‌اندازی می‌کند و آدرس .onion تولید شده را در پیوندهای جداشونده اعلامیه می‌نویسد.

## پشتیبانی از زبان‌ها

ووکس‌ورا کاملاً بومی‌سازی شده است. می‌توانید اولویت زبان خود را به طور دائم با استفاده از انتخاب‌گر تعاملی یا میان‌بر مستقیم تغییر دهید:

- **انتخاب‌گر تعاملی:** `voxvera lang`
- **میان‌بر مستقیم:** `voxvera --lang fa` (تنظیم اولویت روی فارسی)

### زبان‌های پشتیبانی شده:
- **انگلیسی:** `en`
- **اسپانیایی:** `es` (نام مستعار: `--idioma`)
- **آلمانی:** `de` (نام مستعار: `--sprache`)
- **فارسی:** `fa`

همچنین می‌توانید بدون تغییر اولویت دائمی، یک زبان خاص را برای یک دستور واحد اجبار کنید:
- **انگلیسی:** `voxvera --lang en check`
- **فارسی:** `voxvera --lang fa check`

اعلامیه‌های تولید شده به طور خودکار زبان مرورگر بازدیدکننده را تشخیص داده و متن رابط کاربری را بر اساس آن تغییر می‌دهند.

## مدیریت سرورها

چندین اعلامیه و هویت‌های تور آن‌ها را از یک منوی تعاملی واحد مدیریت کنید:

```bash
voxvera manage
```

ویژگی‌ها:
- **--- ایجاد سایت/اعلامیه جدید ---**: شروع توالی کامل تنظیمات.
- **--- اجرای همه سایت‌ها ---**: راه‌اندازی یا توقف همزمان تمام اعلامیه‌های شما.
- **وضعیت لحظه‌ای**: مشاهده آدرس‌های .onion فعال و نشانگرهای پیشرفت تور.
- **کنترل فردی**: صدور به صورت زیپ سایت‌های خاص به فرمت ZIP یا حذف آن‌ها.

## آینه‌سازی همگانی (توزیع ویروسی)

برای اطمینان از اینکه ووکس‌ورا حتی در صورت سانسور مخازن مرکزی در دسترس باقی می‌ماند، هر اعلامیه به عنوان یک آینه برای این ابزار عمل می‌کند.

وقتی اعلامیه‌ای را میزبانی می‌کنید، دکمه **"دانلود ابزار و کد منبع"** در صفحه فرود، یک فایل `voxvera-portable.zip` شامل موارد زیر ارائه می‌دهد:
- سورس کد کامل و تمامی زبان‌های پشتیبانی شده.
- تمامی وابستگی‌های پایتون (از پیش بسته‌بندی شده).
- فایل‌های اجرایی تور برای تمامی پلتفرم‌ها.

این کار به هر کسی که اعلامیه شما را اسکن می‌کند اجازه می‌دهد تا به توزیع‌کننده جدیدی برای ابزار ووکس‌ورا تبدیل شود.

## صدور و پشتیبان‌گیری

از هویت‌های تور منحصر به فرد خود پشتیبان بگیرید (تا آدرس .onion شما هرگز تغییر نکند) یا اعلامیه‌های خود را به سیستم دیگری منتقل کنید.

- **صدور یک سایت واحد:** `voxvera export <folder_name>`
- **صدور تمامی سایت‌ها:** `voxvera export-all`

**محل ذخیره‌سازی:** تمامی موارد صادر شده به صورت فایل ZIP در پوشه‌ای به نام `voxvera-exports` در پوشه خانگی کاربر (`~/voxvera-exports/`) در تمامی پلتفرم‌ها ذخیره می‌شوند.

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

با انتقال فایل‌های ZIP خود به پوشه `~/voxvera-exports/` و اجرای دستور زیر، کل تنظیمات خود را در یک سیستم جدید بازیابی کنید:

```bash
voxvera import-multiple
```

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

اگر نیاز دارید ووکس‌ورا را روی سیستمی بدون دسترسی به اینترنت اجرا کنید، می‌توانید ابتدا وابستگی‌ها را به صورت محلی ذخیره کنید:

```bash
voxvera vendorize
```

این دستور تمامی کتابخانه‌های پایتون مورد نیاز را در پوشه `voxvera/vendor/` دانلود می‌کند. ابزار سپس این فایل‌های محلی را در اولویت قرار می‌دهد و اجازه می‌دهد بدون نیاز به `pip install` اجرا شود.

## وارد کردن گروهی (JSON)

برای تولید انبوه اعلامیه‌ها از چندین فایل تنظیمات JSON، آن‌ها را در پوشه `imports/` قرار داده و اجرا کنید:

```bash
voxvera batch-import
```

## آدرس‌های URL چگونه کار می‌کنند

هر اعلامیه دارای دو آدرس URL جداگانه است:
- **پیوند جداشونده** (تولید خودکار): آدرس .onion که اعلامیه در آن میزبانی می‌شود.
- **پیوند محتوا** (تنظیم توسط کاربر): یک آدرس URL خارجی که به یک وب‌سایت، ویدیو یا فایل دانلود اشاره می‌کند.

نیازی نیست آدرس .onion را به صورت دستی وارد کنید؛ ووکس‌ورا در مرحله میزبانی (`serve`) این کار را به طور خودکار انجام می‌دهد.