# Подробное руководство

Это руководство охватывает основные рабочие процессы CLI. См. `docs/docker.md` для инструкций по Docker и `docs/templates.md` для доступных шаблонов листовок.

## Предварительные требования

VoxVera разработан как высокопортативный инструмент и требует минимум системных зависимостей.

### 1. Автономные бинарные файлы (Рекомендуется)
Вы можете скачать автономные исполняемые файлы без зависимостей для вашей операционной системы:
- **Linux:** `voxvera-linux`
- **Windows:** `voxvera-windows.exe`
- **macOS:** `voxvera-macos`

Эти файлы включают все необходимое для запуска VoxVera (кроме `onionshare-cli`).

### 2. Однострочный установщик
Или установите с помощью нашего автоматического скрипта:

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

### 3. Ручная установка через Python
Если вы предпочитаете запускать из исходного кода:

```bash
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli   # Debian/Ubuntu
```

## Шаг за шагом

1. **Инициализация:** Запустите `voxvera init` и следуйте подсказкам. Вам будет предложено сначала выбрать язык.
2. **Сборка:** Сгенерируйте ресурсы листовки. Каждая сборка автоматически создает файл `voxvera-portable.zip` в папке листовки, позволяя другим скачивать полный инструмент прямо с вашей листовки.
   ```bash
   voxvera build
   ```
3. **Запуск:** Опубликуйте листовку через Tor:
   ```bash
   voxvera serve
   ```
   Это автоматически обнаружит ваш экземпляр Tor, запустит OnionShare и запишет сгенерированный .onion адрес в отрывные ссылки листовки.

## Поддержка языков

VoxVera полностью локализован. Вы можете изменить свои языковые предпочтения навсегда, используя интерактивный селектор или прямой ярлык:

- **Интерактивный селектор:** `voxvera lang`
- **Прямой ярлык:** `voxvera --lang ru` (устанавливает русский язык)

### Поддерживаемые языки:
- **Английский:** `en`
- **Испанский:** `es` (алиас: `--idioma`)
- **Немецкий:** `de` (алиас: `--sprache`)
- **Русский:** `ru`

Вы также можете принудительно использовать определенный язык для одной команды, не меняя постоянные настройки:
- **Английский:** `voxvera --lang en check`
- **Русский:** `voxvera --lang ru check`

Сгенерированные листовки автоматически определяют язык браузера посетителя и соответствующим образом переключают текст интерфейса.

## Управление серверами

Управляйте несколькими листовками и их Tor-идентификаторами из единого интерактивного меню:

```bash
voxvera manage
```

Возможности:
- **--- Создать новый сайт/листовку ---**: Запуск полной последовательности настройки.
- **--- Запустить все сайты ---**: Запуск или остановка всех листовок в вашем парке одновременно.
- **Статус в реальном времени**: Просмотр активных .onion URL и индикаторов прогресса загрузки Tor.
- **Индивидуальный контроль**: Экспорт в Zip определенных сайтов в ZIP или их удаление.

## Универсальное зеркалирование (Вирусное распространение)

Чтобы VoxVera оставался доступным, даже если центральные репозитории будут подвергнуты цензуре, каждая листовка выступает в качестве зеркала для инструмента.

Когда вы хостите листовку, кнопка **"Скачать инструмент и код"** на целевой странице предоставляет `voxvera-portable.zip`, содержащий:
- Полный исходный код и все поддерживаемые языки.
- Все зависимости Python (пре-вендоризованные).
- Кроссплатформенные бинарные файлы Tor.

Это позволяет любому, кто сканирует вашу листовку, стать новым распространителем инструмента VoxVera.

## Экспорт и резервное копирование

Создавайте резервные копии своих уникальных Tor-идентификаторов (чтобы ваш .onion URL никогда не менялся) или переносите листовки на другую машину.

- **Экспорт одного сайта**: `voxvera export <имя_папки>`
- **Экспорт всех сайтов**: `voxvera export-all`

**Место хранения:** Все экспорты сохраняются в виде ZIP-файлов в папке `voxvera-exports` в домашнем каталоге пользователя (`~/voxvera-exports/`) на всех платформах.

## Импорт и восстановление

Восстановите всю свою настройку на новой машине, переместив ZIP-файлы в `~/voxvera-exports/` и запустив:

```bash
voxvera import-multiple
```

## Портативность и работа оффлайн

Если вам нужно запустить VoxVera на машине без доступа к Интернету, вы можете сначала «вендоризовать» зависимости:

```bash
voxvera vendorize
```

Это загрузит все необходимые библиотеки Python в `voxvera/vendor/`. Инструмент будет отдавать приоритет этим локальным файлам, что позволит ему работать без `pip install`.

## Пакетный импорт (JSON)

Чтобы массово генерировать листовки из нескольких конфигурационных файлов JSON, поместите их в директорию `imports/` и запустите:

```bash
voxvera batch-import
```

## Как работают URL-адреса

У каждой листовки есть два отдельных URL-адреса:
- **Отрывная ссылка** (автоматически генерируется): .onion адрес, по которому размещена листовка.
- **Ссылка на контент** (настраивается пользователем): Внешний URL, указывающий на веб-сайт, видео или загрузку.

Вам не нужно вручную вводить .onion адрес; VoxVera обрабатывает это автоматически на этапе `serve`.