Skip to content

Прокси для исходящей доставки ​

Этот документ — про один вопрос: как отправлять уведомления, когда провайдер недоступен из сети, где работает сервис. Заблокированный мессенджер, egress только через один аудируемый хоп, закрытый наружу кластер — с точки зрения доставки это одно и то же.

Без прокси такое уведомление ведёт себя предсказуемо плохо: падает на установке соединения, уходит в retry, исчерпывает попытки и попадает в dead letter. То есть алерт не доходит вообще, а в timeline это выглядит как проблема на стороне провайдера.

Настраивается переменными окружения, как и остальные креды доставки. Это осознанно: одно решение на инсталляцию, оно живёт там же, где описан деплой, а не в базе и не в UI. Ни миграций, ни объектов, ни отдельных прав.

Переменные ​

ПеременнаяЧто задаёт
NXS_ANOMALY_DELIVERY_PROXY_URLПрокси по умолчанию для всех каналов доставки
NXS_ANOMALY_DELIVERY_PROXY_<CHANNEL>_URLПереопределение для одного канала
NXS_ANOMALY_DELIVERY_NO_PROXYХосты, к которым всегда ходим напрямую

<CHANNEL> — один из: TELEGRAM, SLACK, MATTERMOST, WEBHOOK, CHATOPS, MOBILE, ISSUE, EMAIL, CALL. Канал log транспорта не имеет и в списке отсутствует.

Значение direct (синонимы none, off) выключает прокси для конкретного канала, когда задан общий. Пустое значение = «наследовать общий».

NXS_ANOMALY_DELIVERY_NO_PROXY — синтаксис NO_PROXY: через запятую точные хосты и домены, домен покрывает поддомены (.corp.example и corp.example эквивалентны и оба матчат api.corp.example), * — всё.

Переменные читаются один раз при старте, и API, и worker должны получить одинаковый набор: доставку выполняет worker, но тестовое уведомление и ответы на нажатия кнопок Telegram уходят из API.

Схемы ​

СхемаПрименимость
http, httpsHTTP-каналы. HTTPS-назначения идут через CONNECT
socks5, socks5hHTTP-каналы и не-HTTP каналы email (SMTP), call (Asterisk AMI)
tcpПрозрачный TCP-релей (HAProxy mode tcp). Все каналы, включая email и call — см. ниже

Логин и пароль — в самом URL: socks5://user:pass@tunnel.internal:1080. Порт по умолчанию: 80 для http, 443 для https, 1080 для обеих SOCKS-схем. Для tcp порта по умолчанию нет — его задаёт тот, кто поднял релей, и угадывать его значило бы вернуть ошибку соединения вместо ответа.

Прозрачный релей (tcp://) — HAProxy в режиме mode tcp ​

Самый частый способ обойти блокировку — не прокси, а голый TCP-релей на внешней машине:

haproxy
frontend telegram_api
    bind *:443
    mode tcp
    default_backend telegram_api_backend

backend telegram_api_backend
    mode tcp
    server telegram api.telegram.org:443 check

Такой хоп не говорит ни на одном прокси-протоколе: ни CONNECT, ни SOCKS-рукопожатия, и TLS он не терминирует — просто перекладывает байты в свой единственный бэкенд. Поэтому схема tcp:// меняет ровно одно: адрес, куда открывается сокет.

bash
NXS_ANOMALY_DELIVERY_PROXY_TELEGRAM_URL='tcp://relay.example.com:443'

Всё остальное остаётся адресом провайдера — путь запроса, заголовок Host, SNI и проверка сертификата. TLS-сессия устанавливается сквозь релей до настоящего api.telegram.org, и сертификат проверяется против него, а не против релея. Отключать проверку не нужно и не следует: релею нечего предъявить, он ничего не расшифровывает.

Релей слеп к назначению. Он отправляет в свой бэкенд всё, что в него пришло, независимо от того, куда адресован запрос. Это подходит каналу с фиксированным хостом провайдера (telegram, slack, mattermost, mobile). Для каналов, чей адрес пишут в цепочке эскалации — webhook, issue, chatops, — при старте пишется предупреждение delivery_proxy_relay_on_variable_destination: все назначения такого канала уедут на один и тот же сервер. Это предупреждение, а не запрет: единственный внутренний приёмник — законная конфигурация.

Релей несёт email и call. В отличие от HTTP-прокси, он работает ниже протокола, поэтому SMTP и AMI через него проходят так же, как через SOCKS5. NO_PROXY при этом сохраняет смысл: перечисленный хост набирается напрямую по имени, а не уходит в бэкенд релея.

socks5 и socks5h здесь ведут себя одинаково: имя хоста провайдера всегда разрешает прокси, а не сервис. Это не упрощение, а требование задачи: сеть, которая блокирует провайдера, обычно портит и его DNS, и локальный резолв в такой сети ломает доставку раньше, чем начнётся соединение.

Типовые конфигурации ​

Заблокированы только мессенджеры, всё остальное ходит напрямую:

bash
NXS_ANOMALY_DELIVERY_PROXY_TELEGRAM_URL='socks5://tunnel.internal:1080'
NXS_ANOMALY_DELIVERY_PROXY_SLACK_URL='socks5://tunnel.internal:1080'

Наружу только через egress-прокси, внутренний приёмник — напрямую:

bash
NXS_ANOMALY_DELIVERY_PROXY_URL='http://egress.internal:3128'
NXS_ANOMALY_DELIVERY_NO_PROXY='receiver.internal,.corp.example'

То же, но для канала webhook прокси не нужен вовсе:

bash
NXS_ANOMALY_DELIVERY_PROXY_URL='http://egress.internal:3128'
NXS_ANOMALY_DELIVERY_PROXY_WEBHOOK_URL='direct'

Прокси с паролем — переменная с секретом, поэтому в Kubernetes она кладётся в Secret приложения, а не в ConfigMap (см. ниже про чарт):

bash
NXS_ANOMALY_DELIVERY_PROXY_URL='socks5://svc:s3cret@tunnel.internal:1080'

Helm ​

yaml
deliveryProxy:
  url: "http://egress.internal:3128"
  channels:
    telegram: "socks5://tunnel.internal:1080"
    webhook: "direct"
  noProxy: "receiver.internal,.corp.example"

Секция рендерится в общий ConfigMap, поэтому его читает и API, и worker. URL с паролем чарт отвергает при рендере — ConfigMap доступен любому, у кого есть get в namespace, и тихо опубликовать там кредо прокси хуже, чем упасть. Такой URL задаётся в Secret приложения под тем же именем переменной: Secret подключается после ConfigMap и перекрывает его.

Egress к прокси в NetworkPolicy чарта уже разрешён — под доставки и так ходит во внешнюю сеть.

Что происходит по каналам ​

КаналЧерез что идёт
telegramapi.telegram.org, включая ответы на нажатия inline-кнопок
slack, mattermostincoming webhook платформы
webhookадрес из шага TRIGGER_WEBHOOK или цели уведомления
chatopswebhook_url ChatOps-канала
mobilepush-relay оператора (NXS_ANOMALY_MOBILE_PUSH_URL)
issueRedmine или generic-трекер из шага цепочки
emailSMTP-сервер — только SOCKS5
callAsterisk AMI, порт 5038 — только SOCKS5

Через прокси канала webhook идёт также dead-letter-уведомление (NXS_ANOMALY_DEAD_LETTER_WEBHOOK_URL).

ChatOps использует прокси своей платформы. Telegram-канал ChatOps пишет на api.telegram.org, поэтому при заданном ..._TELEGRAM_URL он использует его же — иначе оператор, настроивший прокси для заблокированного Telegram, получил бы работающие личные уведомления и молчащий ChatOps-канал. Явно заданный ..._CHATOPS_URL (в том числе direct) сильнее этого вывода.

email и call не HTTP. HTTP-прокси — механизм уровня запроса, а у SMTP и AMI запросов нет. Если для этих каналов действует HTTP-прокси (например, унаследованный от общего ..._PROXY_URL), он игнорируется, и при старте пишется предупреждение delivery_proxy_ignored_for_tcp_channel. Обычно это и нужно: почтовый релей и телефония чаще всего внутри периметра. Если нет — задайте им явно socks5:// или tcp://: обе схемы работают ниже протокола и несут любой TCP.

Ошибка в конфигурации не превращается в «отправим напрямую» ​

Канал, у которого URL прокси не разобрался, падает на каждой попытке с причиной, вместо того чтобы молча уйти напрямую:

delivery proxy for channel "telegram" is misconfigured: unsupported proxy scheme "htp"

И GET /api/v1/readiness считает такой канал каналом без транспорта — ровно как Telegram без токена бота.

Так сделано намеренно. Тихий переход на прямую отправку в сети, где провайдер заблокирован, — это потерянный алерт, который выглядит как проблема провайдера, и разбираться с ним будут не там, где сломано.

Взаимодействие с SSRF-гейтом ​

При NXS_ANOMALY_BLOCK_PRIVATE_WEBHOOKS=true (по умолчанию в production-профиле) картина для проксированного канала отличается, и это стоит принять осознанно:

  • адрес самого прокси разрешён всегда, даже приватный. Egress-прокси на 10.x или sidecar на loopback — обычная схема, и назвал его оператор, а не редактор цепочки эскалации;
  • адрес назначения проверяется настолько, насколько его видит сервис. Резолвит и набирает его прокси, поэтому проверки на соединении нет; заранее отклоняются IP-литерал из приватного, loopback- или link-local-диапазона и имя, которое локально резолвится в такой адрес. Имя без локального ответа пропускается — в сети с испорченным DNS это обычное дело, — а имя, которое во внутренний адрес превращает только DNS прокси, сервис оценить не может; для этого есть NXS_ANOMALY_EGRESS_ALLOWLIST. До 1.4.3 назначение через прокси не проверялось вовсе, и webhook на http://169.254.169.254/ доходил до сервиса метаданных на хосте прокси;
  • каждый переход по редиректу проверяется так же, как написанный URL: IP-литерал, имя, локально резолвящееся в непубличный адрес, и localhost или любое имя *.localhost (loopback на любой машине, которая его резолвит, в том числе на прокси) отклоняются до обращения к прокси. До 1.9.19 редирект проверялся, только если его хост — IP-литерал, и 307 на http://localhost/private доходил до прокси вместе с телом уведомления (GitHub #52). Граница та же, что выше: имя, которое резолвит только прокси, оценивает прокси — держите его ACL закрытым для собственного loopback и приватных сетей или ограничьте адреса через NXS_ANOMALY_EGRESS_ALLOWLIST;
  • продолжает действовать NXS_ANOMALY_EGRESS_ALLOWLIST — по написанному URL и на каждом редиректе, — а также запрет не-HTTP схем и лимит в 10 переходов;
  • каналы без прокси проверяются полностью, как описано в SECURITY_PROFILE.md. Это касается и назначений, попавших в NXS_ANOMALY_DELIVERY_NO_PROXY: для них прокси не используется, и полный гейт (включая защиту от DNS rebinding и редиректа на метаданные облака) работает как раньше.

Практический вывод: проксировать без оговорок стоит каналы с фиксированным адресом провайдера — telegram, slack, mattermost, mobile. Для канала webhook, где URL задаёт тот, кто правит цепочку, прокси имеет смысл включать вместе с NXS_ANOMALY_EGRESS_ALLOWLIST. Учтите, что NXS_ANOMALY_DELIVERY_PROXY_URL — прокси по умолчанию для всех каналов, включая webhook и issue; чтобы проксировать только провайдеров, задавайте поканальные переменные.

Как проверить ​

1. Старт. Сервис пишет, что понял (пароль вырезан):

INFO delivery_proxy_configured channel=telegram proxy=socks5://svc:xxxxx@tunnel.internal:1080 no_proxy=receiver.internal
WARN delivery_proxy_ignored_for_tcp_channel channel=email ...
ERROR delivery_proxy_invalid channel=slack error=...

2. Готовность. Канал с нечитаемым прокси виден как канал без транспорта — в проверке «Everyone on call can be reached»:

bash
curl -s "$API/api/v1/readiness" | jq '.checks[] | select(.key=="notification_targets")'

3. Настоящая отправка. Тестовое уведомление пользователю или алерт целиком:

bash
curl -X POST "$API/integrations/v1/webhook/<key>" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Проверка прокси","severity":"critical","status":"firing"}'

Результат провайдера — в попытках доставки, там же код ответа и выдержка из тела:

bash
api "$API/api/v1/delivery-attempts?alert_group_id={id}"

4. Локально, без прокси-сервера. SOCKS5 поднимается одной командой через любой доступный SSH-хост:

bash
ssh -N -D 127.0.0.1:1080 user@jump-host
NXS_ANOMALY_DELIVERY_PROXY_TELEGRAM_URL='socks5://127.0.0.1:1080'

Локальный аналог HAProxy-релея — одна команда socat, дальше tcp://:

bash
socat TCP-LISTEN:8443,fork,reuseaddr TCP:api.telegram.org:443 &
NXS_ANOMALY_DELIVERY_PROXY_TELEGRAM_URL='tcp://127.0.0.1:8443'

Что релей действительно проходит насквозь, проверяется без бота — настоящий Bot API отвечает на заведомо неверный токен:

bash
curl --resolve api.telegram.org:8443:127.0.0.1 \
  'https://api.telegram.org:8443/bot123456:INVALID/getMe'
# {"ok":false,"error_code":401,"description":"Unauthorized"}

Ответ 401 от самого Telegram означает, что TLS установился сквозь релей и сертификат сошёлся. Зависший handshake — признак того, что на том конце не mode tcp, а что-то терминирующее TLS (например, nginx с маршрутизацией по Host): такому хосту схема tcp:// не подходит.

Частые ошибки ​

СимптомПричина
delivery proxy for channel ... is misconfiguredОпечатка в URL или неподдерживаемая схема. Напрямую сервис в этом случае намеренно не отправляет
Прокси задан, но канал email/call ходит мимо негоДля них работают только socks5:// и tcp://; HTTP-прокси игнорируется (см. delivery_proxy_ignored_for_tcp_channel)
tcp relay ... needs an explicit portУ схемы tcp нет порта по умолчанию: tcp://relay.example.com:443
Уведомления канала webhook приходят не тому получателюНа канал с переменным адресом назначен tcp://-релей — он слеп к назначению (см. delivery_proxy_relay_on_variable_destination)
tls: failed to verify certificate через tcp://-релейРелей ведёт не в того провайдера, либо где-то по пути TLS всё-таки терминируется. Проверка идёт против хоста провайдера — это и есть смысл схемы, отключать её не нужно
ChatOps-канал молчит, личные уведомления идутЯвно задан ..._CHATOPS_URL=direct и он сильнее прокси платформы
blocked webhook host ... resolves to non-public address при заданном проксиХост попал в NXS_ANOMALY_DELIVERY_NO_PROXY и пошёл напрямую — там гейт действует полностью
destination_not_allowlistedПрокси ни при чём: адрес не входит в NXS_ANOMALY_EGRESS_ALLOWLIST, который проверяется и для проксированных каналов
Чарт падает на рендере с «a delivery proxy URL with a password…»URL с паролем нельзя класть в ConfigMap — перенесите переменную в Secret приложения
Уведомления идут напрямую, хотя переменные заданыПеременные не доехали до worker-деплоймента: доставку выполняет он

Смежные документы ​

  • CONFIGURATION.md — настройка инсталляции целиком.
  • SECURITY_PROFILE.md — SSRF-гейт, allowlist, политика каналов.
  • SETUP.md — полный список переменных окружения.

nxs-anomaly · Documentation