Прокси для исходящей доставки
Этот документ — про один вопрос: как отправлять уведомления, когда провайдер недоступен из сети, где работает сервис. Заблокированный мессенджер, 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, https | HTTP-каналы. HTTPS-назначения идут через CONNECT |
socks5, socks5h | HTTP-каналы и не-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-релей на внешней машине:
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:// меняет ровно одно: адрес, куда открывается сокет.
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, и локальный резолв в такой сети ломает доставку раньше, чем начнётся соединение.
Типовые конфигурации
Заблокированы только мессенджеры, всё остальное ходит напрямую:
NXS_ANOMALY_DELIVERY_PROXY_TELEGRAM_URL='socks5://tunnel.internal:1080'
NXS_ANOMALY_DELIVERY_PROXY_SLACK_URL='socks5://tunnel.internal:1080'Наружу только через egress-прокси, внутренний приёмник — напрямую:
NXS_ANOMALY_DELIVERY_PROXY_URL='http://egress.internal:3128'
NXS_ANOMALY_DELIVERY_NO_PROXY='receiver.internal,.corp.example'То же, но для канала webhook прокси не нужен вовсе:
NXS_ANOMALY_DELIVERY_PROXY_URL='http://egress.internal:3128'
NXS_ANOMALY_DELIVERY_PROXY_WEBHOOK_URL='direct'Прокси с паролем — переменная с секретом, поэтому в Kubernetes она кладётся в Secret приложения, а не в ConfigMap (см. ниже про чарт):
NXS_ANOMALY_DELIVERY_PROXY_URL='socks5://svc:s3cret@tunnel.internal:1080'Helm
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 чарта уже разрешён — под доставки и так ходит во внешнюю сеть.
Что происходит по каналам
| Канал | Через что идёт |
|---|---|
telegram | api.telegram.org, включая ответы на нажатия inline-кнопок |
slack, mattermost | incoming webhook платформы |
webhook | адрес из шага TRIGGER_WEBHOOK или цели уведомления |
chatops | webhook_url ChatOps-канала |
mobile | push-relay оператора (NXS_ANOMALY_MOBILE_PUSH_URL) |
issue | Redmine или generic-трекер из шага цепочки |
email | SMTP-сервер — только SOCKS5 |
call | Asterisk 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»:
curl -s "$API/api/v1/readiness" | jq '.checks[] | select(.key=="notification_targets")'3. Настоящая отправка. Тестовое уведомление пользователю или алерт целиком:
curl -X POST "$API/integrations/v1/webhook/<key>" \
-H 'Content-Type: application/json' \
-d '{"title":"Проверка прокси","severity":"critical","status":"firing"}'Результат провайдера — в попытках доставки, там же код ответа и выдержка из тела:
api "$API/api/v1/delivery-attempts?alert_group_id={id}"4. Локально, без прокси-сервера. SOCKS5 поднимается одной командой через любой доступный SSH-хост:
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://:
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 отвечает на заведомо неверный токен:
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 — полный список переменных окружения.