ppn/free-turn-proxy
3
0
Fork 0
mirror of https://github.com/hackdiaz-dev/free-turn-proxy.git synced 2026-10-12 09:41:53 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: обновить документацию под новые флаги

Browse Source 
-wrap/-vless/-udp/-vk-link/-dns заменены на -obf/-mode/-transport/-link/-dns-mode
This commit is contained in:
samosvalishe
2026-05-21 19:19:44 +03:00
parent 31e35efbf3
commit 1e0ee55e48
8 changed files with 72 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+2 -2
View File
@@ -1,10 +1,10 @@
# Документация
- [Быстрый старт (WireGuard)](quickstart.md)
- [Режимы: UDP / VLESS / WRAP / KCP](modes.md)
- [Режимы: UDP / TCP / OBF / KCP](modes.md)
- [Флаги клиента и сервера](flags.md)
- [Развёртывание: systemd, Docker](deploy.md)
- [Мобильные: Android (Termux), iOS (iSH)](mobile.md)
- [Сборка из исходников](build.md)
- [Решение проблем](troubleshooting.md)
- [Глоссарий](GLOSSARY.md)
- [Глоссарий](glossary.md)
docs/deploy.md
+4 -6
View File
@@ -10,7 +10,7 @@ docker compose logs -f
По умолчанию: WireGuard backend `127.0.0.1:51820`, host network, порт `56000/udp`.
Для VLESS/Xray раскомментируйте `VLESS_MODE: "true"` и смените `CONNECT_ADDR` на `127.0.0.1:443`.
Для Xray/sing-box: `MODE=tcp` и смените `CONNECT_ADDR` на `127.0.0.1:443`. Для SRTP-мимикрии: `OBF_MODE=true` и `OBF_KEY=<64-hex>`.
## Docker Run
@@ -38,12 +38,10 @@ docker run -d --name btp -p 56000:56000/udp --restart unless-stopped \
| --- | --- | --- |
| `CONNECT_ADDR` | **обязательна** | backend сервера |
| `LISTEN_ADDR` | `0.0.0.0:56000` | адрес прослушивания |
| `VLESS_MODE` | `false` | включает `-vless` |
| `WRAP_MODE` | `false` | включает `-wrap` |
| `WRAP_KEY` | пусто | значение `-wrap-key` |
| `MODE` | `udp` | режим туннеля: `udp` \| `tcp` |
| `OBF_MODE` | `false` | включает `-obf` |
| `OBF_KEY` | пусто | значение `-obf-key` |
| `DEBUG` | `false` | включает `-debug` |
| `VK_TURN_KCP_PROFILE` | `balanced` | профиль KCP: `fast` \| `balanced` \| `slow` |
| `VK_TURN_KCP_FEC` | `0:0` | Reed-Solomon FEC: `data:parity` (напр. `10:3`) |
Сборка образа:
docs/flags.md
+12 -15
View File
@@ -6,19 +6,19 @@
| --- | --- | --- |
| `-listen` | `127.0.0.1:9000` | локальный адрес `ip:port`, куда подключается WireGuard или Xray клиент |
| `-peer` | **обязательный** | адрес сервера на VPS, `host:port` |
| `-vk-link` | **обязательный** | ссылка VK Calls `https://vk.com/call/join/...` |
| `-link` | **обязательный** | ссылка VK Calls `https://vk.com/call/join/...` |
| `-n` | `10` | параллельных TURN-потоков |
| `-udp` | `false` | TURN по UDP вместо TCP/TLS |
| `-transport` | `tcp` | транспорт до TURN-реле: `tcp` (TCP/TLS) \| `udp` |
| `-mode` | `udp` | режим туннеля: `udp` (UDP-релей для WireGuard) \| `tcp` (TCP-форвардер для Xray/sing-box) |
| `-bond` | `false` | распределять TCP-соединение по smux-сессиям (только с `-mode tcp`) |
| `-turn` | из ссылки | переопределить IP TURN-сервера |
| `-port` | из ссылки | переопределить порт TURN-сервера |
| `-vless` | `false` | TCP-форвардер (VLESS/Xray) вместо UDP-релея |
| `-vless-bond` | `false` | распределять TCP-соединение по smux-сессиям (только с `-vless`) |
| `-wrap` | `false` | SRTP-мимикрия payload |
| `-wrap-key` | пусто | общий ключ, 32 байта hex (64 символа) |
| `-gen-wrap-key` | `false` | напечатать новый ключ и выйти |
| `-obf` | `false` | SRTP-мимикрия payload |
| `-obf-key` | пусто | общий ключ, 32 байта hex (64 символа) |
| `-gen-obf-key` | `false` | напечатать новый ключ и выйти |
| `-manual-captcha` | `false` | сразу ручной режим captcha |
| `-streams-per-cred` | `10` | потоков на один кеш VK-учёток |
| `-dns` | `auto` | `udp` \| `doh` \| `auto` |
| `-dns-mode` | `auto` | `plain` (UDP/53) \| `doh` \| `auto` |
| `-dns-servers` | пусто | свои UDP/53 резолверы, `ip[:port][,ip[:port]...]` |
| `-debug` | `false` | debug-логи |
@@ -28,12 +28,9 @@
| --- | --- | --- |
| `-listen` | `0.0.0.0:56000` | адрес прослушивания `ip:port` |
| `-connect` | **обязательный** | локальный backend `host:port` (WG `127.0.0.1:51820` / Xray `127.0.0.1:443`) |
| `-vless` | `false` | TCP-форвардер; bond автоопределяется |
| `-wrap` | `false` | SRTP-мимикрия payload |
| `-wrap-key` | пусто | общий ключ, 32 байта hex |
| `-gen-wrap-key` | `false` | напечатать новый ключ и выйти |
| `-mode` | `udp` | режим туннеля: `udp` \| `tcp` (bond автоопределяется) |
| `-obf` | `false` | SRTP-мимикрия payload |
| `-obf-key` | пусто | общий ключ, 32 байта hex |
| `-gen-obf-key` | `false` | напечатать новый ключ и выйти |
| `-debug` | `false` | debug-логи |
## Переменные Окружения (KCP)
См. [modes.md → KCP](modes.md#kcp-только-в--vless).
docs/glossary.md
+26 -32
View File
@@ -9,9 +9,9 @@
```
backend (WireGuard UDP | TCP service)
↑
[app proxy mode] ← UDP-relay | TCP-forward (vless) | TCP-forward+bond
[app proxy mode] ← UDP-relay (-mode udp) | TCP-forward (-mode tcp) | TCP-forward+bond (-mode tcp -bond)
↑
[wrap / SRTP-mimicry] (optional, AEAD obfuscation поверх payload)
[srtpmimicry] (optional, AEAD обфускация поверх payload)
↑
[DTLS] ← обфускация (не security): VK content-filter ожидает DTLS handshake
↑
@@ -30,19 +30,19 @@ client ←→ VK TURN-relay
Standard relay protocol (RFC 5766/8656). VK выдаёт креды на свои TURN-реле. Мы используем эти реле как транзит к собственному серверу. Транспорт до TURN выбирается флагом `-udp` (UDP/TCP).
### DTLS — это **обфускация, не security**
VK content-filter дропает payload, который не похож на legit DTLS-handshake. Мы используем `pion/dtls` чтобы пройти фильтр. Шифрование DTLS — побочный эффект, не цель. Флаг `-no-dtls` был помечен DO NOT USE и удалён в V2-0 (в проде не работал).
VK content-filter дропает payload, который не похож на legit DTLS-handshake. Мы используем `pion/dtls` чтобы пройти фильтр. Шифрование DTLS — побочный эффект, не цель.
### wrap / SRTP-mimicry
Внутреннее имя пакета — `wrap` (планируется переименование в `srtpmimicry` на V2-4). CLI флаг `-wrap`. Это **ChaCha20-Poly1305 AEAD** с RTP-like wire-header (mimicry). Включается опционально поверх DTLS — даёт дополнительный слой обфускации с RTP-видимостью на проводе. CLI help говорит «ChaCha20-XOR» — **врёт**, реально AEAD. Не путать с Go-термином wrap (`errors.Wrap`).
### srtpmimicry
Пакет `internal/wire/srtpmimicry`. CLI флаг `-obf`. Это **ChaCha20-Poly1305 AEAD** с RTP-like wire-header (mimicry). Включается опционально поверх DTLS — даёт дополнительный слой обфускации с RTP-видимостью на проводе. Не путать с Go-термином wrap (`errors.Wrap`).
### app proxy mode (3 значения)
Что копируется поверх DTLS:
- **UDP-relay** (default): UDP-пакеты 1-в-1. Для WireGuard.
- **TCP-forward** (`-vless`): TCP-байты в smux-стрим, на сервере `net.Dial("tcp", backend)`. Generic, имя историческое (первый потребитель — Xray VLESS). Внутренний кандидат имени: `tcpfwd`.
- **TCP-forward + bond** (`-vless-bond` на клиенте): один TCP-коннект страйпится по N smux-сессиям. Сервер автоопределяет по magic первых байтов (`bond-autodetect=true`). Серверный флаг `-vless-bond` удалён в V2-0 как избыточный.
- **UDP-relay** (`-mode udp`, default): UDP-пакеты 1-в-1. Для WireGuard.
- **TCP-forward** (`-mode tcp`): TCP-байты в smux-стрим, на сервере `net.Dial("tcp", backend)`. Для Xray/sing-box. Пакет `internal/proxy/tcpfwd`.
- **TCP-forward + bond** (`-mode tcp -bond` на клиенте): один TCP-коннект страйпится по N smux-сессиям. Сервер автоопределяет по magic первых байтов (`bond-autodetect=true`).
### bond
Опция TCP-forward режима. Не отдельная подсистема — feature `vless`. Wire-формат: magic + frame с seq/type/data. Кодек в `internal/bond`, клиент-handler в `internal/bond/client`, сервер-registry в `internal/bond/server` (планируется переезд в `internal/proxy/bond{client,server}` на V2-4).
Опция TCP-forward режима (`-mode tcp -bond`). Wire-формат: magic + frame с seq/type/data. Кодек в `internal/wire/bondframe`, клиент-handler в `internal/proxy/bondclient`, сервер-registry в `internal/proxy/bondserver`.
### TURN stream
Одна из N TURN-connection'ов клиента. Флаг `-n` (default 10). Каждый stream = отдельный TURN-allocate + DTLS-session. Не путать с smux stream.
@@ -62,43 +62,37 @@ VK content-filter дропает payload, который не похож на le
При чтении кода держи контекст.
### VLESS
Имя проксирующего протокола Xray. **Внутри этого репо** означает только «TCP-forwarder режим». Никакой VLESS-логики в коде нет — мы просто гоним TCP-байты. Имя историческое; внутреннее переименование в `tcpfwd` запланировано на V2-4 (CLI флаг `-vless` остаётся).
Имя проксирующего протокола Xray. В коде нет VLESS-логики — просто TCP-форвардер. CLI флаг: `-mode tcp`. Внутренний пакет: `tcpfwd`.
### iSH
Linux user-mode environment для iOS (через usermode x86 emulation). Пакет `internal/ish` — listener shim вокруг iOS sandbox-ограничений. Только клиент-only; переедет в `internal/client/ish` на V2-4.
Linux user-mode environment для iOS (через usermode x86 emulation). Пакет `internal/client/ish` — listener shim вокруг iOS sandbox-ограничений. Только клиент-only.
### tcputil
Top-level пакет с **KCP/smux**-профилями. Имя врёт (никакого TCP внутри). Запланировано переименование в `internal/transport/kcptun` на V2-4.
### kcptun
Пакет `internal/transport/kcptun` с KCP/smux-профилями. Используется только в TCP-forward режиме.
### turnpipe
Пакет с TURN dial + allocate. Имя `pipe` создаёт коллизию с `pipeConn` (bidi data-copy loop в server). Переедет в `internal/transport/turndial` на V2-4.
### turndial
Пакет `internal/transport/turndial` — TURN dial + allocate.
### netadapt
Conn wrappers (DirectNet, ConnectedUDPConn, SplitFirstWriteConn). Имя не отражает суть — переедет в `internal/netconn` на V2-4.
### netconn
Пакет `internal/netconn` — Conn wrappers (DirectNet, ConnectedUDPConn, SplitFirstWriteConn).
### Mode (5 разных в CLI)
Все ортогональны:
- `-udp` — TURN transport (UDP|TCP к TURN).
- `-vless` — app proxy mode (UDP-relay|TCP-forward).
- `-vless-bond` — внутри TCP-forward (только client).
- `-wrap` — wrap-обфускация (off|SRTP-mimicry).
- `-dns` — DNS resolver (udp|doh|auto).
- `-transport tcp|udp` — транспорт до TURN (TCP/TLS или UDP).
- `-mode udp|tcp` — app proxy mode (UDP-relay|TCP-forward).
- `-bond` — bonding внутри TCP-forward (только client).
- `-obf` — srtpmimicry-обфускация.
- `-dns-mode` — транспорт резолвера клиента (plain|doh|auto).
### captcha (auto / manual)
Один домен, два пути:
- **auto** (`internal/client/captcha`): VK slider-puzzle решается программно через `client/internal/captcha`.
- **manual** (пока в `cmd/client/manual_captcha.go`, package main): HTTP-сервер на 127.0.0.1:8765, запуск браузера, gzip-rewrite VK-страниц. Запланирован вынос в `internal/client/captcha/manual` на V2-2.
- **auto** (`internal/client/captcha`): VK slider-puzzle решается программно.
- **manual** (`internal/client/captcha/manual`): HTTP-сервер на 127.0.0.1:8765, запуск браузера, gzip-rewrite VK-страниц.
Переключение: `vkauth.Client` пробует auto, при провале → manual fallback. Флаг `-manual-captcha` сразу идёт в manual.
### libvkturn.so
Мобильная (Android) сборка клиента в виде shared library. Собирается **вручную** разработчиком и переносится в Android-приложение. CI не строит. Внешних `//export`-функций нет — `package main` ← buildmode определяется на стороне разработчика.
### globalBondRegistry
Server-side глобал, держит активные bond-сессии. Инициализируется на package init — известная фрагильность (`isDebug` ещё false), работает только потому что bondserver `Debug`-поле не читается. Переедет в локальную переменную `cmd/server/main.go` на V2-3.
### `-no-dtls` (УДАЛЕНО)
Был помечен DO NOT USE — в проде не работал, VK content-filter дропает payload без DTLS-handshake. Удалён в V2-0.
### `-vless-bond` на сервере (УДАЛЕНО)
Сервер автоопределяет bond по magic первых байтов. Флаг был избыточен, удалён в V2-0. На клиенте — остаётся.
### `-bond` на сервере
Серверного `-bond` нет — сервер автоопределяет bond по magic первых байтов в стриме. Только клиентский флаг.
docs/mobile.md
+2 -2
View File
@@ -11,7 +11,7 @@
termux-wake-lock
curl -L -o client https://github.com/samosvalishe/btp/releases/latest/download/client-android-arm64
chmod +x client
./client -listen 127.0.0.1:9000 -peer <vps>:56000 -vk-link "<vk-link>"
./client -listen 127.0.0.1:9000 -peer <vps>:56000 -link "<vk-link>"
```
Снять wake lock: `termux-wake-unlock`.
@@ -25,7 +25,7 @@ apk update
apk add curl
curl -L -o client https://github.com/samosvalishe/btp/releases/latest/download/client-linux-386
chmod +x client
GOMAXPROCS=1 GODEBUG=asyncpreemptoff=1 ./client -listen 127.0.0.1:9000 -peer <vps>:56000 -vk-link "<vk-link>"
GOMAXPROCS=1 GODEBUG=asyncpreemptoff=1 ./client -listen 127.0.0.1:9000 -peer <vps>:56000 -link "<vk-link>"
```
Дольше в фоне:
docs/modes.md
+21 -33
View File
@@ -2,63 +2,51 @@
## UDP-Релей (WireGuard / Hysteria)
Дефолт. Клиент слушает локальный UDP, сервер форвардит UDP в backend (WG `127.0.0.1:51820`).
Дефолт (`-mode udp`). Клиент слушает локальный UDP, сервер форвардит UDP в backend (WG `127.0.0.1:51820`).
## VLESS / Xray (TCP)
## TCP-Форвардер (Xray / sing-box)
Флаг `-vless` на обеих сторонах. Сервер коннектит локальный TCP backend (Xray inbound `127.0.0.1:443`). Клиент слушает локальный TCP, на него смотрит Xray/v2rayN/sing-box.
Флаг `-mode tcp` на обеих сторонах. Сервер коннектит локальный TCP backend (Xray inbound `127.0.0.1:443`). Клиент слушает локальный TCP, на него смотрит Xray/v2rayN/sing-box.
Поверх DTLS — KCP + smux.
```bash
./server -listen 0.0.0.0:56000 -connect 127.0.0.1:443 -vless
./client -listen 127.0.0.1:9000 -peer <vps>:56000 -vk-link "<vk-link>" -vless
./server -listen 0.0.0.0:56000 -connect 127.0.0.1:443 -mode tcp
./client -listen 127.0.0.1:9000 -peer <vps>:56000 -link "<vk-link>" -mode tcp
```
**Bonding** — распределение одного TCP-соединения по всем активным smux-сессиям, флаг только клиентский:
```bash
./client -listen 127.0.0.1:9000 -peer <vps>:56000 -vk-link "<vk-link>" -vless -vless-bond -n 4
./client -listen 127.0.0.1:9000 -peer <vps>:56000 -link "<vk-link>" -mode tcp -bond -n 4
```
> **Breaking (V2-0):** серверный `-vless-bond` удалён, сервер автоопределяет bond по magic-префиксу в стриме. Клиентский `-no-dtls` тоже удалён (VK дропает не-DTLS).
Серверного `-bond` нет — сервер автоопределяет bond по magic-префиксу в стриме.
## WRAP (SRTP-Мимикрия)
## OBF (SRTP-Мимикрия)
`-wrap` маскирует TURN-payload под SRTP: RTP/opus-заголовок + ChaCha20-Poly1305 AEAD на теле. Не защита (DTLS уже шифрует), а обфускация под голос — иначе VK content-filter дропает. Ключ должен совпадать.
`-obf` маскирует TURN-payload под SRTP: RTP/opus-заголовок + ChaCha20-Poly1305 AEAD на теле. Не защита (DTLS уже шифрует), а обфускация под голос — иначе VK content-filter дропает. Ключ должен совпадать.
Сгенерировать ключ:
```bash
./server -gen-wrap-key
./server -gen-obf-key
```
Запуск:
```bash
./server ... -wrap -wrap-key <64-hex>
./client ... -wrap -wrap-key <64-hex>
./server ... -obf -obf-key <64-hex>
./client ... -obf -obf-key <64-hex>
```
## KCP (Только В `-vless`)
## TURN Транспорт
Переменные окружения (клиент и сервер):
По умолчанию клиент подключается к TURN-реле по TCP/TLS. Флаг `-transport udp` переключает на UDP:
| Переменная | Значения | Описание |
| --- | --- | --- |
| `VK_TURN_KCP_PROFILE` | `fast` \| `balanced` \| `slow` | Предустановка. |
| `VK_TURN_KCP_MTU` | напр. `1200` | Размер пакета. |
| `VK_TURN_KCP_FEC` | `data:parity`, напр. `10:3` | Reed-Solomon FEC. |
**Профили:**
- `fast` (`legacy`) — минимальные задержки, активная переотправка, MTU 1280.
- `balanced` (`cc`) — баланс для большинства сетей, MTU 1200.
- `slow` (`conservative`) — нестабильные каналы, MTU 1150.
Тонкая настройка: `VK_TURN_KCP_NODELAY`, `_INTERVAL`, `_RESEND`, `_NC`, `_SNDWND`, `_RCVWND`, `_ACK_NODELAY`.
**FEC:** на каждые `data` пакетов — `parity` избыточных. Потери до `parity` из `data+parity` восстанавливаются без ретрансмита. Overhead полосы: `parity/data` (для `10:3` — 30%). Включайте при случайных потерях; при шейпе по полосе FEC ухудшит goodput. По умолчанию `0:0`.
```bash
./client ... -transport udp
```
## Captcha
@@ -72,10 +60,10 @@
## DNS
Флаг `-dns`:
Флаг `-dns-mode` управляет транспортом резолвера самого клиента (VK API, токены, captcha) — не DNS-маршрутизацией пользовательского трафика.
- `udp` — только UDP/53;
- `doh` — только DNS-over-HTTPS;
- `plain` — только UDP/53;
- `doh` — только DNS-over-HTTPS (Yandex DoH);
- `auto` (дефолт) — сначала UDP/53, sticky-fallback на DoH при полном отказе.
Свои резолверы: `-dns-servers ip[:port][,ip[:port]...]`.
Свои UDP/53 резолверы: `-dns-servers ip[:port][,ip[:port]...]`.
docs/quickstart.md
+3 -3
View File
@@ -31,14 +31,14 @@ WireGuard забирает весь трафик, включая трафик к
```bash
curl -L -o client https://github.com/samosvalishe/btp/releases/latest/download/client-linux-amd64
chmod +x client
./client -listen 127.0.0.1:9000 -peer <vps>:56000 -vk-link "<vk-link>" -debug 2>&1 | ./scripts/routes.sh
./client -listen 127.0.0.1:9000 -peer <vps>:56000 -link "<vk-link>" -debug 2>&1 | ./scripts/routes.sh
```
**Windows (PowerShell от администратора):**
```powershell
Invoke-WebRequest -Uri https://github.com/samosvalishe/btp/releases/latest/download/client-windows-amd64.exe -OutFile client.exe
.\client.exe -listen 127.0.0.1:9000 -peer <vps>:56000 -vk-link "<vk-link>" -debug 2>&1 | .\scripts\routes.ps1
.\client.exe -listen 127.0.0.1:9000 -peer <vps>:56000 -link "<vk-link>" -debug 2>&1 | .\scripts\routes.ps1
```
**macOS:**
@@ -46,7 +46,7 @@ Invoke-WebRequest -Uri https://github.com/samosvalishe/btp/releases/latest/downl
```bash
curl -L -o client https://github.com/samosvalishe/btp/releases/latest/download/client-darwin-arm64
chmod +x client
./client -listen 127.0.0.1:9000 -peer <vps>:56000 -vk-link "<vk-link>" -debug 2>&1 | ./scripts/routes-macos.sh
./client -listen 127.0.0.1:9000 -peer <vps>:56000 -link "<vk-link>" -debug 2>&1 | ./scripts/routes-macos.sh
```
Когда скрипт напечатает `Ensuring route to ...` — включайте WireGuard.
docs/troubleshooting.md
+2 -2
View File
@@ -8,5 +8,5 @@
- VK часто требует captcha → `-manual-captcha`, затем обычный запуск.
- Клиент висит на получении TURN-данных → ссылка VK Calls умерла / звонок завершён для всех.
- Docker bridge mode → `CONNECT_ADDR=127.0.0.1:...` указывает внутрь контейнера. Используйте `--network host` или IP хоста.
- `-wrap` включён → ключ должен совпадать на клиенте и сервере.
- `VLESS_BOND=true` в docker → не ставьте, серверный флаг удалён в V2-0.
- `-obf` включён → ключ должен совпадать на клиенте и сервере.
- Bond на сервере не нужен — сервер определяет bond автоматически. Используйте только `-bond` на клиенте с `-mode tcp`.