> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedolagam.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# SOCKS5 прокси

> Настройка проксирования трафика бота к Telegram API через SOCKS5

## Зачем нужен прокси

Если сервер бота находится в сети, где доступ к `api.telegram.org` ограничен или заблокирован, весь трафик к Telegram Bot API можно маршрутизировать через SOCKS5 прокси-сервер.

При настройке `PROXY_URL` **все** обращения бота к Telegram API проходят через указанный прокси — основной бот, уведомления, платёжные инвойсы, webhook-хендлеры и Cabinet API.

## Настройка

Добавьте в `.env` файл:

```env theme={null}
# Без авторизации
PROXY_URL=socks5://proxy-host:1080

# С авторизацией
PROXY_URL=socks5://username:password@proxy-host:1080
```

Перезапустите бот для применения настроек.

<Warning>
  Поддерживаются только SOCKS5, SOCKS5h и SOCKS4 протоколы. HTTP/HTTPS прокси **не поддерживаются** — при их использовании токен бота передаётся в URL запроса и может быть перехвачен прокси-сервером.
</Warning>

## Параметры

| Переменная         | Описание                                                                 | По умолчанию |
| ------------------ | ------------------------------------------------------------------------ | ------------ |
| `PROXY_URL`        | URL SOCKS прокси для Telegram API                                        | —            |
| `NALOGO_PROXY_URL` | URL SOCKS прокси для nalog.ru (если не задан — используется `PROXY_URL`) | —            |

### Поддерживаемые схемы

| Схема        | Описание                           |
| ------------ | ---------------------------------- |
| `socks5://`  | SOCKS5 прокси (рекомендуется)      |
| `socks5h://` | SOCKS5 с удалённым DNS-резолвингом |
| `socks4://`  | SOCKS4 прокси                      |

### Формат URL

```
socks5://[username:password@]host:port
```

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

```env theme={null}
# Локальный прокси (SSH-туннель)
PROXY_URL=socks5://127.0.0.1:1080

# Удалённый прокси с авторизацией
PROXY_URL=socks5://user:pass@proxy.example.com:1080

# SOCKS4
PROXY_URL=socks4://proxy.example.com:1080
```

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

Бот использует централизованную фабричную функцию `create_bot()` для создания всех экземпляров `Bot`. Если `PROXY_URL` задан, каждый экземпляр получает `AiohttpSession` с SOCKS5-проксированием через библиотеку `aiohttp-socks`.

Это гарантирует, что:

* Основной бот (polling/webhook) работает через прокси
* Уведомления пользователям и администраторам идут через прокси
* Создание Telegram Stars инвойсов идёт через прокси
* Отправка рассылок, опросов и тикетов идёт через прокси

<Info>
  Учётные данные прокси маскируются в логах при старте бота — вместо `socks5://user:pass@host:port` в лог попадёт `socks5://***@host:port`.
</Info>

## Быстрая проверка через SSH

Если у вас есть SSH-доступ к серверу с незаблокированным доступом к Telegram, можно быстро поднять SOCKS5 прокси через SSH-туннель:

```bash theme={null}
# На сервере бота: создать SOCKS5 туннель через удалённый сервер
ssh -D 1080 -f -N -q user@remote-server.com
```

```env theme={null}
PROXY_URL=socks5://127.0.0.1:1080
```

<Note>
  SSH-туннель подходит для тестирования. Для продакшена рекомендуется использовать выделенный SOCKS5 прокси-сервер (например, [Dante](https://www.inet.no/dante/), [3proxy](https://github.com/3proxy/3proxy)) или VPN.
</Note>

## Проверка работоспособности

После запуска бота с настроенным `PROXY_URL` в логах появится:

```
[info] Proxy configured proxy_url=socks5://***@proxy-host:1080
```

Если прокси недоступен, бот не сможет подключиться к Telegram API и в логах будет ошибка соединения.

## Прокси для nalog.ru

Если включена интеграция с [NaloGO](/bot/nalogo-setup) (фискальные чеки ФНС), трафик к `lknpd.nalog.ru` также можно маршрутизировать через SOCKS-прокси.

### Единый прокси для всего

Если `NALOGO_PROXY_URL` не задан, трафик к nalog.ru автоматически пойдёт через `PROXY_URL`:

```env theme={null}
# Один прокси для Telegram API и nalog.ru
PROXY_URL=socks5://proxy-host:1080
```

### Раздельные прокси

Для Telegram API и nalog.ru можно использовать разные прокси-серверы:

```env theme={null}
# Прокси для Telegram API
PROXY_URL=socks5://telegram-proxy:1080

# Отдельный прокси для nalog.ru (в РФ)
NALOGO_PROXY_URL=socks5h://russia-proxy:1080
```

<Info>
  Для nalog.ru рекомендуется схема `socks5h://` — DNS-резолвинг выполняется на стороне прокси-сервера, что важно когда `lknpd.nalog.ru` не резолвится с вашего сервера.
</Info>

## Ограничения

* Telegram Login Widget (OIDC JWKS) на странице входа Cabinet обращается к `oauth.telegram.org` напрямую, без прокси. Это не влияет на безопасность — в этом запросе не передаётся токен бота.
* При смене `PROXY_URL` требуется перезапуск бота.