Перейти к содержанию

Сеть: прокси и TLS

Корпоративная сеть обычно закрывает прямой выход в интернет и подписывает внутренние сервисы собственным CA. Synth умеет работать в обоих условиях: исходящий трафик можно направить через прокси, а доверие к сертификатам задать в одном месте — для всех подсистем сразу.

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

Через общий исходящий слой идут:

  • запросы к провайдерам LLM;
  • HTTP- и SSE-подключения к MCP-серверам;
  • исходящие webhooks;
  • web_fetch и web_search;
  • git-операции;
  • проверка обновлений и загрузка внешних инструкций и скиллов.

Поддерживаются HTTP, HTTPS и SOCKS5. HTTPS-прокси может требовать собственный CA, Basic-аутентификацию или клиентский сертификат — эти параметры задаются у профиля отдельно от доверия к цели.

PostgreSQL

База — не HTTP-трафик, поэтому прокси к ней не применяется. Для PostgreSQL настраивается TLS: режим storage.postgres.sslmode и сертификаты из security.tls.

Профили и правила

Маршрут выбирается для каждого хоста назначения:

  1. noProxy — исключения, всегда важнее правил;
  2. правила rules[] — в порядке объявления, побеждает первое совпадение;
  3. режим: all — профиль по умолчанию, selected — напрямую.
Поле Назначение
enabled Явный выключатель; без него прокси включается наличием URL
mode all — проксировать всё, кроме исключений; selected — только по правилам
defaultProfile Профиль для режима all и правил без явного профиля
profiles.<name> Именованный профиль: URL, Basic-аутентификация, TLS к прокси
rules[] {hosts, action: proxy|direct, profile?}; порядок = приоритет
noProxy Хосты и сети, которые всегда идут напрямую

Правило с action: direct не может ссылаться на профиль. В режиме selected всё, что не совпало с правилом, идёт напрямую. Шаблоны хостов: точное имя, .suffix (сам домен и поддомены), *.suffix (только поддомены), host:port, IP-литерал, CIDR и *.

Настройка

Прокси задаётся в config.yaml, переменными SYNTH_PROXY_* или в интерфейсе: Настройки → «Сеть» → «Прокси». Приоритет источников:

SYNTH_PROXY_*  >  runtime-настройка (UI)  >  config.yaml  >  стандартные HTTP_PROXY/HTTPS_PROXY

Стандартные переменные HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY учитываются только при fromEnv: true и если явный enabled: false их не подавляет. Слияние — по полям, но profiles и rules runtime-настройка заменяет целиком: частичного объединения списков нет.

proxy:
  enabled: true
  mode: all
  defaultProfile: default
  profiles:
    default:
      label: Corporate
      url: "http://proxy.corp.example:3128"
      auth:
        type: basic
        username: synth
      tls:
        caFile: "/etc/synth/tls/proxy-ca.pem"
        rejectUnauthorized: true
    llm:
      label: LLM egress
      url: "https://llm-proxy.corp.example:8443"
  rules:
    - hosts: ["api.openai.com", "*.openai.com"]
      action: proxy
      profile: llm
    - hosts: ["*.corp.example", "10.0.0.0/8"]
      action: direct
  noProxy: ["localhost", ".svc"]

Применение — при следующем старте, как и TLS: транспорт создаётся один раз при инициализации процесса. Интерфейс показывает статус saved/running и плашку restartRequired; изменения вступают в силу после перезапуска инстанса.

Пароли

Пароль Basic-аутентификации не хранится ни в config.yaml, ни в settings.json. Источники:

  • профиль default — переменная SYNTH_PROXY_PASSWORD или файл {dataDir}/secrets/proxy-password;
  • остальные профили — SYNTH_PROXY_<NAME>_PASSWORD или файл {dataDir}/secrets/proxy/<name>.password.

Переменная окружения приоритетнее файла. Если пароль задан через окружение, интерфейс не может его изменить и отвечает 409 CONFLICT. Пароль write-only: он не возвращается в ответах, не пишется в аудит и не попадает в журналы. CA и клиентские сертификаты профиля, загруженные из интерфейса, лежат в {dataDir}/secrets/proxy/<name>/.

Ограничения

  • Доменная аутентификация не реализуется. Kerberos, NTLM и Negotiate в приложении не поддерживаются: между Synth и корпоративным прокси ставится промежуточный egress-прокси или шлюз (например, Squid с login=NEGOTIATE или px для NTLM). Synth подключается к шлюзу по Basic, mTLS или без аутентификации.
  • SOCKS5 — best-effort. Имя хоста резолвит прокси; доверие к цели и mTLS через SOCKS5 не применяются. Для Kubernetes целевая схема — HTTP CONNECT.
  • Git и stdio-MCP получают один прокси через окружение дочернего процесса. Per-host маршрут для них не поддерживается; в режиме selected прокси- переменные им не ставятся, чтобы не обойти правила молча.
  • Только Basic. auth.type, отличный от basic, — ошибка конфигурации.
  • Недоступный прокси не означает тихий direct. Прямой обход возможен только при явном fallbackDirect: true; ошибки аутентификации его не разрешают.

TLS и доверенные CA

security.tls — единый источник доверия для всех исходящих соединений: LLM, MCP, webhooks, web_fetch, git и PostgreSQL. Подсистемы не создают собственных HTTP-агентов и не полагаются на переменные окружения как на конфигурацию.

Поле Назначение
caFile Путь к PEM-файлу CA; допускается бандл из нескольких сертификатов
caPem PEM CA строкой, например из Secret; взаимоисключающ с caFile
certFile / keyFile Клиентский сертификат и ключ для mTLS по умолчанию
rejectUnauthorized Проверять сертификат сервера; по умолчанию true

Пользовательский CA дополняет системное доверие, а не заменяет его: публичные сайты продолжают проверяться. Для отдельных хостов можно задать свои клиентские сертификаты — таблица mappings:

  • точное имя хоста;
  • *.suffix — только поддомены;
  • * — все хосты.

Побеждает первое совпадение сверху вниз; если совпадений нет, используется клиентский сертификат по умолчанию. Отдельного CA на хост нет: один CA-бандл на весь исходящий трафик.

security:
  tls:
    caFile: "/etc/synth/tls/corp-ca.pem"
    # certFile: "/etc/synth/tls/client.crt"
    # keyFile:  "/etc/synth/tls/client.key"
    rejectUnauthorized: true

TLS настраивается в config.yaml, переменными SYNTH_TLS_* или в интерфейсе: Настройки → «Сеть» → «Доверенные CA (TLS)». Runtime-настройка хранится в {dataDir}/security-tls.json с правами 0600, а PEM-материалы — в {dataDir}/secrets/tls/. Файл читается до подключения к PostgreSQL, поэтому является осознанным исключением из общего хранилища.

NODE_EXTRA_CA_CERTS — не конфигурация

Переменная остаётся совместимостью для дочерних процессов (MCP stdio, git) и частью базового набора Node. Она не заменяет security.tls и не должна использоваться как способ задать корпоративный CA. Задавайте CA через caFile или caPem.

Изменения TLS применяются после перезапуска процесса: глобальный транспорт строится при старте. Интерфейс показывает restartRequired.

PostgreSQL

Для базы действуют два независимых параметра:

  • storage.postgres.sslmode — режим соединения: disable, require, verify-full (алиас verify-ca). verify-full требует явного CA из security.tls и без него отказывается стартовать.
  • security.tls — CA и клиентский сертификат. PostgreSQL использует тот же резолвер профилей по хосту, что и остальной egress; отдельной настройки сертификата для базы нет.

TLS-параметры в строке подключения (sslmode, sslrootcert, sslcert, sslkey и подобные) запрещены: драйвер накладывает DSN поверх конфига и может молча отключить проверку. Политика доверия задаётся только через sslmode и security.tls.

Что дальше