docs: update README for forge branch — full feature coverage

Rewritten to reflect all forge branch additions: - ECH detection, IPv6 full support, web panel, health check, config validator, rollback, auto updater, custom strategies, CLI commands, telemetry/UCB1, project structure tree - Updated menu table (15 options including B/H/V) - Added CLI commands reference table - Added web panel setup section - Added custom strategies drop-in docs - Added project structure tree with file descriptions - Added code quality stats (0 shellcheck, 98 tests) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-28 03:20:25 +00:00 · 2026-04-10 21:28:09 +03:00 · 2026-04-10 21:28:09 +03:00 · e9ee2dece7
commit e9ee2dece7
parent e9418f41c7
1 changed files with 151 additions and 13 deletions
--- a/README.md
+++ b/README.md
@ -1,11 +1,10 @@
-# z2k v2.0 - Zapret2 для Keenetic
+# z2k v2.0 — Zapret2 для Keenetic

 Поддержать проект:

 - TON: `UQA6Y6Mf1Qge2dVSl3_vSqb29SKrhI8VgJtoRBjgp08oB8QY`
 - USDT (ERC20): `0xA1D6d7d339f05C1560ecAF0c5CB8c4dc80Dc46A9`

-
 **Важно:** после установки применяются autocircular стратегии. Им нужно время и несколько попыток, чтобы подстроиться под сетевую среду. Если сайт не открывается сразу — дайте странице несколько раз перезагрузиться. Параметры перебираются автоматически, после чего соединение обычно стабилизируется.

 > Данный проект предназначен для исследования сетевых протоколов и изучения работы систем анализа трафика. Используется исключительно в учебных целях.
@ -16,12 +15,14 @@

 z2k — модульный установщик zapret2 для роутеров Keenetic с Entware.

-Цель проекта: упростить установку zapret2 на Keenetic и предоставить набор сетевых стратегий с автоподбором (autocircular) и поддержкой IPv6.
+Цель проекта: упростить установку zapret2 на Keenetic и предоставить набор сетевых стратегий с автоподбором (autocircular), персистентной памятью, телеметрией и полной поддержкой IPv4/IPv6.

 ---

 ## Особенности

+### DPI bypass
+
 - Установка zapret2 (openwrt-embedded релиз) без компиляции, с проверкой работоспособности `nfqws2`
 - Три TCP autocircular профиля с разными стратегиями:
  - **RKN** — список ресурсов (TCP/TLS + HTTP) — 45 стратегий
@ -31,11 +32,32 @@ z2k — модульный установщик zapret2 для роутеров
 - Discord профили:
  - TCP: hostlist Discord включён в RKN-профиль
  - UDP voice/video: `circular_locked` (стратегия закрепляется per-domain)
- Telegram: прозрачное проксирование через Cloudflare WebSocket (тестовая функция)
+- ECH (Encrypted Client Hello) detection — автоматический пропуск desync когда SNI зашифрован
 - Hostlist режим: стратегии применяются только к доменам из списков
 - Whitelist: домены-исключения (госуслуги, Steam, VK, Яндекс и др.) не обрабатываются
- IPv6: автоопределение и включение правил если поддерживается
- Списки доменов устанавливаются автоматически
+
+### Сеть и прокси
+
+- **Telegram** — прозрачное проксирование через Cloudflare WebSocket (тестовая функция)
+- **IPv6** — полная поддержка: dual-stack DNS, IPv6 SO_ORIGINAL_DST, Telegram DC IPv6 CIDR
+- **Roblox** — UDP bypass для игровых серверов
+
+### Инструменты и мониторинг
+
+- **Веб-панель** — мониторинг через браузер (busybox httpd CGI): статус сервиса, стратегии, логи, управление
+- **Health check** — автоматическая проверка доступности сервисов (YouTube, Discord, Telegram, RKN)
+- **Config validator** — валидация конфигурации перед применением (порты, hostlist-файлы, blob-файлы, lua-desync)
+- **Rollback** — откат конфигурации к предыдущему snapshot с авто-таймером
+- **Auto updater** — автоматическое обновление списков доменов по cron
+- **Телеметрия** — UCB1-scoring стратегий, латентность, cooldown (опционально)
+
+### Качество кода
+
+- **0 shellcheck warnings** — все shell-скрипты чистые
+- **0 go vet issues** — Go код без замечаний
+- **98 автотестов** — 86 shell + 12 Go, все проходят
+- **CI/CD** — GitHub Actions: shellcheck, go build/test/vet, luacheck, кросс-компиляция 6 архитектур
+- **Безопасность** — нет eval/source инъекций, SHA256 верификация, rate limiting, connection deadlines

 ---

@ -60,7 +82,7 @@ opkg update
 opkg install coreutils-sort curl grep gzip ipset iptables kmod_ndms xtables-addons_legacy libnghttp2
 ```

-### 3) Установка z2k (Zapret2 для Keenetic)
+### 3) Установка z2k

 ```bash
 curl -fsSL https://raw.githubusercontent.com/necronicle/z2k/forge/z2k.sh | sh
@ -76,8 +98,6 @@ curl -fsSL https://raw.githubusercontent.com/necronicle/z2k/forge/z2k.sh | sh
 curl -fsSL https://raw.githubusercontent.com/necronicle/z2k/forge/z2k.sh | sh
 ```

-Пункты меню:
-
 | Пункт | Описание |
 |---|---|
 | **[1]** | Установить/переустановить zapret2 |
@ -92,6 +112,32 @@ curl -fsSL https://raw.githubusercontent.com/necronicle/z2k/forge/z2k.sh | sh
 | **[G]** | Roblox — UDP bypass для игровых серверов |
 | **[T]** | Telegram прокси — прозрачное проксирование через WebSocket |
 | **[S]** | Скрипты custom.d |
+| **[B]** | Rollback — откат конфигурации к snapshot |
+| **[H]** | Health check — проверка доступности сервисов |
+| **[V]** | Валидация конфигурации |
+
+---
+
+## Командная строка
+
+```bash
+sh z2k.sh [команда]
+```
+
+| Команда | Описание |
+|---|---|
+| `install` | Установить zapret2 |
+| `menu` | Открыть интерактивное меню |
+| `uninstall` | Удалить zapret2 |
+| `status` | Показать статус системы |
+| `check` | Показать какие списки обрабатываются |
+| `update` | Обновить z2k до последней версии |
+| `rollback` | Откатить конфигурацию к snapshot |
+| `snapshot` | Создать snapshot конфигурации |
+| `healthcheck` | Проверить доступность сервисов |
+| `validate` | Валидация текущей конфигурации |
+| `cleanup` | Очистить старые бэкапы |
+| `version` | Показать версию |

 ---

@ -102,23 +148,66 @@ curl -fsSL https://raw.githubusercontent.com/necronicle/z2k/forge/z2k.sh | sh
 ### Детекция неудач

 - **Стандартный детектор** — TCP ретрансмиссии и аномальные RST
- **TLS alert детектор** (`z2k_tls_alert_fatal`) — анализирует TLS alert. Включён по умолчанию для РКН
+- **TLS alert детектор** (`z2k_tls_alert_fatal`) — анализирует TLS alert + HTTP DPI redirect. Включён по умолчанию для РКН
 - **Silent fallback** — детектор отсутствия ответа: если несколько запросов подряд без ответа, принудительно ротирует стратегию. Включается через меню [F]

 ### Персистентность

-Найденные рабочие стратегии сохраняются в `state.tsv` и переживают перезапуск сервиса.
+Найденные рабочие стратегии сохраняются в `state.tsv` и переживают перезапуск сервиса. Файл защищён от конкурентной записи через lock-механизм с atomic rename.
+
+### Телеметрия (опционально)
+
+При включении policy-режима стратегии оцениваются через UCB1 алгоритм (multi-armed bandit) с учётом:
+- Success rate per strategy per domain
+- Латентность (EMA)
+- Cooldown при неудачах
+
+---
+
+## Веб-панель мониторинга
+
+Встроенная веб-панель для просмотра состояния и управления через браузер:
+
+```bash
+# Установка
+sh /opt/zapret2/z2k-webpanel-install.sh --port 8080
+
+# Доступ
+http://ROUTER_IP:8080/
+```
+
+Панель показывает:
+- Статус сервиса (PID, uptime)
+- Текущие стратегии по категориям
+- Состояние autocircular (домены, стратегии)
+- Логи healthcheck и debug
+- Системную информацию (память, диск, нагрузка)
+- Статус rollback-snapshot
+
+Кнопки управления: restart / stop / start / очистка состояния.

 ---

 ## Telegram прокси

-Прозрачное проксирование Telegram через Cloudflare WebSocket. Не требует настройки на устройствах — работает автоматически для всех устройств в сети.
+Прозрачное проксирование Telegram через Cloudflare WebSocket. Не требует настройки на устройствах — работает автоматически для всех устройств в сети. Поддерживает IPv4 и IPv6.

 Включается через меню `[T]`.

 ---

+## Пользовательские стратегии
+
+Для добавления собственных стратегий без модификации основного кода создайте файлы в директории:
+
+```
+/opt/zapret2/extra_strats/custom_strategies.d/
+```
+
+Формат файла: `CATEGORY_PROTOCOL.conf` (например `MYSITE_TCP.conf`), содержимое — параметры nfqws2.
+
+---
+
 ## Управление сервисом

 ```bash
@ -166,11 +255,60 @@ curl -fsSL https://raw.githubusercontent.com/necronicle/z2k/forge/z2k_cleanup.sh

 ---

+## Структура проекта
+
+```
+z2k/
+├── z2k.sh                      # Bootstrap / main installer
+├── z2k_cleanup.sh              # Complete uninstall
+├── strats_new2.txt             # TCP strategy database (45 strategies)
+├── quic_strats.ini             # UDP/QUIC strategy database
+├── lib/                        # Core modules
+│   ├── utils.sh                # Utilities, safe_config_read, checks
+│   ├── install.sh              # 12-step install + rollback
+│   ├── menu.sh                 # Interactive menu (15 options)
+│   ├── strategies.sh           # Strategy parsing & management
+│   ├── config.sh               # Configuration management
+│   ├── config_official.sh      # nfqws2 config generation
+│   └── system_init.sh          # System detection
+├── files/
+│   ├── S99zapret2.new          # Init script
+│   ├── fake/                   # Binary protocol blobs (76 files)
+│   ├── lua/
+│   │   ├── z2k-autocircular.lua    # Persistent strategy memory + telemetry
+│   │   └── z2k-modern-core.lua     # IP frag, QUIC morph, TLS shuffle, ECH
+│   ├── lists/                  # Domain lists (RKN, YouTube, Discord)
+│   ├── z2k-healthcheck.sh      # Service availability monitoring
+│   ├── z2k-config-validator.sh # Config validation
+│   ├── z2k-update-lists.sh     # Auto domain list updater
+│   ├── z2k-webpanel.sh         # Web monitoring CGI
+│   └── z2k-webpanel-install.sh # Web panel installer
+├── mtproxy-client/             # Telegram MTProxy (Go)
+│   ├── main.go                 # Obfuscated2 proxy + WS relay
+│   ├── transparent.go          # Transparent mode + DNS cache
+│   ├── listener.go             # SO_ORIGINAL_DST (IPv4 + IPv6)
+│   ├── dcmap.go                # Telegram DC IP mapping (v4 + v6)
+│   ├── relay.go                # Bidirectional MTProto relay
+│   ├── secret.go               # Secret key parsing
+│   └── main_test.go            # Unit tests (12 tests)
+├── tests/                      # Test framework
+│   ├── run_all.sh              # Test runner
+│   ├── test_utils.sh           # Utils tests (23 tests)
+│   ├── test_strategies.sh      # Strategy tests (21 tests)
+│   ├── test_config_official.sh # Config gen tests (24 tests)
+│   └── test_validator.sh       # Validator tests (18 tests)
+└── .github/workflows/ci.yml   # CI: shellcheck + go + luacheck
+```
+
+---
+
 ## Примечания

 - Если вы используете IPv6 в сети, убедитесь что он включён в прошивке (см. требования выше).
- Если в системе нет `cron`, автообновление списков может быть недоступно — обновляйте списки вручную.
+- Автообновление списков доменов — через cron (`/opt/zapret2/z2k-update-lists.sh`).
 - Если многие сайты не открываются — попробуйте включить Silent fallback через меню [F].
+- Валидация конфигурации доступна через `sh z2k.sh validate` или меню [V].
+- Для отката к предыдущей конфигурации используйте `sh z2k.sh rollback` или меню [B].

 ---