mirror of
https://github.com/telemt/telemt.git
synced 2026-11-22 15:26:37 +03:00
Well-defined TUNING.md
This commit is contained in:
@@ -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]
|
||||
|
||||
Reference in New Issue
Block a user