Well-defined TUNING.md

This commit is contained in:
Alexey
2026-11-09 08:50:43 +03:00
parent 90aa574a76
commit ba10d57f9d
3 changed files with 132 additions and 93 deletions
+78 -65
View File
@@ -1,99 +1,103 @@
# Руководство по тюнингу Telemt: Middle-End и Upstreams
[English](TUNING.en.md) · [Русский](TUNING.ru.md) · [Deutsch](TUNING.de.md) · [EN / RU / DE terminology](../TERMINOLOGY.md)
Документ описывает актуальное поведение Middle-End (ME) и маршрутизации через upstream на основе:
- `src/config/types.rs`
- `src/config/defaults.rs`
- `src/config/load.rs`
- `src/transport/upstream.rs`
Значения `Default` ниже — это значения из кода при отсутствии ключа в конфиге, а не обязательно значения из примеров `config.full.toml`.
Значения `По умолчанию` ниже — это значения из кода при отсутствии ключа в конфиге, а не обязательно значения из примеров `config.full.toml`.
`Option<T>` и `null` в столбцах типов и значений по умолчанию обозначают необязательные внутренние значения. В TOML нет литерала `null`. Для старых интервалов обновления не задавайте `general.update_every` и явно укажите старые ключи; в остальных случаях общий интервал по умолчанию равен 300 секундам. Значения null в полях объекта PATCH конфигурации игнорируются и не удаляют настройки.
## Параметры Middle-End
### 1) Базовый режим ME, NAT и STUN
| Параметр | Тип | Default | Ограничения / валидация | Влияние на runtime | Пример |
| Параметр | Тип | По умолчанию | Ограничения / валидация | Влияние на работу | Пример |
|---|---|---:|---|---|---|
| `general.use_middle_proxy` | `bool` | `true` | нет | Включает транспорт ME. При `false` используется Direct-режим. | `use_middle_proxy = true` |
| `general.proxy_secret_path` | `Option<String>` | `"proxy-secret"` | путь может быть `null` | Путь к инфраструктурному proxy-secret Telegram. | `proxy_secret_path = "proxy-secret"` |
| `general.middle_proxy_nat_ip` | `Option<IpAddr>` | `null` | валидный IP при задании | Ручной override публичного NAT IP для адресного материала ME. | `middle_proxy_nat_ip = "203.0.113.10"` |
| `general.middle_proxy_nat_probe` | `bool` | `true` | нет | Включает NAT probing, когда одновременно включены ME-режим и `network.stun_use`. | `middle_proxy_nat_probe = true` |
| `general.proxy_secret_path` | `Option<String>` | `"proxy-secret"` | необязательный путь; в TOML нет `null` | Путь к инфраструктурному proxy-secret Telegram. | `proxy_secret_path = "proxy-secret"` |
| `general.middle_proxy_nat_ip` | `Option<IpAddr>` | `null` | валидный IP при задании | Явный публичный IP за NAT для вычисления адресной части ключей ME. | `middle_proxy_nat_ip = "203.0.113.10"` |
| `general.middle_proxy_nat_probe` | `bool` | `true` | нет | Проверяет внешний адрес за NAT, если включены ME и `network.stun_use`. | `middle_proxy_nat_probe = true` |
| `general.stun_nat_probe_concurrency` | `usize` | `8` | должно быть `> 0` | Максимум параллельных STUN-проб при NAT-детекте. | `stun_nat_probe_concurrency = 16` |
| `network.stun_use` | `bool` | `true` | нет | Глобальный переключатель STUN. При `false` STUN отключен. | `stun_use = true` |
| `network.stun_servers` | `Vec<String>` | встроенный публичный пул | удаляются дубликаты и пустые значения | Основной список STUN-серверов для NAT/public endpoint discovery. | `stun_servers = ["stun1.l.google.com:19302"]` |
| `network.stun_tcp_fallback` | `bool` | `true` | нет | Включает TCP fallback, если UDP STUN недоступен. | `stun_tcp_fallback = true` |
| `network.http_ip_detect_urls` | `Vec<String>` | `ifconfig.me` + `api.ipify.org` | нет | HTTP fallback для определения публичного IPv4 при недоступности STUN. | `http_ip_detect_urls = ["https://api.ipify.org"]` |
| `general.stun_iface_mismatch_ignore` | `bool` | `false` | нет | Зарезервированный флаг в текущей ревизии (runtime его не использует). | `stun_iface_mismatch_ignore = false` |
| `timeouts.me_one_retry` | `u8` | `12` | нет | Количество быстрых reconnect-попыток для DC с одним endpoint. | `me_one_retry = 6` |
| `network.stun_servers` | `Vec<String>` | встроенный публичный пул | удаляются дубликаты и пустые значения | Основной список STUN-серверов для определения внешнего адреса и порта за NAT. | `stun_servers = ["stun1.l.google.com:19302"]` |
| `network.stun_tcp_fallback` | `bool` | `true` | нет | Разрешает резервную проверку по TCP, когда STUN по UDP недоступен. | `stun_tcp_fallback = true` |
| `network.http_ip_detect_urls` | `Vec<String>` | `ifconfig.me` + `api.ipify.org` | нет | Резервные HTTP-сервисы для определения публичного IPv4 при недоступности STUN. | `http_ip_detect_urls = ["https://api.ipify.org"]` |
| `general.stun_iface_mismatch_ignore` | `bool` | `false` | нет | Зарезервированный флаг; в текущей ревизии не влияет на работу. | `stun_iface_mismatch_ignore = false` |
| `timeouts.me_one_retry` | `u8` | `12` | нет | Число быстрых повторных подключений для DC с одним адресом подключения. | `me_one_retry = 6` |
| `timeouts.me_one_timeout_ms` | `u64` | `1200` | нет | Таймаут одной быстрой попытки (мс). | `me_one_timeout_ms = 1500` |
### 2) Размер пула, keepalive и reconnect-политика
| Параметр | Тип | Default | Ограничения / валидация | Влияние на runtime | Пример |
| Параметр | Тип | По умолчанию | Ограничения / валидация | Влияние на работу | Пример |
|---|---|---:|---|---|---|
| `general.middle_proxy_pool_size` | `usize` | `8` | нет | Не влияющий на enforcement compatibility/startup-log input; active writer targets определяет DC-family floor policy. | `middle_proxy_pool_size = 12` |
| `general.middle_proxy_warm_standby` | `usize` | `16` | нет | Зарезервированное поле совместимости в текущей ревизии (активного runtime-consumer нет). | `middle_proxy_warm_standby = 16` |
| `general.middle_proxy_pool_size` | `usize` | `8` | нет | Поле совместимости и стартового журнала. Целевое число активных ME Writer задаёт политика минимального покрытия групп «DC + семейство IP». | `middle_proxy_pool_size = 12` |
| `general.middle_proxy_warm_standby` | `usize` | `16` | нет | Поле совместимости; в текущей ревизии не влияет на работу. | `middle_proxy_warm_standby = 16` |
| `general.me_keepalive_enabled` | `bool` | `true` | нет | Включает периодические keepalive/ping кадры ME. | `me_keepalive_enabled = true` |
| `general.me_keepalive_interval_secs` | `u64` | `8` | нет | Базовый интервал keepalive (сек). | `me_keepalive_interval_secs = 20` |
| `general.me_keepalive_jitter_secs` | `u64` | `2` | нет | Джиттер keepalive для предотвращения синхронных всплесков. | `me_keepalive_jitter_secs = 3` |
| `general.me_keepalive_payload_random` | `bool` | `true` | нет | Рандомизирует payload keepalive-кадров. | `me_keepalive_payload_random = true` |
| `general.me_warmup_stagger_enabled` | `bool` | `true` | нет | Включает staggered warmup дополнительных ME-коннектов. | `me_warmup_stagger_enabled = true` |
| `general.me_warmup_step_delay_ms` | `u64` | `500` | нет | Базовая задержка между шагами warmup (мс). | `me_warmup_step_delay_ms = 300` |
| `general.me_warmup_step_jitter_ms` | `u64` | `300` | нет | Дополнительный случайный warmup-джиттер (мс). | `me_warmup_step_jitter_ms = 200` |
| `general.me_reconnect_max_concurrent_per_dc` | `u32` | `8` | нет | Ограничивает параллельные reconnect worker'ы на один DC. | `me_reconnect_max_concurrent_per_dc = 12` |
| `general.me_reconnect_backoff_base_ms` | `u64` | `500` | нет | Начальный backoff reconnect (мс). | `me_reconnect_backoff_base_ms = 250` |
| `general.me_reconnect_backoff_cap_ms` | `u64` | `30000` | нет | Верхняя граница backoff reconnect (мс). | `me_reconnect_backoff_cap_ms = 10000` |
| `general.me_reconnect_fast_retry_count` | `u32` | `16` | нет | Бюджет быстрых retry до длинного backoff. | `me_reconnect_fast_retry_count = 8` |
| `general.me_writer_byte_budget_bytes` | `usize` | `33570816` | кратно `16384`; динамический минимум для `max_client_frame`; максимум `268435456` | Ограниченные byte permits для исходящей staging queue каждого ME writer. | `me_writer_byte_budget_bytes = 33570816` |
| `general.me_keepalive_payload_random` | `bool` | `true` | нет | Добавляет случайные данные в полезную нагрузку кадров keepalive. | `me_keepalive_payload_random = true` |
| `general.me_warmup_stagger_enabled` | `bool` | `true` | нет | Готовит дополнительные ME-соединения постепенно. | `me_warmup_stagger_enabled = true` |
| `general.me_warmup_step_delay_ms` | `u64` | `500` | нет | Базовая задержка между шагами подготовки соединений, мс. | `me_warmup_step_delay_ms = 300` |
| `general.me_warmup_step_jitter_ms` | `u64` | `300` | нет | Дополнительный случайный разброс задержки при подготовке соединений, мс. | `me_warmup_step_jitter_ms = 200` |
| `general.me_reconnect_max_concurrent_per_dc` | `u32` | `8` | нет | Ограничивает число параллельных задач повторного подключения для одного DC. | `me_reconnect_max_concurrent_per_dc = 12` |
| `general.me_reconnect_backoff_base_ms` | `u64` | `500` | нет | Начальная задержка перед повторным подключением, мс. | `me_reconnect_backoff_base_ms = 250` |
| `general.me_reconnect_backoff_cap_ms` | `u64` | `30000` | нет | Верхняя граница задержки перед повторным подключением, мс. | `me_reconnect_backoff_cap_ms = 10000` |
| `general.me_reconnect_fast_retry_count` | `u32` | `16` | нет | Число быстрых повторных попыток до перехода к увеличенным задержкам. | `me_reconnect_fast_retry_count = 8` |
| `general.me_writer_byte_budget_bytes` | `usize` | `33570816` | кратно `16384`; динамический минимум для `max_client_frame`; максимум `268435456` | Лимит байтов, зарезервированных для исходящей очереди каждого ME Writer. | `me_writer_byte_budget_bytes = 33570816` |
### 3) Reinit/hardswap, ротация секрета и деградация
| Параметр | Тип | Default | Ограничения / валидация | Влияние на runtime | Пример |
| Параметр | Тип | По умолчанию | Ограничения / валидация | Влияние на работу | Пример |
|---|---|---:|---|---|---|
| `general.hardswap` | `bool` | `true` | нет | Включает generation-based стратегию hardswap для ME-пула. | `hardswap = true` |
| `general.me_reinit_every_secs` | `u64` | `900` | должно быть `> 0` | Интервал периодического reinit ME-пула. | `me_reinit_every_secs = 600` |
| `general.me_reinit_singleflight` | `bool` | `true` | нет | Сериализует reinit cycles из всех trigger sources. | `me_reinit_singleflight = true` |
| `general.me_reinit_max_concurrency` | `usize` | `2` | диапазон `[1,8]`; эффективное значение `1` при singleflight | Ограничивает параллельные generation warmup; дополнительные triggers объединяются в один rerun. | `me_reinit_max_concurrency = 2` |
| `general.me_reinit_trigger_channel` | `usize` | `64` | диапазон `[1,4096]` | Ограничивает очередь reinit triggers в каждом runtime generation. | `me_reinit_trigger_channel = 64` |
| `general.me_reinit_coalesce_window_ms` | `u64` | `200` | нет | Объединяет burst triggers перед одним reinit cycle. | `me_reinit_coalesce_window_ms = 200` |
| `general.me_hardswap_warmup_delay_min_ms` | `u64` | `1000` | должно быть `<= me_hardswap_warmup_delay_max_ms` | Нижняя граница пауз между warmup dial попытками. | `me_hardswap_warmup_delay_min_ms = 500` |
| `general.me_hardswap_warmup_delay_max_ms` | `u64` | `2000` | должно быть `> 0` | Верхняя граница пауз между warmup dial попытками. | `me_hardswap_warmup_delay_max_ms = 1200` |
| `general.me_hardswap_warmup_extra_passes` | `u8` | `3` | диапазон `[0,10]` | Дополнительные warmup-проходы после базового. | `me_hardswap_warmup_extra_passes = 2` |
| `general.me_hardswap_warmup_pass_backoff_base_ms` | `u64` | `500` | должно быть `> 0` | Базовый backoff между extra-pass в warmup. | `me_hardswap_warmup_pass_backoff_base_ms = 400` |
| `general.me_config_stable_snapshots` | `u8` | `2` | должно быть `> 0` | Количество одинаковых snapshot перед применением ME map update. | `me_config_stable_snapshots = 3` |
| `general.me_config_apply_cooldown_secs` | `u64` | `300` | нет | Cooldown между применёнными обновлениями ME map. | `me_config_apply_cooldown_secs = 120` |
| `general.proxy_secret_stable_snapshots` | `u8` | `2` | должно быть `> 0` | Количество одинаковых snapshot перед runtime-rotation proxy-secret. | `proxy_secret_stable_snapshots = 3` |
| `general.proxy_secret_rotate_runtime` | `bool` | `true` | нет | Включает runtime-ротацию proxy-secret. | `proxy_secret_rotate_runtime = true` |
| `general.hardswap` | `bool` | `true` | нет | Включает смену поколений пула ME по стратегии hardswap. | `hardswap = true` |
| `general.me_reinit_every_secs` | `u64` | `900` | должно быть `> 0` | Интервал периодической переинициализации пула ME. | `me_reinit_every_secs = 600` |
| `general.me_reinit_singleflight` | `bool` | `true` | нет | Выполняет переинициализации последовательно независимо от источника запроса. | `me_reinit_singleflight = true` |
| `general.me_reinit_max_concurrency` | `usize` | `2` | диапазон `[1,8]`; эффективное значение `1` при singleflight | Ограничивает параллельную подготовку поколений; дополнительные запросы объединяются в один повторный запуск. | `me_reinit_max_concurrency = 2` |
| `general.me_reinit_trigger_channel` | `usize` | `64` | диапазон `[1,4096]` | Ограничивает очередь запросов переинициализации в каждом поколении. | `me_reinit_trigger_channel = 64` |
| `general.me_reinit_coalesce_window_ms` | `u64` | `200` | нет | Объединяет всплеск запросов в один цикл переинициализации. | `me_reinit_coalesce_window_ms = 200` |
| `general.me_hardswap_warmup_delay_min_ms` | `u64` | `1000` | должно быть `<= me_hardswap_warmup_delay_max_ms` | Нижняя граница паузы между попытками подключения при подготовке поколения. | `me_hardswap_warmup_delay_min_ms = 500` |
| `general.me_hardswap_warmup_delay_max_ms` | `u64` | `2000` | должно быть `> 0` | Верхняя граница паузы между попытками подключения при подготовке поколения. | `me_hardswap_warmup_delay_max_ms = 1200` |
| `general.me_hardswap_warmup_extra_passes` | `u8` | `3` | диапазон `[0,10]` | Число дополнительных проходов подготовки после основного. | `me_hardswap_warmup_extra_passes = 2` |
| `general.me_hardswap_warmup_pass_backoff_base_ms` | `u64` | `500` | должно быть `> 0` | Базовая задержка между дополнительными проходами подготовки. | `me_hardswap_warmup_pass_backoff_base_ms = 400` |
| `general.me_config_stable_snapshots` | `u8` | `2` | должно быть `> 0` | Число одинаковых снимков карты ME, необходимых перед её обновлением. | `me_config_stable_snapshots = 3` |
| `general.me_config_apply_cooldown_secs` | `u64` | `300` | нет | Минимальная пауза между применёнными обновлениями карты ME. | `me_config_apply_cooldown_secs = 120` |
| `general.proxy_secret_stable_snapshots` | `u8` | `2` | должно быть `> 0` | Число одинаковых снимков секрета перед его заменой во время работы. | `proxy_secret_stable_snapshots = 3` |
| `general.proxy_secret_rotate_runtime` | `bool` | `true` | нет | Разрешает замену инфраструктурного секрета без перезапуска процесса. | `proxy_secret_rotate_runtime = true` |
| `general.proxy_secret_len_max` | `usize` | `256` | диапазон `[32,4096]` | Верхний лимит длины принимаемого proxy-secret. | `proxy_secret_len_max = 512` |
| `general.update_every` | `Option<u64>` | `300` | если задано: `> 0`; если `null`: fallback на legacy минимум | Единый интервал refresh для ME config + secret updater. | `update_every = 300` |
| `general.me_pool_drain_ttl_secs` | `u64` | `90` | нет | Возрастной порог предупреждений о долгом drain и нижняя граница нормализации force-close timeout; stale binds он не разрешает. | `me_pool_drain_ttl_secs = 120` |
| `general.me_bind_stale_mode` | `"never"`, `"ttl"` или `"always"` | `"never"` | нет | Управляет новыми bindings на draining stale writers для непокрытых DC-family groups. | `me_bind_stale_mode = "never"` |
| `general.me_bind_stale_ttl_secs` | `u64` | `90` | нет | Окно stale-bind только для `me_bind_stale_mode = "ttl"`; `0` отключает TTL expiry для разрешённых draining writers. | `me_bind_stale_ttl_secs = 90` |
| `general.me_pool_min_fresh_ratio` | `f32` | `0.8` | диапазон `[0.0,1.0]` | Минимальная доля fresh DC-family coverage при commit. | `me_pool_min_fresh_ratio = 0.9` |
| `general.me_reinit_drain_timeout_secs` | `u64` | `90` | `0` использует safety fallback 300 секунд; effective value ниже drain TTL повышается до TTL | Таймаут force-close для draining stale writer. | `me_reinit_drain_timeout_secs = 0` |
| `general.auto_degradation_enabled` | `bool` | `true` | нет | Зарезервированный флаг совместимости в текущей ревизии (активного runtime-consumer нет). | `auto_degradation_enabled = true` |
| `general.degradation_min_unavailable_dc_groups` | `u8` | `2` | нет | Зарезервированный порог совместимости в текущей ревизии (активного runtime-consumer нет). | `degradation_min_unavailable_dc_groups = 2` |
| `general.update_every` | `Option<u64>` | `300` | если задано: `> 0`; при отсутствии с явно заданными старыми ключами — их минимум | Общий интервал обновления карты ME и инфраструктурного секрета. | `update_every = 300` |
| `general.me_pool_drain_ttl_secs` | `u64` | `90` | нет | Порог предупреждения о долгом завершении обслуживания и нижняя граница таймаута принудительного закрытия. Не разрешает новые привязки к старым соединениям. | `me_pool_drain_ttl_secs = 120` |
| `general.me_bind_stale_mode` | `"never"`, `"ttl"` или `"always"` | `"never"` | нет | Разрешает или запрещает новые привязки к старым ME Writer для групп «DC + семейство IP», не обеспеченных новым поколением. | `me_bind_stale_mode = "never"` |
| `general.me_bind_stale_ttl_secs` | `u64` | `90` | нет | Срок допуска старых соединений только для режима `ttl`; `0` отключает истечение этого срока для разрешённых ME Writer. | `me_bind_stale_ttl_secs = 90` |
| `general.me_pool_min_fresh_ratio` | `f32` | `0.8` | диапазон `[0.0,1.0]` | Минимальная доля групп «DC + семейство IP», обеспеченных новым поколением перед переходом. | `me_pool_min_fresh_ratio = 0.9` |
| `general.me_reinit_drain_timeout_secs` | `u64` | `90` | `0` означает резервный срок 300 секунд; значение ниже срока drain повышается до него | Срок до принудительного закрытия старых ME Writer, завершающих обслуживание. | `me_reinit_drain_timeout_secs = 0` |
| `general.auto_degradation_enabled` | `bool` | `true` | нет | Флаг совместимости; в текущей ревизии не влияет на работу. | `auto_degradation_enabled = true` |
| `general.degradation_min_unavailable_dc_groups` | `u8` | `2` | нет | Порог совместимости; в текущей ревизии не влияет на работу. | `degradation_min_unavailable_dc_groups = 2` |
Candidate generation hardswap авторитетна только для того же desired-map hash и endpoint revision. Повторные попытки переиспользуют pending generation не более 1800 секунд; после TTL создаётся новая generation. Commit повторно проверяет authority и требует fresh DC-family coverage не ниже `me_pool_min_fresh_ratio`. Отсутствующие groups блокируют commit при `me_bind_stale_mode = "never"`; `ttl` или `always` позволяют commit с ограниченным policy stale fallback для этих groups. Покрытые старые writers могут сразу перейти в retirement, поэтому hardswap является атомарной сменой policy, а не универсальной zero-drop гарантией.
Подготовленное для hardswap поколение можно применить только при неизменных хеше требуемой карты ME и ревизии адресов подключения. При повторных попытках оно используется не дольше 1800 секунд, после чего создаётся новое. Перед фиксацией перехода Telemt заново проверяет эти условия и долю групп «DC + семейство IP», обеспеченных новыми соединениями: она должна быть не ниже `me_pool_min_fresh_ratio`. При `me_bind_stale_mode = "never"` отсутствие любой группы блокирует переход. Режимы `ttl` и `always` допускают для таких групп резервное использование старых соединений в пределах выбранной политики. Старые ME Writer для уже обеспеченных групп могут сразу выводиться из обслуживания. Поэтому атомарность смены политики не означает, что hardswap гарантированно сохранит все соединения.
Writer replacement использует отдельное cancellation-safe состояние `Open -> Preparing -> Retiring`. `Preparing` запрещает дублирующую replacement work, но разрешает новые binds. Под registry binding guard commit повторно проверяет victim, переводит его в `Retiring`, чтобы запретить новые binds, устанавливает и публикует successor и начинает drain predecessor до освобождения guard. Отмена reservation до этой commit boundary возвращает `Open`.
Замена отдельного ME Writer использует состояния `Open -> Preparing -> Retiring` и корректно обрабатывает отмену операции. В `Preparing` нельзя запустить вторую замену того же компонента, но можно привязывать к нему новые потоки. При фиксации замены Telemt под блокировкой реестра привязок заново проверяет заменяемый ME Writer, переводит его в `Retiring`, запрещая новые привязки, устанавливает и публикует замену и начинает завершение обслуживания прежнего компонента. Только после этого блокировка снимается. Отмена резервирования до этой границы возвращает состояние `Open`.
Возраст pending generation, число и дефицит writers, отсутствующие DC groups, актуальность map, orphan warm writers и фазы `preparing`/`retiring` доступны через `/v1/runtime/me_pool_state`. Соответствующие gauges `telemt_me_hardswap_*` и `telemt_me_writer_replacement_current` равны нулю, когда ME telemetry имеет уровень `silent` или активный ME snapshot недоступен. В Prometheus `telemt_me_hardswap_pending_map_current` следует проверять вместе с `telemt_me_hardswap_pending`: нулевая map currency также означает отсутствие pending generation, тогда как API возвращает `null`. Настройте alerts на pending age около 1800 секунд, устойчивый deficit или missing groups, stale map, orphan warm writers и не сходящиеся replacement phases.
Эндпоинт `/v1/runtime/me_pool_state` показывает возраст ожидающего поколения, число и дефицит ME Writer, отсутствующие группы DC, актуальность карты, подготовленные соединения без владельца и фазы `preparing`/`retiring`. Метрики `telemt_me_hardswap_*` и `telemt_me_writer_replacement_current` равны нулю при уровне ME-телеметрии `silent` или отсутствии активного снимка состояния. Проверяйте `telemt_me_hardswap_pending_map_current` вместе с `telemt_me_hardswap_pending`: ноль может означать отсутствие ожидающего поколения, а не устаревшую карту. В таком случае API возвращает `null`. Настройте оповещения при возрасте ожидающего поколения около 1800 секунд, устойчивом дефиците соединений или групп, устаревшей карте, подготовленных соединениях без владельца и затянувшихся фазах замены.
## Устаревшие / legacy параметры
## Устаревшие параметры
| Параметр | Статус | Замена | Текущее поведение | Рекомендация миграции |
|---|---|---|---|---|
| `general.middle_proxy_nat_stun` | Deprecated | `network.stun_servers` | Добавляется в `network.stun_servers`, только если `network.stun_servers` не задан явно. | Перенести значение в `network.stun_servers`, legacy-ключ удалить. |
| `general.middle_proxy_nat_stun_servers` | Deprecated | `network.stun_servers` | Добавляется в `network.stun_servers`, только если `network.stun_servers` не задан явно. | Перенести значения в `network.stun_servers`, legacy-ключ удалить. |
| `general.proxy_secret_auto_reload_secs` | Deprecated | `general.update_every` | Используется только если `update_every = null` (legacy fallback). | Явно задать `general.update_every`, legacy-ключ удалить. |
| `general.proxy_config_auto_reload_secs` | Deprecated | `general.update_every` | Используется только если `update_every = null` (legacy fallback). | Явно задать `general.update_every`, legacy-ключ удалить. |
| `general.middle_proxy_nat_stun` | Устарел | `network.stun_servers` | Добавляется в `network.stun_servers`, только если `network.stun_servers` не задан явно. | Перенести значение в `network.stun_servers`, старый ключ удалить. |
| `general.middle_proxy_nat_stun_servers` | Устарел | `network.stun_servers` | Добавляется в `network.stun_servers`, только если `network.stun_servers` не задан явно. | Перенести значения в `network.stun_servers`, старый ключ удалить. |
| `general.proxy_secret_auto_reload_secs` | Устарел | `general.update_every` | Используется, если `update_every` отсутствует, а старые интервалы заданы явно. | Явно задать `general.update_every`, старый ключ удалить. |
| `general.proxy_config_auto_reload_secs` | Устарел | `general.update_every` | Используется, если `update_every` отсутствует, а старые интервалы заданы явно. | Явно задать `general.update_every`, старый ключ удалить. |
## Как конфигурируются Upstreams
### Схема upstream
| Поле | Применимость | Тип | Обязательно | Default | Назначение |
| Поле | Применимость | Тип | Обязательно | По умолчанию | Назначение |
|---|---|---|---|---|---|
| `[[upstreams]].type` | все upstream | `"direct" \| "socks4" \| "socks5" \| "shadowsocks"` | да | n/a | Тип upstream транспорта. |
| `[[upstreams]].weight` | все upstream | `u16` | нет | `1` | Базовый вес в weighted-random выборе. |
@@ -114,7 +118,7 @@ Writer replacement использует отдельное cancellation-safe с
| `url` | `shadowsocks` | `String` | да | n/a | Shadowsocks SIP002 URL (`ss://...`). В runtime API раскрывается только `host:port`. |
| `interface` | `shadowsocks` | `Option<String>` | нет | `null` | Необязательный исходящий bind-интерфейс или literal локальный IP. |
### Runtime-правила
### Правила выбора соединения
1. Если `[[upstreams]]` отсутствует, loader добавляет один upstream `direct` по умолчанию.
2. Scope-фильтрация — по точному совпадению токена:
@@ -135,7 +139,7 @@ Writer replacement использует отдельное cancellation-safe с
10. В ME-режиме через SOCKS корректные публичные `BND.ADDR/BND.PORT` с ненулевым портом задают полный исходный кортеж KDF. Семейство адреса должно совпадать с логическим ME-назначением независимо от семейства TCP-соединения к SOCKS. Для IPv4-mapped назначения нужен обычный IPv4 BND; IPv4-compatible IPv6 остаётся IPv6.
11. `shadowsocks` upstream требует `general.use_middle_proxy = false`. При включенном ME-режиме конфиг отклоняется при загрузке.
## Примеры конфигурации Upstreams
## Примеры настройки апстримов
### Пример 1: минимальный direct upstream
@@ -182,26 +186,35 @@ weight = 2
enabled = true
```
### Пример 5: смешанные upstream с scopes
### Выбор апстрима по имени пользователя
В Direct-режиме пользователь `scope_premium` выбирает точный scope `premium`. Часть имени после `scope_` должна содержать 1–64 латинские буквы ASCII, цифры или дефисы. Пустой или некорректный суффикс включает обычный выбор без scope. Если корректный scope задан, но подходящего апстрима нет, соединение завершается ошибкой; перехода на маршрут без scope не происходит. Метки scope не создают пользователей и не заменяют аутентификацию.
При выборе scope его строка подставляется вместо `user_id` SOCKS4 и вместо имени и пароля SOCKS5. В этом примере SOCKS5-сервер должен принимать `premium` и как имя, и как пароль. Обычные пользователи выбирают прямой маршрут без scope. Перед использованием замените секрет и адрес SOCKS-сервера.
```toml
[general]
use_middle_proxy = false
[access.users]
scope_premium = "0123456789abcdef0123456789abcdef"
[[upstreams]]
type = "direct"
weight = 5
enabled = true
scopes = ""
[[upstreams]]
type = "socks5"
address = "203.0.113.40:1080"
username = "edge"
password = "edgepass"
weight = 3
enabled = true
scopes = "premium,me"
username = "premium"
password = "premium"
scopes = "premium"
```
### Пример 5: профиль тюнинга под ME
Этот механизм выбора по пользователю действует в Direct-режиме. При подключении ME пользовательский scope сейчас не передаётся: метка `me` сама по себе не выбирает апстрим ME. Для получения TLS-профилей применяется отдельная настройка `censorship.tls_fetch_scope`. См. [правила фильтрации](../Config_params/CONFIG_PARAMS.ru.md#scopes).
### Пример 6: профиль настройки ME
```toml
[general]