From f9dd24548126180945cee29f781aa98e4db4fc60e5d60a71c7808afcb942db4e Mon Sep 17 00:00:00 2001
From: AidarKC <i@aidarkc.ru>
Date: Fri, 24 Jul 2026 19:43:52 +0400
Subject: [PATCH] =?UTF-8?q?Deploy:=20=D1=80=D0=B0=D1=81=D1=88=D0=B8=D1=80?=
 =?UTF-8?q?=D0=B8=D1=82=D1=8C=20relay-range=20coturn?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md                           |  5 +++++
 deploy/SETUP_TURN_SERVER.md         | 12 ++++++++++++
 deploy/TURN_SERVERS.md              |  1 +
 deploy/scripts/setup_turn_coturn.sh | 10 ++++++----
 4 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 286a1818..251b22aa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -45,6 +45,11 @@
   - `docs/Solana_Architecture/README.md`
 - Документ формата пользовательской PDA-записи `shine_users` находится в:
   - `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md`
+- Актуальная документация по серверному модулю синхронизации Solana users находится в:
+  - `docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md`
+- При любом изменении логики серверной синхронизации `shine_users`, её таблиц PostgreSQL, checkpoint-механизма, startup/lifecycle или deploy-настроек обязательно обновлять:
+  - `docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md`
+  - `deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md`
 
 ## Документация блокчейна
 - Актуальная документация по форматам блокчейна находится в `docs/Blockchain/README.md`.
diff --git a/deploy/SETUP_TURN_SERVER.md b/deploy/SETUP_TURN_SERVER.md
index cb2d291f..d45a625f 100644
--- a/deploy/SETUP_TURN_SERVER.md
+++ b/deploy/SETUP_TURN_SERVER.md
@@ -25,6 +25,9 @@ sudo apt install -y coturn caddy
 sudo bash deploy/scripts/setup_turn_coturn.sh --realm turn1.shineup.me --secret CHANGE_ME_LONG_RANDOM_SECRET
 ```
 
+По умолчанию этот скрипт настраивает relay-диапазон `49000-53999`.
+Это стандарт SHiNE: 5000 UDP-портов под TURN relay.
+
 ## 3. coturn
 
 Секреты не хранить в git. Настраивать на сервере через `/etc/turnserver.conf` или отдельный secret/override.
@@ -44,6 +47,14 @@ no-multicast-peers
 no-cli
 ```
 
+Для SHiNE держать relay-range большим сразу, чтобы не упираться в `create_relay_ioa_sockets: no available ports`.
+Стандартный диапазон:
+
+```conf
+min-port=49000
+max-port=53999
+```
+
 Включить сервис:
 
 ```bash
@@ -83,3 +94,4 @@ sudo ss -lntup | grep -E ':(3478|5349)'
 - TURN credentials и shared secret не коммитить.
 - Если TURN домен переносится на другой VPS, менять DNS, а не код приложения.
 - После изменения TURN-адресов обновить серверные/UI настройки, где они используются.
+- Не сужать relay-range ниже 5000 UDP-портов без явной причины: для SHiNE это уже приводило к отказам звонков на проде `24 июля 2026`.
diff --git a/deploy/TURN_SERVERS.md b/deploy/TURN_SERVERS.md
index 3107cb69..8555456d 100644
--- a/deploy/TURN_SERVERS.md
+++ b/deploy/TURN_SERVERS.md
@@ -17,6 +17,7 @@ TURN нужен для WebRTC-звонков, когда прямое peer-to-pe
 - DNS каждого `turnX.shineup.me` указывает на актуальный физический сервер TURN.
 - TLS/HTTPS и вспомогательная маршрутизация обслуживаются через Caddy, если на сервере есть web endpoint для проверки.
 - `coturn` слушает TURN/STUN порты согласно локальному `turnserver.conf`.
+- Стандартный relay-range SHiNE: `49000-53999` (`5000` UDP-портов).
 - Секреты TURN не хранить в git.
 
 ## Что проверять
diff --git a/deploy/scripts/setup_turn_coturn.sh b/deploy/scripts/setup_turn_coturn.sh
index 20494924..a3d7c68b 100755
--- a/deploy/scripts/setup_turn_coturn.sh
+++ b/deploy/scripts/setup_turn_coturn.sh
@@ -9,8 +9,8 @@ set -euo pipefail
 
 SECRET=""
 REALM="turn1.shineup.me"
-MIN_PORT="49160"
-MAX_PORT="49200"
+MIN_PORT="49000"
+MAX_PORT="53999"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -23,11 +23,11 @@ while [[ $# -gt 0 ]]; do
       shift 2
       ;;
     --min-port)
-      MIN_PORT="${2:-49160}"
+      MIN_PORT="${2:-49000}"
       shift 2
       ;;
     --max-port)
-      MAX_PORT="${2:-49200}"
+      MAX_PORT="${2:-53999}"
       shift 2
       ;;
     *)
@@ -87,6 +87,8 @@ systemctl --no-pager --full status coturn
 
 echo
 echo "coturn настроен."
+echo "Стандартный relay-range SHiNE: ${MIN_PORT}-${MAX_PORT}."
+echo "Рекомендуемый размер диапазона: не меньше 5000 UDP-портов."
 echo "Откройте firewall: 3478/tcp, 3478/udp, ${MIN_PORT}-${MAX_PORT}/udp"
 echo "Для SHiNE-сервера задайте такой же shared-secret в параметре:"
 echo "  -Dcall.ice.turn.sharedSecret=${SECRET}"