> [!CAUTION]
>
> ### Реакция антивирусов
>
> Windows Defender часто ошибочно помечает приложение как **Wacatac**.  
> Если вы не можете скачать из-за блокировки, то:
>
> 1) Попробуйте скачать версию win7 (она ничем не отличается в плане функционала)
> 2) Отключите антивирус на время скачивания, добавьте файл в исключения и включите обратно  
>
> **Всегда проверяйте, что скачиваете из интернета, тем более из непроверенных источников. Всегда лучше смотреть на детекты широко известных антивирусов на VirusTotal**

# TG WS Proxy

**Локальный SOCKS5-прокси** для Telegram Desktop, который **ускоряет работу Telegram**, перенаправляя трафик через WebSocket-соединения. Данные передаются в том же зашифрованном виде, а для работы не нужны сторонние сервера.

## Как это работает

```
Telegram Desktop → SOCKS5 (127.0.0.1:1080) → TG WS Proxy → WSS → Telegram DC
```

1. Приложение поднимает локальный SOCKS5-прокси на `127.0.0.1:1080`
2. Перехватывает подключения к IP-адресам Telegram
3. Извлекает DC ID из MTProto obfuscation init-пакета
4. Устанавливает WebSocket (TLS) соединение к соответствующему DC через домены Telegram
5. Если WS недоступен (302 redirect) — автоматически переключается на прямое TCP-соединение

## 🚀 Быстрый старт

### Установка из исходников (консольный прокси)

Для запуска только SOCKS5/WebSocket proxy без графического интерфейса достаточно базовой установки:

```bash
pip install -e .
tg-ws-proxy
```

### Консольный режим из исходников

```bash
tg-ws-proxy [--port PORT] [--host HOST] [--dc-ip DC:IP ...] [-v]
```

**Аргументы:**

| Аргумент | По умолчанию | Описание |
|---|---|---|
| `--port` | `1080` | Порт SOCKS5-прокси |
| `--host` | `127.0.0.1` | Хост для bind |
| `--bind-mode` | `local` | Режим работы: local (127.0.0.1), network (0.0.0.0), internet (0.0.0.0) |
| `--dc-ip` | `2:149.154.167.220 4:149.154.167.220` | IP адреса для DC в формате "DC:IP" |
| `--log-level` | `INFO` | Уровень логирования: DEBUG, INFO, WARNING, ERROR, CRITICAL |
| `--quiet` | `false` | Отключить логирование |
| `--log-file` | `None` | Путь к файлу логов |
| `--log-max-mb` | `100` | Максимальный размер файла логов в MB |
| `--log-backups` | `3` | Количество backup файлов логов |
| `--buf-kb` | `256` | Размер буфера сокета в KB |
| `--pool-size` | `4` | Размер пула WS соединений на DC |
| `--host` | `127.0.0.1` | Хост SOCKS5-прокси |
| `--dc-ip` | `2:149.154.167.220`, `4:149.154.167.220` | Целевой IP для DC (можно указать несколько раз) |
| `-v`, `--verbose` | выкл. | Подробное логирование (DEBUG) |

**Примеры:**

```bash
# Стандартный запуск
tg-ws-proxy

# Другой порт и дополнительные DC
tg-ws-proxy --port 9050 --dc-ip 1:149.154.175.205 --dc-ip 2:149.154.167.220

# С подробным логированием
tg-ws-proxy -v
```

## Настройка Telegram Desktop

### Вручную

1. Telegram → **Настройки** → **Продвинутые настройки** → **Тип подключения** → **Прокси**
2. Добавить прокси:
   - **Тип:** SOCKS5
   - **Сервер:** `127.0.0.1`
   - **Порт:** `1080` (или другой порт, указанный при запуске)
   - **Логин/Пароль:** оставить пустыми

## Конфигурация через переменные окружения

Прокси поддерживает конфигурацию через переменные окружения, что удобно для Docker и CI/CD окружений.

### Доступные переменные окружения

| Переменная | По умолчанию | Описание |
|---|---|---|
| `TG_WS_PROXY_HOST` | `0.0.0.0` | Хост для bind |
| `TG_WS_PROXY_PORT` | `1080` | Порт SOCKS5-прокси |
| `TG_WS_PROXY_LOGGER` | `true` | Включить логирование (true/false) |
| `TG_WS_PROXY_LOG_LEVEL` | `INFO` | Уровень логирования |
| `TG_WS_PROXY_LOG_FILE` | (пусто) | Путь к файлу логов |
| `TG_WS_PROXY_LOG_MAX_MB` | `100` | Макс. размер файла логов в MB |
| `TG_WS_PROXY_LOG_BACKUPS` | `3` | Количество backup файлов |
| `TG_WS_PROXY_BIND_MODE` | `network` | Режим работы: `local`, `network`, `internet` |
| `TG_WS_PROXY_DC_IPS` | `2:149.154.167.220 4:149.154.167.220` | IP адреса DC |
| `TG_WS_PROXY_BUF_KB` | `256` | Размер буфера сокета в KB |
| `TG_WS_PROXY_POOL_SIZE` | `4` | Размер пула WS соединений |

### Режимы работы (BIND_MODE)

- **`local`** - только локальный доступ (`127.0.0.1`)
- **`network`** - доступ в локальной сети (`0.0.0.0`)
- **`internet`** - доступ из интернета (`0.0.0.0`) - используйте с firewall

### Пример использования

```bash
# Установка переменных окружения
export TG_WS_PROXY_PORT=9050
export TG_WS_PROXY_BIND_MODE=local
export TG_WS_PROXY_LOGGER=false

# Запуск с переменными окружения
tg-ws-proxy

# Или с .env файлом
cp .env.example .env
# редактируем .env
tg-ws-proxy
```

## Docker

### Запуск через Docker

```bash
# Сборка образа
docker build -t tg-ws-proxy .

# Запуск с настройками по умолчанию
docker run -d --name tg-proxy -p 1080:1080 tg-ws-proxy

# Запуск с кастомными настройками
docker run -d \
  --name tg-proxy \
  -p 9050:9050 \
  -e TG_WS_PROXY_PORT=9050 \
  -e TG_WS_PROXY_BIND_MODE=network \
  -e TG_WS_PROXY_LOGGER=true \
  -e TG_WS_PROXY_LOG_LEVEL=DEBUG \
  tg-ws-proxy
```

### Docker Compose

```yaml
version: '3.8'
services:
  tg-ws-proxy:
    build: .
    ports:
      - "1080:1080"
    environment:
      - TG_WS_PROXY_PORT=1080
      - TG_WS_PROXY_BIND_MODE=network
      - TG_WS_PROXY_LOGGER=true
      - TG_WS_PROXY_LOG_LEVEL=INFO
    restart: unless-stopped
```

### Coolify / PaaS

При развертывании в Coolify или других PaaS платформах, просто установите переменные окружения в настройках приложения. Все переменные, начинающиеся с `TG_WS_PROXY_`, будут автоматически применены.

## Конфигурация через аргументы командной строки

Прокси также поддерживает конфигурацию через аргументы командной строки (имеют приоритет над переменными окружения).

## Автоматическая сборка

Проект содержит спецификации PyInstaller ([`packaging/windows.spec`](packaging/windows.spec), [`packaging/macos.spec`](packaging/macos.spec), [`packaging/linux.spec`](packaging/linux.spec)) и GitHub Actions workflow ([`.github/workflows/build.yml`](.github/workflows/build.yml)) для автоматической сборки.

Минимально поддерживаемые версии ОС для текущих бинарных сборок:

- Windows 10+ для `TgWsProxy_windows.exe`
- Windows 7 (x64) для `TgWsProxy_windows_7_64bit.exe`
- Windows 7 (x32) для `TgWsProxy_windows_7_32bit.exe`
- Intel macOS 10.15+
- Apple Silicon macOS 11.0+
- Linux x86_64

## Лицензия

[MIT License](LICENSE)
