Skip to main content

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

Если сервер бота находится в сети, где доступ к api.telegram.org ограничен или заблокирован, весь трафик к Telegram Bot API можно маршрутизировать через SOCKS5 прокси-сервер. При настройке PROXY_URL все обращения бота к Telegram API проходят через указанный прокси — основной бот, уведомления, платёжные инвойсы, webhook-хендлеры и Cabinet API.

​
Настройка

Добавьте в .env файл: 
# Без авторизации
PROXY_URL=socks5://proxy-host:1080

# С авторизацией
PROXY_URL=socks5://username:password@proxy-host:1080
Перезапустите бот для применения настроек.
Поддерживаются только SOCKS5, SOCKS5h и SOCKS4 протоколы. HTTP/HTTPS прокси не поддерживаются — при их использовании токен бота передаётся в URL запроса и может быть перехвачен прокси-сервером.

​
Параметры

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

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

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

​
Формат URL

socks5://[username:password@]host:port
Примеры: 
# Локальный прокси (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 инвойсов идёт через прокси
  • Отправка рассылок, опросов и тикетов идёт через прокси
Учётные данные прокси маскируются в логах при старте бота — вместо socks5://user:pass@host:port в лог попадёт socks5://***@host:port.

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

Если у вас есть SSH-доступ к серверу с незаблокированным доступом к Telegram, можно быстро поднять SOCKS5 прокси через SSH-туннель: 
# На сервере бота: создать SOCKS5 туннель через удалённый сервер
ssh -D 1080 -f -N -q user@remote-server.com

PROXY_URL=socks5://127.0.0.1:1080
SSH-туннель подходит для тестирования. Для продакшена рекомендуется использовать выделенный SOCKS5 прокси-сервер (например, Dante, 3proxy) или VPN.

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

После запуска бота с настроенным PROXY_URL в логах появится: 
[info] Proxy configured proxy_url=socks5://***@proxy-host:1080
Если прокси недоступен, бот не сможет подключиться к Telegram API и в логах будет ошибка соединения.

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

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

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

Если NALOGO_PROXY_URL не задан, трафик к nalog.ru автоматически пойдёт через PROXY_URL: 
# Один прокси для Telegram API и nalog.ru
PROXY_URL=socks5://proxy-host:1080

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

Для Telegram API и nalog.ru можно использовать разные прокси-серверы: 
# Прокси для Telegram API
PROXY_URL=socks5://telegram-proxy:1080

# Отдельный прокси для nalog.ru (в РФ)
NALOGO_PROXY_URL=socks5h://russia-proxy:1080
Для nalog.ru рекомендуется схема socks5h:// — DNS-резолвинг выполняется на стороне прокси-сервера, что важно когда lknpd.nalog.ru не резолвится с вашего сервера.

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

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