wolfram - Вклад [ru]

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-13T05:04:44Z

Владимир: /* Подключитесь по SSH к роутеру и выполните одну команду: */

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
[[Файл:Keenetic architecture overview.png|центр|мини|633x633пкс|Общая схема: keen-pbr по адресу домена решает, отправить трафик в туннель singtun (sing-box → VPN-сервер) или пустить через nfqws2 + прямой WAN.]]

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== Какая у вас прошивка ==
KeeneticOS существует в двух вариантах, и от этого зависит, нужен ли вам отдельный шаг включения компонентов прошивки.

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. подсекцию «Только для оригинального Keenetic» ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', всё уже в образе прошивки порта — пропускайте подсекцию ниже и сразу переходите к «Выбор URL установщика»
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как понять, какая у вас:''' На странице '''Системный монитор''' видна модель устройства. Маркетинговое имя "Keenetic Hero" и модель "KN-..." — это оригинальный Keenetic. Имя другого производителя (например, "Xiaomi R3G") + KeeneticOS — это порт сообщества. Дополнительный признак порта — на странице компонентов сообщение «Не удалось получить список компонентов от сервера» (своего сервера обновлений у порта нет).
</div>

== Только для оригинального Keenetic ==
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:

{| class="wikitable"
!Компонент
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|База Entware
|-
|'''Файловая система Ext'''
|Монтирование ext4-флешки
|-
|'''Сервер SSH'''
|Командная строка роутера
|-
|"Netfilter" / "Модули ядра Netfilter"
|База iptables для Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Доп. модули (<code>xt_set</code>, <code>xt_multiport</code>, <code>conntrack-extra</code>) — '''критично''' для keen-pbr
|}

После выбора — '''Установить обновление''' и ждите 2–5 минут, роутер перезагрузится сам.

== Выбор URL установщика ==
{| class="wikitable"
!Архитектура роутера
!URL установщика (одной строкой)
|-
|'''MIPS little-endian (mipsel)''' — большинство Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как узнать архитектуру:''' '''Системный монитор''' → видна модель и процессор. Большинство бытовых моделей — MIPS (верхняя строка). Сомневаетесь — берите mipsel; если не подходит, установщик ругнётся, роутер от этого не сломается.
</div>

== Что вам понадобится ==
Перед тем как идти в командную строку, держите под рукой два значения:

{| class="wikitable"
!Параметр
!Откуда взять
!Пример
|-
|'''UUID USB-диска'''
|<code>show media</code> в веб-CLI Keenetic (см. шаг 3 в 1.1), поле <code>uuid</code> внутри <code>partition</code>
|<code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>
|-
|'''URL установщика'''
|Из таблицы «Выбор URL установщика» выше — по архитектуре
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|}

== 1.1. Установка Entware через командную строку ==

# '''Подключите USB-флешку.''' Воткните флешку в USB-порт роутера. Откройте веб-интерфейс: '''Приложения → USB-диски и принтеры''' — диск должен появиться в списке. Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' → '''EXT4'''.
#: [[File:keenetic_usb_disks.png|center|Страница «USB-диски и принтеры» в веб-интерфейсе Keenetic с подключённой USB-флешкой и опцией «Форматировать» в EXT4.|мини|994x994пкс]]
# '''Откройте встроенный веб-CLI Keenetic:''' <code>http://192.168.1.1/a</code> (или подставьте свой LAN-IP роутера, если он другой). Должно появиться приглашение <code>(config)></code>.
# '''Узнайте UUID диска:'''
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
#: В ответе найдите блок с вашей флешкой и поле <code>uuid</code> внутри <code>partition</code>. Длинная строка вида <code>d5f39712-...</code> — это и есть нужное значение, скопируйте его.
# '''Запустите установку Entware.''' Подставьте '''свой UUID''' и '''URL по архитектуре''' (из таблицы «Выбор URL установщика» выше):
#: <syntaxhighlight lang="bash">opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ></syntaxhighlight>
#: Пример с реальными подставленными значениями (mipsel):
#: <syntaxhighlight lang="bash">opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</syntaxhighlight>
#: '''Угловых скобок <code><</code><code>></code> в финальной команде остаться не должно.''' Двоеточие и слэш <code>:/</code> сразу после UUID — обязательны. После UUID и перед URL — ровно один пробел.
# '''Сразу включите DNS-override и сохраните конфиг:'''
#: <syntaxhighlight lang="bash">opkg dns-override
system configuration save</syntaxhighlight>
#: <code>opkg dns-override</code> заставит KeeneticOS отдавать DNS-запросы клиентов в Entware-овский dnsmasq, который потом будет управляться keen-pbr. Без этого keen-pbr не сможет перехватывать DNS и маршрутизация по доменам работать не будет. Опция применится после reboot ниже.
# '''Дождитесь окончания установки.''' Откройте журнал в веб-интерфейсе: <code>http://192.168.1.1/diagnostics/general/log</code> (если LAN-IP другой — подставьте). Установщик пишет туда что делает: качает <code>installer.tar.gz</code>, распаковывает в <code>/opt</code>, ставит базовые пакеты. Это занимает 2–5 минут. Ждите финальной строки <code>Entware installed</code>.
#: [[File:keenetic_log_entware_installed.png|center|Системный журнал Keenetic (/diagnostics/general/log) с финальной строкой «Entware installed» — установка завершилась успешно, можно перезагружать роутер.|мини|804x804пкс]]
#: <div style="padding: 8px 12px; margin: 8px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">'''Не перезагружайте роутер до этой строки в журнале!''' Если ребутнуть роутер посреди установки, файлы Entware на флешке останутся неконсистентными, и на следующих этапах посыпятся странные ошибки.</div>
# '''Перезагрузите роутер из веб-CLI:'''
#: <syntaxhighlight lang="bash">system reboot</syntaxhighlight>
#: Через 1–2 минуты роутер поднимется обратно. После reboot применятся: монтирование Entware с флешки в <code>/opt</code>, автозапуск его сервисов, а главное — <code>opkg dns-override</code> из шага 5.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Если установщик молчит:''' В некоторых сборках команда <code>opkg disk ... URL</code> молчит, если OPKG-диск уже был назначен раньше. В журнале нет строк про загрузку <code>installer.tar.gz</code>? Сбросьте назначение диска и повторите шаги 4–5:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk <ВАШ_UUID>:/ <URL>
opkg dns-override
system configuration save
</syntaxhighlight>
</div>

== 1.2. Первое подключение по SSH ==

После перезагрузки Entware поднимает встроенный SSH-сервер на порту '''222'''.

На Windows — открываете PowerShell и подключаетесь одной командой:

<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

(LAN-IP роутера другой — подставьте.)

Параметры подключения:

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|LAN-IP роутера (<code>192.168.1.1</code> по умолчанию)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code> (заводской)
|}

При первом подключении SSH спросит fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>
Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' дефолтный <code>keenetic</code> известен всем. Если SSH когда-нибудь будет проброшен наружу — роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите ходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце документа. Для базовой установки это '''не нужно''' — переходите к Этапу 2.
</div>

----

'''Всё готово для установки утилит.''' Переходите к Этапу 2.

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Так как у нас первый чистый запуск нужно установить несколько стандартных вещей:<syntaxhighlight lang="bash">
opkg update
opkg install wget-ssl curl
</syntaxhighlight>Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.
[[Файл:Singbox-helper-g.png|центр|мини|1034x1034пкс|Главный экран приложения Singbox-helper]]
На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.
[[Файл:Singbox-helper-con.png|центр|мини|850x850пкс|Пример успешного подключения в Singbox-helper]]
Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.
[[Файл:Keen-pbr-g.png|центр|мини|1043x1043пкс|Keen-pbr - пример главного экрана]]

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

[[File:keenpbr_outbounds.png|center|Страница «Outbounds (выходы)» в веб-интерфейсе keen-pbr со списком из трёх выходов: wan, block, vpn (interface=singtun).|мини|1005x1005пкс]]

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.

Такие можно брать на '''[https://github.com/itdoginfo/allow-domains allow-domains]''' - тот же podckop использует именно эти списки "Russia inside, Telegram и так далее.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Дополнение:''' <code>bypass</code> это первый список что мы создали, их может быть сколько угодно, можно добавлять несколько. Например создать Russia inside на основе raw ссылки, и Telegram на основе Subnets.
</div>

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
sh /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

</syntaxhighlight>

Последняя строка запустит скрипт в первый раз принудительно.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>[http://192.168.10.1:90 http://192.168.1.1:90]</code>.

Ввести логин и пароль, те же что применяются для входа по ssh.
[[Файл:Nfqws2-g-p.png|центр|мини|914x914пкс|Пример главного окна Nfqws2]]
----

= Финальная архитектура =
[[Файл:Keenetic architecture detailed.png|центр|мини|1031x1031пкс|Полная схема трафика через роутер: DNS-запросы клиента идут в keen-pbr dnsmasq → Quad9, ответы накапливаются в ipset; TCP-трафик в iptables маркируется и уходит либо в singtun (sing-box → VPN-узел), либо через WAN с DPI-обходом nfqws2.]]
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T20:37:22Z

Владимир: /* Шаг 3. Создать правило маршрутизации */

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
[[Файл:Keenetic architecture overview.png|центр|мини|633x633пкс|Общая схема: keen-pbr по адресу домена решает, отправить трафик в туннель singtun (sing-box → VPN-сервер) или пустить через nfqws2 + прямой WAN.]]

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== Какая у вас прошивка ==
KeeneticOS существует в двух вариантах, и от этого зависит, нужен ли вам отдельный шаг включения компонентов прошивки.

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. подсекцию «Только для оригинального Keenetic» ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', всё уже в образе прошивки порта — пропускайте подсекцию ниже и сразу переходите к «Выбор URL установщика»
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как понять, какая у вас:''' На странице '''Системный монитор''' видна модель устройства. Маркетинговое имя "Keenetic Hero" и модель "KN-..." — это оригинальный Keenetic. Имя другого производителя (например, "Xiaomi R3G") + KeeneticOS — это порт сообщества. Дополнительный признак порта — на странице компонентов сообщение «Не удалось получить список компонентов от сервера» (своего сервера обновлений у порта нет).
</div>

== Только для оригинального Keenetic ==
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:

{| class="wikitable"
!Компонент
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|База Entware
|-
|'''Файловая система Ext'''
|Монтирование ext4-флешки
|-
|'''Сервер SSH'''
|Командная строка роутера
|-
|"Netfilter" / "Модули ядра Netfilter"
|База iptables для Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Доп. модули (<code>xt_set</code>, <code>xt_multiport</code>, <code>conntrack-extra</code>) — '''критично''' для keen-pbr
|}

После выбора — '''Установить обновление''' и ждите 2–5 минут, роутер перезагрузится сам.

== Выбор URL установщика ==
{| class="wikitable"
!Архитектура роутера
!URL установщика (одной строкой)
|-
|'''MIPS little-endian (mipsel)''' — большинство Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как узнать архитектуру:''' '''Системный монитор''' → видна модель и процессор. Большинство бытовых моделей — MIPS (верхняя строка). Сомневаетесь — берите mipsel; если не подходит, установщик ругнётся, роутер от этого не сломается.
</div>

== Что вам понадобится ==
Перед тем как идти в командную строку, держите под рукой два значения:

{| class="wikitable"
!Параметр
!Откуда взять
!Пример
|-
|'''UUID USB-диска'''
|<code>show media</code> в веб-CLI Keenetic (см. шаг 3 в 1.1), поле <code>uuid</code> внутри <code>partition</code>
|<code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>
|-
|'''URL установщика'''
|Из таблицы «Выбор URL установщика» выше — по архитектуре
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|}

== 1.1. Установка Entware через командную строку ==

# '''Подключите USB-флешку.''' Воткните флешку в USB-порт роутера. Откройте веб-интерфейс: '''Приложения → USB-диски и принтеры''' — диск должен появиться в списке. Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' → '''EXT4'''.
#: [[File:keenetic_usb_disks.png|center|Страница «USB-диски и принтеры» в веб-интерфейсе Keenetic с подключённой USB-флешкой и опцией «Форматировать» в EXT4.|мини|994x994пкс]]
# '''Откройте встроенный веб-CLI Keenetic:''' <code>http://192.168.1.1/a</code> (или подставьте свой LAN-IP роутера, если он другой). Должно появиться приглашение <code>(config)></code>.
# '''Узнайте UUID диска:'''
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
#: В ответе найдите блок с вашей флешкой и поле <code>uuid</code> внутри <code>partition</code>. Длинная строка вида <code>d5f39712-...</code> — это и есть нужное значение, скопируйте его.
# '''Запустите установку Entware.''' Подставьте '''свой UUID''' и '''URL по архитектуре''' (из таблицы «Выбор URL установщика» выше):
#: <syntaxhighlight lang="bash">opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ></syntaxhighlight>
#: Пример с реальными подставленными значениями (mipsel):
#: <syntaxhighlight lang="bash">opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</syntaxhighlight>
#: '''Угловых скобок <code><</code><code>></code> в финальной команде остаться не должно.''' Двоеточие и слэш <code>:/</code> сразу после UUID — обязательны. После UUID и перед URL — ровно один пробел.
# '''Сразу включите DNS-override и сохраните конфиг:'''
#: <syntaxhighlight lang="bash">opkg dns-override
system configuration save</syntaxhighlight>
#: <code>opkg dns-override</code> заставит KeeneticOS отдавать DNS-запросы клиентов в Entware-овский dnsmasq, который потом будет управляться keen-pbr. Без этого keen-pbr не сможет перехватывать DNS и маршрутизация по доменам работать не будет. Опция применится после reboot ниже.
# '''Дождитесь окончания установки.''' Откройте журнал в веб-интерфейсе: <code>http://192.168.1.1/diagnostics/general/log</code> (если LAN-IP другой — подставьте). Установщик пишет туда что делает: качает <code>installer.tar.gz</code>, распаковывает в <code>/opt</code>, ставит базовые пакеты. Это занимает 2–5 минут. Ждите финальной строки <code>Entware installed</code>.
#: [[File:keenetic_log_entware_installed.png|center|Системный журнал Keenetic (/diagnostics/general/log) с финальной строкой «Entware installed» — установка завершилась успешно, можно перезагружать роутер.|мини|804x804пкс]]
#: <div style="padding: 8px 12px; margin: 8px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">'''Не перезагружайте роутер до этой строки в журнале!''' Если ребутнуть роутер посреди установки, файлы Entware на флешке останутся неконсистентными, и на следующих этапах посыпятся странные ошибки.</div>
# '''Перезагрузите роутер из веб-CLI:'''
#: <syntaxhighlight lang="bash">system reboot</syntaxhighlight>
#: Через 1–2 минуты роутер поднимется обратно. После reboot применятся: монтирование Entware с флешки в <code>/opt</code>, автозапуск его сервисов, а главное — <code>opkg dns-override</code> из шага 5.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Если установщик молчит:''' В некоторых сборках команда <code>opkg disk ... URL</code> молчит, если OPKG-диск уже был назначен раньше. В журнале нет строк про загрузку <code>installer.tar.gz</code>? Сбросьте назначение диска и повторите шаги 4–5:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk <ВАШ_UUID>:/ <URL>
opkg dns-override
system configuration save
</syntaxhighlight>
</div>

== 1.2. Первое подключение по SSH ==

После перезагрузки Entware поднимает встроенный SSH-сервер на порту '''222'''.

На Windows — открываете PowerShell и подключаетесь одной командой:

<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

(LAN-IP роутера другой — подставьте.)

Параметры подключения:

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|LAN-IP роутера (<code>192.168.1.1</code> по умолчанию)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code> (заводской)
|}

При первом подключении SSH спросит fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>
Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' дефолтный <code>keenetic</code> известен всем. Если SSH когда-нибудь будет проброшен наружу — роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите ходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце документа. Для базовой установки это '''не нужно''' — переходите к Этапу 2.
</div>

----

'''Всё готово для установки утилит.''' Переходите к Этапу 2.

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Так как у нас первый чистый запуск нужно установить несколько стандартных вещей:<syntaxhighlight lang="bash">
opkg update
opkg install wget-ssl curl
</syntaxhighlight>Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.
[[Файл:Singbox-helper-g.png|центр|мини|1034x1034пкс|Главный экран приложения Singbox-helper]]
На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.
[[Файл:Singbox-helper-con.png|центр|мини|850x850пкс|Пример успешного подключения в Singbox-helper]]
Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.
[[Файл:Keen-pbr-g.png|центр|мини|1043x1043пкс|Keen-pbr - пример главного экрана]]

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

[[File:keenpbr_outbounds.png|center|Страница «Outbounds (выходы)» в веб-интерфейсе keen-pbr со списком из трёх выходов: wan, block, vpn (interface=singtun).|мини|1005x1005пкс]]

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.

Такие можно брать на '''[https://github.com/itdoginfo/allow-domains allow-domains]''' - тот же podckop использует именно эти списки "Russia inside, Telegram и так далее.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Дополнение:''' <code>bypass</code> это первый список что мы создали, их может быть сколько угодно, можно добавлять несколько. Например создать Russia inside на основе raw ссылки, и Telegram на основе Subnets.
</div>

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
sh /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>[http://192.168.10.1:90 http://192.168.1.1:90]</code>.

Ввести логин и пароль, те же что применяются для входа по ssh.
[[Файл:Nfqws2-g-p.png|центр|мини|914x914пкс|Пример главного окна Nfqws2]]
----

= Финальная архитектура =
[[Файл:Keenetic architecture detailed.png|центр|мини|1031x1031пкс|Полная схема трафика через роутер: DNS-запросы клиента идут в keen-pbr dnsmasq → Quad9, ответы накапливаются в ipset; TCP-трафик в iptables маркируется и уходит либо в singtun (sing-box → VPN-узел), либо через WAN с DPI-обходом nfqws2.]]
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T20:33:37Z

Владимир: /* Шаг 2. Создать список доменов */

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
[[Файл:Keenetic architecture overview.png|центр|мини|633x633пкс|Общая схема: keen-pbr по адресу домена решает, отправить трафик в туннель singtun (sing-box → VPN-сервер) или пустить через nfqws2 + прямой WAN.]]

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== Какая у вас прошивка ==
KeeneticOS существует в двух вариантах, и от этого зависит, нужен ли вам отдельный шаг включения компонентов прошивки.

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. подсекцию «Только для оригинального Keenetic» ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', всё уже в образе прошивки порта — пропускайте подсекцию ниже и сразу переходите к «Выбор URL установщика»
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как понять, какая у вас:''' На странице '''Системный монитор''' видна модель устройства. Маркетинговое имя "Keenetic Hero" и модель "KN-..." — это оригинальный Keenetic. Имя другого производителя (например, "Xiaomi R3G") + KeeneticOS — это порт сообщества. Дополнительный признак порта — на странице компонентов сообщение «Не удалось получить список компонентов от сервера» (своего сервера обновлений у порта нет).
</div>

== Только для оригинального Keenetic ==
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:

{| class="wikitable"
!Компонент
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|База Entware
|-
|'''Файловая система Ext'''
|Монтирование ext4-флешки
|-
|'''Сервер SSH'''
|Командная строка роутера
|-
|"Netfilter" / "Модули ядра Netfilter"
|База iptables для Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Доп. модули (<code>xt_set</code>, <code>xt_multiport</code>, <code>conntrack-extra</code>) — '''критично''' для keen-pbr
|}

После выбора — '''Установить обновление''' и ждите 2–5 минут, роутер перезагрузится сам.

== Выбор URL установщика ==
{| class="wikitable"
!Архитектура роутера
!URL установщика (одной строкой)
|-
|'''MIPS little-endian (mipsel)''' — большинство Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как узнать архитектуру:''' '''Системный монитор''' → видна модель и процессор. Большинство бытовых моделей — MIPS (верхняя строка). Сомневаетесь — берите mipsel; если не подходит, установщик ругнётся, роутер от этого не сломается.
</div>

== Что вам понадобится ==
Перед тем как идти в командную строку, держите под рукой два значения:

{| class="wikitable"
!Параметр
!Откуда взять
!Пример
|-
|'''UUID USB-диска'''
|<code>show media</code> в веб-CLI Keenetic (см. шаг 3 в 1.1), поле <code>uuid</code> внутри <code>partition</code>
|<code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>
|-
|'''URL установщика'''
|Из таблицы «Выбор URL установщика» выше — по архитектуре
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|}

== 1.1. Установка Entware через командную строку ==

# '''Подключите USB-флешку.''' Воткните флешку в USB-порт роутера. Откройте веб-интерфейс: '''Приложения → USB-диски и принтеры''' — диск должен появиться в списке. Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' → '''EXT4'''.
#: [[File:keenetic_usb_disks.png|center|Страница «USB-диски и принтеры» в веб-интерфейсе Keenetic с подключённой USB-флешкой и опцией «Форматировать» в EXT4.|мини|994x994пкс]]
# '''Откройте встроенный веб-CLI Keenetic:''' <code>http://192.168.1.1/a</code> (или подставьте свой LAN-IP роутера, если он другой). Должно появиться приглашение <code>(config)></code>.
# '''Узнайте UUID диска:'''
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
#: В ответе найдите блок с вашей флешкой и поле <code>uuid</code> внутри <code>partition</code>. Длинная строка вида <code>d5f39712-...</code> — это и есть нужное значение, скопируйте его.
# '''Запустите установку Entware.''' Подставьте '''свой UUID''' и '''URL по архитектуре''' (из таблицы «Выбор URL установщика» выше):
#: <syntaxhighlight lang="bash">opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ></syntaxhighlight>
#: Пример с реальными подставленными значениями (mipsel):
#: <syntaxhighlight lang="bash">opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</syntaxhighlight>
#: '''Угловых скобок <code><</code><code>></code> в финальной команде остаться не должно.''' Двоеточие и слэш <code>:/</code> сразу после UUID — обязательны. После UUID и перед URL — ровно один пробел.
# '''Сразу включите DNS-override и сохраните конфиг:'''
#: <syntaxhighlight lang="bash">opkg dns-override
system configuration save</syntaxhighlight>
#: <code>opkg dns-override</code> заставит KeeneticOS отдавать DNS-запросы клиентов в Entware-овский dnsmasq, который потом будет управляться keen-pbr. Без этого keen-pbr не сможет перехватывать DNS и маршрутизация по доменам работать не будет. Опция применится после reboot ниже.
# '''Дождитесь окончания установки.''' Откройте журнал в веб-интерфейсе: <code>http://192.168.1.1/diagnostics/general/log</code> (если LAN-IP другой — подставьте). Установщик пишет туда что делает: качает <code>installer.tar.gz</code>, распаковывает в <code>/opt</code>, ставит базовые пакеты. Это занимает 2–5 минут. Ждите финальной строки <code>Entware installed</code>.
#: [[File:keenetic_log_entware_installed.png|center|Системный журнал Keenetic (/diagnostics/general/log) с финальной строкой «Entware installed» — установка завершилась успешно, можно перезагружать роутер.|мини|804x804пкс]]
#: <div style="padding: 8px 12px; margin: 8px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">'''Не перезагружайте роутер до этой строки в журнале!''' Если ребутнуть роутер посреди установки, файлы Entware на флешке останутся неконсистентными, и на следующих этапах посыпятся странные ошибки.</div>
# '''Перезагрузите роутер из веб-CLI:'''
#: <syntaxhighlight lang="bash">system reboot</syntaxhighlight>
#: Через 1–2 минуты роутер поднимется обратно. После reboot применятся: монтирование Entware с флешки в <code>/opt</code>, автозапуск его сервисов, а главное — <code>opkg dns-override</code> из шага 5.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Если установщик молчит:''' В некоторых сборках команда <code>opkg disk ... URL</code> молчит, если OPKG-диск уже был назначен раньше. В журнале нет строк про загрузку <code>installer.tar.gz</code>? Сбросьте назначение диска и повторите шаги 4–5:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk <ВАШ_UUID>:/ <URL>
opkg dns-override
system configuration save
</syntaxhighlight>
</div>

== 1.2. Первое подключение по SSH ==

После перезагрузки Entware поднимает встроенный SSH-сервер на порту '''222'''.

На Windows — открываете PowerShell и подключаетесь одной командой:

<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

(LAN-IP роутера другой — подставьте.)

Параметры подключения:

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|LAN-IP роутера (<code>192.168.1.1</code> по умолчанию)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code> (заводской)
|}

При первом подключении SSH спросит fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>
Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' дефолтный <code>keenetic</code> известен всем. Если SSH когда-нибудь будет проброшен наружу — роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите ходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце документа. Для базовой установки это '''не нужно''' — переходите к Этапу 2.
</div>

----

'''Всё готово для установки утилит.''' Переходите к Этапу 2.

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Так как у нас первый чистый запуск нужно установить несколько стандартных вещей:<syntaxhighlight lang="bash">
opkg update
opkg install wget-ssl curl
</syntaxhighlight>Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.
[[Файл:Singbox-helper-g.png|центр|мини|1034x1034пкс|Главный экран приложения Singbox-helper]]
На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.
[[Файл:Singbox-helper-con.png|центр|мини|850x850пкс|Пример успешного подключения в Singbox-helper]]
Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.
[[Файл:Keen-pbr-g.png|центр|мини|1043x1043пкс|Keen-pbr - пример главного экрана]]

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

[[File:keenpbr_outbounds.png|center|Страница «Outbounds (выходы)» в веб-интерфейсе keen-pbr со списком из трёх выходов: wan, block, vpn (interface=singtun).|мини|1005x1005пкс]]

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.

Такие можно брать на '''[https://github.com/itdoginfo/allow-domains allow-domains]''' - тот же podckop использует именно эти списки "Russia inside, Russia Outside и так далее.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
sh /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>[http://192.168.10.1:90 http://192.168.1.1:90]</code>.

Ввести логин и пароль, те же что применяются для входа по ssh.
[[Файл:Nfqws2-g-p.png|центр|мини|914x914пкс|Пример главного окна Nfqws2]]
----

= Финальная архитектура =
[[Файл:Keenetic architecture detailed.png|центр|мини|1031x1031пкс|Полная схема трафика через роутер: DNS-запросы клиента идут в keen-pbr dnsmasq → Quad9, ответы накапливаются в ipset; TCP-трафик в iptables маркируется и уходит либо в singtun (sing-box → VPN-узел), либо через WAN с DPI-обходом nfqws2.]]
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T20:28:58Z

Владимир: /* 2.3. Применение узла */

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
[[Файл:Keenetic architecture overview.png|центр|мини|633x633пкс|Общая схема: keen-pbr по адресу домена решает, отправить трафик в туннель singtun (sing-box → VPN-сервер) или пустить через nfqws2 + прямой WAN.]]

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== Какая у вас прошивка ==
KeeneticOS существует в двух вариантах, и от этого зависит, нужен ли вам отдельный шаг включения компонентов прошивки.

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. подсекцию «Только для оригинального Keenetic» ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', всё уже в образе прошивки порта — пропускайте подсекцию ниже и сразу переходите к «Выбор URL установщика»
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как понять, какая у вас:''' На странице '''Системный монитор''' видна модель устройства. Маркетинговое имя "Keenetic Hero" и модель "KN-..." — это оригинальный Keenetic. Имя другого производителя (например, "Xiaomi R3G") + KeeneticOS — это порт сообщества. Дополнительный признак порта — на странице компонентов сообщение «Не удалось получить список компонентов от сервера» (своего сервера обновлений у порта нет).
</div>

== Только для оригинального Keenetic ==
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:

{| class="wikitable"
!Компонент
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|База Entware
|-
|'''Файловая система Ext'''
|Монтирование ext4-флешки
|-
|'''Сервер SSH'''
|Командная строка роутера
|-
|"Netfilter" / "Модули ядра Netfilter"
|База iptables для Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Доп. модули (<code>xt_set</code>, <code>xt_multiport</code>, <code>conntrack-extra</code>) — '''критично''' для keen-pbr
|}

После выбора — '''Установить обновление''' и ждите 2–5 минут, роутер перезагрузится сам.

== Выбор URL установщика ==
{| class="wikitable"
!Архитектура роутера
!URL установщика (одной строкой)
|-
|'''MIPS little-endian (mipsel)''' — большинство Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как узнать архитектуру:''' '''Системный монитор''' → видна модель и процессор. Большинство бытовых моделей — MIPS (верхняя строка). Сомневаетесь — берите mipsel; если не подходит, установщик ругнётся, роутер от этого не сломается.
</div>

== Что вам понадобится ==
Перед тем как идти в командную строку, держите под рукой два значения:

{| class="wikitable"
!Параметр
!Откуда взять
!Пример
|-
|'''UUID USB-диска'''
|<code>show media</code> в веб-CLI Keenetic (см. шаг 3 в 1.1), поле <code>uuid</code> внутри <code>partition</code>
|<code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>
|-
|'''URL установщика'''
|Из таблицы «Выбор URL установщика» выше — по архитектуре
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|}

== 1.1. Установка Entware через командную строку ==

# '''Подключите USB-флешку.''' Воткните флешку в USB-порт роутера. Откройте веб-интерфейс: '''Приложения → USB-диски и принтеры''' — диск должен появиться в списке. Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' → '''EXT4'''.
#: [[File:keenetic_usb_disks.png|center|Страница «USB-диски и принтеры» в веб-интерфейсе Keenetic с подключённой USB-флешкой и опцией «Форматировать» в EXT4.|мини|994x994пкс]]
# '''Откройте встроенный веб-CLI Keenetic:''' <code>http://192.168.1.1/a</code> (или подставьте свой LAN-IP роутера, если он другой). Должно появиться приглашение <code>(config)></code>.
# '''Узнайте UUID диска:'''
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
#: В ответе найдите блок с вашей флешкой и поле <code>uuid</code> внутри <code>partition</code>. Длинная строка вида <code>d5f39712-...</code> — это и есть нужное значение, скопируйте его.
# '''Запустите установку Entware.''' Подставьте '''свой UUID''' и '''URL по архитектуре''' (из таблицы «Выбор URL установщика» выше):
#: <syntaxhighlight lang="bash">opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ></syntaxhighlight>
#: Пример с реальными подставленными значениями (mipsel):
#: <syntaxhighlight lang="bash">opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</syntaxhighlight>
#: '''Угловых скобок <code><</code><code>></code> в финальной команде остаться не должно.''' Двоеточие и слэш <code>:/</code> сразу после UUID — обязательны. После UUID и перед URL — ровно один пробел.
# '''Сразу включите DNS-override и сохраните конфиг:'''
#: <syntaxhighlight lang="bash">opkg dns-override
system configuration save</syntaxhighlight>
#: <code>opkg dns-override</code> заставит KeeneticOS отдавать DNS-запросы клиентов в Entware-овский dnsmasq, который потом будет управляться keen-pbr. Без этого keen-pbr не сможет перехватывать DNS и маршрутизация по доменам работать не будет. Опция применится после reboot ниже.
# '''Дождитесь окончания установки.''' Откройте журнал в веб-интерфейсе: <code>http://192.168.1.1/diagnostics/general/log</code> (если LAN-IP другой — подставьте). Установщик пишет туда что делает: качает <code>installer.tar.gz</code>, распаковывает в <code>/opt</code>, ставит базовые пакеты. Это занимает 2–5 минут. Ждите финальной строки <code>Entware installed</code>.
#: [[File:keenetic_log_entware_installed.png|center|Системный журнал Keenetic (/diagnostics/general/log) с финальной строкой «Entware installed» — установка завершилась успешно, можно перезагружать роутер.|мини|804x804пкс]]
#: <div style="padding: 8px 12px; margin: 8px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">'''Не перезагружайте роутер до этой строки в журнале!''' Если ребутнуть роутер посреди установки, файлы Entware на флешке останутся неконсистентными, и на следующих этапах посыпятся странные ошибки.</div>
# '''Перезагрузите роутер из веб-CLI:'''
#: <syntaxhighlight lang="bash">system reboot</syntaxhighlight>
#: Через 1–2 минуты роутер поднимется обратно. После reboot применятся: монтирование Entware с флешки в <code>/opt</code>, автозапуск его сервисов, а главное — <code>opkg dns-override</code> из шага 5.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Если установщик молчит:''' В некоторых сборках команда <code>opkg disk ... URL</code> молчит, если OPKG-диск уже был назначен раньше. В журнале нет строк про загрузку <code>installer.tar.gz</code>? Сбросьте назначение диска и повторите шаги 4–5:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk <ВАШ_UUID>:/ <URL>
opkg dns-override
system configuration save
</syntaxhighlight>
</div>

== 1.2. Первое подключение по SSH ==

После перезагрузки Entware поднимает встроенный SSH-сервер на порту '''222'''.

На Windows — открываете PowerShell и подключаетесь одной командой:

<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

(LAN-IP роутера другой — подставьте.)

Параметры подключения:

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|LAN-IP роутера (<code>192.168.1.1</code> по умолчанию)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code> (заводской)
|}

При первом подключении SSH спросит fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>
Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' дефолтный <code>keenetic</code> известен всем. Если SSH когда-нибудь будет проброшен наружу — роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите ходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце документа. Для базовой установки это '''не нужно''' — переходите к Этапу 2.
</div>

----

'''Всё готово для установки утилит.''' Переходите к Этапу 2.

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Так как у нас первый чистый запуск нужно установить несколько стандартных вещей:<syntaxhighlight lang="bash">
opkg update
opkg install wget-ssl curl
</syntaxhighlight>Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.
[[Файл:Singbox-helper-g.png|центр|мини|1034x1034пкс|Главный экран приложения Singbox-helper]]
На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.
[[Файл:Singbox-helper-con.png|центр|мини|850x850пкс|Пример успешного подключения в Singbox-helper]]
Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.
[[Файл:Keen-pbr-g.png|центр|мини|1043x1043пкс|Keen-pbr - пример главного экрана]]

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

[[File:keenpbr_outbounds.png|center|Страница «Outbounds (выходы)» в веб-интерфейсе keen-pbr со списком из трёх выходов: wan, block, vpn (interface=singtun).|мини|1005x1005пкс]]

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
sh /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>[http://192.168.10.1:90 http://192.168.1.1:90]</code>.

Ввести логин и пароль, те же что применяются для входа по ssh.
[[Файл:Nfqws2-g-p.png|центр|мини|914x914пкс|Пример главного окна Nfqws2]]
----

= Финальная архитектура =
[[Файл:Keenetic architecture detailed.png|центр|мини|1031x1031пкс|Полная схема трафика через роутер: DNS-запросы клиента идут в keen-pbr dnsmasq → Quad9, ответы накапливаются в ipset; TCP-трафик в iptables маркируется и уходит либо в singtun (sing-box → VPN-узел), либо через WAN с DPI-обходом nfqws2.]]
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T20:25:53Z

Владимир: /* 2.1. Подключение фида singbox-helper и установка */

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
[[Файл:Keenetic architecture overview.png|центр|мини|633x633пкс|Общая схема: keen-pbr по адресу домена решает, отправить трафик в туннель singtun (sing-box → VPN-сервер) или пустить через nfqws2 + прямой WAN.]]

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== Какая у вас прошивка ==
KeeneticOS существует в двух вариантах, и от этого зависит, нужен ли вам отдельный шаг включения компонентов прошивки.

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. подсекцию «Только для оригинального Keenetic» ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', всё уже в образе прошивки порта — пропускайте подсекцию ниже и сразу переходите к «Выбор URL установщика»
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как понять, какая у вас:''' На странице '''Системный монитор''' видна модель устройства. Маркетинговое имя "Keenetic Hero" и модель "KN-..." — это оригинальный Keenetic. Имя другого производителя (например, "Xiaomi R3G") + KeeneticOS — это порт сообщества. Дополнительный признак порта — на странице компонентов сообщение «Не удалось получить список компонентов от сервера» (своего сервера обновлений у порта нет).
</div>

== Только для оригинального Keenetic ==
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:

{| class="wikitable"
!Компонент
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|База Entware
|-
|'''Файловая система Ext'''
|Монтирование ext4-флешки
|-
|'''Сервер SSH'''
|Командная строка роутера
|-
|"Netfilter" / "Модули ядра Netfilter"
|База iptables для Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Доп. модули (<code>xt_set</code>, <code>xt_multiport</code>, <code>conntrack-extra</code>) — '''критично''' для keen-pbr
|}

После выбора — '''Установить обновление''' и ждите 2–5 минут, роутер перезагрузится сам.

== Выбор URL установщика ==
{| class="wikitable"
!Архитектура роутера
!URL установщика (одной строкой)
|-
|'''MIPS little-endian (mipsel)''' — большинство Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как узнать архитектуру:''' '''Системный монитор''' → видна модель и процессор. Большинство бытовых моделей — MIPS (верхняя строка). Сомневаетесь — берите mipsel; если не подходит, установщик ругнётся, роутер от этого не сломается.
</div>

== Что вам понадобится ==
Перед тем как идти в командную строку, держите под рукой два значения:

{| class="wikitable"
!Параметр
!Откуда взять
!Пример
|-
|'''UUID USB-диска'''
|<code>show media</code> в веб-CLI Keenetic (см. шаг 3 в 1.1), поле <code>uuid</code> внутри <code>partition</code>
|<code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>
|-
|'''URL установщика'''
|Из таблицы «Выбор URL установщика» выше — по архитектуре
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|}

== 1.1. Установка Entware через командную строку ==

# '''Подключите USB-флешку.''' Воткните флешку в USB-порт роутера. Откройте веб-интерфейс: '''Приложения → USB-диски и принтеры''' — диск должен появиться в списке. Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' → '''EXT4'''.
#: [[File:keenetic_usb_disks.png|center|Страница «USB-диски и принтеры» в веб-интерфейсе Keenetic с подключённой USB-флешкой и опцией «Форматировать» в EXT4.|мини|994x994пкс]]
# '''Откройте встроенный веб-CLI Keenetic:''' <code>http://192.168.1.1/a</code> (или подставьте свой LAN-IP роутера, если он другой). Должно появиться приглашение <code>(config)></code>.
# '''Узнайте UUID диска:'''
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
#: В ответе найдите блок с вашей флешкой и поле <code>uuid</code> внутри <code>partition</code>. Длинная строка вида <code>d5f39712-...</code> — это и есть нужное значение, скопируйте его.
# '''Запустите установку Entware.''' Подставьте '''свой UUID''' и '''URL по архитектуре''' (из таблицы «Выбор URL установщика» выше):
#: <syntaxhighlight lang="bash">opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ></syntaxhighlight>
#: Пример с реальными подставленными значениями (mipsel):
#: <syntaxhighlight lang="bash">opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</syntaxhighlight>
#: '''Угловых скобок <code><</code><code>></code> в финальной команде остаться не должно.''' Двоеточие и слэш <code>:/</code> сразу после UUID — обязательны. После UUID и перед URL — ровно один пробел.
# '''Сразу включите DNS-override и сохраните конфиг:'''
#: <syntaxhighlight lang="bash">opkg dns-override
system configuration save</syntaxhighlight>
#: <code>opkg dns-override</code> заставит KeeneticOS отдавать DNS-запросы клиентов в Entware-овский dnsmasq, который потом будет управляться keen-pbr. Без этого keen-pbr не сможет перехватывать DNS и маршрутизация по доменам работать не будет. Опция применится после reboot ниже.
# '''Дождитесь окончания установки.''' Откройте журнал в веб-интерфейсе: <code>http://192.168.1.1/diagnostics/general/log</code> (если LAN-IP другой — подставьте). Установщик пишет туда что делает: качает <code>installer.tar.gz</code>, распаковывает в <code>/opt</code>, ставит базовые пакеты. Это занимает 2–5 минут. Ждите финальной строки <code>Entware installed</code>.
#: [[File:keenetic_log_entware_installed.png|center|Системный журнал Keenetic (/diagnostics/general/log) с финальной строкой «Entware installed» — установка завершилась успешно, можно перезагружать роутер.|мини|804x804пкс]]
#: <div style="padding: 8px 12px; margin: 8px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">'''Не перезагружайте роутер до этой строки в журнале!''' Если ребутнуть роутер посреди установки, файлы Entware на флешке останутся неконсистентными, и на следующих этапах посыпятся странные ошибки.</div>
# '''Перезагрузите роутер из веб-CLI:'''
#: <syntaxhighlight lang="bash">system reboot</syntaxhighlight>
#: Через 1–2 минуты роутер поднимется обратно. После reboot применятся: монтирование Entware с флешки в <code>/opt</code>, автозапуск его сервисов, а главное — <code>opkg dns-override</code> из шага 5.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Если установщик молчит:''' В некоторых сборках команда <code>opkg disk ... URL</code> молчит, если OPKG-диск уже был назначен раньше. В журнале нет строк про загрузку <code>installer.tar.gz</code>? Сбросьте назначение диска и повторите шаги 4–5:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk <ВАШ_UUID>:/ <URL>
opkg dns-override
system configuration save
</syntaxhighlight>
</div>

== 1.2. Первое подключение по SSH ==

После перезагрузки Entware поднимает встроенный SSH-сервер на порту '''222'''.

На Windows — открываете PowerShell и подключаетесь одной командой:

<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

(LAN-IP роутера другой — подставьте.)

Параметры подключения:

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|LAN-IP роутера (<code>192.168.1.1</code> по умолчанию)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code> (заводской)
|}

При первом подключении SSH спросит fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>
Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' дефолтный <code>keenetic</code> известен всем. Если SSH когда-нибудь будет проброшен наружу — роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите ходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце документа. Для базовой установки это '''не нужно''' — переходите к Этапу 2.
</div>

----

'''Всё готово для установки утилит.''' Переходите к Этапу 2.

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Так как у нас первый чистый запуск нужно установить несколько стандартных вещей:<syntaxhighlight lang="bash">
opkg update
opkg install wget-ssl curl
</syntaxhighlight>Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.
[[Файл:Singbox-helper-g.png|центр|мини|1034x1034пкс|Главный экран приложения Singbox-helper]]
На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.
[[Файл:Singbox-helper-con.png|центр|мини|850x850пкс|Пример успешного подключения в Singbox-helper]]
Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>. UI покажет жёлтое предупреждение под распознанными параметрами. Решение — попросить владельца сервера переключить транспорт на <code>ws</code>, <code>grpc</code> или <code>tcp</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.
[[Файл:Keen-pbr-g.png|центр|мини|1043x1043пкс|Keen-pbr - пример главного экрана]]

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

[[File:keenpbr_outbounds.png|center|Страница «Outbounds (выходы)» в веб-интерфейсе keen-pbr со списком из трёх выходов: wan, block, vpn (interface=singtun).|мини|1005x1005пкс]]

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
sh /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>[http://192.168.10.1:90 http://192.168.1.1:90]</code>.

Ввести логин и пароль, те же что применяются для входа по ssh.
[[Файл:Nfqws2-g-p.png|центр|мини|914x914пкс|Пример главного окна Nfqws2]]
----

= Финальная архитектура =
[[Файл:Keenetic architecture detailed.png|центр|мини|1031x1031пкс|Полная схема трафика через роутер: DNS-запросы клиента идут в keen-pbr dnsmasq → Quad9, ответы накапливаются в ipset; TCP-трафик в iptables маркируется и уходит либо в singtun (sing-box → VPN-узел), либо через WAN с DPI-обходом nfqws2.]]
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T18:47:49Z

Владимир: /* 3.4. Скрипт правил NAT и FORWARD */

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
[[Файл:Keenetic architecture overview.png|центр|мини|633x633пкс|Общая схема: keen-pbr по адресу домена решает, отправить трафик в туннель singtun (sing-box → VPN-сервер) или пустить через nfqws2 + прямой WAN.]]

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== Какая у вас прошивка ==
KeeneticOS существует в двух вариантах, и от этого зависит, нужен ли вам отдельный шаг включения компонентов прошивки.

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. подсекцию «Только для оригинального Keenetic» ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', всё уже в образе прошивки порта — пропускайте подсекцию ниже и сразу переходите к «Выбор URL установщика»
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как понять, какая у вас:''' На странице '''Системный монитор''' видна модель устройства. Маркетинговое имя "Keenetic Hero" и модель "KN-..." — это оригинальный Keenetic. Имя другого производителя (например, "Xiaomi R3G") + KeeneticOS — это порт сообщества. Дополнительный признак порта — на странице компонентов сообщение «Не удалось получить список компонентов от сервера» (своего сервера обновлений у порта нет).
</div>

== Только для оригинального Keenetic ==
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:

{| class="wikitable"
!Компонент
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|База Entware
|-
|'''Файловая система Ext'''
|Монтирование ext4-флешки
|-
|'''Сервер SSH'''
|Командная строка роутера
|-
|"Netfilter" / "Модули ядра Netfilter"
|База iptables для Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Доп. модули (<code>xt_set</code>, <code>xt_multiport</code>, <code>conntrack-extra</code>) — '''критично''' для keen-pbr
|}

После выбора — '''Установить обновление''' и ждите 2–5 минут, роутер перезагрузится сам.

== Выбор URL установщика ==
{| class="wikitable"
!Архитектура роутера
!URL установщика (одной строкой)
|-
|'''MIPS little-endian (mipsel)''' — большинство Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как узнать архитектуру:''' '''Системный монитор''' → видна модель и процессор. Большинство бытовых моделей — MIPS (верхняя строка). Сомневаетесь — берите mipsel; если не подходит, установщик ругнётся, роутер от этого не сломается.
</div>

== Что вам понадобится ==
Перед тем как идти в командную строку, держите под рукой два значения:

{| class="wikitable"
!Параметр
!Откуда взять
!Пример
|-
|'''UUID USB-диска'''
|<code>show media</code> в веб-CLI Keenetic (см. шаг 3 в 1.1), поле <code>uuid</code> внутри <code>partition</code>
|<code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>
|-
|'''URL установщика'''
|Из таблицы «Выбор URL установщика» выше — по архитектуре
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|}

== 1.1. Установка Entware через командную строку ==

# '''Подключите USB-флешку.''' Воткните флешку в USB-порт роутера. Откройте веб-интерфейс: '''Приложения → USB-диски и принтеры''' — диск должен появиться в списке. Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' → '''EXT4'''.
#: [[File:keenetic_usb_disks.png|center|Страница «USB-диски и принтеры» в веб-интерфейсе Keenetic с подключённой USB-флешкой и опцией «Форматировать» в EXT4.|мини|994x994пкс]]
# '''Откройте встроенный веб-CLI Keenetic:''' <code>http://192.168.1.1/a</code> (или подставьте свой LAN-IP роутера, если он другой). Должно появиться приглашение <code>(config)></code>.
# '''Узнайте UUID диска:'''
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
#: В ответе найдите блок с вашей флешкой и поле <code>uuid</code> внутри <code>partition</code>. Длинная строка вида <code>d5f39712-...</code> — это и есть нужное значение, скопируйте его.
# '''Запустите установку Entware.''' Подставьте '''свой UUID''' и '''URL по архитектуре''' (из таблицы «Выбор URL установщика» выше):
#: <syntaxhighlight lang="bash">opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ></syntaxhighlight>
#: Пример с реальными подставленными значениями (mipsel):
#: <syntaxhighlight lang="bash">opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</syntaxhighlight>
#: '''Угловых скобок <code><</code><code>></code> в финальной команде остаться не должно.''' Двоеточие и слэш <code>:/</code> сразу после UUID — обязательны. После UUID и перед URL — ровно один пробел.
# '''Сразу включите DNS-override и сохраните конфиг:'''
#: <syntaxhighlight lang="bash">opkg dns-override
system configuration save</syntaxhighlight>
#: <code>opkg dns-override</code> заставит KeeneticOS отдавать DNS-запросы клиентов в Entware-овский dnsmasq, который потом будет управляться keen-pbr. Без этого keen-pbr не сможет перехватывать DNS и маршрутизация по доменам работать не будет. Опция применится после reboot ниже.
# '''Дождитесь окончания установки.''' Откройте журнал в веб-интерфейсе: <code>http://192.168.1.1/diagnostics/general/log</code> (если LAN-IP другой — подставьте). Установщик пишет туда что делает: качает <code>installer.tar.gz</code>, распаковывает в <code>/opt</code>, ставит базовые пакеты. Это занимает 2–5 минут. Ждите финальной строки <code>Entware installed</code>.
#: [[File:keenetic_log_entware_installed.png|center|Системный журнал Keenetic (/diagnostics/general/log) с финальной строкой «Entware installed» — установка завершилась успешно, можно перезагружать роутер.|мини|804x804пкс]]
#: <div style="padding: 8px 12px; margin: 8px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">'''Не перезагружайте роутер до этой строки в журнале!''' Если ребутнуть роутер посреди установки, файлы Entware на флешке останутся неконсистентными, и на следующих этапах посыпятся странные ошибки.</div>
# '''Перезагрузите роутер из веб-CLI:'''
#: <syntaxhighlight lang="bash">system reboot</syntaxhighlight>
#: Через 1–2 минуты роутер поднимется обратно. После reboot применятся: монтирование Entware с флешки в <code>/opt</code>, автозапуск его сервисов, а главное — <code>opkg dns-override</code> из шага 5.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Если установщик молчит:''' В некоторых сборках команда <code>opkg disk ... URL</code> молчит, если OPKG-диск уже был назначен раньше. В журнале нет строк про загрузку <code>installer.tar.gz</code>? Сбросьте назначение диска и повторите шаги 4–5:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk <ВАШ_UUID>:/ <URL>
opkg dns-override
system configuration save
</syntaxhighlight>
</div>

== 1.2. Первое подключение по SSH ==

После перезагрузки Entware поднимает встроенный SSH-сервер на порту '''222'''.

На Windows — открываете PowerShell и подключаетесь одной командой:

<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

(LAN-IP роутера другой — подставьте.)

Параметры подключения:

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|LAN-IP роутера (<code>192.168.1.1</code> по умолчанию)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code> (заводской)
|}

При первом подключении SSH спросит fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>
Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' дефолтный <code>keenetic</code> известен всем. Если SSH когда-нибудь будет проброшен наружу — роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите ходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце документа. Для базовой установки это '''не нужно''' — переходите к Этапу 2.
</div>

----

'''Всё готово для установки утилит.''' Переходите к Этапу 2.

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Так как у нас первый чистый запуск нужно установить несколько стандартных вещей:<syntaxhighlight lang="bash">
opkg update
opkg install wget-ssl curl
</syntaxhighlight>Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про место:''' <code>sing-box-go</code> занимает ~62 МБ распакованных, плюс ~7 МБ сам helper, плюс Entware-окружение. На встроенной флэш-памяти роутера не помещается — Entware '''должен''' быть на USB (см. Этап 1).
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.
[[Файл:Singbox-helper-g.png|центр|мини|1034x1034пкс|Главный экран приложения Singbox-helper]]
На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.
[[Файл:Singbox-helper-con.png|центр|мини|850x850пкс|Пример успешного подключения в Singbox-helper]]
Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>. UI покажет жёлтое предупреждение под распознанными параметрами. Решение — попросить владельца сервера переключить транспорт на <code>ws</code>, <code>grpc</code> или <code>tcp</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.
[[Файл:Keen-pbr-g.png|центр|мини|1043x1043пкс|Keen-pbr - пример главного экрана]]

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

[[File:keenpbr_outbounds.png|center|Страница «Outbounds (выходы)» в веб-интерфейсе keen-pbr со списком из трёх выходов: wan, block, vpn (interface=singtun).|мини|1005x1005пкс]]

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
sh /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>[http://192.168.10.1:90 http://192.168.1.1:90]</code>.

Ввести логин и пароль, те же что применяются для входа по ssh.
[[Файл:Nfqws2-g-p.png|центр|мини|914x914пкс|Пример главного окна Nfqws2]]
----

= Финальная архитектура =
[[Файл:Keenetic architecture detailed.png|центр|мини|1031x1031пкс|Полная схема трафика через роутер: DNS-запросы клиента идут в keen-pbr dnsmasq → Quad9, ответы накапливаются в ipset; TCP-трафик в iptables маркируется и уходит либо в singtun (sing-box → VPN-узел), либо через WAN с DPI-обходом nfqws2.]]
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T18:46:08Z

Владимир: /* 2.1. Подключение фида singbox-helper и установка */

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
[[Файл:Keenetic architecture overview.png|центр|мини|633x633пкс|Общая схема: keen-pbr по адресу домена решает, отправить трафик в туннель singtun (sing-box → VPN-сервер) или пустить через nfqws2 + прямой WAN.]]

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== Какая у вас прошивка ==
KeeneticOS существует в двух вариантах, и от этого зависит, нужен ли вам отдельный шаг включения компонентов прошивки.

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. подсекцию «Только для оригинального Keenetic» ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', всё уже в образе прошивки порта — пропускайте подсекцию ниже и сразу переходите к «Выбор URL установщика»
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как понять, какая у вас:''' На странице '''Системный монитор''' видна модель устройства. Маркетинговое имя "Keenetic Hero" и модель "KN-..." — это оригинальный Keenetic. Имя другого производителя (например, "Xiaomi R3G") + KeeneticOS — это порт сообщества. Дополнительный признак порта — на странице компонентов сообщение «Не удалось получить список компонентов от сервера» (своего сервера обновлений у порта нет).
</div>

== Только для оригинального Keenetic ==
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:

{| class="wikitable"
!Компонент
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|База Entware
|-
|'''Файловая система Ext'''
|Монтирование ext4-флешки
|-
|'''Сервер SSH'''
|Командная строка роутера
|-
|"Netfilter" / "Модули ядра Netfilter"
|База iptables для Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Доп. модули (<code>xt_set</code>, <code>xt_multiport</code>, <code>conntrack-extra</code>) — '''критично''' для keen-pbr
|}

После выбора — '''Установить обновление''' и ждите 2–5 минут, роутер перезагрузится сам.

== Выбор URL установщика ==
{| class="wikitable"
!Архитектура роутера
!URL установщика (одной строкой)
|-
|'''MIPS little-endian (mipsel)''' — большинство Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как узнать архитектуру:''' '''Системный монитор''' → видна модель и процессор. Большинство бытовых моделей — MIPS (верхняя строка). Сомневаетесь — берите mipsel; если не подходит, установщик ругнётся, роутер от этого не сломается.
</div>

== Что вам понадобится ==
Перед тем как идти в командную строку, держите под рукой два значения:

{| class="wikitable"
!Параметр
!Откуда взять
!Пример
|-
|'''UUID USB-диска'''
|<code>show media</code> в веб-CLI Keenetic (см. шаг 3 в 1.1), поле <code>uuid</code> внутри <code>partition</code>
|<code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>
|-
|'''URL установщика'''
|Из таблицы «Выбор URL установщика» выше — по архитектуре
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|}

== 1.1. Установка Entware через командную строку ==

# '''Подключите USB-флешку.''' Воткните флешку в USB-порт роутера. Откройте веб-интерфейс: '''Приложения → USB-диски и принтеры''' — диск должен появиться в списке. Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' → '''EXT4'''.
#: [[File:keenetic_usb_disks.png|center|Страница «USB-диски и принтеры» в веб-интерфейсе Keenetic с подключённой USB-флешкой и опцией «Форматировать» в EXT4.|мини|994x994пкс]]
# '''Откройте встроенный веб-CLI Keenetic:''' <code>http://192.168.1.1/a</code> (или подставьте свой LAN-IP роутера, если он другой). Должно появиться приглашение <code>(config)></code>.
# '''Узнайте UUID диска:'''
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
#: В ответе найдите блок с вашей флешкой и поле <code>uuid</code> внутри <code>partition</code>. Длинная строка вида <code>d5f39712-...</code> — это и есть нужное значение, скопируйте его.
# '''Запустите установку Entware.''' Подставьте '''свой UUID''' и '''URL по архитектуре''' (из таблицы «Выбор URL установщика» выше):
#: <syntaxhighlight lang="bash">opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ></syntaxhighlight>
#: Пример с реальными подставленными значениями (mipsel):
#: <syntaxhighlight lang="bash">opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</syntaxhighlight>
#: '''Угловых скобок <code><</code><code>></code> в финальной команде остаться не должно.''' Двоеточие и слэш <code>:/</code> сразу после UUID — обязательны. После UUID и перед URL — ровно один пробел.
# '''Сразу включите DNS-override и сохраните конфиг:'''
#: <syntaxhighlight lang="bash">opkg dns-override
system configuration save</syntaxhighlight>
#: <code>opkg dns-override</code> заставит KeeneticOS отдавать DNS-запросы клиентов в Entware-овский dnsmasq, который потом будет управляться keen-pbr. Без этого keen-pbr не сможет перехватывать DNS и маршрутизация по доменам работать не будет. Опция применится после reboot ниже.
# '''Дождитесь окончания установки.''' Откройте журнал в веб-интерфейсе: <code>http://192.168.1.1/diagnostics/general/log</code> (если LAN-IP другой — подставьте). Установщик пишет туда что делает: качает <code>installer.tar.gz</code>, распаковывает в <code>/opt</code>, ставит базовые пакеты. Это занимает 2–5 минут. Ждите финальной строки <code>Entware installed</code>.
#: [[File:keenetic_log_entware_installed.png|center|Системный журнал Keenetic (/diagnostics/general/log) с финальной строкой «Entware installed» — установка завершилась успешно, можно перезагружать роутер.|мини|804x804пкс]]
#: <div style="padding: 8px 12px; margin: 8px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">'''Не перезагружайте роутер до этой строки в журнале!''' Если ребутнуть роутер посреди установки, файлы Entware на флешке останутся неконсистентными, и на следующих этапах посыпятся странные ошибки.</div>
# '''Перезагрузите роутер из веб-CLI:'''
#: <syntaxhighlight lang="bash">system reboot</syntaxhighlight>
#: Через 1–2 минуты роутер поднимется обратно. После reboot применятся: монтирование Entware с флешки в <code>/opt</code>, автозапуск его сервисов, а главное — <code>opkg dns-override</code> из шага 5.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Если установщик молчит:''' В некоторых сборках команда <code>opkg disk ... URL</code> молчит, если OPKG-диск уже был назначен раньше. В журнале нет строк про загрузку <code>installer.tar.gz</code>? Сбросьте назначение диска и повторите шаги 4–5:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk <ВАШ_UUID>:/ <URL>
opkg dns-override
system configuration save
</syntaxhighlight>
</div>

== 1.2. Первое подключение по SSH ==

После перезагрузки Entware поднимает встроенный SSH-сервер на порту '''222'''.

На Windows — открываете PowerShell и подключаетесь одной командой:

<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

(LAN-IP роутера другой — подставьте.)

Параметры подключения:

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|LAN-IP роутера (<code>192.168.1.1</code> по умолчанию)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code> (заводской)
|}

При первом подключении SSH спросит fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>
Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' дефолтный <code>keenetic</code> известен всем. Если SSH когда-нибудь будет проброшен наружу — роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите ходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце документа. Для базовой установки это '''не нужно''' — переходите к Этапу 2.
</div>

----

'''Всё готово для установки утилит.''' Переходите к Этапу 2.

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Так как у нас первый чистый запуск нужно установить несколько стандартных вещей:<syntaxhighlight lang="bash">
opkg update
opkg install wget-ssl curl
</syntaxhighlight>Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про место:''' <code>sing-box-go</code> занимает ~62 МБ распакованных, плюс ~7 МБ сам helper, плюс Entware-окружение. На встроенной флэш-памяти роутера не помещается — Entware '''должен''' быть на USB (см. Этап 1).
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.
[[Файл:Singbox-helper-g.png|центр|мини|1034x1034пкс|Главный экран приложения Singbox-helper]]
На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.
[[Файл:Singbox-helper-con.png|центр|мини|850x850пкс|Пример успешного подключения в Singbox-helper]]
Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>. UI покажет жёлтое предупреждение под распознанными параметрами. Решение — попросить владельца сервера переключить транспорт на <code>ws</code>, <code>grpc</code> или <code>tcp</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.
[[Файл:Keen-pbr-g.png|центр|мини|1043x1043пкс|Keen-pbr - пример главного экрана]]

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

[[File:keenpbr_outbounds.png|center|Страница «Outbounds (выходы)» в веб-интерфейсе keen-pbr со списком из трёх выходов: wan, block, vpn (interface=singtun).|мини|1005x1005пкс]]

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
sh /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок.

== 3.5. Тестирование ==
На клиентском устройстве, подключённом к Keenetic:

# '''Очистите кеш DNS''' (важно — без этого старые ответы остаются):
#* Windows: <code>ipconfig /flushdns</code> в PowerShell.
#* Android / iOS: переподключиться к Wi-Fi (off → on).
#* macOS: <code>sudo dscacheutil -flushcache</code>.
# Перезапустите браузер (у него свой DNS-кеш).
# Откройте сайт из списка bypass.
# Параллельно откройте <code>https://api.ipify.org</code> в браузере. Адрес должен быть тот же, который вы видели в шаге «IP через TUN» на вкладке Главная UI singbox-helper (т.е. IP вашего VPN-провайдера, а не домашний WAN-IP).

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>[http://192.168.10.1:90 http://192.168.1.1:90]</code>.

Ввести логин и пароль, те же что применяются для входа по ssh.
[[Файл:Nfqws2-g-p.png|центр|мини|914x914пкс|Пример главного окна Nfqws2]]
----

= Финальная архитектура =
[[Файл:Keenetic architecture detailed.png|центр|мини|1031x1031пкс|Полная схема трафика через роутер: DNS-запросы клиента идут в keen-pbr dnsmasq → Quad9, ответы накапливаются в ipset; TCP-трафик в iptables маркируется и уходит либо в singtun (sing-box → VPN-узел), либо через WAN с DPI-обходом nfqws2.]]
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T18:14:43Z

Владимир:

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
[[Файл:Keenetic architecture overview.png|центр|мини|633x633пкс|Общая схема: keen-pbr по адресу домена решает, отправить трафик в туннель singtun (sing-box → VPN-сервер) или пустить через nfqws2 + прямой WAN.]]

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== Какая у вас прошивка ==
KeeneticOS существует в двух вариантах, и от этого зависит, нужен ли вам отдельный шаг включения компонентов прошивки.

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. подсекцию «Только для оригинального Keenetic» ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', всё уже в образе прошивки порта — пропускайте подсекцию ниже и сразу переходите к «Выбор URL установщика»
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как понять, какая у вас:''' На странице '''Системный монитор''' видна модель устройства. Маркетинговое имя "Keenetic Hero" и модель "KN-..." — это оригинальный Keenetic. Имя другого производителя (например, "Xiaomi R3G") + KeeneticOS — это порт сообщества. Дополнительный признак порта — на странице компонентов сообщение «Не удалось получить список компонентов от сервера» (своего сервера обновлений у порта нет).
</div>

== Только для оригинального Keenetic ==
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:

{| class="wikitable"
!Компонент
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|База Entware
|-
|'''Файловая система Ext'''
|Монтирование ext4-флешки
|-
|'''Сервер SSH'''
|Командная строка роутера
|-
|"Netfilter" / "Модули ядра Netfilter"
|База iptables для Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Доп. модули (<code>xt_set</code>, <code>xt_multiport</code>, <code>conntrack-extra</code>) — '''критично''' для keen-pbr
|}

После выбора — '''Установить обновление''' и ждите 2–5 минут, роутер перезагрузится сам.

== Выбор URL установщика ==
{| class="wikitable"
!Архитектура роутера
!URL установщика (одной строкой)
|-
|'''MIPS little-endian (mipsel)''' — большинство Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как узнать архитектуру:''' '''Системный монитор''' → видна модель и процессор. Большинство бытовых моделей — MIPS (верхняя строка). Сомневаетесь — берите mipsel; если не подходит, установщик ругнётся, роутер от этого не сломается.
</div>

== Что вам понадобится ==
Перед тем как идти в командную строку, держите под рукой два значения:

{| class="wikitable"
!Параметр
!Откуда взять
!Пример
|-
|'''UUID USB-диска'''
|<code>show media</code> в веб-CLI Keenetic (см. шаг 3 в 1.1), поле <code>uuid</code> внутри <code>partition</code>
|<code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>
|-
|'''URL установщика'''
|Из таблицы «Выбор URL установщика» выше — по архитектуре
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|}

== 1.1. Установка Entware через командную строку ==

# '''Подключите USB-флешку.''' Воткните флешку в USB-порт роутера. Откройте веб-интерфейс: '''Приложения → USB-диски и принтеры''' — диск должен появиться в списке. Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' → '''EXT4'''.
#: [[File:keenetic_usb_disks.png|center|Страница «USB-диски и принтеры» в веб-интерфейсе Keenetic с подключённой USB-флешкой и опцией «Форматировать» в EXT4.|мини|994x994пкс]]
# '''Откройте встроенный веб-CLI Keenetic:''' <code>http://192.168.1.1/a</code> (или подставьте свой LAN-IP роутера, если он другой). Должно появиться приглашение <code>(config)></code>.
# '''Узнайте UUID диска:'''
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
#: В ответе найдите блок с вашей флешкой и поле <code>uuid</code> внутри <code>partition</code>. Длинная строка вида <code>d5f39712-...</code> — это и есть нужное значение, скопируйте его.
# '''Запустите установку Entware.''' Подставьте '''свой UUID''' и '''URL по архитектуре''' (из таблицы «Выбор URL установщика» выше):
#: <syntaxhighlight lang="bash">opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ></syntaxhighlight>
#: Пример с реальными подставленными значениями (mipsel):
#: <syntaxhighlight lang="bash">opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</syntaxhighlight>
#: '''Угловых скобок <code><</code><code>></code> в финальной команде остаться не должно.''' Двоеточие и слэш <code>:/</code> сразу после UUID — обязательны. После UUID и перед URL — ровно один пробел.
# '''Сразу включите DNS-override и сохраните конфиг:'''
#: <syntaxhighlight lang="bash">opkg dns-override
system configuration save</syntaxhighlight>
#: <code>opkg dns-override</code> заставит KeeneticOS отдавать DNS-запросы клиентов в Entware-овский dnsmasq, который потом будет управляться keen-pbr. Без этого keen-pbr не сможет перехватывать DNS и маршрутизация по доменам работать не будет. Опция применится после reboot ниже.
# '''Дождитесь окончания установки.''' Откройте журнал в веб-интерфейсе: <code>http://192.168.1.1/diagnostics/general/log</code> (если LAN-IP другой — подставьте). Установщик пишет туда что делает: качает <code>installer.tar.gz</code>, распаковывает в <code>/opt</code>, ставит базовые пакеты. Это занимает 2–5 минут. Ждите финальной строки <code>Entware installed</code>.
#: [[File:keenetic_log_entware_installed.png|center|Системный журнал Keenetic (/diagnostics/general/log) с финальной строкой «Entware installed» — установка завершилась успешно, можно перезагружать роутер.|мини|804x804пкс]]
#: <div style="padding: 8px 12px; margin: 8px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">'''Не перезагружайте роутер до этой строки в журнале!''' Если ребутнуть роутер посреди установки, файлы Entware на флешке останутся неконсистентными, и на следующих этапах посыпятся странные ошибки.</div>
# '''Перезагрузите роутер из веб-CLI:'''
#: <syntaxhighlight lang="bash">system reboot</syntaxhighlight>
#: Через 1–2 минуты роутер поднимется обратно. После reboot применятся: монтирование Entware с флешки в <code>/opt</code>, автозапуск его сервисов, а главное — <code>opkg dns-override</code> из шага 5.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Если установщик молчит:''' В некоторых сборках команда <code>opkg disk ... URL</code> молчит, если OPKG-диск уже был назначен раньше. В журнале нет строк про загрузку <code>installer.tar.gz</code>? Сбросьте назначение диска и повторите шаги 4–5:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk <ВАШ_UUID>:/ <URL>
opkg dns-override
system configuration save
</syntaxhighlight>
</div>

== 1.2. Первое подключение по SSH ==

После перезагрузки Entware поднимает встроенный SSH-сервер на порту '''222'''.

На Windows — открываете PowerShell и подключаетесь одной командой:

<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

(LAN-IP роутера другой — подставьте.)

Параметры подключения:

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|LAN-IP роутера (<code>192.168.1.1</code> по умолчанию)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code> (заводской)
|}

При первом подключении SSH спросит fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>
Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' дефолтный <code>keenetic</code> известен всем. Если SSH когда-нибудь будет проброшен наружу — роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите ходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце документа. Для базовой установки это '''не нужно''' — переходите к Этапу 2.
</div>

----

'''Всё готово для установки утилит.''' Переходите к Этапу 2.

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про место:''' <code>sing-box-go</code> занимает ~62 МБ распакованных, плюс ~7 МБ сам helper, плюс Entware-окружение. На встроенной флэш-памяти роутера не помещается — Entware '''должен''' быть на USB (см. Этап 1).
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.
[[Файл:Singbox-helper-g.png|центр|мини|1034x1034пкс|Главный экран приложения Singbox-helper]]
На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.
[[Файл:Singbox-helper-con.png|центр|мини|850x850пкс|Пример успешного подключения в Singbox-helper]]
Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>. UI покажет жёлтое предупреждение под распознанными параметрами. Решение — попросить владельца сервера переключить транспорт на <code>ws</code>, <code>grpc</code> или <code>tcp</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.
[[Файл:Keen-pbr-g.png|центр|мини|1043x1043пкс|Keen-pbr - пример главного экрана]]

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

[[File:keenpbr_outbounds.png|center|Страница «Outbounds (выходы)» в веб-интерфейсе keen-pbr со списком из трёх выходов: wan, block, vpn (interface=singtun).|мини|1005x1005пкс]]

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
sh /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок.

== 3.5. Тестирование ==
На клиентском устройстве, подключённом к Keenetic:

# '''Очистите кеш DNS''' (важно — без этого старые ответы остаются):
#* Windows: <code>ipconfig /flushdns</code> в PowerShell.
#* Android / iOS: переподключиться к Wi-Fi (off → on).
#* macOS: <code>sudo dscacheutil -flushcache</code>.
# Перезапустите браузер (у него свой DNS-кеш).
# Откройте сайт из списка bypass.
# Параллельно откройте <code>https://api.ipify.org</code> в браузере. Адрес должен быть тот же, который вы видели в шаге «IP через TUN» на вкладке Главная UI singbox-helper (т.е. IP вашего VPN-провайдера, а не домашний WAN-IP).

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>[http://192.168.10.1:90 http://192.168.1.1:90]</code>.

Ввести логин и пароль, те же что применяются для входа по ssh.
[[Файл:Nfqws2-g-p.png|центр|мини|914x914пкс|Пример главного окна Nfqws2]]
----

= Финальная архитектура =
[[Файл:Keenetic architecture detailed.png|центр|мини|1031x1031пкс|Полная схема трафика через роутер: DNS-запросы клиента идут в keen-pbr dnsmasq → Quad9, ответы накапливаются в ipset; TCP-трафик в iptables маркируется и уходит либо в singtun (sing-box → VPN-узел), либо через WAN с DPI-обходом nfqws2.]]
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Файл:Keenetic architecture overview.png

2026-05-12T18:14:09Z

Владимир:

Общая схема: keen-pbr по адресу домена решает, отправить трафик в туннель singtun (sing-box → VPN-сервер) или пустить через nfqws2 + прямой WAN.

Файл:Keenetic architecture detailed.png

2026-05-12T18:13:17Z

Владимир:

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T18:02:07Z

Владимир:

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
<pre>
KEENETIC РОУТЕР

┌──────────────────────────────────────────────────────────────┐
│ │
│ ┌────────────────┐ │
│ │ keen-pbr │ --- адрес домена в списке? --- │
│ │ (по доменам) │ │ │ │
│ └────────────────┘ │ ДА │ НЕТ │
│ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ │
│ │ singtun │ │ nfqws2 │ │
│ │ (sing-box) │ │ DPI fix │ │
│ └────────────┘ └────────────┘ │
│ │ │ │
└────────────────────────────┼────────────────┼────────────────┘
│ │
┌────▼────┐ ┌────▼────┐
│ VPN- │ │ Прямой │
│ сервер │ │ WAN │
└─────────┘ └─────────┘
</pre>
''(Здесь схему можно перерисовать в Mermaid или Excalidraw и заменить блок.)''

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== Какая у вас прошивка ==
KeeneticOS существует в двух вариантах, и от этого зависит, нужен ли вам отдельный шаг включения компонентов прошивки.

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. подсекцию «Только для оригинального Keenetic» ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', всё уже в образе прошивки порта — пропускайте подсекцию ниже и сразу переходите к «Выбор URL установщика»
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как понять, какая у вас:''' На странице '''Системный монитор''' видна модель устройства. Маркетинговое имя "Keenetic Hero" и модель "KN-..." — это оригинальный Keenetic. Имя другого производителя (например, "Xiaomi R3G") + KeeneticOS — это порт сообщества. Дополнительный признак порта — на странице компонентов сообщение «Не удалось получить список компонентов от сервера» (своего сервера обновлений у порта нет).
</div>

== Только для оригинального Keenetic ==
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:

{| class="wikitable"
!Компонент
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|База Entware
|-
|'''Файловая система Ext'''
|Монтирование ext4-флешки
|-
|'''Сервер SSH'''
|Командная строка роутера
|-
|"Netfilter" / "Модули ядра Netfilter"
|База iptables для Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Доп. модули (<code>xt_set</code>, <code>xt_multiport</code>, <code>conntrack-extra</code>) — '''критично''' для keen-pbr
|}

После выбора — '''Установить обновление''' и ждите 2–5 минут, роутер перезагрузится сам.

== Выбор URL установщика ==
{| class="wikitable"
!Архитектура роутера
!URL установщика (одной строкой)
|-
|'''MIPS little-endian (mipsel)''' — большинство Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как узнать архитектуру:''' '''Системный монитор''' → видна модель и процессор. Большинство бытовых моделей — MIPS (верхняя строка). Сомневаетесь — берите mipsel; если не подходит, установщик ругнётся, роутер от этого не сломается.
</div>

== Что вам понадобится ==
Перед тем как идти в командную строку, держите под рукой два значения:

{| class="wikitable"
!Параметр
!Откуда взять
!Пример
|-
|'''UUID USB-диска'''
|<code>show media</code> в веб-CLI Keenetic (см. шаг 3 в 1.1), поле <code>uuid</code> внутри <code>partition</code>
|<code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>
|-
|'''URL установщика'''
|Из таблицы «Выбор URL установщика» выше — по архитектуре
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|}

== 1.1. Установка Entware через командную строку ==

# '''Подключите USB-флешку.''' Воткните флешку в USB-порт роутера. Откройте веб-интерфейс: '''Приложения → USB-диски и принтеры''' — диск должен появиться в списке. Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' → '''EXT4'''.
#: [[File:keenetic_usb_disks.png|center|Страница «USB-диски и принтеры» в веб-интерфейсе Keenetic с подключённой USB-флешкой и опцией «Форматировать» в EXT4.|мини|994x994пкс]]
# '''Откройте встроенный веб-CLI Keenetic:''' <code>http://192.168.1.1/a</code> (или подставьте свой LAN-IP роутера, если он другой). Должно появиться приглашение <code>(config)></code>.
# '''Узнайте UUID диска:'''
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
#: В ответе найдите блок с вашей флешкой и поле <code>uuid</code> внутри <code>partition</code>. Длинная строка вида <code>d5f39712-...</code> — это и есть нужное значение, скопируйте его.
# '''Запустите установку Entware.''' Подставьте '''свой UUID''' и '''URL по архитектуре''' (из таблицы «Выбор URL установщика» выше):
#: <syntaxhighlight lang="bash">opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ></syntaxhighlight>
#: Пример с реальными подставленными значениями (mipsel):
#: <syntaxhighlight lang="bash">opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</syntaxhighlight>
#: '''Угловых скобок <code><</code><code>></code> в финальной команде остаться не должно.''' Двоеточие и слэш <code>:/</code> сразу после UUID — обязательны. После UUID и перед URL — ровно один пробел.
# '''Сразу включите DNS-override и сохраните конфиг:'''
#: <syntaxhighlight lang="bash">opkg dns-override
system configuration save</syntaxhighlight>
#: <code>opkg dns-override</code> заставит KeeneticOS отдавать DNS-запросы клиентов в Entware-овский dnsmasq, который потом будет управляться keen-pbr. Без этого keen-pbr не сможет перехватывать DNS и маршрутизация по доменам работать не будет. Опция применится после reboot ниже.
# '''Дождитесь окончания установки.''' Откройте журнал в веб-интерфейсе: <code>http://192.168.1.1/diagnostics/general/log</code> (если LAN-IP другой — подставьте). Установщик пишет туда что делает: качает <code>installer.tar.gz</code>, распаковывает в <code>/opt</code>, ставит базовые пакеты. Это занимает 2–5 минут. Ждите финальной строки <code>Entware installed</code>.
#: [[File:keenetic_log_entware_installed.png|center|Системный журнал Keenetic (/diagnostics/general/log) с финальной строкой «Entware installed» — установка завершилась успешно, можно перезагружать роутер.|мини|804x804пкс]]
#: <div style="padding: 8px 12px; margin: 8px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">'''Не перезагружайте роутер до этой строки в журнале!''' Если ребутнуть роутер посреди установки, файлы Entware на флешке останутся неконсистентными, и на следующих этапах посыпятся странные ошибки.</div>
# '''Перезагрузите роутер из веб-CLI:'''
#: <syntaxhighlight lang="bash">system reboot</syntaxhighlight>
#: Через 1–2 минуты роутер поднимется обратно. После reboot применятся: монтирование Entware с флешки в <code>/opt</code>, автозапуск его сервисов, а главное — <code>opkg dns-override</code> из шага 5.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Если установщик молчит:''' В некоторых сборках команда <code>opkg disk ... URL</code> молчит, если OPKG-диск уже был назначен раньше. В журнале нет строк про загрузку <code>installer.tar.gz</code>? Сбросьте назначение диска и повторите шаги 4–5:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk <ВАШ_UUID>:/ <URL>
opkg dns-override
system configuration save
</syntaxhighlight>
</div>

== 1.2. Первое подключение по SSH ==

После перезагрузки Entware поднимает встроенный SSH-сервер на порту '''222'''.

На Windows — открываете PowerShell и подключаетесь одной командой:

<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

(LAN-IP роутера другой — подставьте.)

Параметры подключения:

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|LAN-IP роутера (<code>192.168.1.1</code> по умолчанию)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code> (заводской)
|}

При первом подключении SSH спросит fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>
Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' дефолтный <code>keenetic</code> известен всем. Если SSH когда-нибудь будет проброшен наружу — роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите ходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце документа. Для базовой установки это '''не нужно''' — переходите к Этапу 2.
</div>

----

'''Всё готово для установки утилит.''' Переходите к Этапу 2.

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про место:''' <code>sing-box-go</code> занимает ~62 МБ распакованных, плюс ~7 МБ сам helper, плюс Entware-окружение. На встроенной флэш-памяти роутера не помещается — Entware '''должен''' быть на USB (см. Этап 1).
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.
[[Файл:Singbox-helper-g.png|центр|мини|1034x1034пкс|Главный экран приложения Singbox-helper]]
На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.
[[Файл:Singbox-helper-con.png|центр|мини|850x850пкс|Пример успешного подключения в Singbox-helper]]
Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>. UI покажет жёлтое предупреждение под распознанными параметрами. Решение — попросить владельца сервера переключить транспорт на <code>ws</code>, <code>grpc</code> или <code>tcp</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.
[[Файл:Keen-pbr-g.png|центр|мини|1043x1043пкс|Keen-pbr - пример главного экрана]]

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

[[File:keenpbr_outbounds.png|center|Страница «Outbounds (выходы)» в веб-интерфейсе keen-pbr со списком из трёх выходов: wan, block, vpn (interface=singtun).|мини|1005x1005пкс]]

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
sh /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок.

== 3.5. Тестирование ==
На клиентском устройстве, подключённом к Keenetic:

# '''Очистите кеш DNS''' (важно — без этого старые ответы остаются):
#* Windows: <code>ipconfig /flushdns</code> в PowerShell.
#* Android / iOS: переподключиться к Wi-Fi (off → on).
#* macOS: <code>sudo dscacheutil -flushcache</code>.
# Перезапустите браузер (у него свой DNS-кеш).
# Откройте сайт из списка bypass.
# Параллельно откройте <code>https://api.ipify.org</code> в браузере. Адрес должен быть тот же, который вы видели в шаге «IP через TUN» на вкладке Главная UI singbox-helper (т.е. IP вашего VPN-провайдера, а не домашний WAN-IP).

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>[http://192.168.10.1:90 http://192.168.1.1:90]</code>.

Ввести логин и пароль, те же что применяются для входа по ssh.
[[Файл:Nfqws2-g-p.png|центр|мини|914x914пкс|Пример главного окна Nfqws2]]
----

= Финальная архитектура =
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

<pre>
K E E N E T I C Р О У Т Е Р
┌───────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ │
LAN│ │ DNS-запрос │ │
───┼──►│ от клиента │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ upstream ┌────────────────┐ │
│ │ keen-pbr │ через │ Quad9 9.9.9.9 │ │
│ │ dnsmasq │ ─────────► │ │ │
│ │ на :53 │ │ │ │
│ └──────┬───────┘ └────────────────┘ │
│ │ IP → ipset │
│ │ │
│ ┌──────▼──────────────────────────────────────────────┐ │
LAN│ │ iptables / маршрутизация │ │
───┼──►│ ├ если dst-IP в ipset bypass: │ │
TCP│ │ │ fwmark → ip rule → table 151 → singtun │ │
│ │ │ │ │
│ │ └ иначе: │ │
│ │ обычный WAN-маршрут │ │
│ │ └ nfqws2 ловит первые пакеты │ │
│ │ и модифицирует для обхода DPI │ │
│ └────┬──────────────────────────────────────────┬─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌────────────────┐ │
│ │ singtun │ │ WAN-интерфейс │ │
│ │ (TUN) │ │ (ваш провайдер)│ │
│ └────┬────┘ └────────┬───────┘ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────┐ │ │
│ │ sing-box │ │ │
│ │ outbound: │ │ │
│ │ hysteria2 │ │ │
│ └──────┬──────┘ │ │
│ │ │ │
└──────────┼────────────────────────────────────────┼───────────────────────┘
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ VPN-узел │ │ Любой │
│ провайдера│ │ интернет │
└───────────┘ └───────────┘
</pre>

''(Здесь можно перерисовать в Mermaid/Excalidraw для финальной картинки.)''

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Файл:Nfqws2-g-p.png

2026-05-12T18:01:31Z

Владимир:

Nfqws2-g-p

Файл:Keen-pbr-g.png

2026-05-12T17:53:21Z

Владимир:

Keen-pbr-g

Файл:Singbox-helper-con.png

2026-05-12T17:51:14Z

Владимир:

Singbox-helper-con

Файл:Singbox-helper-g.png

2026-05-12T17:49:33Z

Владимир:

Singbox-helper-g

Файл:Keenpbr outbounds.png

2026-05-12T17:45:28Z

Владимир:

Файл:Keenetic log entware installed.png

2026-05-12T17:43:54Z

Владимир:

Файл:Keenetic usb disks.png

2026-05-12T17:43:03Z

Владимир:

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T17:42:15Z

Владимир: /* Только для оригинального Keenetic */

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
<pre>
KEENETIC РОУТЕР

┌──────────────────────────────────────────────────────────────┐
│ │
│ ┌────────────────┐ │
│ │ keen-pbr │ --- адрес домена в списке? --- │
│ │ (по доменам) │ │ │ │
│ └────────────────┘ │ ДА │ НЕТ │
│ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ │
│ │ singtun │ │ nfqws2 │ │
│ │ (sing-box) │ │ DPI fix │ │
│ └────────────┘ └────────────┘ │
│ │ │ │
└────────────────────────────┼────────────────┼────────────────┘
│ │
┌────▼────┐ ┌────▼────┐
│ VPN- │ │ Прямой │
│ сервер │ │ WAN │
└─────────┘ └─────────┘
</pre>
''(Здесь схему можно перерисовать в Mermaid или Excalidraw и заменить блок.)''

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== Какая у вас прошивка ==
KeeneticOS существует в двух вариантах, и от этого зависит, нужен ли вам отдельный шаг включения компонентов прошивки.

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. подсекцию «Только для оригинального Keenetic» ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', всё уже в образе прошивки порта — пропускайте подсекцию ниже и сразу переходите к «Выбор URL установщика»
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как понять, какая у вас:''' На странице '''Системный монитор''' видна модель устройства. Маркетинговое имя "Keenetic Hero" и модель "KN-..." — это оригинальный Keenetic. Имя другого производителя (например, "Xiaomi R3G") + KeeneticOS — это порт сообщества. Дополнительный признак порта — на странице компонентов сообщение «Не удалось получить список компонентов от сервера» (своего сервера обновлений у порта нет).
</div>

== Только для оригинального Keenetic ==
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:

{| class="wikitable"
!Компонент
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|База Entware
|-
|'''Файловая система Ext'''
|Монтирование ext4-флешки
|-
|'''Сервер SSH'''
|Командная строка роутера
|-
|"Netfilter" / "Модули ядра Netfilter"
|База iptables для Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Доп. модули (<code>xt_set</code>, <code>xt_multiport</code>, <code>conntrack-extra</code>) — '''критично''' для keen-pbr
|}

После выбора — '''Установить обновление''' и ждите 2–5 минут, роутер перезагрузится сам.

== Выбор URL установщика ==
{| class="wikitable"
!Архитектура роутера
!URL установщика (одной строкой)
|-
|'''MIPS little-endian (mipsel)''' — большинство Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как узнать архитектуру:''' '''Системный монитор''' → видна модель и процессор. Большинство бытовых моделей — MIPS (верхняя строка). Сомневаетесь — берите mipsel; если не подходит, установщик ругнётся, роутер от этого не сломается.
</div>

== Что вам понадобится ==
Перед тем как идти в командную строку, держите под рукой два значения:

{| class="wikitable"
!Параметр
!Откуда взять
!Пример
|-
|'''UUID USB-диска'''
|<code>show media</code> в веб-CLI Keenetic (см. шаг 3 в 1.1), поле <code>uuid</code> внутри <code>partition</code>
|<code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>
|-
|'''URL установщика'''
|Из таблицы «Выбор URL установщика» выше — по архитектуре
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|}

== 1.1. Установка Entware через командную строку ==

# '''Подключите USB-флешку.''' Воткните флешку в USB-порт роутера. Откройте веб-интерфейс: '''Приложения → USB-диски и принтеры''' — диск должен появиться в списке. Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' → '''EXT4'''.
#: [[File:keenetic_usb_disks.png|frame|center|Страница «USB-диски и принтеры» в веб-интерфейсе Keenetic с подключённой USB-флешкой и опцией «Форматировать» в EXT4.]]
# '''Откройте встроенный веб-CLI Keenetic:''' <code>http://192.168.1.1/a</code> (или подставьте свой LAN-IP роутера, если он другой). Должно появиться приглашение <code>(config)></code>.
# '''Узнайте UUID диска:'''
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
#: В ответе найдите блок с вашей флешкой и поле <code>uuid</code> внутри <code>partition</code>. Длинная строка вида <code>d5f39712-...</code> — это и есть нужное значение, скопируйте его.
# '''Запустите установку Entware.''' Подставьте '''свой UUID''' и '''URL по архитектуре''' (из таблицы «Выбор URL установщика» выше):
#: <syntaxhighlight lang="bash">opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ></syntaxhighlight>
#: Пример с реальными подставленными значениями (mipsel):
#: <syntaxhighlight lang="bash">opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</syntaxhighlight>
#: '''Угловых скобок <code><</code><code>></code> в финальной команде остаться не должно.''' Двоеточие и слэш <code>:/</code> сразу после UUID — обязательны. После UUID и перед URL — ровно один пробел.
# '''Сразу включите DNS-override и сохраните конфиг:'''
#: <syntaxhighlight lang="bash">opkg dns-override
system configuration save</syntaxhighlight>
#: <code>opkg dns-override</code> заставит KeeneticOS отдавать DNS-запросы клиентов в Entware-овский dnsmasq, который потом будет управляться keen-pbr. Без этого keen-pbr не сможет перехватывать DNS и маршрутизация по доменам работать не будет. Опция применится после reboot ниже.
# '''Дождитесь окончания установки.''' Откройте журнал в веб-интерфейсе: <code>http://192.168.1.1/diagnostics/general/log</code> (если LAN-IP другой — подставьте). Установщик пишет туда что делает: качает <code>installer.tar.gz</code>, распаковывает в <code>/opt</code>, ставит базовые пакеты. Это занимает 2–5 минут. Ждите финальной строки <code>Entware installed</code>.
#: [[File:keenetic_log_entware_installed.png|frame|center|Системный журнал Keenetic (/diagnostics/general/log) с финальной строкой «Entware installed» — установка завершилась успешно, можно перезагружать роутер.]]
#: <div style="padding: 8px 12px; margin: 8px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">'''Не перезагружайте роутер до этой строки в журнале!''' Если ребутнуть роутер посреди установки, файлы Entware на флешке останутся неконсистентными, и на следующих этапах посыпятся странные ошибки.</div>
# '''Перезагрузите роутер из веб-CLI:'''
#: <syntaxhighlight lang="bash">system reboot</syntaxhighlight>
#: Через 1–2 минуты роутер поднимется обратно. После reboot применятся: монтирование Entware с флешки в <code>/opt</code>, автозапуск его сервисов, а главное — <code>opkg dns-override</code> из шага 5.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Если установщик молчит:''' В некоторых сборках команда <code>opkg disk ... URL</code> молчит, если OPKG-диск уже был назначен раньше. В журнале нет строк про загрузку <code>installer.tar.gz</code>? Сбросьте назначение диска и повторите шаги 4–5:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk <ВАШ_UUID>:/ <URL>
opkg dns-override
system configuration save
</syntaxhighlight>
</div>

== 1.2. Первое подключение по SSH ==

После перезагрузки Entware поднимает встроенный SSH-сервер на порту '''222'''.

На Windows — открываете PowerShell и подключаетесь одной командой:

<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

(LAN-IP роутера другой — подставьте.)

Параметры подключения:

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|LAN-IP роутера (<code>192.168.1.1</code> по умолчанию)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code> (заводской)
|}

При первом подключении SSH спросит fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>
Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' дефолтный <code>keenetic</code> известен всем. Если SSH когда-нибудь будет проброшен наружу — роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите ходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце документа. Для базовой установки это '''не нужно''' — переходите к Этапу 2.
</div>

----

'''Всё готово для установки утилит.''' Переходите к Этапу 2.

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про место:''' <code>sing-box-go</code> занимает ~62 МБ распакованных, плюс ~7 МБ сам helper, плюс Entware-окружение. На встроенной флэш-памяти роутера не помещается — Entware '''должен''' быть на USB (см. Этап 1).
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.

На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.

Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>. UI покажет жёлтое предупреждение под распознанными параметрами. Решение — попросить владельца сервера переключить транспорт на <code>ws</code>, <code>grpc</code> или <code>tcp</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

[[File:keenpbr_outbounds.png|frame|center|Страница «Outbounds (выходы)» в веб-интерфейсе keen-pbr со списком из трёх выходов: wan, block, vpn (interface=singtun).]]

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

[[File:keenpbr_routing_rules.png|frame|center|Страница «Правила маршрутизации» в веб-интерфейсе keen-pbr с активным правилом #2 bypass → vpn (и опционально #1 local_list → block).]]

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
sh /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок.

== 3.5. Тестирование ==
На клиентском устройстве, подключённом к Keenetic:

# '''Очистите кеш DNS''' (важно — без этого старые ответы остаются):
#* Windows: <code>ipconfig /flushdns</code> в PowerShell.
#* Android / iOS: переподключиться к Wi-Fi (off → on).
#* macOS: <code>sudo dscacheutil -flushcache</code>.
# Перезапустите браузер (у него свой DNS-кеш).
# Откройте сайт из списка bypass.
# Параллельно откройте <code>https://api.ipify.org</code> в браузере. Адрес должен быть тот же, который вы видели в шаге «IP через TUN» на вкладке Главная UI singbox-helper (т.е. IP вашего VPN-провайдера, а не домашний WAN-IP).

[[File:client_ipify_through_tunnel.png|frame|center|Страница https://api.ipify.org, открытая на клиентском устройстве, показывает IP туннеля (а не домашний WAN-IP) — значит маршрутизация bypass-домена через singtun работает.]]

----

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web
</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Замечание про «failed» в конце установки:''' В выводе установщика вы можете увидеть строку:
<pre>
Starting /opt/sbin/lighttpd... failed.
NFQWS2 Web Interface installed: http://192.168.10.1:90
</pre>
Это '''не ошибка'''. lighttpd пытается стартануть до того, как все его модули (php8-mod-curl, php8-mod-session, mod-rewrite, mod-redirect) полностью зарегистрировались. Через несколько секунд стартовый скрипт <code>S80lighttpd</code> успешно поднимает сервис. Достаточно проверить:
<syntaxhighlight lang="bash">
pgrep -af lighttpd
netstat -tlnup | grep :90
</syntaxhighlight>
Оба должны показать запущенный процесс на порту 90. Если веб-интерфейс открывается на <code>http://LAN-АДРЕС-РОУТЕРА:90</code> — всё в порядке.
</div>

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>http://192.168.10.1:90</code>.

Для доступа из другой подсети — открыть порт <code>90</code> в фаерволе Keenetic (по аналогии с keen-pbr WebUI).

----

= Финальная архитектура =
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

<pre>
K E E N E T I C Р О У Т Е Р
┌───────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ │
LAN│ │ DNS-запрос │ │
───┼──►│ от клиента │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ upstream ┌────────────────┐ │
│ │ keen-pbr │ через │ Quad9 9.9.9.9 │ │
│ │ dnsmasq │ ─────────► │ │ │
│ │ на :53 │ │ │ │
│ └──────┬───────┘ └────────────────┘ │
│ │ IP → ipset │
│ │ │
│ ┌──────▼──────────────────────────────────────────────┐ │
LAN│ │ iptables / маршрутизация │ │
───┼──►│ ├ если dst-IP в ipset bypass: │ │
TCP│ │ │ fwmark → ip rule → table 151 → singtun │ │
│ │ │ │ │
│ │ └ иначе: │ │
│ │ обычный WAN-маршрут │ │
│ │ └ nfqws2 ловит первые пакеты │ │
│ │ и модифицирует для обхода DPI │ │
│ └────┬──────────────────────────────────────────┬─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌────────────────┐ │
│ │ singtun │ │ WAN-интерфейс │ │
│ │ (TUN) │ │ (ваш провайдер)│ │
│ └────┬────┘ └────────┬───────┘ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────┐ │ │
│ │ sing-box │ │ │
│ │ outbound: │ │ │
│ │ hysteria2 │ │ │
│ └──────┬──────┘ │ │
│ │ │ │
└──────────┼────────────────────────────────────────┼───────────────────────┘
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ VPN-узел │ │ Любой │
│ провайдера│ │ интернет │
└───────────┘ └───────────┘
</pre>

''(Здесь можно перерисовать в Mermaid/Excalidraw для финальной картинки.)''

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T17:41:07Z

Владимир:

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
<pre>
KEENETIC РОУТЕР

┌──────────────────────────────────────────────────────────────┐
│ │
│ ┌────────────────┐ │
│ │ keen-pbr │ --- адрес домена в списке? --- │
│ │ (по доменам) │ │ │ │
│ └────────────────┘ │ ДА │ НЕТ │
│ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ │
│ │ singtun │ │ nfqws2 │ │
│ │ (sing-box) │ │ DPI fix │ │
│ └────────────┘ └────────────┘ │
│ │ │ │
└────────────────────────────┼────────────────┼────────────────┘
│ │
┌────▼────┐ ┌────▼────┐
│ VPN- │ │ Прямой │
│ сервер │ │ WAN │
└─────────┘ └─────────┘
</pre>
''(Здесь схему можно перерисовать в Mermaid или Excalidraw и заменить блок.)''

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== Какая у вас прошивка ==
KeeneticOS существует в двух вариантах, и от этого зависит, нужен ли вам отдельный шаг включения компонентов прошивки.

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. подсекцию «Только для оригинального Keenetic» ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', всё уже в образе прошивки порта — пропускайте подсекцию ниже и сразу переходите к «Выбор URL установщика»
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как понять, какая у вас:''' На странице '''Системный монитор''' видна модель устройства. Маркетинговое имя "Keenetic Hero" и модель "KN-..." — это оригинальный Keenetic. Имя другого производителя (например, "Xiaomi R3G") + KeeneticOS — это порт сообщества. Дополнительный признак порта — на странице компонентов сообщение «Не удалось получить список компонентов от сервера» (своего сервера обновлений у порта нет).
</div>

== Только для оригинального Keenetic ==
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:

{| class="wikitable"
!Компонент
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|База Entware
|-
|'''Файловая система Ext'''
|Монтирование ext4-флешки
|-
|'''Сервер SSH'''
|Командная строка роутера
|-
|"Netfilter" / "Модули ядра Netfilter"
|База iptables для Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Доп. модули (<code>xt_set</code>, <code>xt_multiport</code>, <code>conntrack-extra</code>) — '''критично''' для keen-pbr
|}

После выбора — '''Установить обновление''' и ждите 2–5 минут, роутер перезагрузится сам.

[[File:keenetic_components_select.png|frame|center|Страница «Обновления и компоненты» в веб-интерфейсе Keenetic с открытым окном «Показать компоненты» и отмеченными OPKG, Ext, SSH, Netfilter и Netfilter addons.]]

== Выбор URL установщика ==
{| class="wikitable"
!Архитектура роутера
!URL установщика (одной строкой)
|-
|'''MIPS little-endian (mipsel)''' — большинство Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как узнать архитектуру:''' '''Системный монитор''' → видна модель и процессор. Большинство бытовых моделей — MIPS (верхняя строка). Сомневаетесь — берите mipsel; если не подходит, установщик ругнётся, роутер от этого не сломается.
</div>

== Что вам понадобится ==
Перед тем как идти в командную строку, держите под рукой два значения:

{| class="wikitable"
!Параметр
!Откуда взять
!Пример
|-
|'''UUID USB-диска'''
|<code>show media</code> в веб-CLI Keenetic (см. шаг 3 в 1.1), поле <code>uuid</code> внутри <code>partition</code>
|<code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>
|-
|'''URL установщика'''
|Из таблицы «Выбор URL установщика» выше — по архитектуре
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|}

== 1.1. Установка Entware через командную строку ==

# '''Подключите USB-флешку.''' Воткните флешку в USB-порт роутера. Откройте веб-интерфейс: '''Приложения → USB-диски и принтеры''' — диск должен появиться в списке. Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' → '''EXT4'''.
#: [[File:keenetic_usb_disks.png|frame|center|Страница «USB-диски и принтеры» в веб-интерфейсе Keenetic с подключённой USB-флешкой и опцией «Форматировать» в EXT4.]]
# '''Откройте встроенный веб-CLI Keenetic:''' <code>http://192.168.1.1/a</code> (или подставьте свой LAN-IP роутера, если он другой). Должно появиться приглашение <code>(config)></code>.
# '''Узнайте UUID диска:'''
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
#: В ответе найдите блок с вашей флешкой и поле <code>uuid</code> внутри <code>partition</code>. Длинная строка вида <code>d5f39712-...</code> — это и есть нужное значение, скопируйте его.
# '''Запустите установку Entware.''' Подставьте '''свой UUID''' и '''URL по архитектуре''' (из таблицы «Выбор URL установщика» выше):
#: <syntaxhighlight lang="bash">opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ></syntaxhighlight>
#: Пример с реальными подставленными значениями (mipsel):
#: <syntaxhighlight lang="bash">opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</syntaxhighlight>
#: '''Угловых скобок <code><</code><code>></code> в финальной команде остаться не должно.''' Двоеточие и слэш <code>:/</code> сразу после UUID — обязательны. После UUID и перед URL — ровно один пробел.
# '''Сразу включите DNS-override и сохраните конфиг:'''
#: <syntaxhighlight lang="bash">opkg dns-override
system configuration save</syntaxhighlight>
#: <code>opkg dns-override</code> заставит KeeneticOS отдавать DNS-запросы клиентов в Entware-овский dnsmasq, который потом будет управляться keen-pbr. Без этого keen-pbr не сможет перехватывать DNS и маршрутизация по доменам работать не будет. Опция применится после reboot ниже.
# '''Дождитесь окончания установки.''' Откройте журнал в веб-интерфейсе: <code>http://192.168.1.1/diagnostics/general/log</code> (если LAN-IP другой — подставьте). Установщик пишет туда что делает: качает <code>installer.tar.gz</code>, распаковывает в <code>/opt</code>, ставит базовые пакеты. Это занимает 2–5 минут. Ждите финальной строки <code>Entware installed</code>.
#: [[File:keenetic_log_entware_installed.png|frame|center|Системный журнал Keenetic (/diagnostics/general/log) с финальной строкой «Entware installed» — установка завершилась успешно, можно перезагружать роутер.]]
#: <div style="padding: 8px 12px; margin: 8px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">'''Не перезагружайте роутер до этой строки в журнале!''' Если ребутнуть роутер посреди установки, файлы Entware на флешке останутся неконсистентными, и на следующих этапах посыпятся странные ошибки.</div>
# '''Перезагрузите роутер из веб-CLI:'''
#: <syntaxhighlight lang="bash">system reboot</syntaxhighlight>
#: Через 1–2 минуты роутер поднимется обратно. После reboot применятся: монтирование Entware с флешки в <code>/opt</code>, автозапуск его сервисов, а главное — <code>opkg dns-override</code> из шага 5.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Если установщик молчит:''' В некоторых сборках команда <code>opkg disk ... URL</code> молчит, если OPKG-диск уже был назначен раньше. В журнале нет строк про загрузку <code>installer.tar.gz</code>? Сбросьте назначение диска и повторите шаги 4–5:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk <ВАШ_UUID>:/ <URL>
opkg dns-override
system configuration save
</syntaxhighlight>
</div>

== 1.2. Первое подключение по SSH ==

После перезагрузки Entware поднимает встроенный SSH-сервер на порту '''222'''.

На Windows — открываете PowerShell и подключаетесь одной командой:

<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

(LAN-IP роутера другой — подставьте.)

Параметры подключения:

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|LAN-IP роутера (<code>192.168.1.1</code> по умолчанию)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code> (заводской)
|}

При первом подключении SSH спросит fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>
Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' дефолтный <code>keenetic</code> известен всем. Если SSH когда-нибудь будет проброшен наружу — роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите ходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце документа. Для базовой установки это '''не нужно''' — переходите к Этапу 2.
</div>

----

'''Всё готово для установки утилит.''' Переходите к Этапу 2.

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про место:''' <code>sing-box-go</code> занимает ~62 МБ распакованных, плюс ~7 МБ сам helper, плюс Entware-окружение. На встроенной флэш-памяти роутера не помещается — Entware '''должен''' быть на USB (см. Этап 1).
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.

На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.

Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>. UI покажет жёлтое предупреждение под распознанными параметрами. Решение — попросить владельца сервера переключить транспорт на <code>ws</code>, <code>grpc</code> или <code>tcp</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

[[File:keenpbr_outbounds.png|frame|center|Страница «Outbounds (выходы)» в веб-интерфейсе keen-pbr со списком из трёх выходов: wan, block, vpn (interface=singtun).]]

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

[[File:keenpbr_routing_rules.png|frame|center|Страница «Правила маршрутизации» в веб-интерфейсе keen-pbr с активным правилом #2 bypass → vpn (и опционально #1 local_list → block).]]

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
sh /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок.

== 3.5. Тестирование ==
На клиентском устройстве, подключённом к Keenetic:

# '''Очистите кеш DNS''' (важно — без этого старые ответы остаются):
#* Windows: <code>ipconfig /flushdns</code> в PowerShell.
#* Android / iOS: переподключиться к Wi-Fi (off → on).
#* macOS: <code>sudo dscacheutil -flushcache</code>.
# Перезапустите браузер (у него свой DNS-кеш).
# Откройте сайт из списка bypass.
# Параллельно откройте <code>https://api.ipify.org</code> в браузере. Адрес должен быть тот же, который вы видели в шаге «IP через TUN» на вкладке Главная UI singbox-helper (т.е. IP вашего VPN-провайдера, а не домашний WAN-IP).

[[File:client_ipify_through_tunnel.png|frame|center|Страница https://api.ipify.org, открытая на клиентском устройстве, показывает IP туннеля (а не домашний WAN-IP) — значит маршрутизация bypass-домена через singtun работает.]]

----

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web
</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Замечание про «failed» в конце установки:''' В выводе установщика вы можете увидеть строку:
<pre>
Starting /opt/sbin/lighttpd... failed.
NFQWS2 Web Interface installed: http://192.168.10.1:90
</pre>
Это '''не ошибка'''. lighttpd пытается стартануть до того, как все его модули (php8-mod-curl, php8-mod-session, mod-rewrite, mod-redirect) полностью зарегистрировались. Через несколько секунд стартовый скрипт <code>S80lighttpd</code> успешно поднимает сервис. Достаточно проверить:
<syntaxhighlight lang="bash">
pgrep -af lighttpd
netstat -tlnup | grep :90
</syntaxhighlight>
Оба должны показать запущенный процесс на порту 90. Если веб-интерфейс открывается на <code>http://LAN-АДРЕС-РОУТЕРА:90</code> — всё в порядке.
</div>

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>http://192.168.10.1:90</code>.

Для доступа из другой подсети — открыть порт <code>90</code> в фаерволе Keenetic (по аналогии с keen-pbr WebUI).

----

= Финальная архитектура =
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

<pre>
K E E N E T I C Р О У Т Е Р
┌───────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ │
LAN│ │ DNS-запрос │ │
───┼──►│ от клиента │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ upstream ┌────────────────┐ │
│ │ keen-pbr │ через │ Quad9 9.9.9.9 │ │
│ │ dnsmasq │ ─────────► │ │ │
│ │ на :53 │ │ │ │
│ └──────┬───────┘ └────────────────┘ │
│ │ IP → ipset │
│ │ │
│ ┌──────▼──────────────────────────────────────────────┐ │
LAN│ │ iptables / маршрутизация │ │
───┼──►│ ├ если dst-IP в ipset bypass: │ │
TCP│ │ │ fwmark → ip rule → table 151 → singtun │ │
│ │ │ │ │
│ │ └ иначе: │ │
│ │ обычный WAN-маршрут │ │
│ │ └ nfqws2 ловит первые пакеты │ │
│ │ и модифицирует для обхода DPI │ │
│ └────┬──────────────────────────────────────────┬─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌────────────────┐ │
│ │ singtun │ │ WAN-интерфейс │ │
│ │ (TUN) │ │ (ваш провайдер)│ │
│ └────┬────┘ └────────┬───────┘ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────┐ │ │
│ │ sing-box │ │ │
│ │ outbound: │ │ │
│ │ hysteria2 │ │ │
│ └──────┬──────┘ │ │
│ │ │ │
└──────────┼────────────────────────────────────────┼───────────────────────┘
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ VPN-узел │ │ Любой │
│ провайдера│ │ интернет │
└───────────┘ └───────────┘
</pre>

''(Здесь можно перерисовать в Mermaid/Excalidraw для финальной картинки.)''

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T16:57:39Z

Владимир:

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
<pre>
KEENETIC РОУТЕР

┌──────────────────────────────────────────────────────────────┐
│ │
│ ┌────────────────┐ │
│ │ keen-pbr │ --- адрес домена в списке? --- │
│ │ (по доменам) │ │ │ │
│ └────────────────┘ │ ДА │ НЕТ │
│ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ │
│ │ singtun │ │ nfqws2 │ │
│ │ (sing-box) │ │ DPI fix │ │
│ └────────────┘ └────────────┘ │
│ │ │ │
└────────────────────────────┼────────────────┼────────────────┘
│ │
┌────▼────┐ ┌────▼────┐
│ VPN- │ │ Прямой │
│ сервер │ │ WAN │
└─────────┘ └─────────┘
</pre>
''(Здесь схему можно перерисовать в Mermaid или Excalidraw и заменить блок.)''

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== Какая у вас прошивка ==
KeeneticOS существует в двух вариантах, и от этого зависит, нужен ли вам отдельный шаг включения компонентов прошивки.

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. подсекцию «Только для оригинального Keenetic» ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', всё уже в образе прошивки порта — пропускайте подсекцию ниже и сразу переходите к «Выбор URL установщика»
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как понять, какая у вас:''' На странице '''Системный монитор''' видна модель устройства. Маркетинговое имя "Keenetic Hero" и модель "KN-..." — это оригинальный Keenetic. Имя другого производителя (например, "Xiaomi R3G") + KeeneticOS — это порт сообщества. Дополнительный признак порта — на странице компонентов сообщение «Не удалось получить список компонентов от сервера» (своего сервера обновлений у порта нет).
</div>

== Только для оригинального Keenetic ==
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:

{| class="wikitable"
!Компонент
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|База Entware
|-
|'''Файловая система Ext'''
|Монтирование ext4-флешки
|-
|'''Сервер SSH'''
|Командная строка роутера
|-
|"Netfilter" / "Модули ядра Netfilter"
|База iptables для Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Доп. модули (<code>xt_set</code>, <code>xt_multiport</code>, <code>conntrack-extra</code>) — '''критично''' для keen-pbr
|}

После выбора — '''Установить обновление''' и ждите 2–5 минут, роутер перезагрузится сам.

''(Скриншот: страница "Обновления и компоненты" с открытым окном "Показать компоненты".)''

== Выбор URL установщика ==
{| class="wikitable"
!Архитектура роутера
!URL установщика (одной строкой)
|-
|'''MIPS little-endian (mipsel)''' — большинство Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Как узнать архитектуру:''' '''Системный монитор''' → видна модель и процессор. Большинство бытовых моделей — MIPS (верхняя строка). Сомневаетесь — берите mipsel; если не подходит, установщик ругнётся, роутер от этого не сломается.
</div>

== Что вам понадобится ==
Перед тем как идти в командную строку, держите под рукой два значения:

{| class="wikitable"
!Параметр
!Откуда взять
!Пример
|-
|'''UUID USB-диска'''
|<code>show media</code> в веб-CLI Keenetic (см. шаг 3 в 1.1), поле <code>uuid</code> внутри <code>partition</code>
|<code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>
|-
|'''URL установщика'''
|Из таблицы «Выбор URL установщика» выше — по архитектуре
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|}

== 1.1. Установка Entware через командную строку ==

# '''Подключите USB-флешку.''' Воткните флешку в USB-порт роутера. Откройте веб-интерфейс: '''Приложения → USB-диски и принтеры''' — диск должен появиться в списке. Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' → '''EXT4'''.
#: ''(Скриншот: страница «USB-диски и принтеры» с подключённой флешкой.)''
# '''Откройте встроенный веб-CLI Keenetic:''' <code>http://192.168.1.1/a</code> (или подставьте свой LAN-IP роутера, если он другой). Должно появиться приглашение <code>(config)></code>.
# '''Узнайте UUID диска:'''
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
#: В ответе найдите блок с вашей флешкой и поле <code>uuid</code> внутри <code>partition</code>. Длинная строка вида <code>d5f39712-...</code> — это и есть нужное значение, скопируйте его.
# '''Запустите установку Entware.''' Подставьте '''свой UUID''' и '''URL по архитектуре''' (из таблицы «Выбор URL установщика» выше):
#: <syntaxhighlight lang="bash">opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ></syntaxhighlight>
#: Пример с реальными подставленными значениями (mipsel):
#: <syntaxhighlight lang="bash">opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</syntaxhighlight>
#: '''Угловых скобок <code><</code><code>></code> в финальной команде остаться не должно.''' Двоеточие и слэш <code>:/</code> сразу после UUID — обязательны. После UUID и перед URL — ровно один пробел.
# '''Сразу включите DNS-override и сохраните конфиг:'''
#: <syntaxhighlight lang="bash">opkg dns-override
system configuration save</syntaxhighlight>
#: <code>opkg dns-override</code> заставит KeeneticOS отдавать DNS-запросы клиентов в Entware-овский dnsmasq, который потом будет управляться keen-pbr. Без этого keen-pbr не сможет перехватывать DNS и маршрутизация по доменам работать не будет. Опция применится после reboot ниже.
# '''Дождитесь окончания установки.''' Откройте журнал в веб-интерфейсе: <code>http://192.168.1.1/diagnostics/general/log</code> (если LAN-IP другой — подставьте). Установщик пишет туда что делает: качает <code>installer.tar.gz</code>, распаковывает в <code>/opt</code>, ставит базовые пакеты. Это занимает 2–5 минут. Ждите финальной строки <code>Entware installed</code>.
#: ''(Скриншот: журнал с финальной строкой «Entware installed».)''
#: <div style="padding: 8px 12px; margin: 8px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">'''Не перезагружайте роутер до этой строки в журнале!''' Если ребутнуть роутер посреди установки, файлы Entware на флешке останутся неконсистентными, и на следующих этапах посыпятся странные ошибки.</div>
# '''Перезагрузите роутер из веб-CLI:'''
#: <syntaxhighlight lang="bash">system reboot</syntaxhighlight>
#: Через 1–2 минуты роутер поднимется обратно. После reboot применятся: монтирование Entware с флешки в <code>/opt</code>, автозапуск его сервисов, а главное — <code>opkg dns-override</code> из шага 5.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Если установщик молчит:''' В некоторых сборках команда <code>opkg disk ... URL</code> молчит, если OPKG-диск уже был назначен раньше. В журнале нет строк про загрузку <code>installer.tar.gz</code>? Сбросьте назначение диска и повторите шаги 4–5:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk <ВАШ_UUID>:/ <URL>
opkg dns-override
system configuration save
</syntaxhighlight>
</div>

== 1.2. Первое подключение по SSH ==

После перезагрузки Entware поднимает встроенный SSH-сервер на порту '''222'''.

На Windows — открываете PowerShell и подключаетесь одной командой:

<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

(LAN-IP роутера другой — подставьте.)

Параметры подключения:

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|LAN-IP роутера (<code>192.168.1.1</code> по умолчанию)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code> (заводской)
|}

При первом подключении SSH спросит fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>
Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' дефолтный <code>keenetic</code> известен всем. Если SSH когда-нибудь будет проброшен наружу — роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите ходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце документа. Для базовой установки это '''не нужно''' — переходите к Этапу 2.
</div>

----

'''Всё готово для установки утилит.''' Переходите к Этапу 2.

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про место:''' <code>sing-box-go</code> занимает ~62 МБ распакованных, плюс ~7 МБ сам helper, плюс Entware-окружение. На встроенной флэш-памяти роутера не помещается — Entware '''должен''' быть на USB (см. Этап 1).
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.

На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.

Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>. UI покажет жёлтое предупреждение под распознанными параметрами. Решение — попросить владельца сервера переключить транспорт на <code>ws</code>, <code>grpc</code> или <code>tcp</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

''(Скриншот: страница "Outbounds (выходы)" с тремя строками: wan, block, vpn.)''

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

''(Скриншот: страница "Правила маршрутизации" с активным правилом #2 bypass → vpn.)''

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
sh /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок.

== 3.5. Тестирование ==
На клиентском устройстве, подключённом к Keenetic:

# '''Очистите кеш DNS''' (важно — без этого старые ответы остаются):
#* Windows: <code>ipconfig /flushdns</code> в PowerShell.
#* Android / iOS: переподключиться к Wi-Fi (off → on).
#* macOS: <code>sudo dscacheutil -flushcache</code>.
# Перезапустите браузер (у него свой DNS-кеш).
# Откройте сайт из списка bypass.
# Параллельно откройте <code>https://api.ipify.org</code> в браузере. Адрес должен быть тот же, который вы видели в шаге «IP через TUN» на вкладке Главная UI singbox-helper (т.е. IP вашего VPN-провайдера, а не домашний WAN-IP).

''(Скриншот: страница api.ipify.org с подменённым IP.)''

----

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web
</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Замечание про «failed» в конце установки:''' В выводе установщика вы можете увидеть строку:
<pre>
Starting /opt/sbin/lighttpd... failed.
NFQWS2 Web Interface installed: http://192.168.10.1:90
</pre>
Это '''не ошибка'''. lighttpd пытается стартануть до того, как все его модули (php8-mod-curl, php8-mod-session, mod-rewrite, mod-redirect) полностью зарегистрировались. Через несколько секунд стартовый скрипт <code>S80lighttpd</code> успешно поднимает сервис. Достаточно проверить:
<syntaxhighlight lang="bash">
pgrep -af lighttpd
netstat -tlnup | grep :90
</syntaxhighlight>
Оба должны показать запущенный процесс на порту 90. Если веб-интерфейс открывается на <code>http://LAN-АДРЕС-РОУТЕРА:90</code> — всё в порядке.
</div>

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>http://192.168.10.1:90</code>.

Для доступа из другой подсети — открыть порт <code>90</code> в фаерволе Keenetic (по аналогии с keen-pbr WebUI).

----

= Финальная архитектура =
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

<pre>
K E E N E T I C Р О У Т Е Р
┌───────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ │
LAN│ │ DNS-запрос │ │
───┼──►│ от клиента │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ upstream ┌────────────────┐ │
│ │ keen-pbr │ через │ Quad9 9.9.9.9 │ │
│ │ dnsmasq │ ─────────► │ │ │
│ │ на :53 │ │ │ │
│ └──────┬───────┘ └────────────────┘ │
│ │ IP → ipset │
│ │ │
│ ┌──────▼──────────────────────────────────────────────┐ │
LAN│ │ iptables / маршрутизация │ │
───┼──►│ ├ если dst-IP в ipset bypass: │ │
TCP│ │ │ fwmark → ip rule → table 151 → singtun │ │
│ │ │ │ │
│ │ └ иначе: │ │
│ │ обычный WAN-маршрут │ │
│ │ └ nfqws2 ловит первые пакеты │ │
│ │ и модифицирует для обхода DPI │ │
│ └────┬──────────────────────────────────────────┬─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌────────────────┐ │
│ │ singtun │ │ WAN-интерфейс │ │
│ │ (TUN) │ │ (ваш провайдер)│ │
│ └────┬────┘ └────────┬───────┘ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────┐ │ │
│ │ sing-box │ │ │
│ │ outbound: │ │ │
│ │ hysteria2 │ │ │
│ └──────┬──────┘ │ │
│ │ │ │
└──────────┼────────────────────────────────────────┼───────────────────────┘
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ VPN-узел │ │ Любой │
│ провайдера│ │ интернет │
└───────────┘ └───────────┘
</pre>

''(Здесь можно перерисовать в Mermaid/Excalidraw для финальной картинки.)''

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T16:32:51Z

Владимир: /* Подключитесь по SSH к роутеру и выполните одну команду: */

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
<pre>
KEENETIC РОУТЕР

┌──────────────────────────────────────────────────────────────┐
│ │
│ ┌────────────────┐ │
│ │ keen-pbr │ --- адрес домена в списке? --- │
│ │ (по доменам) │ │ │ │
│ └────────────────┘ │ ДА │ НЕТ │
│ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ │
│ │ singtun │ │ nfqws2 │ │
│ │ (sing-box) │ │ DPI fix │ │
│ └────────────┘ └────────────┘ │
│ │ │ │
└────────────────────────────┼────────────────┼────────────────┘
│ │
┌────▼────┐ ┌────▼────┐
│ VPN- │ │ Прямой │
│ сервер │ │ WAN │
└─────────┘ └─────────┘
</pre>
''(Здесь схему можно перерисовать в Mermaid или Excalidraw и заменить блок.)''

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== 1.1. Подготовка USB-накопителя ==
=== Подключение и форматирование ===
# Воткните флешку в USB-порт роутера.
# Откройте веб-интерфейс Keenetic: '''Приложения''' → '''USB-диски и принтеры'''.
# В списке появится диск. Откройте его параметры.
# Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' и выберите '''EXT4'''.

''(Скриншот: страница "USB-диски" в веб-интерфейсе Keenetic с подключённым диском и кнопкой "Форматировать".)''

=== Узнайте UUID диска через CLI ===
У диска есть уникальный '''UUID''' (длинная строка вида <code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>), который понадобится для установки Entware. Веб-интерфейс Keenetic показывает UUID на странице диска, '''но не позволяет его выделить и скопировать''' — поэтому удобнее получить его через встроенную командную строку.

# Откройте в браузере адрес <code>http://192.168.1.1/a</code> — это встроенный веб-CLI Keenetic. Должно появиться приглашение <code>(config)></code>.
# Выполните команду:
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
# В ответе найдите блок с вашей флешкой и строку <code>uuid</code> внутри <code>partition</code>. Пример вывода:

<syntaxhighlight lang="json">
{
"media": {
"Media0": {
"bus": "usb",
"manufacturer": "SanDisk",
"product": "Ultra",
"state": "ACTIVE",
"partition": [
{
"uuid": "d5f39712-7ae1-dc01-00f3-97127ae1dc01",
"fstype": "ext4",
"state": "MOUNTED",
...
}
]
}
}
}
</syntaxhighlight>

Скопируйте значение поля <code>uuid</code> внутри <code>partition</code> — оно понадобится в следующем шаге.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — пока вы в CLI, можно сразу включить DNS Override.''' Эта опция понадобится позже для keen-pbr — она заставляет KeeneticOS отдавать DNS-трафик в Entware-овский dnsmasq. Чтобы не возвращаться в CLI отдельно, выполните прямо сейчас:
<syntaxhighlight lang="bash">
opkg dns-override
system configuration save
</syntaxhighlight>
Опция применится после ближайшей перезагрузки роутера (она будет в конце Этапа 1).
</div>

== 1.2. Компоненты KeeneticOS ==
=== Какая у вас прошивка? ===
KeeneticOS существует в двух вариантах, и от этого зависит, нужно ли вам что-то включать на этом этапе:

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (роутер, который продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', все нужные пакеты уже включены в образ прошивки этого порта — переходите к разделу 1.3
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — как понять, какая у вас прошивка:''' На странице '''Системный монитор''' (главная страница веб-интерфейса) видна модель устройства. Если рядом с моделью стоит знакомое маркетинговое имя Keenetic (например, "Keenetic Hero") и модель начинается с "KN-" — это оригинальный Keenetic. Если вы видите название роутера другого производителя (например, "Xiaomi R3G") и при этом отображается KeeneticOS — у вас порт сообщества.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Признак порта сообщества:''' На странице с компонентами окно "Компоненты операционной системы" может показывать сообщение "Не удалось получить список компонентов от сервера" — это нормально для портированных сборок, у которых нет своего сервера обновлений. В этом случае шаг с компонентами '''не нужен''' — переходите к разделу 1.3.
</div>

=== Только для оригинального Keenetic ===
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в более старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:
{| class="wikitable"
!Компонент (точное название в UI)
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|Базовая инфраструктура Entware — без этого нельзя ставить пакеты на USB
|-
|'''Файловая система Ext'''
|Чтобы роутер мог монтировать ext4-диск
|-
|'''Сервер SSH'''
|Доступ к командной строке роутера
|}

Кроме того, '''желательно''' проверить наличие следующих компонентов (точные названия в интерфейсе могут отличаться от версии к версии — ищите по словам):

{| class="wikitable"
!Что искать в списке
!Зачем
|-
|"Netfilter" / "Модули ядра Netfilter"
|Базовые модули iptables для работы фаервола Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Дополнительные модули (xt_set, xt_multiport, conntrack-extra) — '''критично''' для работы keen-pbr
|}

После выбора нажмите '''Установить обновление''' и подождите 2–5 минут. Роутер перезагрузится самостоятельно.

''(Скриншот: страница "Обновления и компоненты" с открытым окном "Показать компоненты" и отмеченными нужными пунктами.)''

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В KeeneticOS 5 и новее компонент '''Протокол IPv6''' включён по умолчанию и не может быть отключён — это нормально.
</div>

== 1.3. Установка Entware через командную строку ==
=== Открытие командной строки роутера ===
Если вы вышли из CLI после шага 1.1 — откройте снова: <code>http://192.168.1.1/a</code>. Должно появиться приглашение <code>(config)></code>.

=== Запуск установки Entware ===
Команда состоит из '''двух частей, которые вы должны подставить сами''':

# '''UUID вашего USB-диска''' — тот, который вы получили командой <code>show media</code> в разделе '''1.1''' (длинная строка вида <code>d5f39712-7ae1-...</code>).
# '''URL установщика''' — выбирается по архитектуре вашего роутера (см. таблицу ниже).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — не копируйте команду как есть!''' В шаблоне ниже фигурные скобки <code><...></code> — это места, куда нужно подставить '''ваши''' значения. Если оставить шаблон с угловыми скобками или скопировать чужой UUID — установка не сработает.
</div>

==== Шаблон команды ====
<syntaxhighlight lang="bash">
opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ>
</syntaxhighlight>

==== Выбор URL установщика ====
{| class="wikitable"
!Архитектура роутера
!URL установщика (целиком)
|-
|'''MIPS little-endian (mipsel)''' — большинство моделей Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — как узнать архитектуру:''' Откройте '''Системный монитор''' в веб-интерфейсе → видно модель устройства и процессор. Для большинства бытовых моделей это MIPS — берите верхнюю строку таблицы. Если сомневаетесь — пишите команду с <code>mipsel</code>: если архитектура не подходит, установка скажет об этом ошибкой, и вы не сломаете роутер.
</div>

==== Пример с подставленными значениями ====
Допустим, ваш UUID — <code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>, архитектура — mipsel. Тогда команда полностью выглядит так:
<syntaxhighlight lang="bash">
opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Это '''пример''' — UUID <code>d5f39712-...</code> здесь приведён только для иллюстрации. У '''вашего''' диска UUID будет '''другой'''. Подставьте именно свой со страницы "Диски и принтеры".
</div>

==== Проверочный чек-лист перед нажатием Enter ====
* Двоеточие и слэш <code>:/</code> сразу после UUID — '''обязательны'''.
* URL — '''одной строкой''', без пробелов и переносов.
* После UUID и перед URL — '''ровно один пробел'''.
* Угловых скобок <code><</code> и <code>></code> в финальной команде '''не должно остаться'''.

=== Сохранение конфигурации и перезагрузка ===
После того как установка прошла без ошибок, сохраните конфигурацию и перезагрузите роутер:
<syntaxhighlight lang="bash">
system configuration save
system reboot
</syntaxhighlight>

Перезагрузка нужна, чтобы применился <code>opkg dns-override</code>, который вы включили на шаге 1.1. Ожидайте 1–2 минуты, пока роутер поднимется обратно.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — если установщик "молчит":''' В некоторых сборках команда <code>opkg disk ... URL</code> не работает, если OPKG-диск уже был назначен раньше. Если в логе вы не видите строк про загрузку <code>mipsel-installer.tar.gz</code> — сбросьте диск и повторите:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
</syntaxhighlight>
</div>

=== Проверка установки ===
Откройте журнал: '''Диагностика''' → '''Системный журнал'''. Должны появиться строки примерно такого содержания:
<pre>
Opkg::Manager: downloading installer...
Opkg::Manager: extracting to /opt...
Opkg::Manager: ...
Entware installed.
</pre>

После завершения установки на роутере поднимется встроенный SSH-сервер Entware на порту '''222'''.

== 1.4. Первое подключение по SSH ==
Подключитесь к роутеру с компьютера. На Windows — через PuTTY или через стандартный <code>ssh.exe</code>.

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|<code>192.168.1.1</code> (LAN-адрес роутера)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code>
|}

Из PowerShell это одна строка:
<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

При первом подключении ssh попросит подтвердить fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа смените пароль:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>

Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Дефолтный пароль <code>keenetic</code> известен всем — если SSH будет проброшен наружу, роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите заходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце этого документа. Для базовой установки sing-box / keen-pbr / nfqws2 это '''не нужно''' — переходите к Этапу 2.
</div>

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про место:''' <code>sing-box-go</code> занимает ~62 МБ распакованных, плюс ~7 МБ сам helper, плюс Entware-окружение. На встроенной флэш-памяти роутера не помещается — Entware '''должен''' быть на USB (см. Этап 1).
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.

На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.

Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>. UI покажет жёлтое предупреждение под распознанными параметрами. Решение — попросить владельца сервера переключить транспорт на <code>ws</code>, <code>grpc</code> или <code>tcp</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

''(Скриншот: страница "Outbounds (выходы)" с тремя строками: wan, block, vpn.)''

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

''(Скриншот: страница "Правила маршрутизации" с активным правилом #2 bypass → vpn.)''

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
sh /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок.

== 3.5. Тестирование ==
На клиентском устройстве, подключённом к Keenetic:

# '''Очистите кеш DNS''' (важно — без этого старые ответы остаются):
#* Windows: <code>ipconfig /flushdns</code> в PowerShell.
#* Android / iOS: переподключиться к Wi-Fi (off → on).
#* macOS: <code>sudo dscacheutil -flushcache</code>.
# Перезапустите браузер (у него свой DNS-кеш).
# Откройте сайт из списка bypass.
# Параллельно откройте <code>https://api.ipify.org</code> в браузере. Адрес должен быть тот же, который вы видели в шаге «IP через TUN» на вкладке Главная UI singbox-helper (т.е. IP вашего VPN-провайдера, а не домашний WAN-IP).

''(Скриншот: страница api.ipify.org с подменённым IP.)''

----

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web
</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Замечание про «failed» в конце установки:''' В выводе установщика вы можете увидеть строку:
<pre>
Starting /opt/sbin/lighttpd... failed.
NFQWS2 Web Interface installed: http://192.168.10.1:90
</pre>
Это '''не ошибка'''. lighttpd пытается стартануть до того, как все его модули (php8-mod-curl, php8-mod-session, mod-rewrite, mod-redirect) полностью зарегистрировались. Через несколько секунд стартовый скрипт <code>S80lighttpd</code> успешно поднимает сервис. Достаточно проверить:
<syntaxhighlight lang="bash">
pgrep -af lighttpd
netstat -tlnup | grep :90
</syntaxhighlight>
Оба должны показать запущенный процесс на порту 90. Если веб-интерфейс открывается на <code>http://LAN-АДРЕС-РОУТЕРА:90</code> — всё в порядке.
</div>

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>http://192.168.10.1:90</code>.

Для доступа из другой подсети — открыть порт <code>90</code> в фаерволе Keenetic (по аналогии с keen-pbr WebUI).

----

= Финальная архитектура =
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

<pre>
K E E N E T I C Р О У Т Е Р
┌───────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ │
LAN│ │ DNS-запрос │ │
───┼──►│ от клиента │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ upstream ┌────────────────┐ │
│ │ keen-pbr │ через │ Quad9 9.9.9.9 │ │
│ │ dnsmasq │ ─────────► │ │ │
│ │ на :53 │ │ │ │
│ └──────┬───────┘ └────────────────┘ │
│ │ IP → ipset │
│ │ │
│ ┌──────▼──────────────────────────────────────────────┐ │
LAN│ │ iptables / маршрутизация │ │
───┼──►│ ├ если dst-IP в ipset bypass: │ │
TCP│ │ │ fwmark → ip rule → table 151 → singtun │ │
│ │ │ │ │
│ │ └ иначе: │ │
│ │ обычный WAN-маршрут │ │
│ │ └ nfqws2 ловит первые пакеты │ │
│ │ и модифицирует для обхода DPI │ │
│ └────┬──────────────────────────────────────────┬─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌────────────────┐ │
│ │ singtun │ │ WAN-интерфейс │ │
│ │ (TUN) │ │ (ваш провайдер)│ │
│ └────┬────┘ └────────┬───────┘ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────┐ │ │
│ │ sing-box │ │ │
│ │ outbound: │ │ │
│ │ hysteria2 │ │ │
│ └──────┬──────┘ │ │
│ │ │ │
└──────────┼────────────────────────────────────────┼───────────────────────┘
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ VPN-узел │ │ Любой │
│ провайдера│ │ интернет │
└───────────┘ └───────────┘
</pre>

''(Здесь можно перерисовать в Mermaid/Excalidraw для финальной картинки.)''

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T16:02:07Z

Владимир: /* А.5. Скрипт пересоздания /var/empty при загрузке */

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
<pre>
KEENETIC РОУТЕР

┌──────────────────────────────────────────────────────────────┐
│ │
│ ┌────────────────┐ │
│ │ keen-pbr │ --- адрес домена в списке? --- │
│ │ (по доменам) │ │ │ │
│ └────────────────┘ │ ДА │ НЕТ │
│ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ │
│ │ singtun │ │ nfqws2 │ │
│ │ (sing-box) │ │ DPI fix │ │
│ └────────────┘ └────────────┘ │
│ │ │ │
└────────────────────────────┼────────────────┼────────────────┘
│ │
┌────▼────┐ ┌────▼────┐
│ VPN- │ │ Прямой │
│ сервер │ │ WAN │
└─────────┘ └─────────┘
</pre>
''(Здесь схему можно перерисовать в Mermaid или Excalidraw и заменить блок.)''

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== 1.1. Подготовка USB-накопителя ==
=== Подключение и форматирование ===
# Воткните флешку в USB-порт роутера.
# Откройте веб-интерфейс Keenetic: '''Приложения''' → '''USB-диски и принтеры'''.
# В списке появится диск. Откройте его параметры.
# Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' и выберите '''EXT4'''.

''(Скриншот: страница "USB-диски" в веб-интерфейсе Keenetic с подключённым диском и кнопкой "Форматировать".)''

=== Узнайте UUID диска через CLI ===
У диска есть уникальный '''UUID''' (длинная строка вида <code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>), который понадобится для установки Entware. Веб-интерфейс Keenetic показывает UUID на странице диска, '''но не позволяет его выделить и скопировать''' — поэтому удобнее получить его через встроенную командную строку.

# Откройте в браузере адрес <code>http://192.168.1.1/a</code> — это встроенный веб-CLI Keenetic. Должно появиться приглашение <code>(config)></code>.
# Выполните команду:
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
# В ответе найдите блок с вашей флешкой и строку <code>uuid</code> внутри <code>partition</code>. Пример вывода:

<syntaxhighlight lang="json">
{
"media": {
"Media0": {
"bus": "usb",
"manufacturer": "SanDisk",
"product": "Ultra",
"state": "ACTIVE",
"partition": [
{
"uuid": "d5f39712-7ae1-dc01-00f3-97127ae1dc01",
"fstype": "ext4",
"state": "MOUNTED",
...
}
]
}
}
}
</syntaxhighlight>

Скопируйте значение поля <code>uuid</code> внутри <code>partition</code> — оно понадобится в следующем шаге.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — пока вы в CLI, можно сразу включить DNS Override.''' Эта опция понадобится позже для keen-pbr — она заставляет KeeneticOS отдавать DNS-трафик в Entware-овский dnsmasq. Чтобы не возвращаться в CLI отдельно, выполните прямо сейчас:
<syntaxhighlight lang="bash">
opkg dns-override
system configuration save
</syntaxhighlight>
Опция применится после ближайшей перезагрузки роутера (она будет в конце Этапа 1).
</div>

== 1.2. Компоненты KeeneticOS ==
=== Какая у вас прошивка? ===
KeeneticOS существует в двух вариантах, и от этого зависит, нужно ли вам что-то включать на этом этапе:

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (роутер, который продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', все нужные пакеты уже включены в образ прошивки этого порта — переходите к разделу 1.3
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — как понять, какая у вас прошивка:''' На странице '''Системный монитор''' (главная страница веб-интерфейса) видна модель устройства. Если рядом с моделью стоит знакомое маркетинговое имя Keenetic (например, "Keenetic Hero") и модель начинается с "KN-" — это оригинальный Keenetic. Если вы видите название роутера другого производителя (например, "Xiaomi R3G") и при этом отображается KeeneticOS — у вас порт сообщества.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Признак порта сообщества:''' На странице с компонентами окно "Компоненты операционной системы" может показывать сообщение "Не удалось получить список компонентов от сервера" — это нормально для портированных сборок, у которых нет своего сервера обновлений. В этом случае шаг с компонентами '''не нужен''' — переходите к разделу 1.3.
</div>

=== Только для оригинального Keenetic ===
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в более старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:
{| class="wikitable"
!Компонент (точное название в UI)
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|Базовая инфраструктура Entware — без этого нельзя ставить пакеты на USB
|-
|'''Файловая система Ext'''
|Чтобы роутер мог монтировать ext4-диск
|-
|'''Сервер SSH'''
|Доступ к командной строке роутера
|}

Кроме того, '''желательно''' проверить наличие следующих компонентов (точные названия в интерфейсе могут отличаться от версии к версии — ищите по словам):

{| class="wikitable"
!Что искать в списке
!Зачем
|-
|"Netfilter" / "Модули ядра Netfilter"
|Базовые модули iptables для работы фаервола Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Дополнительные модули (xt_set, xt_multiport, conntrack-extra) — '''критично''' для работы keen-pbr
|}

После выбора нажмите '''Установить обновление''' и подождите 2–5 минут. Роутер перезагрузится самостоятельно.

''(Скриншот: страница "Обновления и компоненты" с открытым окном "Показать компоненты" и отмеченными нужными пунктами.)''

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В KeeneticOS 5 и новее компонент '''Протокол IPv6''' включён по умолчанию и не может быть отключён — это нормально.
</div>

== 1.3. Установка Entware через командную строку ==
=== Открытие командной строки роутера ===
Если вы вышли из CLI после шага 1.1 — откройте снова: <code>http://192.168.1.1/a</code>. Должно появиться приглашение <code>(config)></code>.

=== Запуск установки Entware ===
Команда состоит из '''двух частей, которые вы должны подставить сами''':

# '''UUID вашего USB-диска''' — тот, который вы получили командой <code>show media</code> в разделе '''1.1''' (длинная строка вида <code>d5f39712-7ae1-...</code>).
# '''URL установщика''' — выбирается по архитектуре вашего роутера (см. таблицу ниже).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — не копируйте команду как есть!''' В шаблоне ниже фигурные скобки <code><...></code> — это места, куда нужно подставить '''ваши''' значения. Если оставить шаблон с угловыми скобками или скопировать чужой UUID — установка не сработает.
</div>

==== Шаблон команды ====
<syntaxhighlight lang="bash">
opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ>
</syntaxhighlight>

==== Выбор URL установщика ====
{| class="wikitable"
!Архитектура роутера
!URL установщика (целиком)
|-
|'''MIPS little-endian (mipsel)''' — большинство моделей Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — как узнать архитектуру:''' Откройте '''Системный монитор''' в веб-интерфейсе → видно модель устройства и процессор. Для большинства бытовых моделей это MIPS — берите верхнюю строку таблицы. Если сомневаетесь — пишите команду с <code>mipsel</code>: если архитектура не подходит, установка скажет об этом ошибкой, и вы не сломаете роутер.
</div>

==== Пример с подставленными значениями ====
Допустим, ваш UUID — <code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>, архитектура — mipsel. Тогда команда полностью выглядит так:
<syntaxhighlight lang="bash">
opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Это '''пример''' — UUID <code>d5f39712-...</code> здесь приведён только для иллюстрации. У '''вашего''' диска UUID будет '''другой'''. Подставьте именно свой со страницы "Диски и принтеры".
</div>

==== Проверочный чек-лист перед нажатием Enter ====
* Двоеточие и слэш <code>:/</code> сразу после UUID — '''обязательны'''.
* URL — '''одной строкой''', без пробелов и переносов.
* После UUID и перед URL — '''ровно один пробел'''.
* Угловых скобок <code><</code> и <code>></code> в финальной команде '''не должно остаться'''.

=== Сохранение конфигурации и перезагрузка ===
После того как установка прошла без ошибок, сохраните конфигурацию и перезагрузите роутер:
<syntaxhighlight lang="bash">
system configuration save
system reboot
</syntaxhighlight>

Перезагрузка нужна, чтобы применился <code>opkg dns-override</code>, который вы включили на шаге 1.1. Ожидайте 1–2 минуты, пока роутер поднимется обратно.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — если установщик "молчит":''' В некоторых сборках команда <code>opkg disk ... URL</code> не работает, если OPKG-диск уже был назначен раньше. Если в логе вы не видите строк про загрузку <code>mipsel-installer.tar.gz</code> — сбросьте диск и повторите:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
</syntaxhighlight>
</div>

=== Проверка установки ===
Откройте журнал: '''Диагностика''' → '''Системный журнал'''. Должны появиться строки примерно такого содержания:
<pre>
Opkg::Manager: downloading installer...
Opkg::Manager: extracting to /opt...
Opkg::Manager: ...
Entware installed.
</pre>

После завершения установки на роутере поднимется встроенный SSH-сервер Entware на порту '''222'''.

== 1.4. Первое подключение по SSH ==
Подключитесь к роутеру с компьютера. На Windows — через PuTTY или через стандартный <code>ssh.exe</code>.

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|<code>192.168.1.1</code> (LAN-адрес роутера)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code>
|}

Из PowerShell это одна строка:
<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

При первом подключении ssh попросит подтвердить fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа смените пароль:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>

Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Дефолтный пароль <code>keenetic</code> известен всем — если SSH будет проброшен наружу, роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите заходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце этого документа. Для базовой установки sing-box / keen-pbr / nfqws2 это '''не нужно''' — переходите к Этапу 2.
</div>

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про место:''' <code>sing-box-go</code> занимает ~62 МБ распакованных, плюс ~7 МБ сам helper, плюс Entware-окружение. На встроенной флэш-памяти роутера не помещается — Entware '''должен''' быть на USB (см. Этап 1).
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.

На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.

Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>. UI покажет жёлтое предупреждение под распознанными параметрами. Решение — попросить владельца сервера переключить транспорт на <code>ws</code>, <code>grpc</code> или <code>tcp</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

''(Скриншот: страница "Outbounds (выходы)" с тремя строками: wan, block, vpn.)''

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

''(Скриншот: страница "Правила маршрутизации" с активным правилом #2 bypass → vpn.)''

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
ls -la /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок.

== 3.5. Тестирование ==
На клиентском устройстве, подключённом к Keenetic:

# '''Очистите кеш DNS''' (важно — без этого старые ответы остаются):
#* Windows: <code>ipconfig /flushdns</code> в PowerShell.
#* Android / iOS: переподключиться к Wi-Fi (off → on).
#* macOS: <code>sudo dscacheutil -flushcache</code>.
# Перезапустите браузер (у него свой DNS-кеш).
# Откройте сайт из списка bypass.
# Параллельно откройте <code>https://api.ipify.org</code> в браузере. Адрес должен быть тот же, который вы видели в шаге «IP через TUN» на вкладке Главная UI singbox-helper (т.е. IP вашего VPN-провайдера, а не домашний WAN-IP).

''(Скриншот: страница api.ipify.org с подменённым IP.)''

----

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web
</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Замечание про «failed» в конце установки:''' В выводе установщика вы можете увидеть строку:
<pre>
Starting /opt/sbin/lighttpd... failed.
NFQWS2 Web Interface installed: http://192.168.10.1:90
</pre>
Это '''не ошибка'''. lighttpd пытается стартануть до того, как все его модули (php8-mod-curl, php8-mod-session, mod-rewrite, mod-redirect) полностью зарегистрировались. Через несколько секунд стартовый скрипт <code>S80lighttpd</code> успешно поднимает сервис. Достаточно проверить:
<syntaxhighlight lang="bash">
pgrep -af lighttpd
netstat -tlnup | grep :90
</syntaxhighlight>
Оба должны показать запущенный процесс на порту 90. Если веб-интерфейс открывается на <code>http://LAN-АДРЕС-РОУТЕРА:90</code> — всё в порядке.
</div>

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>http://192.168.10.1:90</code>.

Для доступа из другой подсети — открыть порт <code>90</code> в фаерволе Keenetic (по аналогии с keen-pbr WebUI).

----

= Финальная архитектура =
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

<pre>
K E E N E T I C Р О У Т Е Р
┌───────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ │
LAN│ │ DNS-запрос │ │
───┼──►│ от клиента │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ upstream ┌────────────────┐ │
│ │ keen-pbr │ через │ Quad9 9.9.9.9 │ │
│ │ dnsmasq │ ─────────► │ │ │
│ │ на :53 │ │ │ │
│ └──────┬───────┘ └────────────────┘ │
│ │ IP → ipset │
│ │ │
│ ┌──────▼──────────────────────────────────────────────┐ │
LAN│ │ iptables / маршрутизация │ │
───┼──►│ ├ если dst-IP в ipset bypass: │ │
TCP│ │ │ fwmark → ip rule → table 151 → singtun │ │
│ │ │ │ │
│ │ └ иначе: │ │
│ │ обычный WAN-маршрут │ │
│ │ └ nfqws2 ловит первые пакеты │ │
│ │ и модифицирует для обхода DPI │ │
│ └────┬──────────────────────────────────────────┬─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌────────────────┐ │
│ │ singtun │ │ WAN-интерфейс │ │
│ │ (TUN) │ │ (ваш провайдер)│ │
│ └────┬────┘ └────────┬───────┘ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────┐ │ │
│ │ sing-box │ │ │
│ │ outbound: │ │ │
│ │ hysteria2 │ │ │
│ └──────┬──────┘ │ │
│ │ │ │
└──────────┼────────────────────────────────────────┼───────────────────────┘
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ VPN-узел │ │ Любой │
│ провайдера│ │ интернет │
└───────────┘ └───────────┘
</pre>

''(Здесь можно перерисовать в Mermaid/Excalidraw для финальной картинки.)''

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.6. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.7. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.8. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.9. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T15:33:36Z

Владимир:

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
<pre>
KEENETIC РОУТЕР

┌──────────────────────────────────────────────────────────────┐
│ │
│ ┌────────────────┐ │
│ │ keen-pbr │ --- адрес домена в списке? --- │
│ │ (по доменам) │ │ │ │
│ └────────────────┘ │ ДА │ НЕТ │
│ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ │
│ │ singtun │ │ nfqws2 │ │
│ │ (sing-box) │ │ DPI fix │ │
│ └────────────┘ └────────────┘ │
│ │ │ │
└────────────────────────────┼────────────────┼────────────────┘
│ │
┌────▼────┐ ┌────▼────┐
│ VPN- │ │ Прямой │
│ сервер │ │ WAN │
└─────────┘ └─────────┘
</pre>
''(Здесь схему можно перерисовать в Mermaid или Excalidraw и заменить блок.)''

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== 1.1. Подготовка USB-накопителя ==
=== Подключение и форматирование ===
# Воткните флешку в USB-порт роутера.
# Откройте веб-интерфейс Keenetic: '''Приложения''' → '''USB-диски и принтеры'''.
# В списке появится диск. Откройте его параметры.
# Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' и выберите '''EXT4'''.

''(Скриншот: страница "USB-диски" в веб-интерфейсе Keenetic с подключённым диском и кнопкой "Форматировать".)''

=== Узнайте UUID диска через CLI ===
У диска есть уникальный '''UUID''' (длинная строка вида <code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>), который понадобится для установки Entware. Веб-интерфейс Keenetic показывает UUID на странице диска, '''но не позволяет его выделить и скопировать''' — поэтому удобнее получить его через встроенную командную строку.

# Откройте в браузере адрес <code>http://192.168.1.1/a</code> — это встроенный веб-CLI Keenetic. Должно появиться приглашение <code>(config)></code>.
# Выполните команду:
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
# В ответе найдите блок с вашей флешкой и строку <code>uuid</code> внутри <code>partition</code>. Пример вывода:

<syntaxhighlight lang="json">
{
"media": {
"Media0": {
"bus": "usb",
"manufacturer": "SanDisk",
"product": "Ultra",
"state": "ACTIVE",
"partition": [
{
"uuid": "d5f39712-7ae1-dc01-00f3-97127ae1dc01",
"fstype": "ext4",
"state": "MOUNTED",
...
}
]
}
}
}
</syntaxhighlight>

Скопируйте значение поля <code>uuid</code> внутри <code>partition</code> — оно понадобится в следующем шаге.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — пока вы в CLI, можно сразу включить DNS Override.''' Эта опция понадобится позже для keen-pbr — она заставляет KeeneticOS отдавать DNS-трафик в Entware-овский dnsmasq. Чтобы не возвращаться в CLI отдельно, выполните прямо сейчас:
<syntaxhighlight lang="bash">
opkg dns-override
system configuration save
</syntaxhighlight>
Опция применится после ближайшей перезагрузки роутера (она будет в конце Этапа 1).
</div>

== 1.2. Компоненты KeeneticOS ==
=== Какая у вас прошивка? ===
KeeneticOS существует в двух вариантах, и от этого зависит, нужно ли вам что-то включать на этом этапе:

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (роутер, который продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', все нужные пакеты уже включены в образ прошивки этого порта — переходите к разделу 1.3
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — как понять, какая у вас прошивка:''' На странице '''Системный монитор''' (главная страница веб-интерфейса) видна модель устройства. Если рядом с моделью стоит знакомое маркетинговое имя Keenetic (например, "Keenetic Hero") и модель начинается с "KN-" — это оригинальный Keenetic. Если вы видите название роутера другого производителя (например, "Xiaomi R3G") и при этом отображается KeeneticOS — у вас порт сообщества.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Признак порта сообщества:''' На странице с компонентами окно "Компоненты операционной системы" может показывать сообщение "Не удалось получить список компонентов от сервера" — это нормально для портированных сборок, у которых нет своего сервера обновлений. В этом случае шаг с компонентами '''не нужен''' — переходите к разделу 1.3.
</div>

=== Только для оригинального Keenetic ===
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в более старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:
{| class="wikitable"
!Компонент (точное название в UI)
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|Базовая инфраструктура Entware — без этого нельзя ставить пакеты на USB
|-
|'''Файловая система Ext'''
|Чтобы роутер мог монтировать ext4-диск
|-
|'''Сервер SSH'''
|Доступ к командной строке роутера
|}

Кроме того, '''желательно''' проверить наличие следующих компонентов (точные названия в интерфейсе могут отличаться от версии к версии — ищите по словам):

{| class="wikitable"
!Что искать в списке
!Зачем
|-
|"Netfilter" / "Модули ядра Netfilter"
|Базовые модули iptables для работы фаервола Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Дополнительные модули (xt_set, xt_multiport, conntrack-extra) — '''критично''' для работы keen-pbr
|}

После выбора нажмите '''Установить обновление''' и подождите 2–5 минут. Роутер перезагрузится самостоятельно.

''(Скриншот: страница "Обновления и компоненты" с открытым окном "Показать компоненты" и отмеченными нужными пунктами.)''

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В KeeneticOS 5 и новее компонент '''Протокол IPv6''' включён по умолчанию и не может быть отключён — это нормально.
</div>

== 1.3. Установка Entware через командную строку ==
=== Открытие командной строки роутера ===
Если вы вышли из CLI после шага 1.1 — откройте снова: <code>http://192.168.1.1/a</code>. Должно появиться приглашение <code>(config)></code>.

=== Запуск установки Entware ===
Команда состоит из '''двух частей, которые вы должны подставить сами''':

# '''UUID вашего USB-диска''' — тот, который вы получили командой <code>show media</code> в разделе '''1.1''' (длинная строка вида <code>d5f39712-7ae1-...</code>).
# '''URL установщика''' — выбирается по архитектуре вашего роутера (см. таблицу ниже).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — не копируйте команду как есть!''' В шаблоне ниже фигурные скобки <code><...></code> — это места, куда нужно подставить '''ваши''' значения. Если оставить шаблон с угловыми скобками или скопировать чужой UUID — установка не сработает.
</div>

==== Шаблон команды ====
<syntaxhighlight lang="bash">
opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ>
</syntaxhighlight>

==== Выбор URL установщика ====
{| class="wikitable"
!Архитектура роутера
!URL установщика (целиком)
|-
|'''MIPS little-endian (mipsel)''' — большинство моделей Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — как узнать архитектуру:''' Откройте '''Системный монитор''' в веб-интерфейсе → видно модель устройства и процессор. Для большинства бытовых моделей это MIPS — берите верхнюю строку таблицы. Если сомневаетесь — пишите команду с <code>mipsel</code>: если архитектура не подходит, установка скажет об этом ошибкой, и вы не сломаете роутер.
</div>

==== Пример с подставленными значениями ====
Допустим, ваш UUID — <code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>, архитектура — mipsel. Тогда команда полностью выглядит так:
<syntaxhighlight lang="bash">
opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Это '''пример''' — UUID <code>d5f39712-...</code> здесь приведён только для иллюстрации. У '''вашего''' диска UUID будет '''другой'''. Подставьте именно свой со страницы "Диски и принтеры".
</div>

==== Проверочный чек-лист перед нажатием Enter ====
* Двоеточие и слэш <code>:/</code> сразу после UUID — '''обязательны'''.
* URL — '''одной строкой''', без пробелов и переносов.
* После UUID и перед URL — '''ровно один пробел'''.
* Угловых скобок <code><</code> и <code>></code> в финальной команде '''не должно остаться'''.

=== Сохранение конфигурации и перезагрузка ===
После того как установка прошла без ошибок, сохраните конфигурацию и перезагрузите роутер:
<syntaxhighlight lang="bash">
system configuration save
system reboot
</syntaxhighlight>

Перезагрузка нужна, чтобы применился <code>opkg dns-override</code>, который вы включили на шаге 1.1. Ожидайте 1–2 минуты, пока роутер поднимется обратно.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — если установщик "молчит":''' В некоторых сборках команда <code>opkg disk ... URL</code> не работает, если OPKG-диск уже был назначен раньше. Если в логе вы не видите строк про загрузку <code>mipsel-installer.tar.gz</code> — сбросьте диск и повторите:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
</syntaxhighlight>
</div>

=== Проверка установки ===
Откройте журнал: '''Диагностика''' → '''Системный журнал'''. Должны появиться строки примерно такого содержания:
<pre>
Opkg::Manager: downloading installer...
Opkg::Manager: extracting to /opt...
Opkg::Manager: ...
Entware installed.
</pre>

После завершения установки на роутере поднимется встроенный SSH-сервер Entware на порту '''222'''.

== 1.4. Первое подключение по SSH ==
Подключитесь к роутеру с компьютера. На Windows — через PuTTY или через стандартный <code>ssh.exe</code>.

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|<code>192.168.1.1</code> (LAN-адрес роутера)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code>
|}

Из PowerShell это одна строка:
<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

При первом подключении ssh попросит подтвердить fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа смените пароль:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>

Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Дефолтный пароль <code>keenetic</code> известен всем — если SSH будет проброшен наружу, роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите заходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце этого документа. Для базовой установки sing-box / keen-pbr / nfqws2 это '''не нужно''' — переходите к Этапу 2.
</div>

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code>
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про место:''' <code>sing-box-go</code> занимает ~62 МБ распакованных, плюс ~7 МБ сам helper, плюс Entware-окружение. На встроенной флэш-памяти роутера не помещается — Entware '''должен''' быть на USB (см. Этап 1).
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.

На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''.

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.

Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>. UI покажет жёлтое предупреждение под распознанными параметрами. Решение — попросить владельца сервера переключить транспорт на <code>ws</code>, <code>grpc</code> или <code>tcp</code>.
</div>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

''(Скриншот: страница "Outbounds (выходы)" с тремя строками: wan, block, vpn.)''

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

''(Скриншот: страница "Правила маршрутизации" с активным правилом #2 bypass → vpn.)''

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
ls -la /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок.

== 3.5. Тестирование ==
На клиентском устройстве, подключённом к Keenetic:

# '''Очистите кеш DNS''' (важно — без этого старые ответы остаются):
#* Windows: <code>ipconfig /flushdns</code> в PowerShell.
#* Android / iOS: переподключиться к Wi-Fi (off → on).
#* macOS: <code>sudo dscacheutil -flushcache</code>.
# Перезапустите браузер (у него свой DNS-кеш).
# Откройте сайт из списка bypass.
# Параллельно откройте <code>https://api.ipify.org</code> в браузере. Адрес должен быть тот же, который вы видели в шаге «IP через TUN» на вкладке Главная UI singbox-helper (т.е. IP вашего VPN-провайдера, а не домашний WAN-IP).

''(Скриншот: страница api.ipify.org с подменённым IP.)''

----

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web
</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Замечание про «failed» в конце установки:''' В выводе установщика вы можете увидеть строку:
<pre>
Starting /opt/sbin/lighttpd... failed.
NFQWS2 Web Interface installed: http://192.168.10.1:90
</pre>
Это '''не ошибка'''. lighttpd пытается стартануть до того, как все его модули (php8-mod-curl, php8-mod-session, mod-rewrite, mod-redirect) полностью зарегистрировались. Через несколько секунд стартовый скрипт <code>S80lighttpd</code> успешно поднимает сервис. Достаточно проверить:
<syntaxhighlight lang="bash">
pgrep -af lighttpd
netstat -tlnup | grep :90
</syntaxhighlight>
Оба должны показать запущенный процесс на порту 90. Если веб-интерфейс открывается на <code>http://LAN-АДРЕС-РОУТЕРА:90</code> — всё в порядке.
</div>

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>http://192.168.10.1:90</code>.

Для доступа из другой подсети — открыть порт <code>90</code> в фаерволе Keenetic (по аналогии с keen-pbr WebUI).

----

= Финальная архитектура =
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

<pre>
K E E N E T I C Р О У Т Е Р
┌───────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ │
LAN│ │ DNS-запрос │ │
───┼──►│ от клиента │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ upstream ┌────────────────┐ │
│ │ keen-pbr │ через │ Quad9 9.9.9.9 │ │
│ │ dnsmasq │ ─────────► │ │ │
│ │ на :53 │ │ │ │
│ └──────┬───────┘ └────────────────┘ │
│ │ IP → ipset │
│ │ │
│ ┌──────▼──────────────────────────────────────────────┐ │
LAN│ │ iptables / маршрутизация │ │
───┼──►│ ├ если dst-IP в ipset bypass: │ │
TCP│ │ │ fwmark → ip rule → table 151 → singtun │ │
│ │ │ │ │
│ │ └ иначе: │ │
│ │ обычный WAN-маршрут │ │
│ │ └ nfqws2 ловит первые пакеты │ │
│ │ и модифицирует для обхода DPI │ │
│ └────┬──────────────────────────────────────────┬─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌────────────────┐ │
│ │ singtun │ │ WAN-интерфейс │ │
│ │ (TUN) │ │ (ваш провайдер)│ │
│ └────┬────┘ └────────┬───────┘ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────┐ │ │
│ │ sing-box │ │ │
│ │ outbound: │ │ │
│ │ hysteria2 │ │ │
│ └──────┬──────┘ │ │
│ │ │ │
└──────────┼────────────────────────────────────────┼───────────────────────┘
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ VPN-узел │ │ Любой │
│ провайдера│ │ интернет │
└───────────┘ └───────────┘
</pre>

''(Здесь можно перерисовать в Mermaid/Excalidraw для финальной картинки.)''

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Скрипт пересоздания /var/empty при загрузке ==
Каталог <code>/var</code> на роутере — это tmpfs (RAM-диск), он очищается при каждой загрузке. Создадим стартовый скрипт, который воссоздаёт <code>/var/empty</code>:
<syntaxhighlight lang="bash">
cat > /opt/etc/init.d/S39sshd-prep << 'EOF'
#!/bin/sh
mkdir -p /var/empty
chmod 755 /var/empty
chown root:root /var/empty
EOF
chmod +x /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

== А.6. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.7. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.8. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.9. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.10. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T15:29:28Z

Владимир:

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box''' + '''singbox-helper'''
|sing-box — универсальный туннельный движок, поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается выборочный трафик. singbox-helper — обёртка над ним: ставит как зависимость, даёт веб-UI на <code>:8765</code>, по вставленной ссылке (<code>vless://</code>, <code>hysteria2://</code>, ...) сама генерирует <code>config.json</code>.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
<pre>
KEENETIC РОУТЕР

┌──────────────────────────────────────────────────────────────┐
│ │
│ ┌────────────────┐ │
│ │ keen-pbr │ --- адрес домена в списке? --- │
│ │ (по доменам) │ │ │ │
│ └────────────────┘ │ ДА │ НЕТ │
│ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ │
│ │ singtun │ │ nfqws2 │ │
│ │ (sing-box) │ │ DPI fix │ │
│ └────────────┘ └────────────┘ │
│ │ │ │
└────────────────────────────┼────────────────┼────────────────┘
│ │
┌────▼────┐ ┌────▼────┐
│ VPN- │ │ Прямой │
│ сервер │ │ WAN │
└─────────┘ └─────────┘
</pre>
''(Здесь схему можно перерисовать в Mermaid или Excalidraw и заменить блок.)''

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== 1.1. Подготовка USB-накопителя ==
=== Подключение и форматирование ===
# Воткните флешку в USB-порт роутера.
# Откройте веб-интерфейс Keenetic: '''Приложения''' → '''USB-диски и принтеры'''.
# В списке появится диск. Откройте его параметры.
# Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' и выберите '''EXT4'''.

''(Скриншот: страница "USB-диски" в веб-интерфейсе Keenetic с подключённым диском и кнопкой "Форматировать".)''

=== Узнайте UUID диска через CLI ===
У диска есть уникальный '''UUID''' (длинная строка вида <code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>), который понадобится для установки Entware. Веб-интерфейс Keenetic показывает UUID на странице диска, '''но не позволяет его выделить и скопировать''' — поэтому удобнее получить его через встроенную командную строку.

# Откройте в браузере адрес <code>http://192.168.1.1/a</code> — это встроенный веб-CLI Keenetic. Должно появиться приглашение <code>(config)></code>.
# Выполните команду:
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
# В ответе найдите блок с вашей флешкой и строку <code>uuid</code> внутри <code>partition</code>. Пример вывода:

<syntaxhighlight lang="json">
{
"media": {
"Media0": {
"bus": "usb",
"manufacturer": "SanDisk",
"product": "Ultra",
"state": "ACTIVE",
"partition": [
{
"uuid": "d5f39712-7ae1-dc01-00f3-97127ae1dc01",
"fstype": "ext4",
"state": "MOUNTED",
...
}
]
}
}
}
</syntaxhighlight>

Скопируйте значение поля <code>uuid</code> внутри <code>partition</code> — оно понадобится в следующем шаге.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — пока вы в CLI, можно сразу включить DNS Override.''' Эта опция понадобится позже для keen-pbr — она заставляет KeeneticOS отдавать DNS-трафик в Entware-овский dnsmasq. Чтобы не возвращаться в CLI отдельно, выполните прямо сейчас:
<syntaxhighlight lang="bash">
opkg dns-override
system configuration save
</syntaxhighlight>
Опция применится после ближайшей перезагрузки роутера (она будет в конце Этапа 1).
</div>

== 1.2. Компоненты KeeneticOS ==
=== Какая у вас прошивка? ===
KeeneticOS существует в двух вариантах, и от этого зависит, нужно ли вам что-то включать на этом этапе:

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (роутер, который продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', все нужные пакеты уже включены в образ прошивки этого порта — переходите к разделу 1.3
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — как понять, какая у вас прошивка:''' На странице '''Системный монитор''' (главная страница веб-интерфейса) видна модель устройства. Если рядом с моделью стоит знакомое маркетинговое имя Keenetic (например, "Keenetic Hero") и модель начинается с "KN-" — это оригинальный Keenetic. Если вы видите название роутера другого производителя (например, "Xiaomi R3G") и при этом отображается KeeneticOS — у вас порт сообщества.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Признак порта сообщества:''' На странице с компонентами окно "Компоненты операционной системы" может показывать сообщение "Не удалось получить список компонентов от сервера" — это нормально для портированных сборок, у которых нет своего сервера обновлений. В этом случае шаг с компонентами '''не нужен''' — переходите к разделу 1.3.
</div>

=== Только для оригинального Keenetic ===
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в более старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:
{| class="wikitable"
!Компонент (точное название в UI)
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|Базовая инфраструктура Entware — без этого нельзя ставить пакеты на USB
|-
|'''Файловая система Ext'''
|Чтобы роутер мог монтировать ext4-диск
|-
|'''Сервер SSH'''
|Доступ к командной строке роутера
|}

Кроме того, '''желательно''' проверить наличие следующих компонентов (точные названия в интерфейсе могут отличаться от версии к версии — ищите по словам):

{| class="wikitable"
!Что искать в списке
!Зачем
|-
|"Netfilter" / "Модули ядра Netfilter"
|Базовые модули iptables для работы фаервола Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Дополнительные модули (xt_set, xt_multiport, conntrack-extra) — '''критично''' для работы keen-pbr
|}

После выбора нажмите '''Установить обновление''' и подождите 2–5 минут. Роутер перезагрузится самостоятельно.

''(Скриншот: страница "Обновления и компоненты" с открытым окном "Показать компоненты" и отмеченными нужными пунктами.)''

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В KeeneticOS 5 и новее компонент '''Протокол IPv6''' включён по умолчанию и не может быть отключён — это нормально.
</div>

== 1.3. Установка Entware через командную строку ==
=== Открытие командной строки роутера ===
Если вы вышли из CLI после шага 1.1 — откройте снова: <code>http://192.168.1.1/a</code>. Должно появиться приглашение <code>(config)></code>.

=== Запуск установки Entware ===
Команда состоит из '''двух частей, которые вы должны подставить сами''':

# '''UUID вашего USB-диска''' — тот, который вы получили командой <code>show media</code> в разделе '''1.1''' (длинная строка вида <code>d5f39712-7ae1-...</code>).
# '''URL установщика''' — выбирается по архитектуре вашего роутера (см. таблицу ниже).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — не копируйте команду как есть!''' В шаблоне ниже фигурные скобки <code><...></code> — это места, куда нужно подставить '''ваши''' значения. Если оставить шаблон с угловыми скобками или скопировать чужой UUID — установка не сработает.
</div>

==== Шаблон команды ====
<syntaxhighlight lang="bash">
opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ>
</syntaxhighlight>

==== Выбор URL установщика ====
{| class="wikitable"
!Архитектура роутера
!URL установщика (целиком)
|-
|'''MIPS little-endian (mipsel)''' — большинство моделей Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — как узнать архитектуру:''' Откройте '''Системный монитор''' в веб-интерфейсе → видно модель устройства и процессор. Для большинства бытовых моделей это MIPS — берите верхнюю строку таблицы. Если сомневаетесь — пишите команду с <code>mipsel</code>: если архитектура не подходит, установка скажет об этом ошибкой, и вы не сломаете роутер.
</div>

==== Пример с подставленными значениями ====
Допустим, ваш UUID — <code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>, архитектура — mipsel. Тогда команда полностью выглядит так:
<syntaxhighlight lang="bash">
opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Это '''пример''' — UUID <code>d5f39712-...</code> здесь приведён только для иллюстрации. У '''вашего''' диска UUID будет '''другой'''. Подставьте именно свой со страницы "Диски и принтеры".
</div>

==== Проверочный чек-лист перед нажатием Enter ====
* Двоеточие и слэш <code>:/</code> сразу после UUID — '''обязательны'''.
* URL — '''одной строкой''', без пробелов и переносов.
* После UUID и перед URL — '''ровно один пробел'''.
* Угловых скобок <code><</code> и <code>></code> в финальной команде '''не должно остаться'''.

=== Сохранение конфигурации и перезагрузка ===
После того как установка прошла без ошибок, сохраните конфигурацию и перезагрузите роутер:
<syntaxhighlight lang="bash">
system configuration save
system reboot
</syntaxhighlight>

Перезагрузка нужна, чтобы применился <code>opkg dns-override</code>, который вы включили на шаге 1.1. Ожидайте 1–2 минуты, пока роутер поднимется обратно.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — если установщик "молчит":''' В некоторых сборках команда <code>opkg disk ... URL</code> не работает, если OPKG-диск уже был назначен раньше. Если в логе вы не видите строк про загрузку <code>mipsel-installer.tar.gz</code> — сбросьте диск и повторите:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
</syntaxhighlight>
</div>

=== Проверка установки ===
Откройте журнал: '''Диагностика''' → '''Системный журнал'''. Должны появиться строки примерно такого содержания:
<pre>
Opkg::Manager: downloading installer...
Opkg::Manager: extracting to /opt...
Opkg::Manager: ...
Entware installed.
</pre>

После завершения установки на роутере поднимется встроенный SSH-сервер Entware на порту '''222'''.

== 1.4. Первое подключение по SSH ==
Подключитесь к роутеру с компьютера. На Windows — через PuTTY или через стандартный <code>ssh.exe</code>.

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|<code>192.168.1.1</code> (LAN-адрес роутера)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code>
|}

Из PowerShell это одна строка:
<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

При первом подключении ssh попросит подтвердить fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа смените пароль:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>

Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Дефолтный пароль <code>keenetic</code> известен всем — если SSH будет проброшен наружу, роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите заходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце этого документа. Для базовой установки sing-box / keen-pbr / nfqws2 это '''не нужно''' — переходите к Этапу 2.
</div>

----

= Этап 2. Установка sing-box (через singbox-helper) =
sing-box — движок туннеля. Раньше его ставили вручную (<code>opkg install sing-box-go</code>) и сами писали <code>config.json</code> на 60+ строк JSON. Теперь весь этот шаг делает утилита <b>singbox-helper</b> — она:

* подтягивает <code>sing-box-go</code> как зависимость opkg (62 МБ, ставится автоматически);
* даёт веб-интерфейс на <code>http://<LAN-IP-роутера>:8765</code> с 4-я вкладками (Главная / Настройки / Логи / Бэкапы);
* по вставленной ссылке узла (<code>vless://</code>, <code>hysteria2://</code>, <code>socks5://</code>) сама собирает корректный <code>config.json</code>, бэкапит старый, рестартит sing-box и прогоняет диагностику.

== 2.1. Подключение фида singbox-helper и установка ==
Подключитесь по SSH и добавьте репозиторий пакетов:
<syntaxhighlight lang="bash">
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper
</syntaxhighlight>

opkg увидит зависимость <code>Depends: sing-box-go</code> и поставит обе утилиты сразу. На выходе:
* <code>/opt/bin/singbox-helper</code> — наш бинарь (~7 МБ);
* <code>/opt/sbin/sing-box</code> — sing-box-go от Entware (~62 МБ распакованных);
* <code>/opt/etc/init.d/S98singbox-helper</code> и <code>/opt/etc/init.d/S99sing-box</code> — init-скрипты, прописаны в автозагрузку;
* демон singbox-helper уже стартует и слушает <code>0.0.0.0:8765</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про место:''' <code>sing-box-go</code> занимает ~62 МБ распакованных, плюс ~7 МБ сам helper, плюс Entware-окружение. На встроенной флэш-памяти роутера не помещается — Entware '''должен''' быть на USB (см. Этап 1).
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — другая архитектура:''' Команда выше — для <code>mipsel-3.4</code> (Keenetic / Xiaomi на MT7621/MT7620 — основная масса устройств). Для новых Keenetic Hopper/Hero/Giga на ARM64 — поменяйте URL на <code>...github.io/sing-box-helper/aarch64-3.10</code>.
</div>

== 2.2. Открытие веб-интерфейса ==
В браузере: <code>http://<LAN-IP-вашего-роутера>:8765</code> (например, <code>http://192.168.10.1:8765</code>; LAN-IP видно в веб-интерфейсе Keenetic в карточке «Домашняя сеть»).

Откроется страница с четырьмя вкладками: '''Главная''', '''Настройки''', '''Логи''', '''Бэкапы'''.

На «Главной» сверху видно состояние:
* '''sing-box''' — running / не запущен (после свежей установки — running с заглушечным конфигом);
* '''TUN-интерфейс''' — UP / down;
* '''Текущий узел''' — пусто (мы ещё не применили ссылку).

== 2.3. Применение узла ==
В блоке «Применить узел» вставьте ссылку из вашей VPN-панели (3x-ui, Marzban, Hiddify и т.п.). Поддерживаются:

{| class="wikitable"
!Схема
!Что это
|-
|<code>hysteria2://пароль@сервер:порт</code>
|Hysteria2 (синоним <code>hy2://</code>)
|-
|<code>vless://uuid@сервер:порт?type=tcp&security=tls&...</code>
|VLESS vanilla (TCP / WS / gRPC / h2 / httpupgrade)
|-
|<code>vless://...?security=reality&pbk=...&flow=xtls-rprx-vision</code>
|VLESS + REALITY (+ Vision)
|-
|<code>socks5://127.0.0.1:1080</code>
|Локальный SOCKS-upstream — если на роутере уже работает naive-proxy / mieru-client, sing-box можно использовать как обёртку с TUN над ним
|}

Жмёте '''[ Применить ]'''. Утилита:

# Парсит URI и валидирует обязательные параметры (порт, ключи REALITY и т.п.). Если ссылка кривая — отказ с понятной ошибкой.
# Делает TCP-probe до <code>server:port</code> с таймаутом 3 секунды. Если сервер недоступен — отказ '''до''' рестарта sing-box, чтобы не дёргать рабочий туннель зря.
# Бэкапит текущий <code>/opt/etc/sing-box/config.json</code> в <code>config.json.bak-YYYYMMDD-HHMMSS</code>.
# Генерирует новый <code>config.json</code>: TUN-inbound (<code>auto_route:false</code>, <code>strict_route:false</code> — обязательно для совместимости с keen-pbr), mixed-inbound с автодетектом LAN-IP, outbound из URI с тегом <code>proxy</code>, <code>route.final=proxy</code>, sniff + hijack-dns rules.
# Рестартит sing-box через <code>/opt/etc/init.d/S99sing-box restart</code>.
# Сохраняет URI + label + время применения в <code>/opt/etc/singbox-helper/state.json</code> (метаданные, которых сам sing-box не знает).
# Запускает блок диагностики «Проверка работы».

Через несколько секунд под формой появится блок '''«Проверка работы»''' с пятью шагами:

# '''Доступность узла''' — TCP-connect <code>server:port</code> со временем отклика.
# '''sing-box процесс''' — PID и версия.
# '''Интерфейс singtun''' — UP / down.
# '''Прямой IP''' — что отвечает <code>https://api.ipify.org</code> через WAN.
# '''IP через TUN''' — то же, но <code>curl --interface singtun</code>. '''Должен отличаться''' от прямого.

Если все 5 шагов зелёные — туннель работает.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Особый случай — xhttp:''' Узлы с параметром <code>type=xhttp</code> на REALITY-серверах из 3x-ui '''не подключатся'''. sing-box 1.13 не имеет нативного xhttp-транспорта; helper маппит его в <code>httpupgrade</code> как best-effort, но реальные xhttp-серверы отвечают <code>400 Bad Request</code>. UI покажет жёлтое предупреждение под распознанными параметрами. Решение — попросить владельца сервера переключить транспорт на <code>ws</code>, <code>grpc</code> или <code>tcp</code>.
</div>

== 2.4. Что лежит на диске после установки ==
{| class="wikitable"
!Путь
!Назначение
|-
|<code>/opt/bin/singbox-helper</code>
|Бинарь утилиты (CLI + HTTP-сервер в одном).
|-
|<code>/opt/etc/init.d/S98singbox-helper</code>
|Init-скрипт демона. <code>{start|stop|restart|check}</code>.
|-
|<code>/opt/etc/init.d/S99sing-box</code>
|Init-скрипт самого sing-box (поставлен пакетом <code>sing-box-go</code>).
|-
|<code>/opt/etc/sing-box/config.json</code>
|Сгенерированный конфиг для sing-box. '''Источник истины''' — все запросы UI <code>/api/status</code> читают именно его, а не in-memory кэш.
|-
|<code>/opt/etc/sing-box/config.json.bak-*</code>
|Бэкапы. Создаются перед каждым «Применить»; держатся последние 10 (настраивается).
|-
|<code>/opt/etc/singbox-helper/config.yaml</code>
|YAML-настройки утилиты (создаётся при первом сохранении на вкладке «Настройки»). Отсутствие файла = встроенные defaults.
|-
|<code>/opt/etc/singbox-helper/state.json</code>
|Метаданные текущего узла: URI, метка (<code>#fragment</code>), <code>applied_at</code>. Используются UI чтобы показать «какая именно ссылка сейчас применена».
|}

Управление сервисами:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper {start|stop|restart|check}
/opt/etc/init.d/S99sing-box {start|stop|restart|check}
</syntaxhighlight>

Обновление в будущем — обычным opkg:
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper
</syntaxhighlight>
state.json и config.yaml '''переживают''' обновление.

== 2.5. (Опционально) Ручная проверка туннеля из консоли ==
UI уже прогнал диагностику в §2.3, но если хочется убедиться независимо — те же запросы из SSH:
<syntaxhighlight lang="bash">
# Прямой IP (через ваш WAN)
curl -sS https://api.ipify.org
echo

# IP через TUN — должен отличаться
curl -sS --interface singtun --max-time 8 https://api.ipify.org
echo
</syntaxhighlight>

Если IP совпадают — туннель не работает. Зайдите на вкладку '''Логи''' в UI, выберите источник <code>sing-box</code> — там будет конкретная причина.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

''(Скриншот: страница "Outbounds (выходы)" с тремя строками: wan, block, vpn.)''

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

''(Скриншот: страница "Правила маршрутизации" с активным правилом #2 bypass → vpn.)''

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
ls -la /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|Имя TUN-интерфейса sing-box. singbox-helper в сгенерированном <code>config.json</code> по умолчанию ставит <code>singtun</code> — это совпадает с тем, что ожидают keen-pbr и этот NAT-скрипт. Менять не нужно. Если очень хочется — переименуйте в '''Настройках''' UI singbox-helper (поле «Имя интерфейса») и здесь синхронно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок.

== 3.5. Тестирование ==
На клиентском устройстве, подключённом к Keenetic:

# '''Очистите кеш DNS''' (важно — без этого старые ответы остаются):
#* Windows: <code>ipconfig /flushdns</code> в PowerShell.
#* Android / iOS: переподключиться к Wi-Fi (off → on).
#* macOS: <code>sudo dscacheutil -flushcache</code>.
# Перезапустите браузер (у него свой DNS-кеш).
# Откройте сайт из списка bypass.
# Параллельно откройте <code>https://api.ipify.org</code> в браузере. Адрес должен быть тот же, который вы видели в шаге «IP через TUN» на вкладке Главная UI singbox-helper (т.е. IP вашего VPN-провайдера, а не домашний WAN-IP).

''(Скриншот: страница api.ipify.org с подменённым IP.)''

----

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web
</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Замечание про «failed» в конце установки:''' В выводе установщика вы можете увидеть строку:
<pre>
Starting /opt/sbin/lighttpd... failed.
NFQWS2 Web Interface installed: http://192.168.10.1:90
</pre>
Это '''не ошибка'''. lighttpd пытается стартануть до того, как все его модули (php8-mod-curl, php8-mod-session, mod-rewrite, mod-redirect) полностью зарегистрировались. Через несколько секунд стартовый скрипт <code>S80lighttpd</code> успешно поднимает сервис. Достаточно проверить:
<syntaxhighlight lang="bash">
pgrep -af lighttpd
netstat -tlnup | grep :90
</syntaxhighlight>
Оба должны показать запущенный процесс на порту 90. Если веб-интерфейс открывается на <code>http://LAN-АДРЕС-РОУТЕРА:90</code> — всё в порядке.
</div>

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>http://192.168.10.1:90</code>.

Для доступа из другой подсети — открыть порт <code>90</code> в фаерволе Keenetic (по аналогии с keen-pbr WebUI).

----

= Финальная архитектура =
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

<pre>
K E E N E T I C Р О У Т Е Р
┌───────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ │
LAN│ │ DNS-запрос │ │
───┼──►│ от клиента │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ upstream ┌────────────────┐ │
│ │ keen-pbr │ через │ Quad9 9.9.9.9 │ │
│ │ dnsmasq │ ─────────► │ │ │
│ │ на :53 │ │ │ │
│ └──────┬───────┘ └────────────────┘ │
│ │ IP → ipset │
│ │ │
│ ┌──────▼──────────────────────────────────────────────┐ │
LAN│ │ iptables / маршрутизация │ │
───┼──►│ ├ если dst-IP в ipset bypass: │ │
TCP│ │ │ fwmark → ip rule → table 151 → singtun │ │
│ │ │ │ │
│ │ └ иначе: │ │
│ │ обычный WAN-маршрут │ │
│ │ └ nfqws2 ловит первые пакеты │ │
│ │ и модифицирует для обхода DPI │ │
│ └────┬──────────────────────────────────────────┬─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌────────────────┐ │
│ │ singtun │ │ WAN-интерфейс │ │
│ │ (TUN) │ │ (ваш провайдер)│ │
│ └────┬────┘ └────────┬───────┘ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────┐ │ │
│ │ sing-box │ │ │
│ │ outbound: │ │ │
│ │ hysteria2 │ │ │
│ └──────┬──────┘ │ │
│ │ │ │
└──────────┼────────────────────────────────────────┼───────────────────────┘
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ VPN-узел │ │ Любой │
│ провайдера│ │ интернет │
└───────────┘ └───────────┘
</pre>

''(Здесь можно перерисовать в Mermaid/Excalidraw для финальной картинки.)''

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade singbox-helper sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

postinst-хуки соответствующих пакетов перезапускают свои сервисы сами; runtime-данные (<code>state.json</code>, <code>config.yaml</code>, бэкапы) переживают <code>opkg upgrade</code>. Если что-то осталось висеть со старой версией — перезапустите вручную (<code>/opt/etc/init.d/S98singbox-helper restart</code>, <code>S99sing-box restart</code>) или перезагрузите роутер.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S98singbox-helper check # рекомендую: дальше его UI покажет состояние sing-box
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Подсказка:''' На <code>http://<LAN-IP>:8765</code> на вкладке '''Главная''' сразу видно состояние sing-box (PID, версия) и TUN-интерфейса. На вкладке '''Логи''' можно почитать <code>sing-box</code>-лог (фильтр поверх <code>ndmc show log</code>) и собственный лог helper'а, не залезая в SSH.
</div>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box (через singbox-helper, подтянет sing-box-go как зависимость) ===
echo 'src/gz singbox-helper https://wolfram0108.github.io/sing-box-helper/mipsel-3.4' >> /opt/etc/opkg.conf
opkg update
opkg install singbox-helper curl nano wget-ssl
# UI: http://<LAN-IP>:8765 → вставить URI узла → Применить

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Скрипт пересоздания /var/empty при загрузке ==
Каталог <code>/var</code> на роутере — это tmpfs (RAM-диск), он очищается при каждой загрузке. Создадим стартовый скрипт, который воссоздаёт <code>/var/empty</code>:
<syntaxhighlight lang="bash">
cat > /opt/etc/init.d/S39sshd-prep << 'EOF'
#!/bin/sh
mkdir -p /var/empty
chmod 755 /var/empty
chown root:root /var/empty
EOF
chmod +x /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

== А.6. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.7. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.8. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.9. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.10. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T10:14:47Z

Владимир:

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.

----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:

{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box'''
|Универсальный туннельный движок. Поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный сетевой интерфейс <code>singtun</code>, в который можно завернуть выборочный трафик.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
<pre>
KEENETIC РОУТЕР

┌──────────────────────────────────────────────────────────────┐
│ │
│ ┌────────────────┐ │
│ │ keen-pbr │ --- адрес домена в списке? --- │
│ │ (по доменам) │ │ │ │
│ └────────────────┘ │ ДА │ НЕТ │
│ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ │
│ │ singtun │ │ nfqws2 │ │
│ │ (sing-box) │ │ DPI fix │ │
│ └────────────┘ └────────────┘ │
│ │ │ │
└────────────────────────────┼────────────────┼────────────────┘
│ │
┌────▼────┐ ┌────▼────┐
│ VPN- │ │ Прямой │
│ сервер │ │ WAN │
└─────────┘ └─────────┘
</pre>
''(Здесь схему можно перерисовать в Mermaid или Excalidraw и заменить блок.)''

----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>

----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== 1.1. Подготовка USB-накопителя ==
=== Подключение и форматирование ===
# Воткните флешку в USB-порт роутера.
# Откройте веб-интерфейс Keenetic: '''Приложения''' → '''USB-диски и принтеры'''.
# В списке появится диск. Откройте его параметры.
# Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' и выберите '''EXT4'''.

''(Скриншот: страница "USB-диски" в веб-интерфейсе Keenetic с подключённым диском и кнопкой "Форматировать".)''

=== Узнайте UUID диска через CLI ===
У диска есть уникальный '''UUID''' (длинная строка вида <code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>), который понадобится для установки Entware. Веб-интерфейс Keenetic показывает UUID на странице диска, '''но не позволяет его выделить и скопировать''' — поэтому удобнее получить его через встроенную командную строку.

# Откройте в браузере адрес <code>http://192.168.1.1/a</code> — это встроенный веб-CLI Keenetic. Должно появиться приглашение <code>(config)></code>.
# Выполните команду:
#: <syntaxhighlight lang="bash">show media</syntaxhighlight>
# В ответе найдите блок с вашей флешкой и строку <code>uuid</code> внутри <code>partition</code>. Пример вывода:

<syntaxhighlight lang="json">
{
"media": {
"Media0": {
"bus": "usb",
"manufacturer": "SanDisk",
"product": "Ultra",
"state": "ACTIVE",
"partition": [
{
"uuid": "d5f39712-7ae1-dc01-00f3-97127ae1dc01",
"fstype": "ext4",
"state": "MOUNTED",
...
}
]
}
}
}
</syntaxhighlight>

Скопируйте значение поля <code>uuid</code> внутри <code>partition</code> — оно понадобится в следующем шаге.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — пока вы в CLI, можно сразу включить DNS Override.''' Эта опция понадобится позже для keen-pbr — она заставляет KeeneticOS отдавать DNS-трафик в Entware-овский dnsmasq. Чтобы не возвращаться в CLI отдельно, выполните прямо сейчас:
<syntaxhighlight lang="bash">
opkg dns-override
system configuration save
</syntaxhighlight>
Опция применится после ближайшей перезагрузки роутера (она будет в конце Этапа 1).
</div>

== 1.2. Компоненты KeeneticOS ==
=== Какая у вас прошивка? ===
KeeneticOS существует в двух вариантах, и от этого зависит, нужно ли вам что-то включать на этом этапе:

{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (роутер, который продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', все нужные пакеты уже включены в образ прошивки этого порта — переходите к разделу 1.3
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — как понять, какая у вас прошивка:''' На странице '''Системный монитор''' (главная страница веб-интерфейса) видна модель устройства. Если рядом с моделью стоит знакомое маркетинговое имя Keenetic (например, "Keenetic Hero") и модель начинается с "KN-" — это оригинальный Keenetic. Если вы видите название роутера другого производителя (например, "Xiaomi R3G") и при этом отображается KeeneticOS — у вас порт сообщества.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Признак порта сообщества:''' На странице с компонентами окно "Компоненты операционной системы" может показывать сообщение "Не удалось получить список компонентов от сервера" — это нормально для портированных сборок, у которых нет своего сервера обновлений. В этом случае шаг с компонентами '''не нужен''' — переходите к разделу 1.3.
</div>

=== Только для оригинального Keenetic ===
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в более старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:
{| class="wikitable"
!Компонент (точное название в UI)
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|Базовая инфраструктура Entware — без этого нельзя ставить пакеты на USB
|-
|'''Файловая система Ext'''
|Чтобы роутер мог монтировать ext4-диск
|-
|'''Сервер SSH'''
|Доступ к командной строке роутера
|}

Кроме того, '''желательно''' проверить наличие следующих компонентов (точные названия в интерфейсе могут отличаться от версии к версии — ищите по словам):

{| class="wikitable"
!Что искать в списке
!Зачем
|-
|"Netfilter" / "Модули ядра Netfilter"
|Базовые модули iptables для работы фаервола Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Дополнительные модули (xt_set, xt_multiport, conntrack-extra) — '''критично''' для работы keen-pbr
|}

После выбора нажмите '''Установить обновление''' и подождите 2–5 минут. Роутер перезагрузится самостоятельно.

''(Скриншот: страница "Обновления и компоненты" с открытым окном "Показать компоненты" и отмеченными нужными пунктами.)''

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В KeeneticOS 5 и новее компонент '''Протокол IPv6''' включён по умолчанию и не может быть отключён — это нормально.
</div>

== 1.3. Установка Entware через командную строку ==
=== Открытие командной строки роутера ===
Если вы вышли из CLI после шага 1.1 — откройте снова: <code>http://192.168.1.1/a</code>. Должно появиться приглашение <code>(config)></code>.

=== Запуск установки Entware ===
Команда состоит из '''двух частей, которые вы должны подставить сами''':

# '''UUID вашего USB-диска''' — тот, который вы получили командой <code>show media</code> в разделе '''1.1''' (длинная строка вида <code>d5f39712-7ae1-...</code>).
# '''URL установщика''' — выбирается по архитектуре вашего роутера (см. таблицу ниже).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — не копируйте команду как есть!''' В шаблоне ниже фигурные скобки <code><...></code> — это места, куда нужно подставить '''ваши''' значения. Если оставить шаблон с угловыми скобками или скопировать чужой UUID — установка не сработает.
</div>

==== Шаблон команды ====
<syntaxhighlight lang="bash">
opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ>
</syntaxhighlight>

==== Выбор URL установщика ====
{| class="wikitable"
!Архитектура роутера
!URL установщика (целиком)
|-
|'''MIPS little-endian (mipsel)''' — большинство моделей Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — как узнать архитектуру:''' Откройте '''Системный монитор''' в веб-интерфейсе → видно модель устройства и процессор. Для большинства бытовых моделей это MIPS — берите верхнюю строку таблицы. Если сомневаетесь — пишите команду с <code>mipsel</code>: если архитектура не подходит, установка скажет об этом ошибкой, и вы не сломаете роутер.
</div>

==== Пример с подставленными значениями ====
Допустим, ваш UUID — <code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>, архитектура — mipsel. Тогда команда полностью выглядит так:
<syntaxhighlight lang="bash">
opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Это '''пример''' — UUID <code>d5f39712-...</code> здесь приведён только для иллюстрации. У '''вашего''' диска UUID будет '''другой'''. Подставьте именно свой со страницы "Диски и принтеры".
</div>

==== Проверочный чек-лист перед нажатием Enter ====
* Двоеточие и слэш <code>:/</code> сразу после UUID — '''обязательны'''.
* URL — '''одной строкой''', без пробелов и переносов.
* После UUID и перед URL — '''ровно один пробел'''.
* Угловых скобок <code><</code> и <code>></code> в финальной команде '''не должно остаться'''.

=== Сохранение конфигурации и перезагрузка ===
После того как установка прошла без ошибок, сохраните конфигурацию и перезагрузите роутер:
<syntaxhighlight lang="bash">
system configuration save
system reboot
</syntaxhighlight>

Перезагрузка нужна, чтобы применился <code>opkg dns-override</code>, который вы включили на шаге 1.1. Ожидайте 1–2 минуты, пока роутер поднимется обратно.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — если установщик "молчит":''' В некоторых сборках команда <code>opkg disk ... URL</code> не работает, если OPKG-диск уже был назначен раньше. Если в логе вы не видите строк про загрузку <code>mipsel-installer.tar.gz</code> — сбросьте диск и повторите:
<syntaxhighlight lang="bash">
no opkg disk
opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
</syntaxhighlight>
</div>

=== Проверка установки ===
Откройте журнал: '''Диагностика''' → '''Системный журнал'''. Должны появиться строки примерно такого содержания:
<pre>
Opkg::Manager: downloading installer...
Opkg::Manager: extracting to /opt...
Opkg::Manager: ...
Entware installed.
</pre>

После завершения установки на роутере поднимется встроенный SSH-сервер Entware на порту '''222'''.

== 1.4. Первое подключение по SSH ==
Подключитесь к роутеру с компьютера. На Windows — через PuTTY или через стандартный <code>ssh.exe</code>.

{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|<code>192.168.1.1</code> (LAN-адрес роутера)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code>
|}

Из PowerShell это одна строка:
<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>

При первом подключении ssh попросит подтвердить fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа смените пароль:
<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>

Введите новый пароль дважды.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Дефолтный пароль <code>keenetic</code> известен всем — если SSH будет проброшен наружу, роутер взломают за минуты.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Хотите заходить по ключу, без ввода пароля?''' См. '''[[#Приложение А. OpenSSH с ключом (опционально)|Приложение А]]''' в конце этого документа. Для базовой установки sing-box / keen-pbr / nfqws2 это '''не нужно''' — переходите к Этапу 2.
</div>

----

= Этап 2. Установка sing-box =
sing-box — это движок туннеля. Он умеет «слушать» виртуальный TUN-интерфейс и пересылать всё, что туда прилетит, через выбранный протокол (VLESS, Hysteria2, и др.) на удалённый сервер.

== 2.1. Установка пакета ==
Подключитесь к роутеру по SSH и выполните:
<syntaxhighlight lang="bash">
opkg update
opkg install sing-box-go curl nano wget-ssl
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Пакет <code>sing-box-go</code> занимает '''около 62 МБ''' в распакованном виде. Установка во встроенную память роутера (без USB) почти всегда невозможна — поэтому Entware должен быть на USB.
</div>

=== Проверка ===
<syntaxhighlight lang="bash">
sing-box version
</syntaxhighlight>

'''Ожидаемый вывод:'''
<pre>
sing-box version 1.13.3

Environment: go1.26.1 linux/mipsle
Tags: ... with_quic ... with_clash_api ... with_gvisor ...
</pre>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Обратите внимание на флаги в выводе. <code>with_quic</code> означает поддержку Hysteria/Hysteria2/TUIC. <code>with_clash_api</code> — встроенный API для подключения веб-дашбордов. Если этих флагов нет — версия урезана, нужна другая сборка.
</div>

== 2.2. Создание конфига ==
sing-box читает конфиг из <code>/opt/etc/sing-box/config.json</code>. Заводской пример нам не подойдёт — там настроен серверный режим Shadowsocks. Создадим клиентский конфиг.

=== Пример: Hysteria2-узел в туннеле ===
Предположим, ваш провайдер выдал ссылку вида:
<pre>
hysteria2://ПАРОЛЬ@ВАШ_СЕРВЕР:ПОРТ
</pre>

Запишите рабочий конфиг:
<syntaxhighlight lang="bash">
cat > /opt/etc/sing-box/config.json << 'EOF'
{
"log": { "level": "info", "timestamp": true },
"dns": {
"servers": [
{ "type": "udp", "tag": "dns-direct", "server": "1.1.1.1" }
],
"strategy": "ipv4_only"
},
"inbounds": [
{
"type": "tun",
"tag": "tun-in",
"interface_name": "singtun",
"address": ["198.18.0.1/30"],
"mtu": 1500,
"auto_route": false,
"strict_route": false,
"stack": "gvisor",
"sniff": true
},
{
"type": "mixed",
"tag": "test-proxy",
"listen": "192.168.10.1",
"listen_port": 7891
}
],
"outbounds": [
{
"type": "hysteria2",
"tag": "hy2",
"server": "ВАШ_СЕРВЕР",
"server_port": ПОРТ,
"password": "ПАРОЛЬ",
"tls": {
"enabled": true,
"server_name": "ВАШ_СЕРВЕР"
}
},
{ "type": "direct", "tag": "direct" }
],
"route": {
"final": "hy2",
"rules": [
{ "action": "sniff" },
{ "protocol": "dns", "action": "hijack-dns" }
]
},
"experimental": {
"clash_api": {
"external_controller": "0.0.0.0:9090",
"external_ui": "/opt/share/dashboard"
}
}
}
EOF
</syntaxhighlight>

Замените <code>ВАШ_СЕРВЕР</code>, <code>ПОРТ</code>, <code>ПАРОЛЬ</code> на реальные значения.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — про подсеть TUN:''' Значение <code>"address": ["198.18.0.1/30"]</code> — это подсеть TUN-интерфейса (внутренний адрес виртуального сетевого устройства). Диапазон <code>198.18.0.0/15</code> зарезервирован RFC 2544 и не используется в реальном интернете — он не конфликтует ни с вашей LAN, ни с публичными адресами.
</div>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — про IP роутера:''' В строке <code>"listen": "192.168.10.1"</code> подставьте '''LAN-адрес вашего роутера''' (увидеть его можно в веб-интерфейсе Keenetic в карточке "Домашняя сеть"). Этот mixed-inbound — служебный, мы используем его для тестов; для боевой работы он не нужен, но не мешает.
</div>

=== Что делает каждая секция ===
{| class="wikitable"
!Секция
!Назначение
|-
|<code>log</code>
|Уровень логирования. <code>info</code> достаточно; для отладки можно поставить <code>debug</code>.
|-
|<code>dns</code>
|Какие DNS-серверы использует сам sing-box для резолва имён узлов (например, сервера Hysteria2).
|-
|<code>inbounds → tun</code>
|Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается трафик. Этот интерфейс будет использовать <code>keen-pbr</code>.
|-
|<code>inbounds → mixed</code>
|Локальный HTTP/SOCKS5-прокси на порту <code>7891</code>. Удобен для проверки туннеля.
|-
|<code>outbounds → hysteria2</code>
|Описание узла на удалённой стороне — куда идёт инкапсулированный трафик.
|-
|<code>outbounds → direct</code>
|"Прямой" выход — используется для трафика, который не нужно туннелировать.
|-
|<code>route.final = hy2</code>
|По умолчанию весь трафик, попавший в sing-box, отправляется через outbound с тегом <code>hy2</code>.
|-
|<code>experimental.clash_api</code>
|REST API на порту <code>9090</code>. Через него к sing-box подключаются дашборды (Yacd, Zashboard, metacubexd).
|}

=== Проверка конфига ===
<syntaxhighlight lang="bash">
sing-box check -c /opt/etc/sing-box/config.json
</syntaxhighlight>

Если конфиг корректен — команда отработает молча. Если ошибка — sing-box подскажет, какая.

== 2.3. Запуск ==
Запустить через init-скрипт Entware:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S99sing-box start
</syntaxhighlight>

В норме скрипт автоматически прописывает sing-box в автозагрузку — после перезагрузки роутера он стартует сам.

=== Проверка процесса и интерфейса ===
<syntaxhighlight lang="bash">
# Процесс
pgrep -af sing-box

# Создался ли TUN-интерфейс
awk '/:/{print $1}' /proc/net/dev | grep singtun

# Порты, которые слушает
netstat -tlnup | grep sing-box
</syntaxhighlight>

'''Ожидаемые результаты:'''
* Процесс <code>sing-box run -C /opt/etc/sing-box</code> существует.
* Интерфейс <code>singtun:</code> есть в списке.
* Слушаются как минимум: <code>0.0.0.0:7891</code> (mixed proxy), <code>0.0.0.0:9090</code> (clash-api).

== 2.4. Проверка туннеля ==
Сделайте запрос через локальный mixed-proxy и сравните с прямым:
<syntaxhighlight lang="bash">
# Прямой запрос (через ваш WAN)
curl -sS https://api.ipify.org
echo

# Тот же запрос, но через туннель
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org
echo
</syntaxhighlight>

'''Ожидаемый результат:''' два разных IP — первый ваш домашний, второй — IP туннеля.

Если IP совпадают или второй запрос не отвечает — туннель не работает. Проверьте логи sing-box и параметры конфига.

----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория и установка ==
Добавьте feed keen-pbr к конфигу OPKG и установите пакет:
<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code> (выбрать OS = '''Keenetic / NetCraze''', version = '''current''', архитектуру — свою). Узнать архитектуру роутера можно командой <code>opkg print-architecture</code>.
</div>

Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

=== Интерактивный диалог при установке ===
В процессе установки появится вопрос:
<pre>
Configuring keen-pbr.
keen-pbr installation
------------------------
Tip: set KEEN_PBR_REPLACE_DNSMASQ_DEFAULTS=Y or N to automate keen-pbr installation.
Replace /opt/etc/dnsmasq.conf with recommended keen-pbr dnsmasq defaults? [y/n]:
</pre>

Ответьте '''<code>y</code>''' и нажмите Enter. Это критически важно — keen-pbr заменит дефолтный <code>/opt/etc/dnsmasq.conf</code> на свой шаблон, который позволяет keen-pbr динамически наполнять ipset-списки доменами. Без этого ничего работать не будет.

Ожидаемый ответ после ввода <code>y</code>:
<pre>
Backing up existing /opt/etc/dnsmasq.conf to /opt/etc/dnsmasq.conf.backup-pre-keen-pbr
Installing recommended keen-pbr dnsmasq base config to /opt/etc/dnsmasq.conf

keen-pbr: Disabling HW NAT...
net.netfilter.nf_conntrack_fastnat = 0
[local_list] Skipped (no URL)
Starting keen-pbr... done.

Installation complete!
Config path: /opt/etc/keen-pbr/config.json
Web API: http://my.keenetic.net:12121
</pre>

== 3.2. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого к Keenetic:
<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>

Например, <code>http://192.168.1.1:12121</code>, или <code>http://my.keenetic.net:12121</code>.

== 3.3. Базовая настройка через веб-интерфейс ==
Все пять шагов ниже делаются в UI keen-pbr. После них трафик пойдёт в туннель и DNS будет давать реальные IP, а не подменённые.

=== Шаг 1. Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → '''+ Добавить outbound'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}

Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''Исправен''' и активным интерфейсом.

''(Скриншот: страница "Outbounds (выходы)" с тремя строками: wan, block, vpn.)''

=== Шаг 2. Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''+ Добавить список'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''Имя'''
|<code>bypass</code>
|-
|'''Тип'''
|<code>Домены</code>
|-
|'''Источник'''
|<code>Inline</code> (вкладка с textarea)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:
<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>

Сохранить.

=== Шаг 3. Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''+ Добавить правило маршрутизации'''.

{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (созданный на шаге 1)
|-
|'''Enabled'''
|включить
|}

Сохранить.

=== Шаг 4. Убрать встроенный keenetic_dns ===
В меню слева: '''Интернет''' → '''DNS-серверы'''.

В таблице вы увидите две строки: <code>keenetic_dns</code> и <code>quad9</code>. '''Удалите <code>keenetic_dns</code>''' (иконка корзины в столбце «Действия»).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем это нужно:''' Сервер <code>keenetic_dns</code> идёт через встроенный DNS-резолвер прошивки KeeneticOS. На некоторых конфигурациях (включённые «защитные» сервисы, community-порты) этот резолвер подменяет ответы для конкретных доменов на fake-IP из диапазона <code>198.18.x.x</code>. Эти fake-IP попадают в ipset keen-pbr → маршрутизация формально срабатывает → но трафик улетает на несуществующий адрес и клиент получает таймаут.
</div>

=== Шаг 5. Назначить основной DNS-сервер ===
В меню слева: '''Правила трафика''' → '''DNS-правила''' → блок '''«Основные DNS сервера»''' (вверху страницы).

Нажмите '''+ Добавить основной DNS сервер''' и выберите из списка <code>quad9</code>.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Что это такое:''' «Основные DNS сервера» — это fallback dnsmasq, то есть сервер, который используется, когда ни одно DNS-правило не подходит. После удаления <code>keenetic_dns</code> на шаге 4 он стал пустым — назначаем <code>quad9</code> (9.9.9.9), чтобы все запросы шли на публичный DNS, а не на DNS прошивки.
</div>

=== Применить изменения ===
В правом нижнем углу горит оранжевый баннер '''«Несохранённые изменения»'''. Нажмите '''«Применить и перезапустить»''' — keen-pbr перестроит конфигурацию dnsmasq и применит правила маршрутизации.

''(Скриншот: страница "Правила маршрутизации" с активным правилом #2 bypass → vpn.)''

== 3.4. Скрипт правил NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Зачем нужен этот шаг:''' keen-pbr настраивает маркировку пакетов, ip-rule и таблицу маршрутизации, но '''не трогает''' таблицы NAT и FORWARD. Для интерфейсов, которые KeeneticOS знает (например, штатный WireGuard <code>nwg0</code>), правила NAT/FORWARD добавляет сам ndm. Но <code>singtun</code> от sing-box — userspace-интерфейс, ndm о нём не знает. Без MASQUERADE и FORWARD ACCEPT трафик клиентов LAN до туннеля не доходит. Создадим один маленький скрипт, который добавляет эти правила автоматически.
</div>

=== Подключитесь по SSH к роутеру и выполните одну команду: ===
<syntaxhighlight lang="bash">
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
ls -la /opt/etc/ndm/netfilter.d/40-singtun-nat.sh
</syntaxhighlight>

Последняя строка покажет файл — должно быть <code>-rwxr-xr-x ... 40-singtun-nat.sh</code>.

=== Почему именно <code>/opt/etc/ndm/netfilter.d/</code>, а не <code>init.d</code> ===
KeeneticOS-овский ndm периодически перестраивает таблицы iptables «с нуля» (при изменении сети, новых клиентах, реконфигурации). Всё, что добавлено обычным <code>init.d</code>-скриптом, при этом стирается. А скрипты в <code>/opt/etc/ndm/netfilter.d/</code> ndm '''сам дёргает''' после каждого перестроения. Так что наш хук переживает любые события сети без вмешательства пользователя.

=== Переменные в скрипте ===
В скрипте всего два места, которые '''теоретически''' могут отличаться у разных пользователей:

{| class="wikitable"
!Переменная
!Значение по умолчанию
!Что подставить, если у вас иначе
|-
|<code>TUN</code>
|<code>singtun</code>
|То имя, которое вы прописали в поле <code>interface_name</code> своего <code>sing-box/config.json</code> (Этап 2.2). В этом гайде — <code>singtun</code>, и менять не нужно.
|-
|<code>LAN</code>
|<code>br0</code>
|Имя LAN-bridge KeeneticOS. '''На всех Keenetic-роутерах''' (включая community-порты на Xiaomi/TP-Link/Mercusys) это <code>br0</code>. Проверить: <code>ip link show \| grep "state UP"</code> на роутере или раздел "Домашняя сеть" в веб-UI Keenetic.
|}

Архитектура (mipsel/aarch64) на этот скрипт '''не влияет''' — пути <code>/opt/etc/ndm/netfilter.d/</code> и <code>/opt/sbin/iptables</code> одинаковы для всех Entware-сборок.

== 3.5. Тестирование ==
На клиентском устройстве, подключённом к Keenetic:

# '''Очистите кеш DNS''' (важно — без этого старые ответы остаются):
#* Windows: <code>ipconfig /flushdns</code> в PowerShell.
#* Android / iOS: переподключиться к Wi-Fi (off → on).
#* macOS: <code>sudo dscacheutil -flushcache</code>.
# Перезапустите браузер (у него свой DNS-кеш).
# Откройте сайт из списка bypass.
# Параллельно откройте <code>https://api.ipify.org</code> в браузере. Адрес должен быть тот же, который вы видели в проверке туннеля sing-box (т.е. IP вашего VPN-провайдера, а не домашний WAN-IP).

''(Скриншот: страница api.ipify.org с подменённым IP.)''

----

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Установка ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
</syntaxhighlight>

После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

'''Ожидаемый результат:'''
<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}

Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.2. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Установка ===
<syntaxhighlight lang="bash">
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web
</syntaxhighlight>

Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Замечание про «failed» в конце установки:''' В выводе установщика вы можете увидеть строку:
<pre>
Starting /opt/sbin/lighttpd... failed.
NFQWS2 Web Interface installed: http://192.168.10.1:90
</pre>
Это '''не ошибка'''. lighttpd пытается стартануть до того, как все его модули (php8-mod-curl, php8-mod-session, mod-rewrite, mod-redirect) полностью зарегистрировались. Через несколько секунд стартовый скрипт <code>S80lighttpd</code> успешно поднимает сервис. Достаточно проверить:
<syntaxhighlight lang="bash">
pgrep -af lighttpd
netstat -tlnup | grep :90
</syntaxhighlight>
Оба должны показать запущенный процесс на порту 90. Если веб-интерфейс открывается на <code>http://LAN-АДРЕС-РОУТЕРА:90</code> — всё в порядке.
</div>

=== Доступ ===
<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>

Например, <code>http://192.168.10.1:90</code>.

Для доступа из другой подсети — открыть порт <code>90</code> в фаерволе Keenetic (по аналогии с keen-pbr WebUI).

----

= Финальная архитектура =
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''dnsmasq'''
|UDP/TCP :53 на LAN-адресе роутера
|Принимает DNS-запросы от LAN и наполняет ipset keen-pbr
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|}

<pre>
K E E N E T I C Р О У Т Е Р
┌───────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ │
LAN│ │ DNS-запрос │ │
───┼──►│ от клиента │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ upstream ┌────────────────┐ │
│ │ keen-pbr │ через │ Quad9 9.9.9.9 │ │
│ │ dnsmasq │ ─────────► │ │ │
│ │ на :53 │ │ │ │
│ └──────┬───────┘ └────────────────┘ │
│ │ IP → ipset │
│ │ │
│ ┌──────▼──────────────────────────────────────────────┐ │
LAN│ │ iptables / маршрутизация │ │
───┼──►│ ├ если dst-IP в ipset bypass: │ │
TCP│ │ │ fwmark → ip rule → table 151 → singtun │ │
│ │ │ │ │
│ │ └ иначе: │ │
│ │ обычный WAN-маршрут │ │
│ │ └ nfqws2 ловит первые пакеты │ │
│ │ и модифицирует для обхода DPI │ │
│ └────┬──────────────────────────────────────────┬─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌────────────────┐ │
│ │ singtun │ │ WAN-интерфейс │ │
│ │ (TUN) │ │ (ваш провайдер)│ │
│ └────┬────┘ └────────┬───────┘ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────┐ │ │
│ │ sing-box │ │ │
│ │ outbound: │ │ │
│ │ hysteria2 │ │ │
│ └──────┬──────┘ │ │
│ │ │ │
└──────────┼────────────────────────────────────────┼───────────────────────┘
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ VPN-узел │ │ Любой │
│ провайдера│ │ интернет │
└───────────┘ └───────────┘
</pre>

''(Здесь можно перерисовать в Mermaid/Excalidraw для финальной картинки.)''

----

= Эксплуатация =
== Добавление новых доменов в список keen-pbr ==
# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==
=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>

После обновления может потребоваться перезапуск сервисов или роутера.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|<code>logread \| grep sing-box</code>
|-
|keen-pbr
|<code>logread \| grep keen-pbr</code> + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}

----

= Диагностика =
== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S56dnsmasq status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

== Проверка keen-pbr ==
<syntaxhighlight lang="bash">
keen-pbr --config /opt/etc/keen-pbr/config.json status
</syntaxhighlight>

В выводе должно быть '''<code>Overall: OK</code>''', а у outbound <code>vpn [interface] iface=singtun</code> — все строки со статусом <code>OK</code>.

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

Оба должны вернуть IP вашего VPN-узла.

== Проверка DNS ==
<syntaxhighlight lang="bash">
# Должен вернуться реальный публичный IP (НЕ из 198.18.x.x)
nslookup example.com 127.0.0.1

# Self-test keen-pbr — должен вернуть 127.0.0.88
nslookup check.keen.pbr 127.0.0.1
</syntaxhighlight>

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список (должны быть реальные публичные)
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица для помеченного трафика
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе

# NAT и FORWARD для singtun (наш хук)
iptables -t nat -S POSTROUTING | grep singtun
iptables -S FORWARD | grep singtun
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>: <pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы — сервер <code>keenetic_dns</code> не удалён в UI keen-pbr
|Проверьте Шаги 4 и 5 раздела '''3.3''' — должен быть удалён <code>keenetic_dns</code> и добавлен <code>quad9</code> в "Основные DNS сервера". После — '''Применить и перезапустить'''.
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr (вы ответили <code>n</code> на вопрос при установке)
|Восстановить шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf && /opt/etc/init.d/S56dnsmasq restart</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут с клиента)
|Нет NAT/FORWARD-правил для singtun (хук не создан или не выполняется)
|Проверить <code>ls /opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>. Если нет — пересоздать (раздел '''3.4'''). Если есть — выполнить вручную: <code>/opt/etc/ndm/netfilter.d/40-singtun-nat.sh</code>
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|-
|После установки nfqws-keenetic-web видна строка "Starting lighttpd... failed"
|Не ошибка — lighttpd стартует до полной регистрации модулей и поднимается на следующей попытке
|Проверить, что lighttpd сейчас запущен: <code>pgrep -af lighttpd</code> и <code>netstat -tlnup \| grep :90</code>. Если процесс есть и порт слушается — всё в порядке.
|}

----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (в командной строке Keenetic /a) ===
show media # узнать UUID
opkg dns-override # сразу включаем DNS-override
system configuration save
opkg disk ВАШ_UUID_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
system reboot

# === 2. После SSH-входа на :222 (пароль keenetic) ===
passwd # сменить пароль root

# === 3. sing-box ===
opkg update
opkg install sing-box-go curl nano wget-ssl
# Поместить рабочий config.json в /opt/etc/sing-box/ (см. Этап 2.2)
sing-box check -c /opt/etc/sing-box/config.json
/opt/etc/init.d/S99sing-box start

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr # на вопрос про dnsmasq.conf — ответить y

# Дальше — UI на http://my.keenetic.net:12121:
# * Outbounds: создать vpn (type=Interface, interface=singtun)
# * Списки: создать bypass с доменами
# * Правила маршрутизации: bypass → vpn
# * DNS-серверы: удалить keenetic_dns
# * DNS-правила → Основные DNS сервера: добавить quad9
# * Применить и перезапустить

# Скрипт NAT/FORWARD для singtun:
cat > /opt/etc/ndm/netfilter.d/40-singtun-nat.sh << 'EOF'
#!/opt/bin/sh
[ "$table" = "nat" ] || [ "$table" = "filter" ] || [ -z "$table" ] || exit 0
TUN=singtun
LAN=br0
PATH=/opt/sbin:/opt/usr/sbin:$PATH
ip link show "$TUN" >/dev/null 2>&1 || exit 0
iptables -t nat -C POSTROUTING -o $TUN -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN -j MASQUERADE
iptables -C FORWARD -i $LAN -o $TUN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN -o $TUN -j ACCEPT
iptables -C FORWARD -i $TUN -o $LAN -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN -o $LAN -j ACCEPT
EOF
chmod +x /opt/etc/ndm/netfilter.d/40-singtun-nat.sh

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic # стартует автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web # "failed" в конце — нормально, см. 4.2
</syntaxhighlight>

----

<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

----

= Приложение А. OpenSSH с ключом (опционально) =
Этот раздел описывает '''продвинутую''' настройку SSH-доступа: установку полноценного OpenSSH-сервера в Entware и настройку входа по публичному ключу вместо пароля.

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Для всего, что описано в Этапах 1–4 (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю через встроенный SSH-сервер Entware (dropbear) на порту '''222''' — настроенный в разделе 1.4. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам.
</div>

== Когда этот раздел действительно полезен ==
* Вы заходите на роутер часто и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время.

== Что мы получим ==
* Дополнительный SSH-сервер OpenSSH на порту '''2022''' (рядом с dropbear на 222, не вместо).
* Вход по публичному ключу без ввода пароля.
* Удобный алиас на ПК — подключение одной командой <code>ssh keen</code>.

Встроенный dropbear на 222 остаётся работать — это «запасной» канал на случай, если что-то сломается в настройках OpenSSH.

== А.1. Установка OpenSSH-сервера ==
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

== А.2. Создание пользователя для privsep ==
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:
<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

== А.3. Генерация host-ключей ==
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

== А.4. Конфигурация sshd ==
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>

Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):
<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight>

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание про StrictModes:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code>. Это нормально для прошивки, но OpenSSH '''по умолчанию''' отказывает в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>

Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

== А.5. Скрипт пересоздания /var/empty при загрузке ==
Каталог <code>/var</code> на роутере — это tmpfs (RAM-диск), он очищается при каждой загрузке. Создадим стартовый скрипт, который воссоздаёт <code>/var/empty</code>:
<syntaxhighlight lang="bash">
cat > /opt/etc/init.d/S39sshd-prep << 'EOF'
#!/bin/sh
mkdir -p /var/empty
chmod 755 /var/empty
chown root:root /var/empty
EOF
chmod +x /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

== А.6. Добавление публичного ключа ==
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):
<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>

Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:
<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>

Вставьте строку публичного ключа (правой кнопкой мыши в PuTTY), сохраните файл, дайте права:
<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

== А.7. Запуск ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

== А.8. Открытие порта в фаерволе (если нужен внешний доступ) ==
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

== А.9. Удобный алиас на ПК ==
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:
<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>

Подставьте свой LAN-адрес роутера в <code>HostName</code>.

Теперь подключение — одной командой:
<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>

== А.10. Откат ==
Если что-то пошло не так — встроенный dropbear на :222 продолжает работать, через него зайдите и удалите OpenSSH:
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd stop
opkg remove openssh-server
rm -f /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

Суверенный интернет

2026-05-12T08:04:15Z

Владимир:

Эта страница посвящается всему что связано с ограничим доступа в интернет.

На данный момент 20.04.26 мы имеем полную блокировку по белыми IP у операторов мобильной связи. И предпосылки к блокировкам на уровне провайдеров домашнего интернета.

* [[Обход НКР|Установка и настройка связки Zapret + Podkop на OpenWRT]]
* [[Hysteria 2 каскад]]
* [[Whitelist-bypass: VK Creator (headless на сервере) + Joiner (Android)]]
* [[Установка MTProto Proxy (mtg) на Linux-сервере]]
* [[VK Turn Proxy + FreeTurn + VLESS]]
* [[NaïveProxy: установка полной каскадной цепочки]]
* [[OlcRTC: туннель через WebRTC-сервисы|olcRTC: туннель через легальные WebRTC-сервисы]]
* [[mieru: каскадный шифрованный SOCKS5-туннель]]
* [[Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)]]

Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

2026-05-12T07:32:46Z

Владимир: Новая страница: «= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic = Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщес...»

= Установка стека: гибкая маршрутизация и обход DPI на роутере Keenetic =
Подробная пошаговая инструкция для пользователя, который умеет работать в терминале, но не знаком с устройством роутерных систем. Проверено на '''Xiaomi Mi Router 3G''' с KeeneticOS '''5.0.7''' (порт сообщества). Подходит для любого Keenetic-устройства с поддержкой OPKG/Entware.
----

== Что мы построим ==
Связка из четырёх компонентов, каждый из которых решает свою задачу:
{| class="wikitable"
!Компонент
!Назначение
|-
|'''Entware'''
|Менеджер пакетов на роутере. Позволяет ставить любой Linux-софт через <code>opkg install</code>.
|-
|'''sing-box'''
|Универсальный туннельный движок. Поддерживает VLESS, Hysteria2, Trojan, Shadowsocks, WireGuard и др. Создаёт виртуальный сетевой интерфейс <code>singtun</code>, в который можно завернуть выборочный трафик.
|-
|'''keen-pbr'''
|Маршрутизатор по доменам. Решает, какой трафик отправлять в туннель <code>singtun</code>, а какой пускать напрямую. Имеет полноценный веб-интерфейс.
|-
|'''nfqws2''' (zapret v2)
|Утилита модификации сетевых пакетов. Обходит DPI-фильтрацию для сервисов, которые '''не нужно''' заворачивать в туннель (например, потоковое видео — чтобы не нагружать тоннель и не терять скорость).
|}

=== Общая архитектура ===
<pre>
KEENETIC РОУТЕР

┌──────────────────────────────────────────────────────────────┐
│ │
│ ┌────────────────┐ │
│ │ keen-pbr │ --- адрес домена в списке? --- │
│ │ (по доменам) │ │ │ │
│ └────────────────┘ │ ДА │ НЕТ │
│ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ │
│ │ singtun │ │ nfqws2 │ │
│ │ (sing-box) │ │ DPI fix │ │
│ └────────────┘ └────────────┘ │
│ │ │ │
└────────────────────────────┼────────────────┼────────────────┘
│ │
┌────▼────┐ ┌────▼────┐
│ VPN- │ │ Прямой │
│ сервер │ │ WAN │
└─────────┘ └─────────┘
</pre>''(Здесь схему можно перерисовать в Mermaid или Excalidraw и заменить блок.)''
----

== Требования ==
{| class="wikitable"
!Требование
!Описание
|-
|'''Роутер'''
|Keenetic с поддержкой Entware/OPKG (KeeneticOS 3.7 и новее) и хотя бы одним свободным USB-портом.
|-
|'''USB-накопитель'''
|Любая флешка от '''8 ГБ'''. Будет отформатирована в EXT4. Без флешки не получится — встроенной памяти роутера не хватит.
|-
|'''Доступ к веб-интерфейсу'''
|Адрес роутера в браузере (обычно <code>192.168.1.1</code> или <code>my.keenetic.net</code>), логин администратора.
|-
|'''SSH-клиент'''
|PuTTY, Windows Terminal с OpenSSH, или любой другой.
|-
|'''VPN-узел'''
|Любой провайдер с протоколами VLESS, Hysteria2, Trojan и т.п. (необходим только для туннеля; обход DPI работает без него).
|}
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Полный стек (sing-box + keen-pbr + nfqws2 + зависимости) занимает '''около 110 МБ''' распакованного места. На встроенной флэш-памяти большинства роутеров этого нет — поэтому USB-накопитель '''обязателен'''.
</div>
----

= Этап 1. Установка Entware =
Entware — это система пакетов на основе OpenWrt-репозитория. После установки на роутере появится Linux-окружение в каталоге <code>/opt</code>, в которое можно ставить пакеты командой <code>opkg install</code>.

== 1.1. Подготовка USB-накопителя ==

=== Подключение и форматирование ===

# Воткните флешку в USB-порт роутера.
# Откройте веб-интерфейс Keenetic: '''Приложения''' → '''USB-диски и принтеры'''.
# В списке появится диск. Откройте его параметры.
# Если файловая система не <code>ext4</code> — нажмите '''Форматировать''' и выберите '''EXT4'''.

''(Скриншот: страница "USB-диски" в веб-интерфейсе Keenetic с подключённым диском и кнопкой "Форматировать".)''

=== Запомните идентификатор диска ===
После форматирования у диска есть уникальный '''идентификатор''' (UUID или метка). Он понадобится в следующем шаге. Идентификатор виден на той же странице — обычно это длинная строка вида:<pre>
d5f39712-7ae1-dc01-00f3-97127ae1dc01
</pre>''(Скриншот: страница диска с подсвеченным UUID/идентификатором.)''<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Скопируйте идентификатор в блокнот — впереди он пригодится несколько раз.
</div>

== 1.2. Компоненты KeeneticOS ==

=== Какая у вас прошивка? ===
KeeneticOS существует в двух вариантах, и от этого зависит, нужно ли вам что-то включать на этом этапе:
{| class="wikitable"
!Вариант прошивки
!Нужно ли включать компоненты?
|-
|'''Оригинальный Keenetic''' (роутер, который продавался как Keenetic с завода: KN-..., Hero, Ultra, Giga, Viva, Hopper, Peak и т.п.)
|'''Да''', через веб-интерфейс — см. ниже
|-
|'''Порт сообщества''' (например, [https://keeneticported.dev keeneticported.dev]) на роутере другой марки (Xiaomi Mi Router 3G/3/Pro, TP-Link, Mercusys и др.)
|'''Нет''', все нужные пакеты уже включены в образ прошивки этого порта — переходите к разделу 1.3
|}
<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — как понять, какая у вас прошивка:''' На странице '''Системный монитор''' (главная страница веб-интерфейса) видна модель устройства. Если рядом с моделью стоит знакомое маркетинговое имя Keenetic (например, "Keenetic Hero") и модель начинается с "KN-" — это оригинальный Keenetic. Если вы видите название роутера другого производителя (например, "Xiaomi R3G") и при этом отображается KeeneticOS — у вас порт сообщества.
</div><div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Признак порта сообщества:''' На странице с компонентами окно "Компоненты операционной системы" может показывать сообщение "Не удалось получить список компонентов от сервера" — это нормально для портированных сборок, у которых нет своего сервера обновлений. В этом случае шаг с компонентами '''не нужен''' — переходите к разделу 1.3.
</div>

=== Только для оригинального Keenetic ===
В веб-интерфейсе: '''Управление → Общие настройки''' → блок '''Обновления и компоненты''' → кнопка '''Показать компоненты''' (в более старых версиях UI — '''Изменить набор компонентов''').

Включите следующие компоненты:
{| class="wikitable"
!Компонент (точное название в UI)
!Зачем
|-
|'''Поддержка открытых пакетов''' (OPKG)
|Базовая инфраструктура Entware — без этого нельзя ставить пакеты на USB
|-
|'''Файловая система Ext'''
|Чтобы роутер мог монтировать ext4-диск
|-
|'''Сервер SSH'''
|Доступ к командной строке роутера
|}
Кроме того, '''желательно''' проверить наличие следующих компонентов (точные названия в интерфейсе могут отличаться от версии к версии — ищите по словам):
{| class="wikitable"
!Что искать в списке
!Зачем
|-
|"Netfilter" / "Модули ядра Netfilter"
|Базовые модули iptables для работы фаервола Entware
|-
|"Расширенные модули Netfilter" / "Netfilter addons"
|Дополнительные модули (xt_set, xt_multiport, conntrack-extra) — '''критично''' для работы keen-pbr
|-
|"Конструктор Access Policy" / "IntelliQoS"
|Для тонкой настройки nfqws2 по устройствам (опционально)
|}
После выбора нажмите '''Установить обновление''' и подождите 2–5 минут. Роутер перезагрузится самостоятельно.

''(Скриншот: страница "Обновления и компоненты" с открытым окном "Показать компоненты" и отмеченными нужными пунктами.)''<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В KeeneticOS 5 и новее компонент '''Протокол IPv6''' включён по умолчанию и не может быть отключён — это нормально.
</div>

== 1.3. Установка Entware через командную строку ==

=== Открытие командной строки роутера ===
Веб-интерфейс Keenetic имеет встроенную консоль. Откройте её одним из способов:

* '''Способ A:''' Перейдите по адресу <code>http://192.168.1.1/a</code> в браузере.
* '''Способ B:''' '''Диагностика''' → '''Командная строка''' (в новых прошивках).

Должно появиться приглашение вида:<pre>
(config)>
</pre>''(Скриншот: окно командной строки с приглашением <code>(config)></code>.)''

=== Запуск установки Entware ===
Команда состоит из '''двух частей, которые вы должны подставить сами''':

# '''Идентификатор вашего USB-диска''' — тот UUID, который вы запомнили на шаге '''1.1''' (длинная строка вида <code>d5f39712-7ae1-...</code>).
# '''URL установщика''' — выбирается по архитектуре вашего роутера (см. таблицу ниже).

<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — не копируйте команду как есть!''' В шаблоне ниже фигурные скобки <code><...></code> — это места, куда нужно подставить '''ваши''' значения. Если оставить шаблон с угловыми скобками или скопировать чужой UUID — установка не сработает.
</div>

==== Шаблон команды ====
<syntaxhighlight lang="bash">
opkg disk <ВАШ_UUID_ДИСКА>:/ <URL_УСТАНОВЩИКА_ДЛЯ_ВАШЕЙ_АРХИТЕКТУРЫ>
</syntaxhighlight>

==== Где взять каждую часть ====
'''(1) UUID диска''' — со страницы '''Приложения → Диски и принтеры''' (раздел 1.1 этого гайда). Скопируйте длинную строку, которая отображается как имя диска.

'''(2) URL установщика''' — выберите по архитектуре вашего роутера:
{| class="wikitable"
!Архитектура роутера
!URL установщика (целиком)
|-
|'''MIPS little-endian (mipsel)''' — большинство моделей Keenetic и портов на Xiaomi/TP-Link/Mercusys (Mi 3G, Mi 3, Mi 4A, Hero, Ultra, Giga, Viva, Air и др.)
|<code>https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz</code>
|-
|'''ARM 64-bit (aarch64)''' — современные Keenetic (Hopper KN-3810, Peak KN-2710 и др.)
|<code>https://bin.entware.net/aarch64-k3.10/installer/aarch64-installer.tar.gz</code>
|}
<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — как узнать архитектуру:''' Откройте '''Системный монитор''' в веб-интерфейсе → видно модель устройства и процессор. Для большинства бытовых моделей это MIPS — берите верхнюю строку таблицы. Если сомневаетесь — пишите команду с <code>mipsel</code>: если архитектура не подходит, установка скажет об этом ошибкой, и вы не сломаете роутер.
</div>

==== Пример с подставленными значениями ====
Допустим, ваш UUID — <code>d5f39712-7ae1-dc01-00f3-97127ae1dc01</code>, архитектура — mipsel. Тогда команда полностью выглядит так:<syntaxhighlight lang="bash">
opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
</syntaxhighlight><div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Это '''пример''' — UUID <code>d5f39712-...</code> здесь приведён только для иллюстрации. У '''вашего''' диска UUID будет '''другой'''. Подставьте именно свой со страницы "Диски и принтеры".
</div>

==== Проверочный чек-лист перед нажатием Enter ====

* Двоеточие и слэш <code>:/</code> сразу после UUID — '''обязательны'''.
* URL — '''одной строкой''', без пробелов и переносов.
* После UUID и перед URL — '''ровно один пробел'''.
* Угловых скобок <code><</code> и <code>></code> в финальной команде '''не должно остаться'''.

=== Сохранение конфигурации ===
После того как установка прошла без ошибок, сохраните конфигурацию:<syntaxhighlight lang="bash">
system configuration save
</syntaxhighlight><div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — если установщик "молчит":''' В некоторых сборках команда <code>opkg disk ... URL</code> не работает, если OPKG-диск уже был назначен раньше. Если в логе вы не видите строк про загрузку <code>mipsel-installer.tar.gz</code> — сбросьте диск и повторите:<syntaxhighlight lang="bash">
no opkg disk
opkg disk d5f39712-7ae1-dc01-00f3-97127ae1dc01:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save
</syntaxhighlight></div>

=== Проверка установки ===
Откройте журнал: '''Диагностика''' → '''Системный журнал'''. Должны появиться строки примерно такого содержания:<pre>
Opkg::Manager: downloading installer...
Opkg::Manager: extracting to /opt...
Opkg::Manager: ...
Entware installed.
</pre>После завершения установки на роутере поднимется встроенный SSH-сервер Entware на порту '''222'''.

== 1.4. Первое подключение по SSH ==
Подключитесь к роутеру с компьютера. На Windows — через PuTTY или через стандартный <code>ssh.exe</code>.
{| class="wikitable"
!Параметр
!Значение
|-
|Хост
|<code>192.168.1.1</code> (LAN-адрес роутера)
|-
|Порт
|'''222'''
|-
|Логин
|<code>root</code>
|-
|Пароль
|<code>keenetic</code>
|}
Из PowerShell это одна строка:<syntaxhighlight lang="powershell">
ssh -p 222 root@192.168.1.1
</syntaxhighlight>При первом подключении ssh попросит подтвердить fingerprint — ответьте <code>yes</code>.

=== Смена пароля (обязательно!) ===
Сразу после входа смените пароль:<syntaxhighlight lang="bash">
passwd
</syntaxhighlight>Введите новый пароль дважды.<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Дефолтный пароль <code>keenetic</code> известен всем — если SSH будет проброшен наружу, роутер взломают за минуты.
</div>

== 1.5. (опционально) Доступ по SSH-ключу через OpenSSH ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — этот раздел не нужен для обычной установки.''' Здесь описана продвинутая настройка: замена встроенного SSH-сервера (dropbear на порту 222) на полноценный OpenSSH с поддержкой ключей. Делайте, только если вы '''понимаете, зачем это нужно''' лично вам. Для всего, что описано в гайде дальше (sing-box, keen-pbr, nfqws2), хватает стандартного входа по паролю из раздела '''1.4''' — можете спокойно его пропустить и перейти к '''Этапу 2'''.
</div>

=== Когда этот раздел действительно полезен ===

* Вы заходите на роутер часто, и каждый раз вводить пароль раздражает.
* На том же ПК уже есть SSH-ключ, которым вы пользуетесь для других серверов, и хочется единообразия.
* Вы планируете давать роутеру доступ автоматизированным инструментам (скрипты, агенты, CI), которые не умеют вводить пароль.
* Хочется иметь возможность '''выключить парольную аутентификацию''' и оставить только ключ — это сильно повышает безопасность, если SSH будет проброшен наружу.

Если ни один пункт не про вас — не тратьте время, переходите к '''Этапу 2'''.

=== Установка OpenSSH-сервера ===
<syntaxhighlight lang="bash">
opkg update
opkg install openssh-server
</syntaxhighlight>

=== Создание пользователя для privsep ===
OpenSSH требует системного пользователя <code>sshd</code> для изоляции привилегий. В Entware его по умолчанию нет:<syntaxhighlight lang="bash">
echo 'sshd:*:22:22:sshd:/var/empty:/bin/false' >> /opt/etc/passwd
echo 'sshd:*:22:' >> /opt/etc/group
mkdir -p /var/empty
chmod 755 /var/empty
</syntaxhighlight>

=== Генерация host-ключей ===
<syntaxhighlight lang="bash">
ssh-keygen -A
</syntaxhighlight>

=== Конфигурация sshd ===
<syntaxhighlight lang="bash">
nano /opt/etc/ssh/sshd_config
</syntaxhighlight>Найдите и отредактируйте следующие параметры (раскомментируйте, если стоит <code>#</code>):<syntaxhighlight lang="ini">
Port 2022
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes
StrictModes no
AuthorizedKeysFile /opt/root/.ssh/authorized_keys
</syntaxhighlight><div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' На Keenetic корневой каталог <code>/</code> смонтирован с правами <code>777</code> (write для всех). Это нормально для прошивки, но dropbear и OpenSSH '''по умолчанию''' отказывают в pubkey-аутентификации, если хоть один каталог в пути до <code>authorized_keys</code> доступен на запись группе или всем. Параметр <code>StrictModes no</code> отключает эту проверку.
</div>Сохраните файл (<code>Ctrl+O</code> → <code>Enter</code> → <code>Ctrl+X</code>).

=== Скрипт пересоздания /var/empty при загрузке ===
Каталог <code>/var</code> на роутере — это tmpfs (RAM-диск), он очищается при каждой загрузке. Создадим стартовый скрипт, который воссоздаёт <code>/var/empty</code>:<syntaxhighlight lang="bash">
cat > /opt/etc/init.d/S39sshd-prep << 'EOF'
#!/bin/sh
mkdir -p /var/empty
chmod 755 /var/empty
chown root:root /var/empty
EOF
chmod +x /opt/etc/init.d/S39sshd-prep
</syntaxhighlight>

=== Добавление публичного ключа ===
На вашем компьютере получите содержимое публичного ключа (Windows, PowerShell):<syntaxhighlight lang="powershell">
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
</syntaxhighlight>Если ключа нет — создайте: <code>ssh-keygen -t ed25519</code>.

На роутере:<syntaxhighlight lang="bash">
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys
</syntaxhighlight>Вставьте строку публичного ключа (правой кнопкой в PuTTY), сохраните файл, дайте права:<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/authorized_keys
</syntaxhighlight>

=== Запуск ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S40sshd start
</syntaxhighlight>

=== Открытие порта в фаерволе ===
Если планируете заходить с другой сети — добавьте правило в '''Сетевые правила → Межсетевой экран → Ethernet-подключение → Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>SSH OpenSSH</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>2022</code>
|}

=== Удобный алиас на ПК ===
Создайте/откройте файл <code>C:\Users\ВашИмя\.ssh\config</code> и добавьте:<syntaxhighlight lang="ini">
Host keen
HostName 192.168.1.1
User root
Port 2022
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
</syntaxhighlight>Теперь подключение — одной командой:<syntaxhighlight lang="powershell">
ssh keen
</syntaxhighlight>
----

= Этап 2. Установка sing-box =
sing-box — это движок туннеля. Он умеет «слушать» виртуальный TUN-интерфейс и пересылать всё, что туда прилетит, через выбранный протокол (VLESS, Hysteria2, и др.) на удалённый сервер.

== 2.1. Установка пакета ==
Подключитесь к роутеру по SSH и выполните:<syntaxhighlight lang="bash">
opkg update
opkg install sing-box-go
</syntaxhighlight><div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание:''' Пакет занимает '''около 62 МБ''' в распакованном виде. Установка во встроенную память роутера (без USB) почти всегда невозможна — поэтому Entware должен быть на USB.
</div>

=== Проверка ===
<syntaxhighlight lang="bash">
sing-box version
</syntaxhighlight>'''Ожидаемый вывод:'''<pre>
sing-box version 1.13.3

Environment: go1.26.1 linux/mipsle
Tags: ... with_quic ... with_clash_api ... with_gvisor ...
</pre><div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Обратите внимание на флаги в выводе. <code>with_quic</code> означает поддержку Hysteria/Hysteria2/TUIC. <code>with_clash_api</code> — встроенный API для подключения веб-дашбордов. Если этих флагов нет — версия урезана, нужна другая сборка.
</div>

== 2.2. Создание конфига ==
sing-box читает конфиг из <code>/opt/etc/sing-box/config.json</code>. Заводской пример нам не подойдёт — там настроен серверный режим Shadowsocks. Создадим клиентский конфиг.

=== Пример: Hysteria2-узел в туннеле ===
Предположим, ваш провайдер выдал ссылку вида:<pre>
hysteria2://ПАРОЛЬ@ВАШ_СЕРВЕР:ПОРТ
</pre>Запишите рабочий конфиг:<syntaxhighlight lang="bash">
cat > /opt/etc/sing-box/config.json << 'EOF'
{
"log": { "level": "info", "timestamp": true },
"dns": {
"servers": [
{ "type": "udp", "tag": "dns-direct", "server": "1.1.1.1" }
],
"strategy": "ipv4_only"
},
"inbounds": [
{
"type": "tun",
"tag": "tun-in",
"interface_name": "singtun",
"address": ["198.18.0.1/30"],
"mtu": 1500,
"auto_route": false,
"strict_route": false,
"stack": "gvisor",
"sniff": true
},
{
"type": "mixed",
"tag": "test-proxy",
"listen": "192.168.10.1",
"listen_port": 7891
}
],
"outbounds": [
{
"type": "hysteria2",
"tag": "hy2",
"server": "ВАШ_СЕРВЕР",
"server_port": ПОРТ,
"password": "ПАРОЛЬ",
"tls": {
"enabled": true,
"server_name": "ВАШ_СЕРВЕР"
}
},
{ "type": "direct", "tag": "direct" }
],
"route": {
"final": "hy2",
"rules": [
{ "action": "sniff" },
{ "protocol": "dns", "action": "hijack-dns" }
]
},
"experimental": {
"clash_api": {
"external_controller": "0.0.0.0:9090",
"external_ui": "/opt/share/dashboard"
}
}
}
EOF
</syntaxhighlight>Замените <code>ВАШ_СЕРВЕР</code>, <code>ПОРТ</code>, <code>ПАРОЛЬ</code> на реальные значения.<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — про подсеть TUN:''' Значение <code>"address": ["198.18.0.1/30"]</code> — это подсеть TUN-интерфейса (внутренний адрес виртуального сетевого устройства). Диапазон <code>198.18.0.0/15</code> зарезервирован RFC 2544 и не используется в реальном интернете — он не конфликтует ни с вашей LAN, ни с публичными адресами.
</div><div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет — про IP роутера:''' В строке <code>"listen": "192.168.10.1"</code> подставьте '''LAN-адрес вашего роутера''' (увидеть его можно в веб-интерфейсе Keenetic в карточке "Домашняя сеть"). Этот mixed-inbound — служебный, мы используем его для тестов; для боевой работы он не нужен, но не мешает.
</div>

=== Что делает каждая секция ===
{| class="wikitable"
!Секция
!Назначение
|-
|<code>log</code>
|Уровень логирования. <code>info</code> достаточно; для отладки можно поставить <code>debug</code>.
|-
|<code>dns</code>
|Какие DNS-серверы использует сам sing-box для резолва имён узлов (например, сервера Hysteria2).
|-
|<code>inbounds → tun</code>
|Создаёт виртуальный интерфейс <code>singtun</code>, в который заворачивается трафик. Этот интерфейс будет использовать <code>keen-pbr</code>.
|-
|<code>inbounds → mixed</code>
|Локальный HTTP/SOCKS5-прокси на порту <code>7891</code>. Удобен для проверки туннеля.
|-
|<code>outbounds → hysteria2</code>
|Описание узла на удалённой стороне — куда идёт инкапсулированный трафик.
|-
|<code>outbounds → direct</code>
|"Прямой" выход — используется для трафика, который не нужно туннелировать.
|-
|<code>route.final = hy2</code>
|По умолчанию весь трафик, попавший в sing-box, отправляется через outbound с тегом <code>hy2</code>.
|-
|<code>experimental.clash_api</code>
|REST API на порту <code>9090</code>. Через него к sing-box подключаются дашборды (Yacd, Zashboard, metacubexd).
|}

=== Проверка конфига ===
<syntaxhighlight lang="bash">
sing-box check -c /opt/etc/sing-box/config.json
</syntaxhighlight>Если конфиг корректен — команда отработает молча. Если ошибка — sing-box подскажет, какая.

== 2.3. Запуск ==
Запустить через init-скрипт Entware:<syntaxhighlight lang="bash">
/opt/etc/init.d/S99sing-box start
</syntaxhighlight>В норме скрипт автоматически прописывает sing-box в автозагрузку — после перезагрузки роутера он стартует сам.

=== Проверка процесса и интерфейса ===
<syntaxhighlight lang="bash">
# Процесс
pgrep -af sing-box

# Создался ли TUN-интерфейс
awk '/:/{print $1}' /proc/net/dev | grep singtun

# Порты, которые слушает
netstat -tlnup | grep sing-box
</syntaxhighlight>'''Ожидаемые результаты:'''

* Процесс <code>sing-box run -C /opt/etc/sing-box</code> существует.
* Интерфейс <code>singtun:</code> есть в списке.
* Слушаются как минимум: <code>0.0.0.0:7891</code> (mixed proxy), <code>0.0.0.0:9090</code> (clash-api).

== 2.4. Проверка туннеля ==
Сделайте запрос через локальный mixed-proxy и сравните с прямым:<syntaxhighlight lang="bash">
# Поставим curl, если ещё не стоит
opkg install curl

# Прямой запрос (через ваш WAN)
curl -sS https://api.ipify.org
echo

# Тот же запрос, но через туннель
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org
echo
</syntaxhighlight>'''Ожидаемый результат:''' два разных IP — первый ваш домашний, второй — IP туннеля.

Если IP совпадают или второй запрос не отвечает — туннель не работает. Проверьте логи sing-box и параметры конфига.
----

= Этап 3. Установка keen-pbr =
keen-pbr решает '''одну задачу''': какие домены отправлять в туннель <code>singtun</code>, а какие пускать напрямую. Имеет современный веб-интерфейс на отдельном порту.

== 3.1. Подключение репозитория ==
Добавьте feed keen-pbr к конфигу OPKG:<syntaxhighlight lang="bash">
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
</syntaxhighlight><div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' Для других архитектур URL feed-а отличается. Список архитектур и URL — на странице репозитория проекта: <code>https://repo.keen-pbr.fyi/repository/stable/</code>
</div>

== 3.2. Установка пакета ==
<syntaxhighlight lang="bash">
opkg install keen-pbr
</syntaxhighlight>Пакет потянет за собой зависимости: <code>dnsmasq-full</code>, <code>ipset</code>, <code>iptables</code>, <code>libnl-*</code> и др. — это нормально.

''(Скриншот: вывод команды <code>opkg install keen-pbr</code> с перечислением устанавливаемых зависимостей.)''

== 3.3. Замена dnsmasq.conf ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — это критичный шаг:''' При установке через SSH postinst-скрипт keen-pbr ждёт интерактивного ответа («заменить ли <code>/opt/etc/dnsmasq.conf</code> на шаблон keen-pbr?»). В неинтерактивном режиме скрипт ничего не делает — и dnsmasq стартует без интеграции с keen-pbr. Сделаем замену вручную.
</div><syntaxhighlight lang="bash">
# Сохраним заводской конфиг про запас
cp /opt/etc/dnsmasq.conf /opt/etc/dnsmasq.conf.backup-pre-keen-pbr

# Установим шаблон keen-pbr
cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf
</syntaxhighlight>

== 3.4. Включение DNS Override ==
Чтобы прошивка KeeneticOS отдавала перехваченный 53-й порт нашему dnsmasq, нужно включить опцию '''opkg dns-override'''.

Выполните в командной строке роутера (<code>http://192.168.1.1/a</code>):<syntaxhighlight lang="bash">
opkg dns-override
system configuration save
</syntaxhighlight>''(Скриншот: окно <code>192.168.1.1/a</code> с введённой командой и ответом <code>DNS override enabled.</code>)''

== 3.5. Перезагрузка роутера ==
Опция <code>opkg dns-override</code> применяется только после полной перезагрузки. Выполните:<syntaxhighlight lang="bash">
system reboot
</syntaxhighlight>Или через веб-интерфейс: '''Системный монитор''' → '''Перезагрузить'''.

Ожидайте 1–2 минуты, пока роутер поднимется обратно.

== 3.6. Workaround: правила NAT и FORWARD ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — известный нюанс keen-pbr 3.x:''' Для outbound типа <code>interface</code> (т.е. для отправки трафика в TUN-интерфейс sing-box) keen-pbr 3.x '''не добавляет''' необходимые правила NAT MASQUERADE и FORWARD ACCEPT. Без них трафик клиентов LAN не доходит до туннеля. Создадим стартовый скрипт, который добавит их.
</div>Подключитесь по SSH и создайте файл:<syntaxhighlight lang="bash">
cat > /opt/etc/init.d/S81keen-pbr-fixup << 'EOF'
#!/bin/sh
# Workaround для keen-pbr 3.x + sing-box TUN.
# Добавляет MASQUERADE на singtun и FORWARD ACCEPT br0 <-> singtun.

PATH=/opt/sbin:/opt/usr/sbin:/opt/bin:/opt/usr/bin:$PATH
TUN_IFACE=singtun
LAN_IFACE=br0

# Подождать пока интерфейс появится после старта sing-box
for i in 1 2 3 4 5 6 7 8 9 10; do
ip link show $TUN_IFACE >/dev/null 2>&1 && break
sleep 1
done

iptables -t nat -C POSTROUTING -o $TUN_IFACE -j MASQUERADE 2>/dev/null || \
iptables -t nat -A POSTROUTING -o $TUN_IFACE -j MASQUERADE

iptables -C FORWARD -i $LAN_IFACE -o $TUN_IFACE -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $LAN_IFACE -o $TUN_IFACE -j ACCEPT

iptables -C FORWARD -i $TUN_IFACE -o $LAN_IFACE -j ACCEPT 2>/dev/null || \
iptables -I FORWARD 1 -i $TUN_IFACE -o $LAN_IFACE -j ACCEPT

logger -t keen-pbr-fixup "NAT/FORWARD rules applied for $TUN_IFACE"
EOF
chmod +x /opt/etc/init.d/S81keen-pbr-fixup

# Запустим прямо сейчас
/opt/etc/init.d/S81keen-pbr-fixup
</syntaxhighlight>Скрипт стартует автоматически с Entware (имя начинается с <code>S81</code>).

== 3.7. Замена upstream DNS на публичные серверы ==
<div style="padding: 10px 15px; margin: 10px 0; background-color: #fff3cd; border-left: 4px solid #ffc107; border-radius: 4px;">
'''Внимание — обязательный шаг:''' По умолчанию keen-pbr использует встроенный DNS-сервер KeeneticOS в качестве upstream. Этот сервер может подменять ответы на fake-IP из диапазона <code>198.18.x.x</code> для некоторых доменов (это поведение зависит от настроек прошивки и подключённых "защитных" сервисов). В итоге keen-pbr получает поддельные IP, кладёт их в свой ipset, а трафик клиента уходит "в никуда".
</div>Откройте конфиг keen-pbr:<syntaxhighlight lang="bash">
nano /opt/etc/keen-pbr/config.json
</syntaxhighlight>Найдите блок <code>"dns"</code> и замените его на:<syntaxhighlight lang="json">
"dns": {
"system_resolver": {
"address": "127.0.0.1"
},
"dns_test_server": {
"listen": "127.0.0.88:12153"
},
"servers": [
{ "tag": "cloudflare", "address": "1.1.1.1" },
{ "tag": "quad9", "address": "9.9.9.9" }
],
"rules": [],
"fallback": ["cloudflare", "quad9"]
},
</syntaxhighlight>Сохраните файл и перезапустите сервис:<syntaxhighlight lang="bash">
/opt/etc/init.d/S80keen-pbr restart
</syntaxhighlight>

=== Проверка ===
<syntaxhighlight lang="bash">
# Резолв через локальный сервер должен вернуть реальный IP
nslookup example.com 127.0.0.1
</syntaxhighlight>'''Хороший результат:''' нормальный публичный IP. '''Плохой результат:''' что-то из <code>198.18.x.x</code> — DNS не сменился, проверьте конфиг ещё раз.

== 3.8. Доступ к веб-интерфейсу ==
keen-pbr слушает на порту '''12121'''.

=== Изнутри LAN роутера ===
В браузере устройства, подключённого по Wi-Fi/Ethernet к Keenetic:<pre>
http://LAN-АДРЕС-РОУТЕРА:12121
</pre>Например, <code>http://192.168.10.1:12121</code>.

=== Снаружи (если хочется заходить из другой подсети) ===
В веб-интерфейсе Keenetic: '''Сетевые правила''' → '''Межсетевой экран''' → '''Ethernet-подключение''' → '''Добавить правило''':
{| class="wikitable"
!Поле
!Значение
|-
|Имя
|<code>keen-pbr WebUI</code>
|-
|Действие
|Разрешить
|-
|Протокол
|TCP
|-
|Порт назначения
|Один порт → <code>12121</code>
|-
|IP-адрес источника
|подсеть, из которой будете заходить (например, <code>192.168.1.0/24</code>)
|}
''(Скриншот: страница межсетевого экрана с добавленным правилом.)''

После этого UI доступен по адресу <code>http://WAN-IP-РОУТЕРА:12121</code>.

== 3.9. Настройка через веб-интерфейс ==
Откройте UI keen-pbr и убедитесь, что баннер про '''dnsmasq''' зелёный.

''(Скриншот: главная страница UI keen-pbr с зелёным статусом "dnsmasq исправен".)''

=== Шаг 1: Создать outbound (точку выхода в туннель) ===
В меню слева: '''Интернет''' → '''Outbounds (выходы)''' → кнопка '''Создать'''.

Заполните:
{| class="wikitable"
!Поле
!Значение
|-
|'''Tag'''
|<code>vpn</code> (или любое короткое имя)
|-
|'''Type'''
|<code>Interface</code>
|-
|'''Interface'''
|<code>singtun</code>
|-
|'''Gateway'''
|''оставить пустым''
|-
|'''Gateway IPv6'''
|''оставить пустым''
|}
Сохранить. В списке outbounds появится строка <code>vpn</code> со статусом '''healthy''' и активным интерфейсом.

''(Скриншот: форма создания outbound с заполненными полями.)''

=== Шаг 2: Создать список доменов ===
В меню слева: '''Правила трафика''' → '''Списки''' → '''Создать'''.

Заполните:
{| class="wikitable"
!Поле
!Значение
|-
|'''Name'''
|<code>bypass</code>
|-
|'''Source'''
|<code>Inline</code> (вкладка)
|-
|'''Domains'''
|вставьте список доменов, '''по одному на строку'''. Например:<pre>
example.com
streaming-service.net
another-site.org
</pre>
|}
<div style="padding: 10px 15px; margin: 10px 0; background-color: #d1ecf1; border-left: 4px solid #17a2b8; border-radius: 4px;">
'''Совет:''' В режиме Inline можно вставить тысячи строк сразу — поддержка большого списка предусмотрена. Один домен покрывает и сам сайт, и все его поддомены. Если вместо Inline хочется автоматическую подписку — выберите вариант '''URL''' и укажите адрес внешнего списка; keen-pbr будет обновлять его по расписанию.
</div>Сохранить.

''(Скриншот: форма создания списка с textarea, в которую вставлены домены.)''

=== Шаг 3: Создать правило маршрутизации ===
В меню слева: '''Правила трафика''' → '''Правила маршрутизации''' → '''Создать'''.

Заполните:
{| class="wikitable"
!Поле
!Значение
|-
|'''List(s)'''
|<code>bypass</code> (выбрать из выпадающего)
|-
|'''Outbound'''
|<code>vpn</code> (наш только что созданный)
|-
|'''Enabled'''
|включить
|}
Сохранить.

=== Шаг 4: Применить изменения ===
Внизу страницы появится кнопка '''«Применить и перезапустить»'''. Нажмите её — keen-pbr перестроит конфигурацию dnsmasq и применит новые правила маршрутизации.

''(Скриншот: страница "Правила маршрутизации" с активным правилом и кнопкой "Применить".)''

== 3.10. Тестирование ==
На клиентском устройстве, подключённом к Keenetic:

# '''Очистите кеш DNS''' (важно — без этого старые ответы остаются):
#* Windows: <code>ipconfig /flushdns</code> в PowerShell.
#* Android / iOS: переподключиться к Wi-Fi (off → on).
#* macOS: <code>sudo dscacheutil -flushcache</code>.
# Перезапустите браузер (у него свой DNS-кеш).
# Откройте сайт из списка.
# Параллельно откройте <code>https://api.ipify.org</code> в браузере. Адрес должен быть тот же, который вы видели в проверке туннеля sing-box (т.е. IP вашего VPN-провайдера, а не домашний WAN-IP).

''(Скриншот: страница api.ipify.org с подменённым IP.)''
----

= Этап 4. Установка nfqws2 =
nfqws2 — это userspace-демон, который через очередь NFQUEUE перехватывает первые пакеты соединений и модифицирует их так, чтобы DPI-фильтры не распознали трафик. Используется для обхода замедления сервисов потокового видео, голосовой связи и т.п. — '''без необходимости заворачивать их в туннель'''.

== 4.1. Подключение репозитория ==
<syntaxhighlight lang="bash">
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
</syntaxhighlight>

== 4.2. Установка пакета ==
<syntaxhighlight lang="bash">
opkg install nfqws2-keenetic
</syntaxhighlight>После установки сервис стартует автоматически — вмешательства не требуется.

=== Проверка ===
<syntaxhighlight lang="bash">
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>'''Ожидаемый результат:'''<pre>
Service NFQWS2 is running
</pre>

=== Что обрабатывается по умолчанию ===
В заводском конфиге работает режим <code>MODE_AUTO</code> — комбинация:
{| class="wikitable"
!Список
!Назначение
|-
|<code>/opt/etc/nfqws2/lists/user.list</code>
|Домены, для которых '''всегда''' применяется обход (по умолчанию ~280 строк: Google/YouTube/CDN сервисы).
|-
|<code>/opt/etc/nfqws2/lists/auto.list</code>
|Домены, которые nfqws2 '''сам обнаружил''' как замедленные/блокируемые. Заполняется автоматически.
|-
|<code>/opt/etc/nfqws2/lists/exclude.list</code>
|Домены, которые '''нельзя''' трогать (по умолчанию: домены KeeneticOS, чтобы не сломать облачные сервисы прошивки).
|}
Покрываемые протоколы: HTTPS (TCP/443), HTTP (TCP/80), QUIC (UDP/443), Discord voice, WireGuard handshake, STUN/TURN, Telegram MTProto.

== 4.3. (опционально) Веб-интерфейс ==
Для удобной работы со списками и стратегиями есть отдельный пакет с веб-UI.

=== Подключение repo ===
<syntaxhighlight lang="bash">
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
</syntaxhighlight>

=== Установка ===
<syntaxhighlight lang="bash">
opkg install nfqws-keenetic-web
</syntaxhighlight>Пакет потянет lighttpd + PHP 8 — общий размер около '''10 МБ'''. После установки лёгкий веб-сервер запустится автоматически.

=== Доступ ===
Веб-морда слушает на порту '''90''':<pre>
http://LAN-АДРЕС-РОУТЕРА:90
</pre>Для доступа из другой подсети — открыть порт <code>90</code> в фаерволе Keenetic (по аналогии с keen-pbr).

''(Скриншот: главная страница UI nfqws-keenetic-web.)''
----

= Финальная архитектура =
После завершения всех этапов на роутере работают четыре сервиса:
{| class="wikitable"
!Сервис
!Порт / Управление
!Что делает
|-
|'''sing-box'''
|TUN-интерфейс <code>singtun</code>; Clash API на <code>:9090</code>
|Шифрует и пересылает трафик в туннель
|-
|'''keen-pbr'''
|Web UI на <code>:12121</code>
|Решает, какой трафик отправить в туннель
|-
|'''nfqws2'''
|Демон, без отдельного порта (управление через файлы или nfqws-keenetic-web на <code>:90</code>)
|Обходит DPI-фильтры для прямого трафика
|-
|'''Entware OpenSSH'''
|TCP <code>:2022</code> (если настраивали) / <code>:222</code> dropbear
|Удалённое управление
|}
<pre>
K E E N E T I C Р О У Т Е Р
┌───────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ │
LAN│ │ DNS-запрос │ │
───┼──►│ от клиента │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ upstream ┌────────────────┐ │
│ │ keen-pbr │ через │ Cloudflare │ │
│ │ dnsmasq │ ─────────► │ / Quad9 │ │
│ │ на :53 │ │ │ │
│ └──────┬───────┘ └────────────────┘ │
│ │ IP → ipset │
│ │ │
│ ┌──────▼──────────────────────────────────────────────┐ │
LAN│ │ iptables / маршрутизация │ │
───┼──►│ ├ если dst-IP в ipset bypass: │ │
TCP│ │ │ fwmark → ip rule → table 151 → singtun │ │
│ │ │ │ │
│ │ └ иначе: │ │
│ │ обычный WAN-маршрут │ │
│ │ └ nfqws2 ловит первые пакеты │ │
│ │ и модифицирует для обхода DPI │ │
│ └────┬──────────────────────────────────────────┬─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌────────────────┐ │
│ │ singtun │ │ WAN-интерфейс │ │
│ │ (TUN) │ │ (ваш провайдер)│ │
│ └────┬────┘ └────────┬───────┘ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────┐ │ │
│ │ sing-box │ │ │
│ │ outbound: │ │ │
│ │ hysteria2 │ │ │
│ └──────┬──────┘ │ │
│ │ │ │
└──────────┼────────────────────────────────────────┼───────────────────────┘
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ VPN-узел │ │ Любой │
│ провайдера│ │ интернет │
└───────────┘ └───────────┘
</pre>''(Здесь можно перерисовать в Mermaid/Excalidraw для финальной картинки.)''
----

= Эксплуатация =

== Добавление новых доменов в список keen-pbr ==

# Открыть UI keen-pbr на <code>:12121</code>.
# '''Правила трафика''' → '''Списки''' → выбрать список <code>bypass</code> → '''Изменить'''.
# Добавить новые домены в textarea, '''Сохранить'''.
# Нажать '''«Применить и перезапустить»''' внизу страницы.

== Добавление новых доменов в список nfqws2 ==

=== Через файл ===
<syntaxhighlight lang="bash">
echo 'new-site.com' >> /opt/etc/nfqws2/lists/user.list
/opt/etc/init.d/S51nfqws2 restart
</syntaxhighlight>

=== Через веб-UI ===
Открыть <code>http://LAN-АДРЕС-РОУТЕРА:90</code>, секция работы со списками.

== Обновление компонентов ==
<syntaxhighlight lang="bash">
opkg update
opkg upgrade sing-box-go keen-pbr nfqws2-keenetic
</syntaxhighlight>После обновления может потребоваться перезапуск сервисов или роутера.

== Просмотр логов ==
{| class="wikitable"
!Сервис
!Команда
|-
|sing-box
|grep sing-box
|-
|keen-pbr
|grep keen-pbr + системный журнал в веб-UI Keenetic
|-
|nfqws2
|<code>tail -f /opt/var/log/nfqws2.log</code> (если включено логирование в конфиге)
|}
----

= Диагностика =

== Проверка статусов всех сервисов ==
<syntaxhighlight lang="bash">
/opt/etc/init.d/S99sing-box status
/opt/etc/init.d/S80keen-pbr status
/opt/etc/init.d/S51nfqws2 status
</syntaxhighlight>

== Проверка туннеля ==
<syntaxhighlight lang="bash">
# Через локальный mixed-proxy sing-box
curl -sS --socks5-hostname 192.168.10.1:7891 https://api.ipify.org

# Прямо через TUN (если интерфейс на роутере)
curl -sS --interface singtun https://api.ipify.org
</syntaxhighlight>

== Проверка DNS keen-pbr ==
<syntaxhighlight lang="bash">
nslookup example.com 127.0.0.1
</syntaxhighlight>Если получаете адрес из <code>198.18.x.x</code> — значит DNS-фильтр прошивки подменяет ответ. Замените upstream-DNS на публичные (см. этап 3.7).

== Проверка ipset и маршрутизации ==
<syntaxhighlight lang="bash">
# Какие IP уложены в bypass-список
ipset list kpbr4d_bypass | tail -20

# Маршрутная таблица куда идёт помеченный трафик
ip route show table 151
# Должна быть строка вида: default dev singtun scope link

# Помечает ли iptables пакеты
iptables -t mangle -L KeenPbrTable -n -v
# Счётчики MARK должны увеличиваться при тестовом запросе
</syntaxhighlight>

== Частые проблемы ==
{| class="wikitable"
!Симптом
!Причина
!Решение
|-
|У клиентов нет интернета совсем
|dnsmasq keen-pbr остановлен или поломан
|Откатить <code>opkg dns-override</code> через <code>192.168.1.1/a</code>:<pre>no opkg dns-override
system configuration save</pre>и перезагрузить роутер
|-
|Сайт из списка не открывается, но другие работают
|Старый DNS-кеш на клиенте
|<code>ipconfig /flushdns</code> + перезапуск браузера
|-
|<code>nslookup site.com 127.0.0.1</code> возвращает <code>198.18.x.x</code>
|DNS прошивки подменяет ответы
|Заменить upstream на <code>1.1.1.1</code> в <code>/opt/etc/keen-pbr/config.json</code>
|-
|keen-pbr UI показывает "dnsmasq недоступен"
|<code>/opt/etc/dnsmasq.conf</code> не содержит секцию <code>conf-script=...</code> keen-pbr
|Скопировать шаблон: <code>cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf</code>
|-
|Домены в списке резолвятся в реальный IP, но не открываются (таймаут)
|Нет NAT/FORWARD-правил для singtun
|Проверить наличие скрипта <code>/opt/etc/init.d/S81keen-pbr-fixup</code> и запустить его вручную
|-
|sing-box не стартует, в логе "no firewall backend"
|В PATH процесса нет <code>iptables</code>
|Запускать только через init-скрипт <code>/opt/etc/init.d/S99sing-box</code> (он сам задаёт PATH)
|-
|YouTube/Discord работают медленно или не работают
|nfqws2 не запущен или его правила не применены
|<code>/opt/etc/init.d/S51nfqws2 status</code> и при необходимости <code>restart</code>
|}
----

= Шпаргалка (все команды на одной странице) =
<syntaxhighlight lang="bash">
# === 1. ENTWARE (выполняется в командной строке Keenetic) ===
opkg disk ВАШ_ID_USB_ДИСКА:/ https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
system configuration save

# === 2. После SSH-входа на :222 ===
passwd # сменить пароль root

# === 3. sing-box ===
opkg update
opkg install sing-box-go
# Поместить рабочий config.json в /opt/etc/sing-box/
sing-box check -c /opt/etc/sing-box/config.json
/opt/etc/init.d/S99sing-box start

# === 4. keen-pbr ===
echo 'src/gz keen-pbr https://repo.keen-pbr.fyi/repository/stable/keenetic/current/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install keen-pbr
cp /opt/usr/lib/keen-pbr/dnsmasq.conf.template /opt/etc/dnsmasq.conf

# Через 192.168.1.1/a:
# opkg dns-override
# system configuration save
# system reboot

# Скрипт NAT/FORWARD:
cat > /opt/etc/init.d/S81keen-pbr-fixup << 'EOF'
#!/bin/sh
PATH=/opt/sbin:/opt/usr/sbin:/opt/bin:/opt/usr/bin:$PATH
TUN_IFACE=singtun
LAN_IFACE=br0
for i in 1 2 3 4 5 6 7 8 9 10; do
ip link show $TUN_IFACE >/dev/null 2>&1 && break
sleep 1
done
iptables -t nat -C POSTROUTING -o $TUN_IFACE -j MASQUERADE 2>/dev/null || iptables -t nat -A POSTROUTING -o $TUN_IFACE -j MASQUERADE
iptables -C FORWARD -i $LAN_IFACE -o $TUN_IFACE -j ACCEPT 2>/dev/null || iptables -I FORWARD 1 -i $LAN_IFACE -o $TUN_IFACE -j ACCEPT
iptables -C FORWARD -i $TUN_IFACE -o $LAN_IFACE -j ACCEPT 2>/dev/null || iptables -I FORWARD 1 -i $TUN_IFACE -o $LAN_IFACE -j ACCEPT
EOF
chmod +x /opt/etc/init.d/S81keen-pbr-fixup
/opt/etc/init.d/S81keen-pbr-fixup

# Замена DNS на 1.1.1.1/9.9.9.9 в /opt/etc/keen-pbr/config.json (см. этап 3.7)
/opt/etc/init.d/S80keen-pbr restart

# === 5. nfqws2 ===
echo 'src/gz nfqws2-keenetic https://nfqws.github.io/nfqws2-keenetic/mipsel' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws2-keenetic
# Уже запущен автоматически

# === 6. (опц) Веб-UI для nfqws2 ===
echo 'src/gz nfqws-keenetic-web https://nfqws.github.io/nfqws-keenetic-web/all' >> /opt/etc/opkg.conf
opkg update
opkg install nfqws-keenetic-web
</syntaxhighlight>
----<div style="padding: 10px 15px; margin: 10px 0; background-color: #d4edda; border-left: 4px solid #28a745; border-radius: 4px;">
'''Ссылки на проекты:'''

* Entware: <code>https://github.com/Entware/Entware</code>
* sing-box: <code>https://sing-box.sagernet.org</code> / <code>https://github.com/SagerNet/sing-box</code>
* keen-pbr: <code>https://keen-pbr.fyi</code> / <code>https://github.com/maksimkurb/keen-pbr</code>
* nfqws2-keenetic: <code>https://github.com/nfqws/nfqws2-keenetic</code>
* nfqws-keenetic-web: <code>https://github.com/nfqws/nfqws-keenetic-web</code>
* zapret (upstream): <code>https://github.com/bol-van/zapret</code>
</div>

Суверенный интернет

2026-05-12T07:04:25Z

Владимир:

Эта страница посвящается всему что связано с ограничим доступа в интернет.

На данный момент 20.04.26 мы имеем полную блокировку по белыми IP у операторов мобильной связи. И предпосылки к блокировкам на уровне провайдеров домашнего интернета.

* [[Обход НКР|Установка и настройка связки Zapret + Podkop на OpenWRT]]
* [[Hysteria 2 каскад]]
* [[Whitelist-bypass: VK Creator (headless на сервере) + Joiner (Android)]]
* [[Установка MTProto Proxy (mtg) на Linux-сервере]]
* [[VK Turn Proxy + FreeTurn + VLESS]]
* [[NaïveProxy: установка полной каскадной цепочки]]
* [[OlcRTC: туннель через WebRTC-сервисы|olcRTC: туннель через легальные WebRTC-сервисы]]
* [[mieru: каскадный шифрованный SOCKS5-туннель]]
* Гибкая маршрутизация и обход DPI на Keenetic (sing-box + keen-pbr + nfqws2)

Mieru: каскадный шифрованный SOCKS5-туннель

2026-05-10T20:22:09Z

Владимир: /* Поток данных в одиночном режиме */

= mieru: каскадный шифрованный SOCKS5-туннель с устойчивостью к классификации трафика =

== Введение ==

=== Что такое mieru ===
'''mieru''' (見える, «видимый») — это криптографически защищённый прокси-протокол, ориентированный на работу в средах с активным DPI и статистическим анализом сетевого трафика. В отличие от большинства современных туннелей, mieru '''не использует TLS''' и '''не маскируется под легитимный сайт'''. Вместо этого он подаёт на провод поток, который при пассивном анализе выглядит как случайные байты или произвольный текстовый протокол — без узнаваемых заголовков, фиксированных длин и характерных handshake-паттернов.

Программный пакет состоит из двух самостоятельных бинарников:
{| class="wikitable"
!Бинарник
!Роль
|-
|<code>mita</code>
|Серверная часть. Принимает зашифрованные соединения, аутентифицирует пользователей, переправляет полезную нагрузку наружу
|-
|<code>mieru</code>
|Клиентская часть. Поднимает локальный SOCKS5-прокси на машине пользователя; всё, что в него пришло, шифруется и отправляется на <code>mita</code>
|}

=== Когда применяется ===

* Канал между клиентом и обычными VPN-серверами проходит через инфраструктуру с DPI или ML-классификацией протоколов.
* Нужен альтернативный канал, не зависящий от валидного TLS-сертификата и собственного домена (mieru вообще не требует доменного имени).
* Нужна устойчивость к активному зондированию: сервер mieru, в отличие от REALITY-/Trojan-серверов, при попытке зондирования просто '''молчит''', не имитируя ни сайта-донора, ни TLS-handshake — нечего фингерпринтить.

=== Сравнение с другими методами туннелирования ===
{| class="wikitable"
!Метод
!Транспорт
!Маскировка
!Требует домен и TLS
!Устойчивость к ML-классификации
|-
|WireGuard
|UDP
|нет (явный WG)
|нет
|низкая
|-
|OpenVPN
|UDP/TCP
|нет
|опционально
|низкая
|-
|Shadowsocks-AEAD-2022
|TCP
|случайный шум
|нет
|средняя
|-
|VLESS + REALITY
|TCP (TLS)
|TLS-handshake чужого сайта
|да
|высокая (внутри пула TLS)
|-
|NaiveProxy
|TCP (HTTP/2)
|Chromium-стек, неотличим от HTTPS
|да
|высокая (внутри пула HTTPS)
|-
|Hysteria2
|UDP (QUIC)
|QUIC поверх UDP с маскировкой под HTTPS
|да
|высокая (внутри пула QUIC)
|-
|'''mieru'''
|'''TCP / UDP, без TLS'''
|'''случайный шум либо текстоподобный поток (через traffic pattern)'''
|'''нет — только пара логин/пароль'''
|'''высокая (специальная подгонка энтропии и ASCII)'''
|}
----

== Принципы работы ==

=== Поток данных в одиночном режиме ===
[[Файл:Mieru-single-flow.png|центр|685x685px|Поток данных одиночного mieru: клиент → SOCKS5 → mieru → шифр → mita → интернет]]
=== Каскадный режим (двухзвенный) ===
В каскаде роль обычного «сервера» выполняют два узла. Первый принимает клиентов и не выходит в интернет напрямую; вместо этого он переправляет уже расшифрованный трафик во второй узел через тот же протокол mieru. Второй узел осуществляет финальный egress.
[[Файл:Mieru-cascade-flow.png|центр|1010x1010px|Поток данных каскадного mieru: Сервер A (frontend) → Сервер B (backend) → egress]]
=== Зачем разделять frontend и backend ===

* Адрес backend-сервера никогда не виден клиентскому ПО. Если frontend замечен и заблокирован — backend остаётся неизвестным наблюдателям и переиспользуется со следующим frontend.
* Frontend хранит '''только''' учётки клиентов и не имеет финального egress. Компрометация его конфига не раскрывает финальный IP.
* Двойное шифрование mieru на каждом плече: каждый сегмент дважды проходит AEAD с разными ключами, что усложняет статистический анализ.

=== Шифрование и аутентификация ===
{| class="wikitable"
!Параметр
!Значение
|-
|Алгоритм
|XChaCha20-Poly1305 (AEAD) с 24-байтным nonce
|-
|Длина ключа
|32 байта
|-
|Метод выработки ключа
|PBKDF2-SHA256, 64 итерации, соль = SHA-256 от текущего времени, округлённого до 2 минут
|-
|Идентификатор пользователя в пакете
|Последние 4 байта nonce заменены на префикс SHA-256 от <code>username + nonce[0:16]</code>; имя пользователя на провод не передаётся
|-
|Защита от reuse
|Проверка nonce-кэша на серверной стороне; повторный пакет отбрасывается
|}
Ключ шифрования '''не передаётся''' через канал и нигде не хранится в виде сериализованной строки: он каждый раз генерируется на лету из пары логин+пароль и текущего времени. Из этого следует одно практическое требование, которое легко не заметить.

==== Требование к синхронизации часов ====
Расхождение системного времени клиента и сервера '''не должно превышать 4 минуты'''. При большем расхождении ключ, выработанный клиентом, не сойдётся с ключом сервера, и подключения будут '''молча''' падать (без явной ошибки в логах). На обоих серверах и на клиентском устройстве должен работать NTP-демон.

=== Формат сегмента ===
[[Файл:Mieru-segment-format.png|центр|984x984px|Формат сегмента mieru: padding, nonce, шифр-метаданные, шифр-полезная нагрузка]]Ключевое отличие от других протоколов: '''ВСЕ''' структурные поля сегмента (тип, размер, sequence number, ID сессии и пр.) находятся внутри поля <code>enc-meta</code> — то есть зашифрованы. Снаружи невозможно даже определить, что это за пакет, какой длины полезная нагрузка, в начале или в середине сессии находится клиент. Видны только три зоны паддинга и зашифрованные блобы.

=== Traffic pattern (опциональная подгонка маскировки) ===
mieru предоставляет два независимых механизма для подмены статистических признаков шифр-трафика на «обычные»:
{| class="wikitable"
!Опция
!Что делает
!Накладные расходы
|-
|<code>tcpFragment</code>
|Дробит TCP-пакеты на мелкие куски и вставляет случайную задержку между ними. Цель — сломать узнаваемость «один большой шифр-стрим»
| +латентность до <code>maxSleepMs</code> мс на каждый фрагмент
|-
|<code>nonce.NONCE_TYPE_PRINTABLE</code>
|Подменяет первые N байт nonce печатными ASCII-символами. Цель — увести классификатор «высокая энтропия от нулевого байта» в ложное «это текстовый протокол»
|почти ноль (только подмена байтов)
|-
|<code>nonce.NONCE_TYPE_FIXED</code>
|Подменяет первые байты nonce фиксированными hex-строками из списка. Цель — имитировать конкретный фиксированный заголовок
|ноль
|}
Включение traffic pattern имеет смысл '''только''' на видимом анализатором плече (клиент → frontend). На внутреннем плече каскада (frontend → backend) это лишний overhead.

=== Многопользовательский режим ===
Один сервер mita может обслуживать неограниченное число учёток одновременно. Каждый user — это пара <code>(name, password)</code>; лимит по числу одновременных сессий внутри одной учётки '''не задан в протоколе''' (можно опционально настраивать квоты по объёму трафика).
[[Файл:Mieru-multi-user.png|центр|958x958px|Многопользовательский режим: один сервер mita обслуживает несколько учёток одновременно]]Такая модель радикально отличается от mash-/torch-протоколов с архитектурой «один сервер — один пользователь»: вам '''не нужно''' создавать отдельный контейнер на каждого пользователя.
----

== Что должно быть на серверах перед установкой ==

=== Минимальная конфигурация каждого сервера ===
{| class="wikitable"
!№
!Требование
!Зачем
|-
|1
|Linux дистрибутив (Ubuntu 22.04+, Debian 12+, Fedora 38+ или сравнимый)
|Среда выполнения Docker
|-
|2
|SSH-доступ с правами <code>root</code> либо аккаунт с <code>sudo</code> без пароля
|Установка пакетов и управление контейнерами
|-
|3
|Docker Engine 24.0+ и плагин Docker Compose v2.20+
|Запуск контейнеров mita и mieru
|-
|4
|NTP-демон активен (<code>chrony</code> или <code>systemd-timesyncd</code>)
|Синхронизация часов в пределах 4 минут (см. раздел «Шифрование»)
|-
|5
|Открытый наружу TCP-диапазон (для нашей статьи — <code>2012-2022</code>)
|Принимающий порт mita
|}

=== Опциональная конфигурация: egress через сторонний прокси ===
По умолчанию backend-сервер выходит в интернет напрямую с публичного IP виртуальной машины. В качестве промежуточной цепочки часто используется выделенный SOCKS5-прокси, обслуживаемый сторонней панелью (например, '''3x-ui''' над xray-core).
{| class="wikitable"
!№
!Параметр
!Пример
!Комментарий
|-
|1
|SOCKS5-inbound, слушающий '''только на <code>172.17.0.1</code>''' (docker0-bridge gateway)
|порт <code>24366</code>
|Слушать на <code>127.0.0.1</code> '''не подойдёт''': контейнер mita с <code>network_mode: host</code> увидит нужный адрес именно как <code>172.17.0.1</code>
|-
|2
|Аутентификация на этом inbound отключена
|—
|Можно включить и прописать креды в <code>egress.proxies</code> mita, но без авторизации проще
|-
|3
|Routing-rule: трафик с этого inbound → нужный outbound (например, WireGuard-к-WARP, наружный VPN, сторонний прокси)
|—
|Зависит от вашей панели; в 3x-ui — раздел «Маршрутизация»
|}

==== Проверка egress-цепочки ====
Команда выполняется на самом backend-сервере. Заменить <code>24366</code> на ваш порт.<syntaxhighlight lang="bash">
docker run --rm curlimages/curl:latest --max-time 12 --socks5 172.17.0.1:24366 https://icanhazip.com
</syntaxhighlight>Ожидание: IP вашего egress-узла (например, IP Cloudflare WARP или IP стороннего VPN). Если возвращается публичный IP вашей VM — egress не работает, проверьте routing панели.

Если egress через сторонний прокси не нужен (готовы выходить с публичного IP backend-сервера) — пропустите этот раздел; в дальнейших шагах указания «без egress» помечены явно.
----

== Параметры, которые нужно подготовить заранее ==
Перед началом установки заполните таблицу собственными значениями. На каждом шаге, где встретится плейсхолдер, мы будем ссылаться на эту таблицу.
{| class="wikitable"
!Плейсхолдер
!Что это
!Пример
|-
|<code>YOUR_FRONTEND_HOST</code>
|Адрес frontend-сервера для SSH (IP, имя из <code>~/.ssh/config</code> либо домен)
|<code>198.51.100.10</code>
|-
|<code>YOUR_BACKEND_HOST</code>
|Адрес backend-сервера для SSH
|<code>203.0.113.20</code>
|-
|<code>YOUR_BACKEND_PUBLIC_IP</code>
|Публичный IP backend-сервера, к которому будет коннектиться mieru-client с frontend
|<code>203.0.113.20</code>
|-
|<code>YOUR_FRONTEND_PUBLIC_IP</code>
|Публичный IP frontend-сервера, к которому будут коннектиться клиенты
|<code>198.51.100.10</code>
|-
|<code>YOUR_BRIDGE_PASSWORD</code>
|Пароль учётки mieru, которой mieru-client на frontend подключается к mita на backend. Один на оба узла
|длинная случайная строка, сгенерированная <code>openssl rand</code>
|-
|<code>YOUR_CLIENT_PASSWORD</code>
|Пароль первой клиентской учётки <code>client01</code> на frontend
|длинная случайная строка
|-
|<code>YOUR_EGRESS_HOST</code>
|Адрес SOCKS5-egress на backend (если используете)
|<code>172.17.0.1</code>
|-
|<code>YOUR_EGRESS_PORT</code>
|Порт SOCKS5-egress
|<code>24366</code>
|}
Сохраните таблицу в надёжное место — особенно пароли. Без них восстановить рабочее состояние нельзя.
----

== Установка backend-сервера (точка выхода) ==
Все команды этого раздела выполняются на backend-сервере по SSH. Каждое пояснение — одна команда.

=== Шаг 1. Подключение по SSH ===
<syntaxhighlight lang="bash">
ssh root@YOUR_BACKEND_HOST
</syntaxhighlight>

=== Шаг 2. Проверка Docker ===
<syntaxhighlight lang="bash">
docker --version
</syntaxhighlight>Если выведено <code>Docker version 24.0.x</code> или новее — переходите к шагу 3. Если <code>command not found</code> — установите Docker по официальной инструкции для вашей ОС: <code>https://docs.docker.com/engine/install/</code>. После установки вернитесь сюда.

Дополнительно проверьте плагин Compose.<syntaxhighlight lang="bash">
docker compose version
</syntaxhighlight>

=== Шаг 3. Создание рабочего каталога ===
<syntaxhighlight lang="bash">
mkdir -p /opt/mieru-backend
</syntaxhighlight><syntaxhighlight lang="bash">
cd /opt/mieru-backend
</syntaxhighlight>

=== Шаг 4. Создание Dockerfile ===
Откройте файл для редактирования.<syntaxhighlight lang="bash">
nano /opt/mieru-backend/Dockerfile
</syntaxhighlight>Вставьте следующее содержимое полностью.<syntaxhighlight lang="dockerfile">
ARG MIERU_VERSION=3.32.0
ARG TARGETARCH=amd64

FROM alpine:3.19 AS downloader
ARG MIERU_VERSION
ARG TARGETARCH
RUN apk add --no-cache ca-certificates wget
WORKDIR /tmp/mita
RUN wget -qO- "https://github.com/enfein/mieru/releases/download/v${MIERU_VERSION}/mita_${MIERU_VERSION}_linux_${TARGETARCH}.tar.gz" | tar xz
WORKDIR /tmp/mieru
RUN wget -qO- "https://github.com/enfein/mieru/releases/download/v${MIERU_VERSION}/mieru_${MIERU_VERSION}_linux_${TARGETARCH}.tar.gz" | tar xz

FROM alpine:3.19
RUN apk add --no-cache ca-certificates tini && \
adduser -H -D -g "" mita && \
adduser -H -D -g "" mieru
COPY --from=downloader /tmp/mita/mita /usr/local/bin/mita
COPY --from=downloader /tmp/mieru/mieru /usr/local/bin/mieru
RUN chmod +x /usr/local/bin/mita /usr/local/bin/mieru && \
mkdir -p /etc/mita /var/lib/mita /var/run/mita \
/etc/mieru /var/lib/mieru /var/run/mieru /srv && \
chown -R mita:mita /etc/mita /var/lib/mita /var/run/mita && \
chown -R mieru:mieru /etc/mieru /var/lib/mieru /var/run/mieru
COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
ENTRYPOINT ["/sbin/tini","--","/usr/local/bin/docker-entrypoint.sh"]
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

=== Шаг 5. Создание скрипта-entrypoint ===
<syntaxhighlight lang="bash">
nano /opt/mieru-backend/docker-entrypoint.sh
</syntaxhighlight>Вставьте полное содержимое.<syntaxhighlight lang="bash">
#!/bin/sh
set -eu

MODE="${MIERU_MODE:-mita}"
CONFIG_FILE="${MIERU_CONFIG:-/srv/config.json}"

case "$MODE" in
mita) BIN=mita ;;
mieru) BIN=mieru ;;
*) echo "[entrypoint] FATAL: MIERU_MODE='$MODE' (mita или mieru)"; exit 1 ;;
esac

if [ ! -f "$CONFIG_FILE" ]; then
echo "[entrypoint] WARN: $CONFIG_FILE не найден"
fi

if [ "$MODE" = "mieru" ]; then
if [ -f "$CONFIG_FILE" ]; then
mieru apply config "$CONFIG_FILE" 2>&1
fi
exec mieru run
else
apply_via_rpc() {
i=0
while [ "$i" -lt 30 ]; do
i=$((i+1)); sleep 1
if [ -f "$CONFIG_FILE" ] && mita apply config "$CONFIG_FILE" >/tmp/apply.out 2>&1; then
mita start >/tmp/start.out 2>&1
return 0
fi
done
}
apply_via_rpc &
exec mita run
fi
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

Дайте файлу права на исполнение.<syntaxhighlight lang="bash">
chmod +x /opt/mieru-backend/docker-entrypoint.sh
</syntaxhighlight>

=== Шаг 6. Генерация пароля для bridge-учётки ===
<syntaxhighlight lang="bash">
openssl rand -base64 24 | tr -d '=/+' | head -c 31
</syntaxhighlight>Команда выведет одну строку из 31 символа. Скопируйте её и впишите в подготовленную таблицу как <code>YOUR_BRIDGE_PASSWORD</code>. Этот же пароль понадобится на frontend-сервере (шаг ниже).

=== Шаг 7. Создание серверного конфига ===
<syntaxhighlight lang="bash">
nano /opt/mieru-backend/server.json
</syntaxhighlight>Вставьте содержимое и замените <code>YOUR_BRIDGE_PASSWORD</code> на скопированное значение из шага 6.

Если вы '''используете''' egress через сторонний SOCKS5-прокси — оставьте секцию <code>egress</code> как есть и при необходимости подправьте <code>host</code> и <code>port</code>. Если '''не используете''' — удалите всю секцию <code>egress</code> от открывающей до закрывающей фигурной скобки.<syntaxhighlight lang="json">
{
"portBindings": [
{"portRange": "2012-2022", "protocol": "TCP"}
],
"users": [
{"name": "frontend-bridge", "password": "YOUR_BRIDGE_PASSWORD"}
],
"loggingLevel": "INFO",
"mtu": 1380,
"egress": {
"proxies": [
{
"name": "external-egress",
"protocol": "SOCKS5_PROXY_PROTOCOL",
"host": "172.17.0.1",
"port": 24366
}
],
"rules": [
{
"ipRanges": ["*"],
"domainNames": ["*"],
"action": "PROXY",
"proxyNames": ["external-egress"]
}
]
}
}
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

Защитите файл (содержит пароль).<syntaxhighlight lang="bash">
chmod 600 /opt/mieru-backend/server.json
</syntaxhighlight>

=== Шаг 8. Создание docker-compose.yml ===
<syntaxhighlight lang="bash">
nano /opt/mieru-backend/docker-compose.yml
</syntaxhighlight>Вставьте.<syntaxhighlight lang="yaml">
services:
mita:
build:
context: .
args:
MIERU_VERSION: "3.32.0"
image: mieru-bundle:3.32.0
container_name: mita-backend
restart: unless-stopped
network_mode: host
environment:
MIERU_MODE: mita
MIERU_CONFIG: /srv/server.json
volumes:
- ./server.json:/srv/server.json:ro
- mita-state:/etc/mita
- mita-runtime:/var/run/mita
- mita-data:/var/lib/mita
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"

volumes:
mita-state:
mita-runtime:
mita-data:
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

=== Шаг 9. Сборка образа ===
<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml build
</syntaxhighlight>Сборка длится 1–3 минуты. По завершении выводится <code>Image mieru-bundle:3.32.0 Built</code>.

=== Шаг 10. Запуск ===
<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml up -d
</syntaxhighlight>Подождите 10 секунд.<syntaxhighlight lang="bash">
sleep 10
</syntaxhighlight>Проверьте логи.<syntaxhighlight lang="bash">
docker logs mita-backend --tail 25
</syntaxhighlight>Ожидаемые строки:
[entrypoint] config применён (/srv/server.json)
[entrypoint] mita start: OK
mita server status is "RUNNING"
Проверьте, что сервер слушает порты <code>2012-2022</code>.<syntaxhighlight lang="bash">
ss -tlnp | grep -E ':20(1[2-9]|2[012]) '
</syntaxhighlight>Должны появиться 11 строк со статусом <code>LISTEN</code> и пользователем <code>mita</code>. Если их нет — обратитесь к разделу «Поиск проблем».
----

== Установка frontend-сервера (точка входа) ==
Все команды этого раздела выполняются на frontend-сервере по SSH.

=== Шаг 1. Подключение и подготовка ===
<syntaxhighlight lang="bash">
ssh root@YOUR_FRONTEND_HOST
</syntaxhighlight><syntaxhighlight lang="bash">
mkdir -p /opt/mieru-frontend && cd /opt/mieru-frontend
</syntaxhighlight>

=== Шаг 2. Dockerfile и entrypoint (одинаковые с backend) ===
Создайте оба файла так же, как на backend-сервере (см. шаги 4–5 раздела «Установка backend-сервера»). Содержимое идентично — образ универсальный, режим работы выбирается переменной окружения.<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/Dockerfile
</syntaxhighlight>(вставьте тот же Dockerfile, что на backend)<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/docker-entrypoint.sh
</syntaxhighlight>(вставьте тот же entrypoint)<syntaxhighlight lang="bash">
chmod +x /opt/mieru-frontend/docker-entrypoint.sh
</syntaxhighlight>

=== Шаг 3. Генерация пароля первой клиентской учётки ===
<syntaxhighlight lang="bash">
openssl rand -base64 24 | tr -d '=/+' | head -c 31
</syntaxhighlight>Скопируйте результат и впишите в таблицу как <code>YOUR_CLIENT_PASSWORD</code>. Это пароль учётки <code>client01</code>, который вы потом отдадите своему первому клиентскому устройству.

=== Шаг 4. Серверный конфиг (mita-frontend) ===
<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/server.json
</syntaxhighlight>Замените <code>YOUR_CLIENT_PASSWORD</code> на значение из шага 3.<syntaxhighlight lang="json">
{
"portBindings": [
{"portRange": "2012-2022", "protocol": "TCP"}
],
"users": [
{"name": "client01", "password": "YOUR_CLIENT_PASSWORD"}
],
"loggingLevel": "INFO",
"mtu": 1380,
"trafficPattern": {
"unlockAll": false,
"tcpFragment": {"enable": true, "maxSleepMs": 10},
"nonce": {
"type": "NONCE_TYPE_PRINTABLE",
"minLen": 6,
"maxLen": 8
}
},
"egress": {
"proxies": [
{
"name": "to-backend",
"protocol": "SOCKS5_PROXY_PROTOCOL",
"host": "127.0.0.1",
"port": 1080
}
],
"rules": [
{
"ipRanges": ["*"],
"domainNames": ["*"],
"action": "PROXY",
"proxyNames": ["to-backend"]
}
]
}
}
</syntaxhighlight>Сохраните и защитите файл.<syntaxhighlight lang="bash">
chmod 600 /opt/mieru-frontend/server.json
</syntaxhighlight>

=== Шаг 5. Клиентский конфиг (mieru-client) ===
<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/client.json
</syntaxhighlight>Замените <code>YOUR_BACKEND_PUBLIC_IP</code> на публичный IP backend-сервера, <code>YOUR_BRIDGE_PASSWORD</code> — на пароль bridge-учётки, который вы создавали на backend в шаге 6.<syntaxhighlight lang="json">
{
"profiles": [
{
"profileName": "default",
"user": {
"name": "frontend-bridge",
"password": "YOUR_BRIDGE_PASSWORD"
},
"servers": [
{
"ipAddress": "YOUR_BACKEND_PUBLIC_IP",
"portBindings": [
{"portRange": "2012-2022", "protocol": "TCP"}
]
}
],
"mtu": 1380,
"multiplexing": {"level": "MULTIPLEXING_HIGH"},
"handshakeMode": "HANDSHAKE_NO_WAIT"
}
],
"activeProfile": "default",
"rpcPort": 8964,
"socks5Port": 1080,
"loggingLevel": "INFO",
"socks5ListenLAN": false,
"httpProxyListenLAN": false
}
</syntaxhighlight>Сохраните и защитите файл.<syntaxhighlight lang="bash">
chmod 600 /opt/mieru-frontend/client.json
</syntaxhighlight>

=== Шаг 6. docker-compose.yml на frontend ===
<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/docker-compose.yml
</syntaxhighlight>Вставьте.<syntaxhighlight lang="yaml">
services:
mieru-client:
build:
context: .
args:
MIERU_VERSION: "3.32.0"
image: mieru-bundle:3.32.0
container_name: mieru-client
restart: unless-stopped
network_mode: host
environment:
MIERU_MODE: mieru
MIERU_CONFIG: /srv/client.json
volumes:
- ./client.json:/srv/client.json:ro
- mieru-client-state:/etc/mieru
- mieru-client-runtime:/var/run/mieru
- mieru-client-data:/var/lib/mieru
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"

mita:
image: mieru-bundle:3.32.0
container_name: mita-frontend
restart: unless-stopped
network_mode: host
depends_on:
- mieru-client
environment:
MIERU_MODE: mita
MIERU_CONFIG: /srv/server.json
volumes:
- ./server.json:/srv/server.json:ro
- mita-state:/etc/mita
- mita-runtime:/var/run/mita
- mita-data:/var/lib/mita
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"

volumes:
mieru-client-state:
mieru-client-runtime:
mieru-client-data:
mita-state:
mita-runtime:
mita-data:
</syntaxhighlight>Сохраните.

=== Шаг 7. Сборка и запуск ===
<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-frontend/docker-compose.yml build
</syntaxhighlight><syntaxhighlight lang="bash">
docker compose -f /opt/mieru-frontend/docker-compose.yml up -d
</syntaxhighlight><syntaxhighlight lang="bash">
sleep 12
</syntaxhighlight>

=== Шаг 8. Проверка ===
<syntaxhighlight lang="bash">
docker logs mieru-client --tail 10
</syntaxhighlight>Должна быть строка <code>mieru: config применён</code> и затем <code>запуск mieru run</code>.<syntaxhighlight lang="bash">
docker logs mita-frontend --tail 10
</syntaxhighlight>Должно быть <code>RUNNING</code> и <code>mita start: OK</code>.<syntaxhighlight lang="bash">
docker exec mieru-client mieru status
</syntaxhighlight>Ожидание: <code>mieru client is running</code>.<syntaxhighlight lang="bash">
docker exec mita-frontend mita status
</syntaxhighlight>Ожидание: <code>mita server status is "RUNNING"</code>.

=== Шаг 9. Сквозной тест каскада ===
С frontend-сервера обратитесь во внешний интернет через локальный SOCKS5 mieru-client. Это эквивалент того, как пойдёт реальный клиентский запрос.<syntaxhighlight lang="bash">
curl -sS --max-time 30 --proxy socks5h://127.0.0.1:1080 https://icanhazip.com
</syntaxhighlight>Ожидание: IP вашего egress-узла. Например, IP Cloudflare WARP, если на backend настроен такой outbound. Команда '''не должна''' возвращать публичный IP frontend-сервера.

Контрольный замер прямого IP frontend для сравнения.<syntaxhighlight lang="bash">
curl -sS --max-time 5 https://icanhazip.com
</syntaxhighlight>Если первый IP отличается от второго — каскад работает.
----

== Подключение клиентов ==
mieru имеет два равнозначных формата отдачи параметров клиенту: '''Clash/Mihomo YAML''' и '''<code>mierus://</code> URI'''. На практике YAML более переносим — его понимает большинство клиентов в одном виде, тогда как URI разбирается каждым приложением по-своему.

=== Десктоп: Clash Verge Rev / Mihomo Party / NekoBox ===
Создайте новый профиль (или отредактируйте существующий) и добавьте блок <code>proxies</code>:<syntaxhighlight lang="yaml">
proxies:
- name: mieru-frontend
type: mieru
server: YOUR_FRONTEND_PUBLIC_IP
port: 2022
username: client01
password: YOUR_CLIENT_PASSWORD
multiplexing: MULTIPLEXING_HIGH
</syntaxhighlight>Параметр <code>port: 2022</code> — это один из портов из диапазона <code>2012-2022</code>; mita слушает все 11 параллельно, клиент использует один (мультиплексор).

=== Мобильные: Karing / ClashMi / NekoBox+plugin / husi ===
Подключение через тот же YAML-блок выше — большинство клиентов поддерживают вставку YAML вручную в раздел «Серверы» или «Outbounds». Сценарий импорта URI в Karing 1.2.x работает плохо (поле порта обнуляется), поэтому YAML предпочтительнее.

=== Универсальный URI-формат ===
<syntaxhighlight>
mierus://client01:YOUR_CLIENT_PASSWORD@YOUR_FRONTEND_PUBLIC_IP?port=2022&protocol=TCP&mtu=1380&multiplexing=MULTIPLEXING_HIGH&handshake-mode=HANDSHAKE_NO_WAIT
</syntaxhighlight>Подходит для нативного <code>mieru</code> CLI, husi с mieru-плагином, Exclave.
----

== Подключение клиента на OpenWrt-роутере ==
Если на роутере уже стоит трафик-менеджер (например, podkop), и вы хотите, чтобы он отправлял трафик через mieru — поставьте на роутер standalone mieru-клиент с локальным SOCKS5, и подкоп цепляйте к этому SOCKS5.

=== Шаг 1. Подключение к роутеру ===
<syntaxhighlight lang="bash">
ssh root@YOUR_ROUTER_HOST
</syntaxhighlight>

=== Шаг 2. Скачивание бинаря ===
Архитектура роутера большинства современных моделей — <code>aarch64</code>. Если ваш роутер — другой (например, <code>mips</code>), проверьте список релизов <code>https://github.com/enfein/mieru/releases/latest</code> и подставьте нужный артефакт в команду.<syntaxhighlight lang="bash">
cd /tmp && wget -q https://github.com/enfein/mieru/releases/download/v3.32.0/mieru_3.32.0_linux_arm64.tar.gz -O mieru.tar.gz
</syntaxhighlight><syntaxhighlight lang="bash">
tar xzf mieru.tar.gz && mv mieru /usr/bin/mieru && chmod +x /usr/bin/mieru && rm -f /tmp/mieru.tar.gz /tmp/LICENSE /tmp/README.md
</syntaxhighlight><syntaxhighlight lang="bash">
/usr/bin/mieru version
</syntaxhighlight>Должно вывести <code>3.32.0</code>.

=== Шаг 3. Клиентский конфиг ===
<syntaxhighlight lang="bash">
nano /etc/mieru_client_config.json
</syntaxhighlight>Вставьте, заменив плейсхолдеры:<syntaxhighlight lang="json">
{
"profiles": [
{
"profileName": "default",
"user": {
"name": "client01",
"password": "YOUR_CLIENT_PASSWORD"
},
"servers": [
{
"ipAddress": "YOUR_FRONTEND_PUBLIC_IP",
"portBindings": [
{"portRange": "2012-2022", "protocol": "TCP"}
]
}
],
"mtu": 1380,
"multiplexing": {"level": "MULTIPLEXING_HIGH"},
"handshakeMode": "HANDSHAKE_NO_WAIT",
"trafficPattern": {
"unlockAll": false,
"tcpFragment": {"enable": true, "maxSleepMs": 10},
"nonce": {
"type": "NONCE_TYPE_PRINTABLE",
"minLen": 6,
"maxLen": 8
}
}
}
],
"activeProfile": "default",
"rpcPort": 8964,
"socks5Port": 1090,
"loggingLevel": "ERROR",
"socks5ListenLAN": false,
"httpProxyListenLAN": false
}
</syntaxhighlight>Сохраните и защитите файл.<syntaxhighlight lang="bash">
chmod 600 /etc/mieru_client_config.json
</syntaxhighlight>Ключевые отличия конфига для роутера от десктопного клиента:

* <code>socks5Port: 1090</code> — порт <code>1080</code> часто занят другими прокси (например, naive); 1090 свободен.
* <code>loggingLevel: "ERROR"</code> — overlay на роутерах маленький, ограничение логов защищает от заполнения диска.
* <code>trafficPattern</code> включён полностью — на пути «роутер → frontend» классификатор смотрит, маскировка нужна.

=== Шаг 4. Init.d-скрипт ===
OpenWrt использует procd; в отличие от mita, на OpenWrt mieru читает JSON-конфиг напрямую через переменную <code>MIERU_CONFIG_JSON_FILE</code>, и команды <code>mieru apply config</code> и <code>mieru describe config</code> '''не используются'''.<syntaxhighlight lang="bash">
nano /etc/init.d/mieru
</syntaxhighlight>Вставьте.<syntaxhighlight lang="bash">
#!/bin/sh /etc/rc.common

START=99
STOP=01

MIERU_BIN="/usr/bin/mieru"
MIERU_CONFIG="/etc/mieru_client_config.json"
PID_FILE="/var/run/mieru.pid"

start() {
echo "Starting mieru client..."
export MIERU_CONFIG_JSON_FILE=$MIERU_CONFIG
start-stop-daemon -S -b -m -p "$PID_FILE" -x "$MIERU_BIN" -- run
RC=$?
if [ $RC -eq 0 ]; then
echo "mieru client is started"
exit 0
else
echo "failed to start mieru client"
exit $RC
fi
}

stop() {
echo "Stopping mieru client..."
start-stop-daemon -K -p "$PID_FILE"
RC=$?
if [ $RC -eq 0 ]; then
echo "mieru client is stopped"
rm -f "$PID_FILE"
else
echo "failed to stop mieru client"
fi
}
</syntaxhighlight>Сохраните и сделайте исполняемым.<syntaxhighlight lang="bash">
chmod +x /etc/init.d/mieru
</syntaxhighlight>

=== Шаг 5. Запуск и автозапуск ===
<syntaxhighlight lang="bash">
/etc/init.d/mieru enable
</syntaxhighlight><syntaxhighlight lang="bash">
/etc/init.d/mieru start
</syntaxhighlight>

=== Шаг 6. Проверка ===
<syntaxhighlight lang="bash">
ps | grep mieru | grep -v grep
</syntaxhighlight>Должна быть одна строка с процессом <code>/usr/bin/mieru run</code>.<syntaxhighlight lang="bash">
netstat -tlnp 2>/dev/null | grep 1090
</syntaxhighlight>Должна быть строка <code>127.0.0.1:1090 ... LISTEN ... mieru</code>.<syntaxhighlight lang="bash">
curl -sS --max-time 30 -x socks5h://127.0.0.1:1090 https://icanhazip.com
</syntaxhighlight>Должен вернуть IP egress-узла каскада.

=== Шаг 7. Подключение podkop к локальному mieru ===
В LuCI откройте подкоп. Создайте новую секцию или измените существующую:
{| class="wikitable"
!Поле
!Значение
|-
|Тип конфига
|URL
|-
|Proxy string
|<code>socks5://127.0.0.1:1090</code>
|}
Эквивалент через <code>uci</code>:<syntaxhighlight lang="bash">
uci set podkop.10=section
uci set podkop.10.connection_type='proxy'
uci set podkop.10.proxy_config_type='url'
uci set podkop.10.proxy_string='socks5://127.0.0.1:1090'
uci commit podkop
service podkop restart
</syntaxhighlight>Подкоп отправляет mieru-серверу обычный SOCKS5-запрос на <code>127.0.0.1:1090</code>; mieru шифрует его и отправляет через каскад.
----

== Управление пользователями: скрипт <code>mieru-users.sh</code> ==

=== Зачем он нужен ===
mita-сервер хранит список учёток в файле <code>server.json</code>. Чтобы добавлять/удалять/смотреть пользователей вручную каждый раз — много шагов: jq-правка JSON, вызов <code>mita apply config</code>, генерация ссылки клиенту, опционально <code>mita delete user</code> для разрыва активных сессий. Скрипт <code>mieru-users.sh</code> автоматизирует это всё.

=== Что делает скрипт ===
{| class="wikitable"
!Пункт меню
!Действие
|-
|1. Список пользователей
|Чтение <code>server.json</code> + опрос <code>mita get connections</code> для активных сессий
|-
|2. Добавить пользователя
|Запрос имени, генерация пароля через <code>openssl rand</code>, бэкап JSON, <code>jq</code>-вставка, <code>mita apply config</code>, выдача готовых YAML и URI клиенту
|-
|3. Удалить пользователя
|<code>mita delete user</code> для разрыва сессий → <code>jq</code>-удаление из JSON → <code>apply config</code>
|-
|4. Показать URI клиента
|Сборка YAML и URI по выбранному имени
|-
|5. Статус сервера
|<code>mita status</code> + <code>get connections</code> + <code>get metrics</code>
|}

=== Установка скрипта ===
Все команды выполняются на frontend-сервере по SSH.

==== Шаг 1. Загрузка скрипта ====
<syntaxhighlight lang="bash">
nano /usr/local/bin/mieru-users.sh
</syntaxhighlight>Вставьте полное содержимое скрипта (исходный код в спойлере «Исходный код <code>mieru-users.sh</code>» в конце статьи).

Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

==== Шаг 2. Подстановка реального адреса ====
В начале скрипта есть строка <code>SERVER_IP="YOUR_FRONTEND_PUBLIC_IP"</code>. Замените её на реальный IP frontend-сервера.<syntaxhighlight lang="bash">
sed -i 's/YOUR_FRONTEND_PUBLIC_IP/198.51.100.10/' /usr/local/bin/mieru-users.sh
</syntaxhighlight>(подставьте свой IP вместо <code>198.51.100.10</code>).

==== Шаг 3. Права на исполнение ====
<syntaxhighlight lang="bash">
chmod +x /usr/local/bin/mieru-users.sh
</syntaxhighlight>

==== Шаг 4. Проверка ====
<syntaxhighlight lang="bash">
bash -n /usr/local/bin/mieru-users.sh && echo OK
</syntaxhighlight>Если выводит <code>OK</code> — скрипт установлен корректно.

=== Использование ===
<syntaxhighlight lang="bash">
sudo bash /usr/local/bin/mieru-users.sh
</syntaxhighlight>Появится меню:<pre>
╔══════════════════════════════════════╗
║ mieru User Manager ║
║ IP: 198.51.100.10 ║
╚══════════════════════════════════════╝

Пользователей в конфиге: 1

1. Список пользователей и активных сессий
2. Добавить пользователя
3. Удалить пользователя
4. Показать URI клиента
5. Статус сервера
0. Выход
</pre>После добавления пользователя скрипт выводит готовые конфиги:<pre>
=== Вариант 1: Clash / Mihomo YAML (рекомендую) ===
proxies:
- name: mieru-RU-alice
type: mieru
server: 198.51.100.10
port: 2022
username: alice
password: <автогенерированный>
multiplexing: MULTIPLEXING_HIGH

=== Вариант 2: mierus:// URI ===
mierus://alice:<пароль>@198.51.100.10?port=2022&protocol=TCP&mtu=1380&multiplexing=MULTIPLEXING_HIGH&handshake-mode=HANDSHAKE_NO_WAIT
</pre>
----

== Команды управления ==

=== На обоих серверах ===
Посмотреть логи в реальном времени.<syntaxhighlight lang="bash">
docker logs -f mita-backend # на backend
</syntaxhighlight><syntaxhighlight lang="bash">
docker logs -f mita-frontend mieru-client # на frontend
</syntaxhighlight>Перезапустить.<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml restart # на backend
</syntaxhighlight><syntaxhighlight lang="bash">
docker compose -f /opt/mieru-frontend/docker-compose.yml restart # на frontend
</syntaxhighlight>Остановить.<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml down # на backend
</syntaxhighlight><syntaxhighlight lang="bash">
docker compose -f /opt/mieru-frontend/docker-compose.yml down # на frontend
</syntaxhighlight>Обновить версию mita/mieru. Поменяйте <code>3.32.0</code> на нужную в <code>docker-compose.yml</code> и пересоберите.<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml build && docker compose -f /opt/mieru-backend/docker-compose.yml up -d
</syntaxhighlight>

=== Команды mita через CLI (внутри контейнера) ===
<syntaxhighlight lang="bash">
docker exec mita-backend mita status # IDLE / RUNNING
</syntaxhighlight><syntaxhighlight lang="bash">
docker exec mita-backend mita get users # список user'ов и их статистика
</syntaxhighlight><syntaxhighlight lang="bash">
docker exec mita-backend mita get connections # активные сессии
</syntaxhighlight><syntaxhighlight lang="bash">
docker exec mita-backend mita get metrics # метрики
</syntaxhighlight><syntaxhighlight lang="bash">
docker exec mita-backend mita describe config # текущий применённый конфиг
</syntaxhighlight>

=== На OpenWrt-роутере ===
<syntaxhighlight lang="bash">
/etc/init.d/mieru start | stop | restart
</syntaxhighlight><syntaxhighlight lang="bash">
ps | grep mieru | grep -v grep
</syntaxhighlight><syntaxhighlight lang="bash">
logread | grep mieru
</syntaxhighlight>
----

== Поиск проблем ==

=== Симптом: сервер показывает <code>IDLE</code>, порты не слушаются ===
mita после <code>apply config</code> остаётся в <code>IDLE</code> до явной команды <code>mita start</code>. В нашем entrypoint это происходит автоматически, но если что-то пошло не так, выполните вручную внутри контейнера:<syntaxhighlight lang="bash">
docker exec mita-backend mita start
</syntaxhighlight>

=== Симптом: <code>FATAL: getUid("mita") failed</code> ===
В образ не добавлен системный пользователь <code>mita</code>. Проверьте, что Dockerfile содержит строки <code>adduser -H -D -g "" mita</code> и <code>adduser -H -D -g "" mieru</code>, пересоберите образ.

=== Симптом: клиент подключается, но трафик не идёт ===
Проверьте на клиенте время системы. Расхождение более 4 минут с сервером приведёт к молчаливому отказу. Команда на Linux/macOS:<syntaxhighlight lang="bash">
date -u
</syntaxhighlight>Если время существенно расходится — настройте NTP.

=== Симптом: на frontend curl возвращает не egress-IP, а frontend-IP ===
Trafic идёт мимо mieru-client. Возможные причины:

* <code>egress.action</code> в frontend-конфиге — <code>DIRECT</code> вместо <code>PROXY</code>.
* mieru-client не запущен либо упал. Проверьте: <code>docker ps</code>.
* Backend не доступен. Проверьте на frontend: <code>nc -vz YOUR_BACKEND_PUBLIC_IP 2022</code>.

=== Симптом: на frontend curl возвращает frontend-IP, а должен — backend-IP ===
То же самое, что выше: трафик не доходит до backend. Дополнительно посмотрите логи:<syntaxhighlight lang="bash">
docker logs mieru-client --tail 50
</syntaxhighlight>Ошибки <code>TLS handshake</code> здесь невозможны — mieru не использует TLS. Ищите <code>auth failed</code> (неверная пара логин/пароль на mita-backend) и <code>connection refused</code> (backend не слушает).

=== Симптом: на роутере Karing/Clash подключается, но трафик не идёт ===
В первую очередь проверить YAML-конфиг: тип <code>type: mieru</code> (не <code>type: socks5</code>!), порт <code>port: 2022</code> (одиночное число, не диапазон). Многие mihomo-форки не парсят диапазон портов корректно.
----

== Исходный код <code>mieru-users.sh</code> ==
Полный текст скрипта приведён ниже. Скопируйте его целиком в <code>/usr/local/bin/mieru-users.sh</code> на frontend-сервере по инструкции выше.<syntaxhighlight lang="bash">
#!/bin/bash
# mieru-users — управление пользователями mita
# Источник истины: /opt/mieru-frontend/server.json
# Применение через mita apply config (RPC к работающему daemon).

CONFIG_FILE="/opt/mieru-frontend/server.json"
COMPOSE_DIR="/opt/mieru-frontend"
COMPOSE_SVC="mita"
BACKUP_DIR="/opt/mieru-frontend/backups"
BACKUP_KEEP=10
SERVER_IP="YOUR_FRONTEND_PUBLIC_IP"

RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'
CYAN='\033[0;36m'; BOLD='\033[1m'; NC='\033[0m'

check_root() {
if [[ $EUID -ne 0 ]]; then
echo -e "${RED}Запусти от root: sudo bash mieru-users.sh${NC}"; exit 1
fi
}

check_deps() {
for c in jq docker openssl; do
if ! command -v "$c" >/dev/null 2>&1; then
echo -e "${RED}Не найдено: $c${NC}"; exit 1
fi
done
if [[ ! -f "$CONFIG_FILE" ]]; then
echo -e "${RED}Не найден $CONFIG_FILE${NC}"; exit 1
fi
}

mita_cli() {
docker compose -f "$COMPOSE_DIR/docker-compose.yml" exec -T "$COMPOSE_SVC" mita "$@"
}

backup_config() {
mkdir -p "$BACKUP_DIR"
local stamp; stamp=$(date +%Y%m%d-%H%M%S)
cp "$CONFIG_FILE" "$BACKUP_DIR/server-$stamp.json"
ls -1t "$BACKUP_DIR"/server-*.json 2>/dev/null | tail -n +$((BACKUP_KEEP+1)) | xargs -r rm -f
}

apply_config() {
if ! mita_cli apply config /srv/server.json 2>&1; then
echo -e "${RED}mita apply config упал. Откатываюсь к последнему бэкапу.${NC}"
local last; last=$(ls -1t "$BACKUP_DIR"/server-*.json 2>/dev/null | head -1)
if [[ -n "$last" ]]; then
cp "$last" "$CONFIG_FILE"
mita_cli apply config /srv/server.json >/dev/null 2>&1 || true
fi
return 1
fi
return 0
}

press_enter() { echo ""; read -rp "Enter для возврата..."; }

generate_password() {
openssl rand -base64 24 | tr -d '=/+' | head -c 31
}

generate_uri() {
echo "mierus://${1}:${2}@${SERVER_IP}?port=2022&protocol=TCP&mtu=1380&multiplexing=MULTIPLEXING_HIGH&handshake-mode=HANDSHAKE_NO_WAIT"
}

generate_yaml() {
cat <<EOF
proxies:
- name: mieru-${1}
type: mieru
server: ${SERVER_IP}
port: 2022
username: ${1}
password: ${2}
multiplexing: MULTIPLEXING_HIGH
EOF
}

print_uri_for() {
echo ""
echo -e "${CYAN}=== Вариант 1: Clash / Mihomo YAML ===${NC}"
echo -e "${BOLD}$(generate_yaml "$1" "$2")${NC}"
echo ""
echo -e "${CYAN}=== Вариант 2: mierus:// URI ===${NC}"
echo -e "${BOLD} $(generate_uri "$1" "$2")${NC}"
echo ""
echo -e "${CYAN}user=${BOLD}${1}${NC}, pwd=${BOLD}${2}${NC}, host=${BOLD}${SERVER_IP}${NC}, port=${BOLD}2022${NC}"
}

list_users() {
echo ""
local n; n=$(jq '.users | length' "$CONFIG_FILE")
echo -e "${BOLD}${CYAN}=== Пользователей: $n ===${NC}"
jq -r '.users[] | " \(.name)\t\(.password[0:6])…"' "$CONFIG_FILE" | nl -w2 -s'. '
echo ""
echo -e "${BOLD}${CYAN}=== Активные сессии ===${NC}"
mita_cli get connections 2>&1 | head -20
press_enter
}

add_user() {
echo ""; read -rp "Имя пользователя: " name
name=$(echo "$name" | tr -d ' ')
[[ -z "$name" ]] && { echo "Пусто."; press_enter; return; }
if jq -e --arg n "$name" '.users[] | select(.name == $n)' "$CONFIG_FILE" >/dev/null; then
echo "Уже есть."; press_enter; return
fi
read -rp "Пароль (Enter — сгенерировать): " pwd
[[ -z "$pwd" ]] && pwd=$(generate_password)

backup_config
local tmp; tmp=$(mktemp)
jq --arg n "$name" --arg p "$pwd" '.users += [{"name":$n,"password":$p}]' "$CONFIG_FILE" > "$tmp" && mv "$tmp" "$CONFIG_FILE"

if apply_config; then
echo -e "${GREEN}Пользователь $name добавлен.${NC}"
print_uri_for "$name" "$pwd"
fi
press_enter
}

delete_user() {
mapfile -t users < <(jq -r '.users[].name' "$CONFIG_FILE")
[[ ${#users[@]} -eq 0 ]] && { echo "Пусто."; press_enter; return; }
for i in "${!users[@]}"; do echo " $((i+1))) ${users[$i]}"; done
echo " 0) Отмена"; read -rp "Номер: " n
[[ "$n" == "0" || -z "$n" ]] && return
local target="${users[$((n-1))]}"
read -rp "Удалить '$target'? (y/N): " yn
[[ ! "$yn" =~ ^[Yy]$ ]] && return

mita_cli delete user "$target" 2>&1
backup_config
local tmp; tmp=$(mktemp)
jq --arg n "$target" 'del(.users[] | select(.name == $n))' "$CONFIG_FILE" > "$tmp" && mv "$tmp" "$CONFIG_FILE"
apply_config && echo -e "${GREEN}Удалён.${NC}"
press_enter
}

show_uri() {
mapfile -t users < <(jq -r '.users[].name' "$CONFIG_FILE")
[[ ${#users[@]} -eq 0 ]] && { echo "Пусто."; press_enter; return; }
for i in "${!users[@]}"; do echo " $((i+1))) ${users[$i]}"; done
read -rp "Номер: " n
[[ -z "$n" ]] && return
local user="${users[$((n-1))]}"
local pwd; pwd=$(jq -r --arg n "$user" '.users[] | select(.name == $n) | .password' "$CONFIG_FILE")
print_uri_for "$user" "$pwd"
press_enter
}

server_status() {
mita_cli status 2>&1
echo
mita_cli get connections 2>&1
echo
mita_cli get metrics 2>&1 | head -30
press_enter
}

main_menu() {
check_root; check_deps
while true; do
clear
echo "╔══════════════════════════════════════╗"
echo "║ mieru User Manager ║"
echo "║ IP: $SERVER_IP"
echo "╚══════════════════════════════════════╝"
echo
echo " 1) Список пользователей"
echo " 2) Добавить"
echo " 3) Удалить"
echo " 4) URI клиента"
echo " 5) Статус сервера"
echo " 0) Выход"
read -rp "Выбор: " opt
case "$opt" in
1) list_users ;; 2) add_user ;;
3) delete_user ;; 4) show_uri ;;
5) server_status ;; 0) exit 0 ;;
esac
done
}

main_menu
</syntaxhighlight>
----

== См. также ==

* [https://github.com/enfein/mieru Официальный репозиторий mieru]
* [https://github.com/enfein/mieru/blob/master/docs/protocol.md Спецификация протокола mieru]
* [https://github.com/enfein/mieru/blob/master/docs/traffic-pattern.md Документация по traffic pattern]
* [https://github.com/enfein/mieru/blob/master/docs/security.md Руководство по безопасности]

Файл:Mieru-multi-user.png

2026-05-10T20:20:15Z

Владимир:

Файл:Mieru-segment-format.png

2026-05-10T20:20:01Z

Владимир:

Файл:Mieru-cascade-flow.png

2026-05-10T20:19:47Z

Владимир:

Mieru: каскадный шифрованный SOCKS5-туннель

2026-05-10T20:17:45Z

Владимир: /* Поток данных в одиночном режиме */

= mieru: каскадный шифрованный SOCKS5-туннель с устойчивостью к классификации трафика =

== Введение ==

=== Что такое mieru ===
'''mieru''' (見える, «видимый») — это криптографически защищённый прокси-протокол, ориентированный на работу в средах с активным DPI и статистическим анализом сетевого трафика. В отличие от большинства современных туннелей, mieru '''не использует TLS''' и '''не маскируется под легитимный сайт'''. Вместо этого он подаёт на провод поток, который при пассивном анализе выглядит как случайные байты или произвольный текстовый протокол — без узнаваемых заголовков, фиксированных длин и характерных handshake-паттернов.

Программный пакет состоит из двух самостоятельных бинарников:
{| class="wikitable"
!Бинарник
!Роль
|-
|<code>mita</code>
|Серверная часть. Принимает зашифрованные соединения, аутентифицирует пользователей, переправляет полезную нагрузку наружу
|-
|<code>mieru</code>
|Клиентская часть. Поднимает локальный SOCKS5-прокси на машине пользователя; всё, что в него пришло, шифруется и отправляется на <code>mita</code>
|}

=== Когда применяется ===

* Канал между клиентом и обычными VPN-серверами проходит через инфраструктуру с DPI или ML-классификацией протоколов.
* Нужен альтернативный канал, не зависящий от валидного TLS-сертификата и собственного домена (mieru вообще не требует доменного имени).
* Нужна устойчивость к активному зондированию: сервер mieru, в отличие от REALITY-/Trojan-серверов, при попытке зондирования просто '''молчит''', не имитируя ни сайта-донора, ни TLS-handshake — нечего фингерпринтить.

=== Сравнение с другими методами туннелирования ===
{| class="wikitable"
!Метод
!Транспорт
!Маскировка
!Требует домен и TLS
!Устойчивость к ML-классификации
|-
|WireGuard
|UDP
|нет (явный WG)
|нет
|низкая
|-
|OpenVPN
|UDP/TCP
|нет
|опционально
|низкая
|-
|Shadowsocks-AEAD-2022
|TCP
|случайный шум
|нет
|средняя
|-
|VLESS + REALITY
|TCP (TLS)
|TLS-handshake чужого сайта
|да
|высокая (внутри пула TLS)
|-
|NaiveProxy
|TCP (HTTP/2)
|Chromium-стек, неотличим от HTTPS
|да
|высокая (внутри пула HTTPS)
|-
|Hysteria2
|UDP (QUIC)
|QUIC поверх UDP с маскировкой под HTTPS
|да
|высокая (внутри пула QUIC)
|-
|'''mieru'''
|'''TCP / UDP, без TLS'''
|'''случайный шум либо текстоподобный поток (через traffic pattern)'''
|'''нет — только пара логин/пароль'''
|'''высокая (специальная подгонка энтропии и ASCII)'''
|}
----

== Принципы работы ==

=== Поток данных в одиночном режиме ===
[[Файл:Mieru-single-flow.png|центр|517x517px|Поток данных одиночного mieru: клиент → SOCKS5 → mieru → шифр → mita → интернет]]
=== Каскадный режим (двухзвенный) ===
В каскаде роль обычного «сервера» выполняют два узла. Первый принимает клиентов и не выходит в интернет напрямую; вместо этого он переправляет уже расшифрованный трафик во второй узел через тот же протокол mieru. Второй узел осуществляет финальный egress.
[[Файл:Mieru-cascade-flow.png|центр|600x600пкс|Поток данных каскадного mieru: Сервер A (frontend) → Сервер B (backend) → egress]]
=== Зачем разделять frontend и backend ===

* Адрес backend-сервера никогда не виден клиентскому ПО. Если frontend замечен и заблокирован — backend остаётся неизвестным наблюдателям и переиспользуется со следующим frontend.
* Frontend хранит '''только''' учётки клиентов и не имеет финального egress. Компрометация его конфига не раскрывает финальный IP.
* Двойное шифрование mieru на каждом плече: каждый сегмент дважды проходит AEAD с разными ключами, что усложняет статистический анализ.

=== Шифрование и аутентификация ===
{| class="wikitable"
!Параметр
!Значение
|-
|Алгоритм
|XChaCha20-Poly1305 (AEAD) с 24-байтным nonce
|-
|Длина ключа
|32 байта
|-
|Метод выработки ключа
|PBKDF2-SHA256, 64 итерации, соль = SHA-256 от текущего времени, округлённого до 2 минут
|-
|Идентификатор пользователя в пакете
|Последние 4 байта nonce заменены на префикс SHA-256 от <code>username + nonce[0:16]</code>; имя пользователя на провод не передаётся
|-
|Защита от reuse
|Проверка nonce-кэша на серверной стороне; повторный пакет отбрасывается
|}
Ключ шифрования '''не передаётся''' через канал и нигде не хранится в виде сериализованной строки: он каждый раз генерируется на лету из пары логин+пароль и текущего времени. Из этого следует одно практическое требование, которое легко не заметить.

==== Требование к синхронизации часов ====
Расхождение системного времени клиента и сервера '''не должно превышать 4 минуты'''. При большем расхождении ключ, выработанный клиентом, не сойдётся с ключом сервера, и подключения будут '''молча''' падать (без явной ошибки в логах). На обоих серверах и на клиентском устройстве должен работать NTP-демон.

=== Формат сегмента ===
[[Файл:Mieru-segment-format.png|центр|500x500пкс|Формат сегмента mieru: padding, nonce, шифр-метаданные, шифр-полезная нагрузка]]Ключевое отличие от других протоколов: '''ВСЕ''' структурные поля сегмента (тип, размер, sequence number, ID сессии и пр.) находятся внутри поля <code>enc-meta</code> — то есть зашифрованы. Снаружи невозможно даже определить, что это за пакет, какой длины полезная нагрузка, в начале или в середине сессии находится клиент. Видны только три зоны паддинга и зашифрованные блобы.

=== Traffic pattern (опциональная подгонка маскировки) ===
mieru предоставляет два независимых механизма для подмены статистических признаков шифр-трафика на «обычные»:
{| class="wikitable"
!Опция
!Что делает
!Накладные расходы
|-
|<code>tcpFragment</code>
|Дробит TCP-пакеты на мелкие куски и вставляет случайную задержку между ними. Цель — сломать узнаваемость «один большой шифр-стрим»
| +латентность до <code>maxSleepMs</code> мс на каждый фрагмент
|-
|<code>nonce.NONCE_TYPE_PRINTABLE</code>
|Подменяет первые N байт nonce печатными ASCII-символами. Цель — увести классификатор «высокая энтропия от нулевого байта» в ложное «это текстовый протокол»
|почти ноль (только подмена байтов)
|-
|<code>nonce.NONCE_TYPE_FIXED</code>
|Подменяет первые байты nonce фиксированными hex-строками из списка. Цель — имитировать конкретный фиксированный заголовок
|ноль
|}
Включение traffic pattern имеет смысл '''только''' на видимом анализатором плече (клиент → frontend). На внутреннем плече каскада (frontend → backend) это лишний overhead.

=== Многопользовательский режим ===
Один сервер mita может обслуживать неограниченное число учёток одновременно. Каждый user — это пара <code>(name, password)</code>; лимит по числу одновременных сессий внутри одной учётки '''не задан в протоколе''' (можно опционально настраивать квоты по объёму трафика).
[[Файл:Mieru-multi-user.png|центр|450x450пкс|Многопользовательский режим: один сервер mita обслуживает несколько учёток одновременно]]Такая модель радикально отличается от mash-/torch-протоколов с архитектурой «один сервер — один пользователь»: вам '''не нужно''' создавать отдельный контейнер на каждого пользователя.
----

== Что должно быть на серверах перед установкой ==

=== Минимальная конфигурация каждого сервера ===
{| class="wikitable"
!№
!Требование
!Зачем
|-
|1
|Linux дистрибутив (Ubuntu 22.04+, Debian 12+, Fedora 38+ или сравнимый)
|Среда выполнения Docker
|-
|2
|SSH-доступ с правами <code>root</code> либо аккаунт с <code>sudo</code> без пароля
|Установка пакетов и управление контейнерами
|-
|3
|Docker Engine 24.0+ и плагин Docker Compose v2.20+
|Запуск контейнеров mita и mieru
|-
|4
|NTP-демон активен (<code>chrony</code> или <code>systemd-timesyncd</code>)
|Синхронизация часов в пределах 4 минут (см. раздел «Шифрование»)
|-
|5
|Открытый наружу TCP-диапазон (для нашей статьи — <code>2012-2022</code>)
|Принимающий порт mita
|}

=== Опциональная конфигурация: egress через сторонний прокси ===
По умолчанию backend-сервер выходит в интернет напрямую с публичного IP виртуальной машины. В качестве промежуточной цепочки часто используется выделенный SOCKS5-прокси, обслуживаемый сторонней панелью (например, '''3x-ui''' над xray-core).
{| class="wikitable"
!№
!Параметр
!Пример
!Комментарий
|-
|1
|SOCKS5-inbound, слушающий '''только на <code>172.17.0.1</code>''' (docker0-bridge gateway)
|порт <code>24366</code>
|Слушать на <code>127.0.0.1</code> '''не подойдёт''': контейнер mita с <code>network_mode: host</code> увидит нужный адрес именно как <code>172.17.0.1</code>
|-
|2
|Аутентификация на этом inbound отключена
|—
|Можно включить и прописать креды в <code>egress.proxies</code> mita, но без авторизации проще
|-
|3
|Routing-rule: трафик с этого inbound → нужный outbound (например, WireGuard-к-WARP, наружный VPN, сторонний прокси)
|—
|Зависит от вашей панели; в 3x-ui — раздел «Маршрутизация»
|}

==== Проверка egress-цепочки ====
Команда выполняется на самом backend-сервере. Заменить <code>24366</code> на ваш порт.<syntaxhighlight lang="bash">
docker run --rm curlimages/curl:latest --max-time 12 --socks5 172.17.0.1:24366 https://icanhazip.com
</syntaxhighlight>Ожидание: IP вашего egress-узла (например, IP Cloudflare WARP или IP стороннего VPN). Если возвращается публичный IP вашей VM — egress не работает, проверьте routing панели.

Если egress через сторонний прокси не нужен (готовы выходить с публичного IP backend-сервера) — пропустите этот раздел; в дальнейших шагах указания «без egress» помечены явно.
----

== Параметры, которые нужно подготовить заранее ==
Перед началом установки заполните таблицу собственными значениями. На каждом шаге, где встретится плейсхолдер, мы будем ссылаться на эту таблицу.
{| class="wikitable"
!Плейсхолдер
!Что это
!Пример
|-
|<code>YOUR_FRONTEND_HOST</code>
|Адрес frontend-сервера для SSH (IP, имя из <code>~/.ssh/config</code> либо домен)
|<code>198.51.100.10</code>
|-
|<code>YOUR_BACKEND_HOST</code>
|Адрес backend-сервера для SSH
|<code>203.0.113.20</code>
|-
|<code>YOUR_BACKEND_PUBLIC_IP</code>
|Публичный IP backend-сервера, к которому будет коннектиться mieru-client с frontend
|<code>203.0.113.20</code>
|-
|<code>YOUR_FRONTEND_PUBLIC_IP</code>
|Публичный IP frontend-сервера, к которому будут коннектиться клиенты
|<code>198.51.100.10</code>
|-
|<code>YOUR_BRIDGE_PASSWORD</code>
|Пароль учётки mieru, которой mieru-client на frontend подключается к mita на backend. Один на оба узла
|длинная случайная строка, сгенерированная <code>openssl rand</code>
|-
|<code>YOUR_CLIENT_PASSWORD</code>
|Пароль первой клиентской учётки <code>client01</code> на frontend
|длинная случайная строка
|-
|<code>YOUR_EGRESS_HOST</code>
|Адрес SOCKS5-egress на backend (если используете)
|<code>172.17.0.1</code>
|-
|<code>YOUR_EGRESS_PORT</code>
|Порт SOCKS5-egress
|<code>24366</code>
|}
Сохраните таблицу в надёжное место — особенно пароли. Без них восстановить рабочее состояние нельзя.
----

== Установка backend-сервера (точка выхода) ==
Все команды этого раздела выполняются на backend-сервере по SSH. Каждое пояснение — одна команда.

=== Шаг 1. Подключение по SSH ===
<syntaxhighlight lang="bash">
ssh root@YOUR_BACKEND_HOST
</syntaxhighlight>

=== Шаг 2. Проверка Docker ===
<syntaxhighlight lang="bash">
docker --version
</syntaxhighlight>Если выведено <code>Docker version 24.0.x</code> или новее — переходите к шагу 3. Если <code>command not found</code> — установите Docker по официальной инструкции для вашей ОС: <code>https://docs.docker.com/engine/install/</code>. После установки вернитесь сюда.

Дополнительно проверьте плагин Compose.<syntaxhighlight lang="bash">
docker compose version
</syntaxhighlight>

=== Шаг 3. Создание рабочего каталога ===
<syntaxhighlight lang="bash">
mkdir -p /opt/mieru-backend
</syntaxhighlight><syntaxhighlight lang="bash">
cd /opt/mieru-backend
</syntaxhighlight>

=== Шаг 4. Создание Dockerfile ===
Откройте файл для редактирования.<syntaxhighlight lang="bash">
nano /opt/mieru-backend/Dockerfile
</syntaxhighlight>Вставьте следующее содержимое полностью.<syntaxhighlight lang="dockerfile">
ARG MIERU_VERSION=3.32.0
ARG TARGETARCH=amd64

FROM alpine:3.19 AS downloader
ARG MIERU_VERSION
ARG TARGETARCH
RUN apk add --no-cache ca-certificates wget
WORKDIR /tmp/mita
RUN wget -qO- "https://github.com/enfein/mieru/releases/download/v${MIERU_VERSION}/mita_${MIERU_VERSION}_linux_${TARGETARCH}.tar.gz" | tar xz
WORKDIR /tmp/mieru
RUN wget -qO- "https://github.com/enfein/mieru/releases/download/v${MIERU_VERSION}/mieru_${MIERU_VERSION}_linux_${TARGETARCH}.tar.gz" | tar xz

FROM alpine:3.19
RUN apk add --no-cache ca-certificates tini && \
adduser -H -D -g "" mita && \
adduser -H -D -g "" mieru
COPY --from=downloader /tmp/mita/mita /usr/local/bin/mita
COPY --from=downloader /tmp/mieru/mieru /usr/local/bin/mieru
RUN chmod +x /usr/local/bin/mita /usr/local/bin/mieru && \
mkdir -p /etc/mita /var/lib/mita /var/run/mita \
/etc/mieru /var/lib/mieru /var/run/mieru /srv && \
chown -R mita:mita /etc/mita /var/lib/mita /var/run/mita && \
chown -R mieru:mieru /etc/mieru /var/lib/mieru /var/run/mieru
COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
ENTRYPOINT ["/sbin/tini","--","/usr/local/bin/docker-entrypoint.sh"]
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

=== Шаг 5. Создание скрипта-entrypoint ===
<syntaxhighlight lang="bash">
nano /opt/mieru-backend/docker-entrypoint.sh
</syntaxhighlight>Вставьте полное содержимое.<syntaxhighlight lang="bash">
#!/bin/sh
set -eu

MODE="${MIERU_MODE:-mita}"
CONFIG_FILE="${MIERU_CONFIG:-/srv/config.json}"

case "$MODE" in
mita) BIN=mita ;;
mieru) BIN=mieru ;;
*) echo "[entrypoint] FATAL: MIERU_MODE='$MODE' (mita или mieru)"; exit 1 ;;
esac

if [ ! -f "$CONFIG_FILE" ]; then
echo "[entrypoint] WARN: $CONFIG_FILE не найден"
fi

if [ "$MODE" = "mieru" ]; then
if [ -f "$CONFIG_FILE" ]; then
mieru apply config "$CONFIG_FILE" 2>&1
fi
exec mieru run
else
apply_via_rpc() {
i=0
while [ "$i" -lt 30 ]; do
i=$((i+1)); sleep 1
if [ -f "$CONFIG_FILE" ] && mita apply config "$CONFIG_FILE" >/tmp/apply.out 2>&1; then
mita start >/tmp/start.out 2>&1
return 0
fi
done
}
apply_via_rpc &
exec mita run
fi
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

Дайте файлу права на исполнение.<syntaxhighlight lang="bash">
chmod +x /opt/mieru-backend/docker-entrypoint.sh
</syntaxhighlight>

=== Шаг 6. Генерация пароля для bridge-учётки ===
<syntaxhighlight lang="bash">
openssl rand -base64 24 | tr -d '=/+' | head -c 31
</syntaxhighlight>Команда выведет одну строку из 31 символа. Скопируйте её и впишите в подготовленную таблицу как <code>YOUR_BRIDGE_PASSWORD</code>. Этот же пароль понадобится на frontend-сервере (шаг ниже).

=== Шаг 7. Создание серверного конфига ===
<syntaxhighlight lang="bash">
nano /opt/mieru-backend/server.json
</syntaxhighlight>Вставьте содержимое и замените <code>YOUR_BRIDGE_PASSWORD</code> на скопированное значение из шага 6.

Если вы '''используете''' egress через сторонний SOCKS5-прокси — оставьте секцию <code>egress</code> как есть и при необходимости подправьте <code>host</code> и <code>port</code>. Если '''не используете''' — удалите всю секцию <code>egress</code> от открывающей до закрывающей фигурной скобки.<syntaxhighlight lang="json">
{
"portBindings": [
{"portRange": "2012-2022", "protocol": "TCP"}
],
"users": [
{"name": "frontend-bridge", "password": "YOUR_BRIDGE_PASSWORD"}
],
"loggingLevel": "INFO",
"mtu": 1380,
"egress": {
"proxies": [
{
"name": "external-egress",
"protocol": "SOCKS5_PROXY_PROTOCOL",
"host": "172.17.0.1",
"port": 24366
}
],
"rules": [
{
"ipRanges": ["*"],
"domainNames": ["*"],
"action": "PROXY",
"proxyNames": ["external-egress"]
}
]
}
}
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

Защитите файл (содержит пароль).<syntaxhighlight lang="bash">
chmod 600 /opt/mieru-backend/server.json
</syntaxhighlight>

=== Шаг 8. Создание docker-compose.yml ===
<syntaxhighlight lang="bash">
nano /opt/mieru-backend/docker-compose.yml
</syntaxhighlight>Вставьте.<syntaxhighlight lang="yaml">
services:
mita:
build:
context: .
args:
MIERU_VERSION: "3.32.0"
image: mieru-bundle:3.32.0
container_name: mita-backend
restart: unless-stopped
network_mode: host
environment:
MIERU_MODE: mita
MIERU_CONFIG: /srv/server.json
volumes:
- ./server.json:/srv/server.json:ro
- mita-state:/etc/mita
- mita-runtime:/var/run/mita
- mita-data:/var/lib/mita
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"

volumes:
mita-state:
mita-runtime:
mita-data:
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

=== Шаг 9. Сборка образа ===
<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml build
</syntaxhighlight>Сборка длится 1–3 минуты. По завершении выводится <code>Image mieru-bundle:3.32.0 Built</code>.

=== Шаг 10. Запуск ===
<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml up -d
</syntaxhighlight>Подождите 10 секунд.<syntaxhighlight lang="bash">
sleep 10
</syntaxhighlight>Проверьте логи.<syntaxhighlight lang="bash">
docker logs mita-backend --tail 25
</syntaxhighlight>Ожидаемые строки:
[entrypoint] config применён (/srv/server.json)
[entrypoint] mita start: OK
mita server status is "RUNNING"
Проверьте, что сервер слушает порты <code>2012-2022</code>.<syntaxhighlight lang="bash">
ss -tlnp | grep -E ':20(1[2-9]|2[012]) '
</syntaxhighlight>Должны появиться 11 строк со статусом <code>LISTEN</code> и пользователем <code>mita</code>. Если их нет — обратитесь к разделу «Поиск проблем».
----

== Установка frontend-сервера (точка входа) ==
Все команды этого раздела выполняются на frontend-сервере по SSH.

=== Шаг 1. Подключение и подготовка ===
<syntaxhighlight lang="bash">
ssh root@YOUR_FRONTEND_HOST
</syntaxhighlight><syntaxhighlight lang="bash">
mkdir -p /opt/mieru-frontend && cd /opt/mieru-frontend
</syntaxhighlight>

=== Шаг 2. Dockerfile и entrypoint (одинаковые с backend) ===
Создайте оба файла так же, как на backend-сервере (см. шаги 4–5 раздела «Установка backend-сервера»). Содержимое идентично — образ универсальный, режим работы выбирается переменной окружения.<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/Dockerfile
</syntaxhighlight>(вставьте тот же Dockerfile, что на backend)<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/docker-entrypoint.sh
</syntaxhighlight>(вставьте тот же entrypoint)<syntaxhighlight lang="bash">
chmod +x /opt/mieru-frontend/docker-entrypoint.sh
</syntaxhighlight>

=== Шаг 3. Генерация пароля первой клиентской учётки ===
<syntaxhighlight lang="bash">
openssl rand -base64 24 | tr -d '=/+' | head -c 31
</syntaxhighlight>Скопируйте результат и впишите в таблицу как <code>YOUR_CLIENT_PASSWORD</code>. Это пароль учётки <code>client01</code>, который вы потом отдадите своему первому клиентскому устройству.

=== Шаг 4. Серверный конфиг (mita-frontend) ===
<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/server.json
</syntaxhighlight>Замените <code>YOUR_CLIENT_PASSWORD</code> на значение из шага 3.<syntaxhighlight lang="json">
{
"portBindings": [
{"portRange": "2012-2022", "protocol": "TCP"}
],
"users": [
{"name": "client01", "password": "YOUR_CLIENT_PASSWORD"}
],
"loggingLevel": "INFO",
"mtu": 1380,
"trafficPattern": {
"unlockAll": false,
"tcpFragment": {"enable": true, "maxSleepMs": 10},
"nonce": {
"type": "NONCE_TYPE_PRINTABLE",
"minLen": 6,
"maxLen": 8
}
},
"egress": {
"proxies": [
{
"name": "to-backend",
"protocol": "SOCKS5_PROXY_PROTOCOL",
"host": "127.0.0.1",
"port": 1080
}
],
"rules": [
{
"ipRanges": ["*"],
"domainNames": ["*"],
"action": "PROXY",
"proxyNames": ["to-backend"]
}
]
}
}
</syntaxhighlight>Сохраните и защитите файл.<syntaxhighlight lang="bash">
chmod 600 /opt/mieru-frontend/server.json
</syntaxhighlight>

=== Шаг 5. Клиентский конфиг (mieru-client) ===
<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/client.json
</syntaxhighlight>Замените <code>YOUR_BACKEND_PUBLIC_IP</code> на публичный IP backend-сервера, <code>YOUR_BRIDGE_PASSWORD</code> — на пароль bridge-учётки, который вы создавали на backend в шаге 6.<syntaxhighlight lang="json">
{
"profiles": [
{
"profileName": "default",
"user": {
"name": "frontend-bridge",
"password": "YOUR_BRIDGE_PASSWORD"
},
"servers": [
{
"ipAddress": "YOUR_BACKEND_PUBLIC_IP",
"portBindings": [
{"portRange": "2012-2022", "protocol": "TCP"}
]
}
],
"mtu": 1380,
"multiplexing": {"level": "MULTIPLEXING_HIGH"},
"handshakeMode": "HANDSHAKE_NO_WAIT"
}
],
"activeProfile": "default",
"rpcPort": 8964,
"socks5Port": 1080,
"loggingLevel": "INFO",
"socks5ListenLAN": false,
"httpProxyListenLAN": false
}
</syntaxhighlight>Сохраните и защитите файл.<syntaxhighlight lang="bash">
chmod 600 /opt/mieru-frontend/client.json
</syntaxhighlight>

=== Шаг 6. docker-compose.yml на frontend ===
<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/docker-compose.yml
</syntaxhighlight>Вставьте.<syntaxhighlight lang="yaml">
services:
mieru-client:
build:
context: .
args:
MIERU_VERSION: "3.32.0"
image: mieru-bundle:3.32.0
container_name: mieru-client
restart: unless-stopped
network_mode: host
environment:
MIERU_MODE: mieru
MIERU_CONFIG: /srv/client.json
volumes:
- ./client.json:/srv/client.json:ro
- mieru-client-state:/etc/mieru
- mieru-client-runtime:/var/run/mieru
- mieru-client-data:/var/lib/mieru
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"

mita:
image: mieru-bundle:3.32.0
container_name: mita-frontend
restart: unless-stopped
network_mode: host
depends_on:
- mieru-client
environment:
MIERU_MODE: mita
MIERU_CONFIG: /srv/server.json
volumes:
- ./server.json:/srv/server.json:ro
- mita-state:/etc/mita
- mita-runtime:/var/run/mita
- mita-data:/var/lib/mita
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"

volumes:
mieru-client-state:
mieru-client-runtime:
mieru-client-data:
mita-state:
mita-runtime:
mita-data:
</syntaxhighlight>Сохраните.

=== Шаг 7. Сборка и запуск ===
<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-frontend/docker-compose.yml build
</syntaxhighlight><syntaxhighlight lang="bash">
docker compose -f /opt/mieru-frontend/docker-compose.yml up -d
</syntaxhighlight><syntaxhighlight lang="bash">
sleep 12
</syntaxhighlight>

=== Шаг 8. Проверка ===
<syntaxhighlight lang="bash">
docker logs mieru-client --tail 10
</syntaxhighlight>Должна быть строка <code>mieru: config применён</code> и затем <code>запуск mieru run</code>.<syntaxhighlight lang="bash">
docker logs mita-frontend --tail 10
</syntaxhighlight>Должно быть <code>RUNNING</code> и <code>mita start: OK</code>.<syntaxhighlight lang="bash">
docker exec mieru-client mieru status
</syntaxhighlight>Ожидание: <code>mieru client is running</code>.<syntaxhighlight lang="bash">
docker exec mita-frontend mita status
</syntaxhighlight>Ожидание: <code>mita server status is "RUNNING"</code>.

=== Шаг 9. Сквозной тест каскада ===
С frontend-сервера обратитесь во внешний интернет через локальный SOCKS5 mieru-client. Это эквивалент того, как пойдёт реальный клиентский запрос.<syntaxhighlight lang="bash">
curl -sS --max-time 30 --proxy socks5h://127.0.0.1:1080 https://icanhazip.com
</syntaxhighlight>Ожидание: IP вашего egress-узла. Например, IP Cloudflare WARP, если на backend настроен такой outbound. Команда '''не должна''' возвращать публичный IP frontend-сервера.

Контрольный замер прямого IP frontend для сравнения.<syntaxhighlight lang="bash">
curl -sS --max-time 5 https://icanhazip.com
</syntaxhighlight>Если первый IP отличается от второго — каскад работает.
----

== Подключение клиентов ==
mieru имеет два равнозначных формата отдачи параметров клиенту: '''Clash/Mihomo YAML''' и '''<code>mierus://</code> URI'''. На практике YAML более переносим — его понимает большинство клиентов в одном виде, тогда как URI разбирается каждым приложением по-своему.

=== Десктоп: Clash Verge Rev / Mihomo Party / NekoBox ===
Создайте новый профиль (или отредактируйте существующий) и добавьте блок <code>proxies</code>:<syntaxhighlight lang="yaml">
proxies:
- name: mieru-frontend
type: mieru
server: YOUR_FRONTEND_PUBLIC_IP
port: 2022
username: client01
password: YOUR_CLIENT_PASSWORD
multiplexing: MULTIPLEXING_HIGH
</syntaxhighlight>Параметр <code>port: 2022</code> — это один из портов из диапазона <code>2012-2022</code>; mita слушает все 11 параллельно, клиент использует один (мультиплексор).

=== Мобильные: Karing / ClashMi / NekoBox+plugin / husi ===
Подключение через тот же YAML-блок выше — большинство клиентов поддерживают вставку YAML вручную в раздел «Серверы» или «Outbounds». Сценарий импорта URI в Karing 1.2.x работает плохо (поле порта обнуляется), поэтому YAML предпочтительнее.

=== Универсальный URI-формат ===
<syntaxhighlight>
mierus://client01:YOUR_CLIENT_PASSWORD@YOUR_FRONTEND_PUBLIC_IP?port=2022&protocol=TCP&mtu=1380&multiplexing=MULTIPLEXING_HIGH&handshake-mode=HANDSHAKE_NO_WAIT
</syntaxhighlight>Подходит для нативного <code>mieru</code> CLI, husi с mieru-плагином, Exclave.
----

== Подключение клиента на OpenWrt-роутере ==
Если на роутере уже стоит трафик-менеджер (например, podkop), и вы хотите, чтобы он отправлял трафик через mieru — поставьте на роутер standalone mieru-клиент с локальным SOCKS5, и подкоп цепляйте к этому SOCKS5.

=== Шаг 1. Подключение к роутеру ===
<syntaxhighlight lang="bash">
ssh root@YOUR_ROUTER_HOST
</syntaxhighlight>

=== Шаг 2. Скачивание бинаря ===
Архитектура роутера большинства современных моделей — <code>aarch64</code>. Если ваш роутер — другой (например, <code>mips</code>), проверьте список релизов <code>https://github.com/enfein/mieru/releases/latest</code> и подставьте нужный артефакт в команду.<syntaxhighlight lang="bash">
cd /tmp && wget -q https://github.com/enfein/mieru/releases/download/v3.32.0/mieru_3.32.0_linux_arm64.tar.gz -O mieru.tar.gz
</syntaxhighlight><syntaxhighlight lang="bash">
tar xzf mieru.tar.gz && mv mieru /usr/bin/mieru && chmod +x /usr/bin/mieru && rm -f /tmp/mieru.tar.gz /tmp/LICENSE /tmp/README.md
</syntaxhighlight><syntaxhighlight lang="bash">
/usr/bin/mieru version
</syntaxhighlight>Должно вывести <code>3.32.0</code>.

=== Шаг 3. Клиентский конфиг ===
<syntaxhighlight lang="bash">
nano /etc/mieru_client_config.json
</syntaxhighlight>Вставьте, заменив плейсхолдеры:<syntaxhighlight lang="json">
{
"profiles": [
{
"profileName": "default",
"user": {
"name": "client01",
"password": "YOUR_CLIENT_PASSWORD"
},
"servers": [
{
"ipAddress": "YOUR_FRONTEND_PUBLIC_IP",
"portBindings": [
{"portRange": "2012-2022", "protocol": "TCP"}
]
}
],
"mtu": 1380,
"multiplexing": {"level": "MULTIPLEXING_HIGH"},
"handshakeMode": "HANDSHAKE_NO_WAIT",
"trafficPattern": {
"unlockAll": false,
"tcpFragment": {"enable": true, "maxSleepMs": 10},
"nonce": {
"type": "NONCE_TYPE_PRINTABLE",
"minLen": 6,
"maxLen": 8
}
}
}
],
"activeProfile": "default",
"rpcPort": 8964,
"socks5Port": 1090,
"loggingLevel": "ERROR",
"socks5ListenLAN": false,
"httpProxyListenLAN": false
}
</syntaxhighlight>Сохраните и защитите файл.<syntaxhighlight lang="bash">
chmod 600 /etc/mieru_client_config.json
</syntaxhighlight>Ключевые отличия конфига для роутера от десктопного клиента:

* <code>socks5Port: 1090</code> — порт <code>1080</code> часто занят другими прокси (например, naive); 1090 свободен.
* <code>loggingLevel: "ERROR"</code> — overlay на роутерах маленький, ограничение логов защищает от заполнения диска.
* <code>trafficPattern</code> включён полностью — на пути «роутер → frontend» классификатор смотрит, маскировка нужна.

=== Шаг 4. Init.d-скрипт ===
OpenWrt использует procd; в отличие от mita, на OpenWrt mieru читает JSON-конфиг напрямую через переменную <code>MIERU_CONFIG_JSON_FILE</code>, и команды <code>mieru apply config</code> и <code>mieru describe config</code> '''не используются'''.<syntaxhighlight lang="bash">
nano /etc/init.d/mieru
</syntaxhighlight>Вставьте.<syntaxhighlight lang="bash">
#!/bin/sh /etc/rc.common

START=99
STOP=01

MIERU_BIN="/usr/bin/mieru"
MIERU_CONFIG="/etc/mieru_client_config.json"
PID_FILE="/var/run/mieru.pid"

start() {
echo "Starting mieru client..."
export MIERU_CONFIG_JSON_FILE=$MIERU_CONFIG
start-stop-daemon -S -b -m -p "$PID_FILE" -x "$MIERU_BIN" -- run
RC=$?
if [ $RC -eq 0 ]; then
echo "mieru client is started"
exit 0
else
echo "failed to start mieru client"
exit $RC
fi
}

stop() {
echo "Stopping mieru client..."
start-stop-daemon -K -p "$PID_FILE"
RC=$?
if [ $RC -eq 0 ]; then
echo "mieru client is stopped"
rm -f "$PID_FILE"
else
echo "failed to stop mieru client"
fi
}
</syntaxhighlight>Сохраните и сделайте исполняемым.<syntaxhighlight lang="bash">
chmod +x /etc/init.d/mieru
</syntaxhighlight>

=== Шаг 5. Запуск и автозапуск ===
<syntaxhighlight lang="bash">
/etc/init.d/mieru enable
</syntaxhighlight><syntaxhighlight lang="bash">
/etc/init.d/mieru start
</syntaxhighlight>

=== Шаг 6. Проверка ===
<syntaxhighlight lang="bash">
ps | grep mieru | grep -v grep
</syntaxhighlight>Должна быть одна строка с процессом <code>/usr/bin/mieru run</code>.<syntaxhighlight lang="bash">
netstat -tlnp 2>/dev/null | grep 1090
</syntaxhighlight>Должна быть строка <code>127.0.0.1:1090 ... LISTEN ... mieru</code>.<syntaxhighlight lang="bash">
curl -sS --max-time 30 -x socks5h://127.0.0.1:1090 https://icanhazip.com
</syntaxhighlight>Должен вернуть IP egress-узла каскада.

=== Шаг 7. Подключение podkop к локальному mieru ===
В LuCI откройте подкоп. Создайте новую секцию или измените существующую:
{| class="wikitable"
!Поле
!Значение
|-
|Тип конфига
|URL
|-
|Proxy string
|<code>socks5://127.0.0.1:1090</code>
|}
Эквивалент через <code>uci</code>:<syntaxhighlight lang="bash">
uci set podkop.10=section
uci set podkop.10.connection_type='proxy'
uci set podkop.10.proxy_config_type='url'
uci set podkop.10.proxy_string='socks5://127.0.0.1:1090'
uci commit podkop
service podkop restart
</syntaxhighlight>Подкоп отправляет mieru-серверу обычный SOCKS5-запрос на <code>127.0.0.1:1090</code>; mieru шифрует его и отправляет через каскад.
----

== Управление пользователями: скрипт <code>mieru-users.sh</code> ==

=== Зачем он нужен ===
mita-сервер хранит список учёток в файле <code>server.json</code>. Чтобы добавлять/удалять/смотреть пользователей вручную каждый раз — много шагов: jq-правка JSON, вызов <code>mita apply config</code>, генерация ссылки клиенту, опционально <code>mita delete user</code> для разрыва активных сессий. Скрипт <code>mieru-users.sh</code> автоматизирует это всё.

=== Что делает скрипт ===
{| class="wikitable"
!Пункт меню
!Действие
|-
|1. Список пользователей
|Чтение <code>server.json</code> + опрос <code>mita get connections</code> для активных сессий
|-
|2. Добавить пользователя
|Запрос имени, генерация пароля через <code>openssl rand</code>, бэкап JSON, <code>jq</code>-вставка, <code>mita apply config</code>, выдача готовых YAML и URI клиенту
|-
|3. Удалить пользователя
|<code>mita delete user</code> для разрыва сессий → <code>jq</code>-удаление из JSON → <code>apply config</code>
|-
|4. Показать URI клиента
|Сборка YAML и URI по выбранному имени
|-
|5. Статус сервера
|<code>mita status</code> + <code>get connections</code> + <code>get metrics</code>
|}

=== Установка скрипта ===
Все команды выполняются на frontend-сервере по SSH.

==== Шаг 1. Загрузка скрипта ====
<syntaxhighlight lang="bash">
nano /usr/local/bin/mieru-users.sh
</syntaxhighlight>Вставьте полное содержимое скрипта (исходный код в спойлере «Исходный код <code>mieru-users.sh</code>» в конце статьи).

Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

==== Шаг 2. Подстановка реального адреса ====
В начале скрипта есть строка <code>SERVER_IP="YOUR_FRONTEND_PUBLIC_IP"</code>. Замените её на реальный IP frontend-сервера.<syntaxhighlight lang="bash">
sed -i 's/YOUR_FRONTEND_PUBLIC_IP/198.51.100.10/' /usr/local/bin/mieru-users.sh
</syntaxhighlight>(подставьте свой IP вместо <code>198.51.100.10</code>).

==== Шаг 3. Права на исполнение ====
<syntaxhighlight lang="bash">
chmod +x /usr/local/bin/mieru-users.sh
</syntaxhighlight>

==== Шаг 4. Проверка ====
<syntaxhighlight lang="bash">
bash -n /usr/local/bin/mieru-users.sh && echo OK
</syntaxhighlight>Если выводит <code>OK</code> — скрипт установлен корректно.

=== Использование ===
<syntaxhighlight lang="bash">
sudo bash /usr/local/bin/mieru-users.sh
</syntaxhighlight>Появится меню:<pre>
╔══════════════════════════════════════╗
║ mieru User Manager ║
║ IP: 198.51.100.10 ║
╚══════════════════════════════════════╝

Пользователей в конфиге: 1

1. Список пользователей и активных сессий
2. Добавить пользователя
3. Удалить пользователя
4. Показать URI клиента
5. Статус сервера
0. Выход
</pre>После добавления пользователя скрипт выводит готовые конфиги:<pre>
=== Вариант 1: Clash / Mihomo YAML (рекомендую) ===
proxies:
- name: mieru-RU-alice
type: mieru
server: 198.51.100.10
port: 2022
username: alice
password: <автогенерированный>
multiplexing: MULTIPLEXING_HIGH

=== Вариант 2: mierus:// URI ===
mierus://alice:<пароль>@198.51.100.10?port=2022&protocol=TCP&mtu=1380&multiplexing=MULTIPLEXING_HIGH&handshake-mode=HANDSHAKE_NO_WAIT
</pre>
----

== Команды управления ==

=== На обоих серверах ===
Посмотреть логи в реальном времени.<syntaxhighlight lang="bash">
docker logs -f mita-backend # на backend
</syntaxhighlight><syntaxhighlight lang="bash">
docker logs -f mita-frontend mieru-client # на frontend
</syntaxhighlight>Перезапустить.<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml restart # на backend
</syntaxhighlight><syntaxhighlight lang="bash">
docker compose -f /opt/mieru-frontend/docker-compose.yml restart # на frontend
</syntaxhighlight>Остановить.<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml down # на backend
</syntaxhighlight><syntaxhighlight lang="bash">
docker compose -f /opt/mieru-frontend/docker-compose.yml down # на frontend
</syntaxhighlight>Обновить версию mita/mieru. Поменяйте <code>3.32.0</code> на нужную в <code>docker-compose.yml</code> и пересоберите.<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml build && docker compose -f /opt/mieru-backend/docker-compose.yml up -d
</syntaxhighlight>

=== Команды mita через CLI (внутри контейнера) ===
<syntaxhighlight lang="bash">
docker exec mita-backend mita status # IDLE / RUNNING
</syntaxhighlight><syntaxhighlight lang="bash">
docker exec mita-backend mita get users # список user'ов и их статистика
</syntaxhighlight><syntaxhighlight lang="bash">
docker exec mita-backend mita get connections # активные сессии
</syntaxhighlight><syntaxhighlight lang="bash">
docker exec mita-backend mita get metrics # метрики
</syntaxhighlight><syntaxhighlight lang="bash">
docker exec mita-backend mita describe config # текущий применённый конфиг
</syntaxhighlight>

=== На OpenWrt-роутере ===
<syntaxhighlight lang="bash">
/etc/init.d/mieru start | stop | restart
</syntaxhighlight><syntaxhighlight lang="bash">
ps | grep mieru | grep -v grep
</syntaxhighlight><syntaxhighlight lang="bash">
logread | grep mieru
</syntaxhighlight>
----

== Поиск проблем ==

=== Симптом: сервер показывает <code>IDLE</code>, порты не слушаются ===
mita после <code>apply config</code> остаётся в <code>IDLE</code> до явной команды <code>mita start</code>. В нашем entrypoint это происходит автоматически, но если что-то пошло не так, выполните вручную внутри контейнера:<syntaxhighlight lang="bash">
docker exec mita-backend mita start
</syntaxhighlight>

=== Симптом: <code>FATAL: getUid("mita") failed</code> ===
В образ не добавлен системный пользователь <code>mita</code>. Проверьте, что Dockerfile содержит строки <code>adduser -H -D -g "" mita</code> и <code>adduser -H -D -g "" mieru</code>, пересоберите образ.

=== Симптом: клиент подключается, но трафик не идёт ===
Проверьте на клиенте время системы. Расхождение более 4 минут с сервером приведёт к молчаливому отказу. Команда на Linux/macOS:<syntaxhighlight lang="bash">
date -u
</syntaxhighlight>Если время существенно расходится — настройте NTP.

=== Симптом: на frontend curl возвращает не egress-IP, а frontend-IP ===
Trafic идёт мимо mieru-client. Возможные причины:

* <code>egress.action</code> в frontend-конфиге — <code>DIRECT</code> вместо <code>PROXY</code>.
* mieru-client не запущен либо упал. Проверьте: <code>docker ps</code>.
* Backend не доступен. Проверьте на frontend: <code>nc -vz YOUR_BACKEND_PUBLIC_IP 2022</code>.

=== Симптом: на frontend curl возвращает frontend-IP, а должен — backend-IP ===
То же самое, что выше: трафик не доходит до backend. Дополнительно посмотрите логи:<syntaxhighlight lang="bash">
docker logs mieru-client --tail 50
</syntaxhighlight>Ошибки <code>TLS handshake</code> здесь невозможны — mieru не использует TLS. Ищите <code>auth failed</code> (неверная пара логин/пароль на mita-backend) и <code>connection refused</code> (backend не слушает).

=== Симптом: на роутере Karing/Clash подключается, но трафик не идёт ===
В первую очередь проверить YAML-конфиг: тип <code>type: mieru</code> (не <code>type: socks5</code>!), порт <code>port: 2022</code> (одиночное число, не диапазон). Многие mihomo-форки не парсят диапазон портов корректно.
----

== Исходный код <code>mieru-users.sh</code> ==
Полный текст скрипта приведён ниже. Скопируйте его целиком в <code>/usr/local/bin/mieru-users.sh</code> на frontend-сервере по инструкции выше.<syntaxhighlight lang="bash">
#!/bin/bash
# mieru-users — управление пользователями mita
# Источник истины: /opt/mieru-frontend/server.json
# Применение через mita apply config (RPC к работающему daemon).

CONFIG_FILE="/opt/mieru-frontend/server.json"
COMPOSE_DIR="/opt/mieru-frontend"
COMPOSE_SVC="mita"
BACKUP_DIR="/opt/mieru-frontend/backups"
BACKUP_KEEP=10
SERVER_IP="YOUR_FRONTEND_PUBLIC_IP"

RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'
CYAN='\033[0;36m'; BOLD='\033[1m'; NC='\033[0m'

check_root() {
if [[ $EUID -ne 0 ]]; then
echo -e "${RED}Запусти от root: sudo bash mieru-users.sh${NC}"; exit 1
fi
}

check_deps() {
for c in jq docker openssl; do
if ! command -v "$c" >/dev/null 2>&1; then
echo -e "${RED}Не найдено: $c${NC}"; exit 1
fi
done
if [[ ! -f "$CONFIG_FILE" ]]; then
echo -e "${RED}Не найден $CONFIG_FILE${NC}"; exit 1
fi
}

mita_cli() {
docker compose -f "$COMPOSE_DIR/docker-compose.yml" exec -T "$COMPOSE_SVC" mita "$@"
}

backup_config() {
mkdir -p "$BACKUP_DIR"
local stamp; stamp=$(date +%Y%m%d-%H%M%S)
cp "$CONFIG_FILE" "$BACKUP_DIR/server-$stamp.json"
ls -1t "$BACKUP_DIR"/server-*.json 2>/dev/null | tail -n +$((BACKUP_KEEP+1)) | xargs -r rm -f
}

apply_config() {
if ! mita_cli apply config /srv/server.json 2>&1; then
echo -e "${RED}mita apply config упал. Откатываюсь к последнему бэкапу.${NC}"
local last; last=$(ls -1t "$BACKUP_DIR"/server-*.json 2>/dev/null | head -1)
if [[ -n "$last" ]]; then
cp "$last" "$CONFIG_FILE"
mita_cli apply config /srv/server.json >/dev/null 2>&1 || true
fi
return 1
fi
return 0
}

press_enter() { echo ""; read -rp "Enter для возврата..."; }

generate_password() {
openssl rand -base64 24 | tr -d '=/+' | head -c 31
}

generate_uri() {
echo "mierus://${1}:${2}@${SERVER_IP}?port=2022&protocol=TCP&mtu=1380&multiplexing=MULTIPLEXING_HIGH&handshake-mode=HANDSHAKE_NO_WAIT"
}

generate_yaml() {
cat <<EOF
proxies:
- name: mieru-${1}
type: mieru
server: ${SERVER_IP}
port: 2022
username: ${1}
password: ${2}
multiplexing: MULTIPLEXING_HIGH
EOF
}

print_uri_for() {
echo ""
echo -e "${CYAN}=== Вариант 1: Clash / Mihomo YAML ===${NC}"
echo -e "${BOLD}$(generate_yaml "$1" "$2")${NC}"
echo ""
echo -e "${CYAN}=== Вариант 2: mierus:// URI ===${NC}"
echo -e "${BOLD} $(generate_uri "$1" "$2")${NC}"
echo ""
echo -e "${CYAN}user=${BOLD}${1}${NC}, pwd=${BOLD}${2}${NC}, host=${BOLD}${SERVER_IP}${NC}, port=${BOLD}2022${NC}"
}

list_users() {
echo ""
local n; n=$(jq '.users | length' "$CONFIG_FILE")
echo -e "${BOLD}${CYAN}=== Пользователей: $n ===${NC}"
jq -r '.users[] | " \(.name)\t\(.password[0:6])…"' "$CONFIG_FILE" | nl -w2 -s'. '
echo ""
echo -e "${BOLD}${CYAN}=== Активные сессии ===${NC}"
mita_cli get connections 2>&1 | head -20
press_enter
}

add_user() {
echo ""; read -rp "Имя пользователя: " name
name=$(echo "$name" | tr -d ' ')
[[ -z "$name" ]] && { echo "Пусто."; press_enter; return; }
if jq -e --arg n "$name" '.users[] | select(.name == $n)' "$CONFIG_FILE" >/dev/null; then
echo "Уже есть."; press_enter; return
fi
read -rp "Пароль (Enter — сгенерировать): " pwd
[[ -z "$pwd" ]] && pwd=$(generate_password)

backup_config
local tmp; tmp=$(mktemp)
jq --arg n "$name" --arg p "$pwd" '.users += [{"name":$n,"password":$p}]' "$CONFIG_FILE" > "$tmp" && mv "$tmp" "$CONFIG_FILE"

if apply_config; then
echo -e "${GREEN}Пользователь $name добавлен.${NC}"
print_uri_for "$name" "$pwd"
fi
press_enter
}

delete_user() {
mapfile -t users < <(jq -r '.users[].name' "$CONFIG_FILE")
[[ ${#users[@]} -eq 0 ]] && { echo "Пусто."; press_enter; return; }
for i in "${!users[@]}"; do echo " $((i+1))) ${users[$i]}"; done
echo " 0) Отмена"; read -rp "Номер: " n
[[ "$n" == "0" || -z "$n" ]] && return
local target="${users[$((n-1))]}"
read -rp "Удалить '$target'? (y/N): " yn
[[ ! "$yn" =~ ^[Yy]$ ]] && return

mita_cli delete user "$target" 2>&1
backup_config
local tmp; tmp=$(mktemp)
jq --arg n "$target" 'del(.users[] | select(.name == $n))' "$CONFIG_FILE" > "$tmp" && mv "$tmp" "$CONFIG_FILE"
apply_config && echo -e "${GREEN}Удалён.${NC}"
press_enter
}

show_uri() {
mapfile -t users < <(jq -r '.users[].name' "$CONFIG_FILE")
[[ ${#users[@]} -eq 0 ]] && { echo "Пусто."; press_enter; return; }
for i in "${!users[@]}"; do echo " $((i+1))) ${users[$i]}"; done
read -rp "Номер: " n
[[ -z "$n" ]] && return
local user="${users[$((n-1))]}"
local pwd; pwd=$(jq -r --arg n "$user" '.users[] | select(.name == $n) | .password' "$CONFIG_FILE")
print_uri_for "$user" "$pwd"
press_enter
}

server_status() {
mita_cli status 2>&1
echo
mita_cli get connections 2>&1
echo
mita_cli get metrics 2>&1 | head -30
press_enter
}

main_menu() {
check_root; check_deps
while true; do
clear
echo "╔══════════════════════════════════════╗"
echo "║ mieru User Manager ║"
echo "║ IP: $SERVER_IP"
echo "╚══════════════════════════════════════╝"
echo
echo " 1) Список пользователей"
echo " 2) Добавить"
echo " 3) Удалить"
echo " 4) URI клиента"
echo " 5) Статус сервера"
echo " 0) Выход"
read -rp "Выбор: " opt
case "$opt" in
1) list_users ;; 2) add_user ;;
3) delete_user ;; 4) show_uri ;;
5) server_status ;; 0) exit 0 ;;
esac
done
}

main_menu
</syntaxhighlight>
----

== См. также ==

* [https://github.com/enfein/mieru Официальный репозиторий mieru]
* [https://github.com/enfein/mieru/blob/master/docs/protocol.md Спецификация протокола mieru]
* [https://github.com/enfein/mieru/blob/master/docs/traffic-pattern.md Документация по traffic pattern]
* [https://github.com/enfein/mieru/blob/master/docs/security.md Руководство по безопасности]

Файл:Mieru-single-flow.png

2026-05-10T20:15:17Z

Владимир:

Суверенный интернет

2026-05-10T20:15:01Z

Владимир:

Mieru: каскадный шифрованный SOCKS5-туннель

2026-05-10T18:44:09Z

Владимир: Новая страница: «= mieru: каскадный шифрованный SOCKS5-туннель с устойчивостью к классификации трафика = == Введение == === Что такое mieru === '''mieru''' (見える, «видимый») — это криптографически защищённый прокси-протокол, ориентированный на работу в средах с активным DPI и статистичес...»

= mieru: каскадный шифрованный SOCKS5-туннель с устойчивостью к классификации трафика =

== Введение ==

=== Что такое mieru ===
'''mieru''' (見える, «видимый») — это криптографически защищённый прокси-протокол, ориентированный на работу в средах с активным DPI и статистическим анализом сетевого трафика. В отличие от большинства современных туннелей, mieru '''не использует TLS''' и '''не маскируется под легитимный сайт'''. Вместо этого он подаёт на провод поток, который при пассивном анализе выглядит как случайные байты или произвольный текстовый протокол — без узнаваемых заголовков, фиксированных длин и характерных handshake-паттернов.

Программный пакет состоит из двух самостоятельных бинарников:
{| class="wikitable"
!Бинарник
!Роль
|-
|<code>mita</code>
|Серверная часть. Принимает зашифрованные соединения, аутентифицирует пользователей, переправляет полезную нагрузку наружу
|-
|<code>mieru</code>
|Клиентская часть. Поднимает локальный SOCKS5-прокси на машине пользователя; всё, что в него пришло, шифруется и отправляется на <code>mita</code>
|}

=== Когда применяется ===

* Канал между клиентом и обычными VPN-серверами проходит через инфраструктуру с DPI или ML-классификацией протоколов.
* Нужен альтернативный канал, не зависящий от валидного TLS-сертификата и собственного домена (mieru вообще не требует доменного имени).
* Нужна устойчивость к активному зондированию: сервер mieru, в отличие от REALITY-/Trojan-серверов, при попытке зондирования просто '''молчит''', не имитируя ни сайта-донора, ни TLS-handshake — нечего фингерпринтить.

=== Сравнение с другими методами туннелирования ===
{| class="wikitable"
!Метод
!Транспорт
!Маскировка
!Требует домен и TLS
!Устойчивость к ML-классификации
|-
|WireGuard
|UDP
|нет (явный WG)
|нет
|низкая
|-
|OpenVPN
|UDP/TCP
|нет
|опционально
|низкая
|-
|Shadowsocks-AEAD-2022
|TCP
|случайный шум
|нет
|средняя
|-
|VLESS + REALITY
|TCP (TLS)
|TLS-handshake чужого сайта
|да
|высокая (внутри пула TLS)
|-
|NaiveProxy
|TCP (HTTP/2)
|Chromium-стек, неотличим от HTTPS
|да
|высокая (внутри пула HTTPS)
|-
|Hysteria2
|UDP (QUIC)
|QUIC поверх UDP с маскировкой под HTTPS
|да
|высокая (внутри пула QUIC)
|-
|'''mieru'''
|'''TCP / UDP, без TLS'''
|'''случайный шум либо текстоподобный поток (через traffic pattern)'''
|'''нет — только пара логин/пароль'''
|'''высокая (специальная подгонка энтропии и ASCII)'''
|}
----

== Принципы работы ==

=== Поток данных в одиночном режиме ===
[[Файл:Mieru-single-flow.png|центр|450x450пкс|Поток данных одиночного mieru: клиент → SOCKS5 → mieru → шифр → mita → интернет]]
<pre>
клиентское локальный шифрованный сервер интернет
приложение прокси-демон туннель (опц. через
(браузер, mieru protocol другой прокси
мессенджер) (TCP или UDP) для egress)
┌────────┐ SOCKS5 ┌─────────────┐ AEAD ┌──────────┐ открытый ┌──────────┐
│ app │────────►│ mieru │ ───────► │ mita │ TCP/UDP │ целевой │
│ │ :1080 │ (клиент) │ │ (сервер) │ ──────────► │ сайт/IP │
└────────┘ └─────────────┘ └──────────┘ └──────────┘
▲
│ конфиг с user/password
│ → AEAD-ключ детерминированно
│ из (user, password, time)
</pre>

=== Каскадный режим (двухзвенный) ===
В каскаде роль обычного «сервера» выполняют два узла. Первый принимает клиентов и не выходит в интернет напрямую; вместо этого он переправляет уже расшифрованный трафик во второй узел через тот же протокол mieru. Второй узел осуществляет финальный egress.
[[Файл:Mieru-cascade-flow.png|центр|600x600пкс|Поток данных каскадного mieru: Сервер A (frontend) → Сервер B (backend) → egress]]
<pre>
Сервер A (frontend) Сервер B (backend)
┌─────────────────────────┐ ┌─────────────────────────┐
│ │ │ │
┌────────┐ │ ┌──────────────────┐ │ mieru protocol │ ┌──────────────────┐ │
│клиент │ │ │ mita server │ │ (TCP) │ │ mita server │ │
│mieru- │ ─► │ │ :2012-2022 │ │ │ │ :2012-2022 │ │
│capable │ │ │ users[] = N │ │ │ │ users[] = 1 │ │
└────────┘ │ └──────────┬───────┘ │ │ └──────────┬───────┘ │
│ │ │ │ │ │
│ ▼ socks5 │ │ ▼ socks5 │
│ ┌──────────────────┐ │ │ ┌──────────────────┐ │
│ │ mieru client │ ───┼──────────────────┼─►│ (один user: │ │
│ │ :1080 localhost │ │ зашифрованный │ │ "frontend- │ │
│ │ user="frontend- │ │ туннель │ │ bridge") │ │
│ │ bridge" │ │ │ └──────────┬───────┘ │
│ └──────────────────┘ │ │ │ │
└─────────────────────────┘ │ ▼ │
│ ┌──────────────────┐ │
│ │ egress (любой │ │
│ │ SOCKS5 / TUN / │ │
│ │ прямой выход) │ │
│ └──────────┬───────┘ │
└─────────────┼────────────┘
▼
интернет
</pre>

=== Зачем разделять frontend и backend ===

* Адрес backend-сервера никогда не виден клиентскому ПО. Если frontend замечен и заблокирован — backend остаётся неизвестным наблюдателям и переиспользуется со следующим frontend.
* Frontend хранит '''только''' учётки клиентов и не имеет финального egress. Компрометация его конфига не раскрывает финальный IP.
* Двойное шифрование mieru на каждом плече: каждый сегмент дважды проходит AEAD с разными ключами, что усложняет статистический анализ.

=== Шифрование и аутентификация ===
{| class="wikitable"
!Параметр
!Значение
|-
|Алгоритм
|XChaCha20-Poly1305 (AEAD) с 24-байтным nonce
|-
|Длина ключа
|32 байта
|-
|Метод выработки ключа
|PBKDF2-SHA256, 64 итерации, соль = SHA-256 от текущего времени, округлённого до 2 минут
|-
|Идентификатор пользователя в пакете
|Последние 4 байта nonce заменены на префикс SHA-256 от <code>username + nonce[0:16]</code>; имя пользователя на провод не передаётся
|-
|Защита от reuse
|Проверка nonce-кэша на серверной стороне; повторный пакет отбрасывается
|}
Ключ шифрования '''не передаётся''' через канал и нигде не хранится в виде сериализованной строки: он каждый раз генерируется на лету из пары логин+пароль и текущего времени. Из этого следует одно практическое требование, которое легко не заметить.

==== Требование к синхронизации часов ====
Расхождение системного времени клиента и сервера '''не должно превышать 4 минуты'''. При большем расхождении ключ, выработанный клиентом, не сойдётся с ключом сервера, и подключения будут '''молча''' падать (без явной ошибки в логах). На обоих серверах и на клиентском устройстве должен работать NTP-демон.

=== Формат сегмента ===
[[Файл:Mieru-segment-format.png|центр|500x500пкс|Формат сегмента mieru: padding, nonce, шифр-метаданные, шифр-полезная нагрузка]]
<pre>
| pad0 | nonce | enc-meta | tag | pad1 | enc-payload | tag | pad2 |
| ? | 0 или 24| 32 | 16 | ? | до 32 КБ | 16 | ? |
▲ ▲ ▲
│ │ │
│ │ └── произвольный мусор
│ └── случайной длины разрыв (тоже шифр-нейтральный)
│
└── динамическая «прелюдия»: либо случайные байты,
либо ASCII-строка (см. traffic pattern)
</pre>Ключевое отличие от других протоколов: '''ВСЕ''' структурные поля сегмента (тип, размер, sequence number, ID сессии и пр.) находятся внутри поля <code>enc-meta</code> — то есть зашифрованы. Снаружи невозможно даже определить, что это за пакет, какой длины полезная нагрузка, в начале или в середине сессии находится клиент. Видны только три зоны паддинга и зашифрованные блобы.

=== Traffic pattern (опциональная подгонка маскировки) ===
mieru предоставляет два независимых механизма для подмены статистических признаков шифр-трафика на «обычные»:
{| class="wikitable"
!Опция
!Что делает
!Накладные расходы
|-
|<code>tcpFragment</code>
|Дробит TCP-пакеты на мелкие куски и вставляет случайную задержку между ними. Цель — сломать узнаваемость «один большой шифр-стрим»
| +латентность до <code>maxSleepMs</code> мс на каждый фрагмент
|-
|<code>nonce.NONCE_TYPE_PRINTABLE</code>
|Подменяет первые N байт nonce печатными ASCII-символами. Цель — увести классификатор «высокая энтропия от нулевого байта» в ложное «это текстовый протокол»
|почти ноль (только подмена байтов)
|-
|<code>nonce.NONCE_TYPE_FIXED</code>
|Подменяет первые байты nonce фиксированными hex-строками из списка. Цель — имитировать конкретный фиксированный заголовок
|ноль
|}
Включение traffic pattern имеет смысл '''только''' на видимом анализатором плече (клиент → frontend). На внутреннем плече каскада (frontend → backend) это лишний overhead.

=== Многопользовательский режим ===
Один сервер mita может обслуживать неограниченное число учёток одновременно. Каждый user — это пара <code>(name, password)</code>; лимит по числу одновременных сессий внутри одной учётки '''не задан в протоколе''' (можно опционально настраивать квоты по объёму трафика).
[[Файл:Mieru-multi-user.png|центр|450x450пкс|Многопользовательский режим: один сервер mita обслуживает несколько учёток одновременно]]
<pre>
Сервер A (frontend)
┌──────────────────────────────────────────────┐
│ mita server │
│ слушает :2012-2022 │
│ │
│ users[]: │
│ ┌────────────┬────────────┬────────────┐ │
│ │ alice │ bob │ carol │ │
│ │ pwd_alice │ pwd_bob │ pwd_carol │ │
│ └─────┬──────┴─────┬──────┴─────┬──────┘ │
│ │ │ │ │
│ └────────────┼────────────┘ │
│ ▼ │
│ один общий outbound │
│ (egress на следующий узел) │
└──────────────────────────────────────────────┘
</pre>Такая модель радикально отличается от mash-/torch-протоколов с архитектурой «один сервер — один пользователь»: вам '''не нужно''' создавать отдельный контейнер на каждого пользователя.
----

== Что должно быть на серверах перед установкой ==

=== Минимальная конфигурация каждого сервера ===
{| class="wikitable"
!№
!Требование
!Зачем
|-
|1
|Linux дистрибутив (Ubuntu 22.04+, Debian 12+, Fedora 38+ или сравнимый)
|Среда выполнения Docker
|-
|2
|SSH-доступ с правами <code>root</code> либо аккаунт с <code>sudo</code> без пароля
|Установка пакетов и управление контейнерами
|-
|3
|Docker Engine 24.0+ и плагин Docker Compose v2.20+
|Запуск контейнеров mita и mieru
|-
|4
|NTP-демон активен (<code>chrony</code> или <code>systemd-timesyncd</code>)
|Синхронизация часов в пределах 4 минут (см. раздел «Шифрование»)
|-
|5
|Открытый наружу TCP-диапазон (для нашей статьи — <code>2012-2022</code>)
|Принимающий порт mita
|}

=== Опциональная конфигурация: egress через сторонний прокси ===
По умолчанию backend-сервер выходит в интернет напрямую с публичного IP виртуальной машины. В качестве промежуточной цепочки часто используется выделенный SOCKS5-прокси, обслуживаемый сторонней панелью (например, '''3x-ui''' над xray-core).
{| class="wikitable"
!№
!Параметр
!Пример
!Комментарий
|-
|1
|SOCKS5-inbound, слушающий '''только на <code>172.17.0.1</code>''' (docker0-bridge gateway)
|порт <code>24366</code>
|Слушать на <code>127.0.0.1</code> '''не подойдёт''': контейнер mita с <code>network_mode: host</code> увидит нужный адрес именно как <code>172.17.0.1</code>
|-
|2
|Аутентификация на этом inbound отключена
|—
|Можно включить и прописать креды в <code>egress.proxies</code> mita, но без авторизации проще
|-
|3
|Routing-rule: трафик с этого inbound → нужный outbound (например, WireGuard-к-WARP, наружный VPN, сторонний прокси)
|—
|Зависит от вашей панели; в 3x-ui — раздел «Маршрутизация»
|}

==== Проверка egress-цепочки ====
Команда выполняется на самом backend-сервере. Заменить <code>24366</code> на ваш порт.<syntaxhighlight lang="bash">
docker run --rm curlimages/curl:latest --max-time 12 --socks5 172.17.0.1:24366 https://icanhazip.com
</syntaxhighlight>Ожидание: IP вашего egress-узла (например, IP Cloudflare WARP или IP стороннего VPN). Если возвращается публичный IP вашей VM — egress не работает, проверьте routing панели.

Если egress через сторонний прокси не нужен (готовы выходить с публичного IP backend-сервера) — пропустите этот раздел; в дальнейших шагах указания «без egress» помечены явно.
----

== Параметры, которые нужно подготовить заранее ==
Перед началом установки заполните таблицу собственными значениями. На каждом шаге, где встретится плейсхолдер, мы будем ссылаться на эту таблицу.
{| class="wikitable"
!Плейсхолдер
!Что это
!Пример
|-
|<code>YOUR_FRONTEND_HOST</code>
|Адрес frontend-сервера для SSH (IP, имя из <code>~/.ssh/config</code> либо домен)
|<code>198.51.100.10</code>
|-
|<code>YOUR_BACKEND_HOST</code>
|Адрес backend-сервера для SSH
|<code>203.0.113.20</code>
|-
|<code>YOUR_BACKEND_PUBLIC_IP</code>
|Публичный IP backend-сервера, к которому будет коннектиться mieru-client с frontend
|<code>203.0.113.20</code>
|-
|<code>YOUR_FRONTEND_PUBLIC_IP</code>
|Публичный IP frontend-сервера, к которому будут коннектиться клиенты
|<code>198.51.100.10</code>
|-
|<code>YOUR_BRIDGE_PASSWORD</code>
|Пароль учётки mieru, которой mieru-client на frontend подключается к mita на backend. Один на оба узла
|длинная случайная строка, сгенерированная <code>openssl rand</code>
|-
|<code>YOUR_CLIENT_PASSWORD</code>
|Пароль первой клиентской учётки <code>client01</code> на frontend
|длинная случайная строка
|-
|<code>YOUR_EGRESS_HOST</code>
|Адрес SOCKS5-egress на backend (если используете)
|<code>172.17.0.1</code>
|-
|<code>YOUR_EGRESS_PORT</code>
|Порт SOCKS5-egress
|<code>24366</code>
|}
Сохраните таблицу в надёжное место — особенно пароли. Без них восстановить рабочее состояние нельзя.
----

== Установка backend-сервера (точка выхода) ==
Все команды этого раздела выполняются на backend-сервере по SSH. Каждое пояснение — одна команда.

=== Шаг 1. Подключение по SSH ===
<syntaxhighlight lang="bash">
ssh root@YOUR_BACKEND_HOST
</syntaxhighlight>

=== Шаг 2. Проверка Docker ===
<syntaxhighlight lang="bash">
docker --version
</syntaxhighlight>Если выведено <code>Docker version 24.0.x</code> или новее — переходите к шагу 3. Если <code>command not found</code> — установите Docker по официальной инструкции для вашей ОС: <code>https://docs.docker.com/engine/install/</code>. После установки вернитесь сюда.

Дополнительно проверьте плагин Compose.<syntaxhighlight lang="bash">
docker compose version
</syntaxhighlight>

=== Шаг 3. Создание рабочего каталога ===
<syntaxhighlight lang="bash">
mkdir -p /opt/mieru-backend
</syntaxhighlight><syntaxhighlight lang="bash">
cd /opt/mieru-backend
</syntaxhighlight>

=== Шаг 4. Создание Dockerfile ===
Откройте файл для редактирования.<syntaxhighlight lang="bash">
nano /opt/mieru-backend/Dockerfile
</syntaxhighlight>Вставьте следующее содержимое полностью.<syntaxhighlight lang="dockerfile">
ARG MIERU_VERSION=3.32.0
ARG TARGETARCH=amd64

FROM alpine:3.19 AS downloader
ARG MIERU_VERSION
ARG TARGETARCH
RUN apk add --no-cache ca-certificates wget
WORKDIR /tmp/mita
RUN wget -qO- "https://github.com/enfein/mieru/releases/download/v${MIERU_VERSION}/mita_${MIERU_VERSION}_linux_${TARGETARCH}.tar.gz" | tar xz
WORKDIR /tmp/mieru
RUN wget -qO- "https://github.com/enfein/mieru/releases/download/v${MIERU_VERSION}/mieru_${MIERU_VERSION}_linux_${TARGETARCH}.tar.gz" | tar xz

FROM alpine:3.19
RUN apk add --no-cache ca-certificates tini && \
adduser -H -D -g "" mita && \
adduser -H -D -g "" mieru
COPY --from=downloader /tmp/mita/mita /usr/local/bin/mita
COPY --from=downloader /tmp/mieru/mieru /usr/local/bin/mieru
RUN chmod +x /usr/local/bin/mita /usr/local/bin/mieru && \
mkdir -p /etc/mita /var/lib/mita /var/run/mita \
/etc/mieru /var/lib/mieru /var/run/mieru /srv && \
chown -R mita:mita /etc/mita /var/lib/mita /var/run/mita && \
chown -R mieru:mieru /etc/mieru /var/lib/mieru /var/run/mieru
COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
ENTRYPOINT ["/sbin/tini","--","/usr/local/bin/docker-entrypoint.sh"]
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

=== Шаг 5. Создание скрипта-entrypoint ===
<syntaxhighlight lang="bash">
nano /opt/mieru-backend/docker-entrypoint.sh
</syntaxhighlight>Вставьте полное содержимое.<syntaxhighlight lang="bash">
#!/bin/sh
set -eu

MODE="${MIERU_MODE:-mita}"
CONFIG_FILE="${MIERU_CONFIG:-/srv/config.json}"

case "$MODE" in
mita) BIN=mita ;;
mieru) BIN=mieru ;;
*) echo "[entrypoint] FATAL: MIERU_MODE='$MODE' (mita или mieru)"; exit 1 ;;
esac

if [ ! -f "$CONFIG_FILE" ]; then
echo "[entrypoint] WARN: $CONFIG_FILE не найден"
fi

if [ "$MODE" = "mieru" ]; then
if [ -f "$CONFIG_FILE" ]; then
mieru apply config "$CONFIG_FILE" 2>&1
fi
exec mieru run
else
apply_via_rpc() {
i=0
while [ "$i" -lt 30 ]; do
i=$((i+1)); sleep 1
if [ -f "$CONFIG_FILE" ] && mita apply config "$CONFIG_FILE" >/tmp/apply.out 2>&1; then
mita start >/tmp/start.out 2>&1
return 0
fi
done
}
apply_via_rpc &
exec mita run
fi
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

Дайте файлу права на исполнение.<syntaxhighlight lang="bash">
chmod +x /opt/mieru-backend/docker-entrypoint.sh
</syntaxhighlight>

=== Шаг 6. Генерация пароля для bridge-учётки ===
<syntaxhighlight lang="bash">
openssl rand -base64 24 | tr -d '=/+' | head -c 31
</syntaxhighlight>Команда выведет одну строку из 31 символа. Скопируйте её и впишите в подготовленную таблицу как <code>YOUR_BRIDGE_PASSWORD</code>. Этот же пароль понадобится на frontend-сервере (шаг ниже).

=== Шаг 7. Создание серверного конфига ===
<syntaxhighlight lang="bash">
nano /opt/mieru-backend/server.json
</syntaxhighlight>Вставьте содержимое и замените <code>YOUR_BRIDGE_PASSWORD</code> на скопированное значение из шага 6.

Если вы '''используете''' egress через сторонний SOCKS5-прокси — оставьте секцию <code>egress</code> как есть и при необходимости подправьте <code>host</code> и <code>port</code>. Если '''не используете''' — удалите всю секцию <code>egress</code> от открывающей до закрывающей фигурной скобки.<syntaxhighlight lang="json">
{
"portBindings": [
{"portRange": "2012-2022", "protocol": "TCP"}
],
"users": [
{"name": "frontend-bridge", "password": "YOUR_BRIDGE_PASSWORD"}
],
"loggingLevel": "INFO",
"mtu": 1380,
"egress": {
"proxies": [
{
"name": "external-egress",
"protocol": "SOCKS5_PROXY_PROTOCOL",
"host": "172.17.0.1",
"port": 24366
}
],
"rules": [
{
"ipRanges": ["*"],
"domainNames": ["*"],
"action": "PROXY",
"proxyNames": ["external-egress"]
}
]
}
}
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

Защитите файл (содержит пароль).<syntaxhighlight lang="bash">
chmod 600 /opt/mieru-backend/server.json
</syntaxhighlight>

=== Шаг 8. Создание docker-compose.yml ===
<syntaxhighlight lang="bash">
nano /opt/mieru-backend/docker-compose.yml
</syntaxhighlight>Вставьте.<syntaxhighlight lang="yaml">
services:
mita:
build:
context: .
args:
MIERU_VERSION: "3.32.0"
image: mieru-bundle:3.32.0
container_name: mita-backend
restart: unless-stopped
network_mode: host
environment:
MIERU_MODE: mita
MIERU_CONFIG: /srv/server.json
volumes:
- ./server.json:/srv/server.json:ro
- mita-state:/etc/mita
- mita-runtime:/var/run/mita
- mita-data:/var/lib/mita
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"

volumes:
mita-state:
mita-runtime:
mita-data:
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

=== Шаг 9. Сборка образа ===
<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml build
</syntaxhighlight>Сборка длится 1–3 минуты. По завершении выводится <code>Image mieru-bundle:3.32.0 Built</code>.

=== Шаг 10. Запуск ===
<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml up -d
</syntaxhighlight>Подождите 10 секунд.<syntaxhighlight lang="bash">
sleep 10
</syntaxhighlight>Проверьте логи.<syntaxhighlight lang="bash">
docker logs mita-backend --tail 25
</syntaxhighlight>Ожидаемые строки:
[entrypoint] config применён (/srv/server.json)
[entrypoint] mita start: OK
mita server status is "RUNNING"
Проверьте, что сервер слушает порты <code>2012-2022</code>.<syntaxhighlight lang="bash">
ss -tlnp | grep -E ':20(1[2-9]|2[012]) '
</syntaxhighlight>Должны появиться 11 строк со статусом <code>LISTEN</code> и пользователем <code>mita</code>. Если их нет — обратитесь к разделу «Поиск проблем».
----

== Установка frontend-сервера (точка входа) ==
Все команды этого раздела выполняются на frontend-сервере по SSH.

=== Шаг 1. Подключение и подготовка ===
<syntaxhighlight lang="bash">
ssh root@YOUR_FRONTEND_HOST
</syntaxhighlight><syntaxhighlight lang="bash">
mkdir -p /opt/mieru-frontend && cd /opt/mieru-frontend
</syntaxhighlight>

=== Шаг 2. Dockerfile и entrypoint (одинаковые с backend) ===
Создайте оба файла так же, как на backend-сервере (см. шаги 4–5 раздела «Установка backend-сервера»). Содержимое идентично — образ универсальный, режим работы выбирается переменной окружения.<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/Dockerfile
</syntaxhighlight>(вставьте тот же Dockerfile, что на backend)<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/docker-entrypoint.sh
</syntaxhighlight>(вставьте тот же entrypoint)<syntaxhighlight lang="bash">
chmod +x /opt/mieru-frontend/docker-entrypoint.sh
</syntaxhighlight>

=== Шаг 3. Генерация пароля первой клиентской учётки ===
<syntaxhighlight lang="bash">
openssl rand -base64 24 | tr -d '=/+' | head -c 31
</syntaxhighlight>Скопируйте результат и впишите в таблицу как <code>YOUR_CLIENT_PASSWORD</code>. Это пароль учётки <code>client01</code>, который вы потом отдадите своему первому клиентскому устройству.

=== Шаг 4. Серверный конфиг (mita-frontend) ===
<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/server.json
</syntaxhighlight>Замените <code>YOUR_CLIENT_PASSWORD</code> на значение из шага 3.<syntaxhighlight lang="json">
{
"portBindings": [
{"portRange": "2012-2022", "protocol": "TCP"}
],
"users": [
{"name": "client01", "password": "YOUR_CLIENT_PASSWORD"}
],
"loggingLevel": "INFO",
"mtu": 1380,
"trafficPattern": {
"unlockAll": false,
"tcpFragment": {"enable": true, "maxSleepMs": 10},
"nonce": {
"type": "NONCE_TYPE_PRINTABLE",
"minLen": 6,
"maxLen": 8
}
},
"egress": {
"proxies": [
{
"name": "to-backend",
"protocol": "SOCKS5_PROXY_PROTOCOL",
"host": "127.0.0.1",
"port": 1080
}
],
"rules": [
{
"ipRanges": ["*"],
"domainNames": ["*"],
"action": "PROXY",
"proxyNames": ["to-backend"]
}
]
}
}
</syntaxhighlight>Сохраните и защитите файл.<syntaxhighlight lang="bash">
chmod 600 /opt/mieru-frontend/server.json
</syntaxhighlight>

=== Шаг 5. Клиентский конфиг (mieru-client) ===
<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/client.json
</syntaxhighlight>Замените <code>YOUR_BACKEND_PUBLIC_IP</code> на публичный IP backend-сервера, <code>YOUR_BRIDGE_PASSWORD</code> — на пароль bridge-учётки, который вы создавали на backend в шаге 6.<syntaxhighlight lang="json">
{
"profiles": [
{
"profileName": "default",
"user": {
"name": "frontend-bridge",
"password": "YOUR_BRIDGE_PASSWORD"
},
"servers": [
{
"ipAddress": "YOUR_BACKEND_PUBLIC_IP",
"portBindings": [
{"portRange": "2012-2022", "protocol": "TCP"}
]
}
],
"mtu": 1380,
"multiplexing": {"level": "MULTIPLEXING_HIGH"},
"handshakeMode": "HANDSHAKE_NO_WAIT"
}
],
"activeProfile": "default",
"rpcPort": 8964,
"socks5Port": 1080,
"loggingLevel": "INFO",
"socks5ListenLAN": false,
"httpProxyListenLAN": false
}
</syntaxhighlight>Сохраните и защитите файл.<syntaxhighlight lang="bash">
chmod 600 /opt/mieru-frontend/client.json
</syntaxhighlight>

=== Шаг 6. docker-compose.yml на frontend ===
<syntaxhighlight lang="bash">
nano /opt/mieru-frontend/docker-compose.yml
</syntaxhighlight>Вставьте.<syntaxhighlight lang="yaml">
services:
mieru-client:
build:
context: .
args:
MIERU_VERSION: "3.32.0"
image: mieru-bundle:3.32.0
container_name: mieru-client
restart: unless-stopped
network_mode: host
environment:
MIERU_MODE: mieru
MIERU_CONFIG: /srv/client.json
volumes:
- ./client.json:/srv/client.json:ro
- mieru-client-state:/etc/mieru
- mieru-client-runtime:/var/run/mieru
- mieru-client-data:/var/lib/mieru
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"

mita:
image: mieru-bundle:3.32.0
container_name: mita-frontend
restart: unless-stopped
network_mode: host
depends_on:
- mieru-client
environment:
MIERU_MODE: mita
MIERU_CONFIG: /srv/server.json
volumes:
- ./server.json:/srv/server.json:ro
- mita-state:/etc/mita
- mita-runtime:/var/run/mita
- mita-data:/var/lib/mita
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"

volumes:
mieru-client-state:
mieru-client-runtime:
mieru-client-data:
mita-state:
mita-runtime:
mita-data:
</syntaxhighlight>Сохраните.

=== Шаг 7. Сборка и запуск ===
<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-frontend/docker-compose.yml build
</syntaxhighlight><syntaxhighlight lang="bash">
docker compose -f /opt/mieru-frontend/docker-compose.yml up -d
</syntaxhighlight><syntaxhighlight lang="bash">
sleep 12
</syntaxhighlight>

=== Шаг 8. Проверка ===
<syntaxhighlight lang="bash">
docker logs mieru-client --tail 10
</syntaxhighlight>Должна быть строка <code>mieru: config применён</code> и затем <code>запуск mieru run</code>.<syntaxhighlight lang="bash">
docker logs mita-frontend --tail 10
</syntaxhighlight>Должно быть <code>RUNNING</code> и <code>mita start: OK</code>.<syntaxhighlight lang="bash">
docker exec mieru-client mieru status
</syntaxhighlight>Ожидание: <code>mieru client is running</code>.<syntaxhighlight lang="bash">
docker exec mita-frontend mita status
</syntaxhighlight>Ожидание: <code>mita server status is "RUNNING"</code>.

=== Шаг 9. Сквозной тест каскада ===
С frontend-сервера обратитесь во внешний интернет через локальный SOCKS5 mieru-client. Это эквивалент того, как пойдёт реальный клиентский запрос.<syntaxhighlight lang="bash">
curl -sS --max-time 30 --proxy socks5h://127.0.0.1:1080 https://icanhazip.com
</syntaxhighlight>Ожидание: IP вашего egress-узла. Например, IP Cloudflare WARP, если на backend настроен такой outbound. Команда '''не должна''' возвращать публичный IP frontend-сервера.

Контрольный замер прямого IP frontend для сравнения.<syntaxhighlight lang="bash">
curl -sS --max-time 5 https://icanhazip.com
</syntaxhighlight>Если первый IP отличается от второго — каскад работает.
----

== Подключение клиентов ==
mieru имеет два равнозначных формата отдачи параметров клиенту: '''Clash/Mihomo YAML''' и '''<code>mierus://</code> URI'''. На практике YAML более переносим — его понимает большинство клиентов в одном виде, тогда как URI разбирается каждым приложением по-своему.

=== Десктоп: Clash Verge Rev / Mihomo Party / NekoBox ===
Создайте новый профиль (или отредактируйте существующий) и добавьте блок <code>proxies</code>:<syntaxhighlight lang="yaml">
proxies:
- name: mieru-frontend
type: mieru
server: YOUR_FRONTEND_PUBLIC_IP
port: 2022
username: client01
password: YOUR_CLIENT_PASSWORD
multiplexing: MULTIPLEXING_HIGH
</syntaxhighlight>Параметр <code>port: 2022</code> — это один из портов из диапазона <code>2012-2022</code>; mita слушает все 11 параллельно, клиент использует один (мультиплексор).

=== Мобильные: Karing / ClashMi / NekoBox+plugin / husi ===
Подключение через тот же YAML-блок выше — большинство клиентов поддерживают вставку YAML вручную в раздел «Серверы» или «Outbounds». Сценарий импорта URI в Karing 1.2.x работает плохо (поле порта обнуляется), поэтому YAML предпочтительнее.

=== Универсальный URI-формат ===
<syntaxhighlight>
mierus://client01:YOUR_CLIENT_PASSWORD@YOUR_FRONTEND_PUBLIC_IP?port=2022&protocol=TCP&mtu=1380&multiplexing=MULTIPLEXING_HIGH&handshake-mode=HANDSHAKE_NO_WAIT
</syntaxhighlight>Подходит для нативного <code>mieru</code> CLI, husi с mieru-плагином, Exclave.
----

== Подключение клиента на OpenWrt-роутере ==
Если на роутере уже стоит трафик-менеджер (например, podkop), и вы хотите, чтобы он отправлял трафик через mieru — поставьте на роутер standalone mieru-клиент с локальным SOCKS5, и подкоп цепляйте к этому SOCKS5.

=== Шаг 1. Подключение к роутеру ===
<syntaxhighlight lang="bash">
ssh root@YOUR_ROUTER_HOST
</syntaxhighlight>

=== Шаг 2. Скачивание бинаря ===
Архитектура роутера большинства современных моделей — <code>aarch64</code>. Если ваш роутер — другой (например, <code>mips</code>), проверьте список релизов <code>https://github.com/enfein/mieru/releases/latest</code> и подставьте нужный артефакт в команду.<syntaxhighlight lang="bash">
cd /tmp && wget -q https://github.com/enfein/mieru/releases/download/v3.32.0/mieru_3.32.0_linux_arm64.tar.gz -O mieru.tar.gz
</syntaxhighlight><syntaxhighlight lang="bash">
tar xzf mieru.tar.gz && mv mieru /usr/bin/mieru && chmod +x /usr/bin/mieru && rm -f /tmp/mieru.tar.gz /tmp/LICENSE /tmp/README.md
</syntaxhighlight><syntaxhighlight lang="bash">
/usr/bin/mieru version
</syntaxhighlight>Должно вывести <code>3.32.0</code>.

=== Шаг 3. Клиентский конфиг ===
<syntaxhighlight lang="bash">
nano /etc/mieru_client_config.json
</syntaxhighlight>Вставьте, заменив плейсхолдеры:<syntaxhighlight lang="json">
{
"profiles": [
{
"profileName": "default",
"user": {
"name": "client01",
"password": "YOUR_CLIENT_PASSWORD"
},
"servers": [
{
"ipAddress": "YOUR_FRONTEND_PUBLIC_IP",
"portBindings": [
{"portRange": "2012-2022", "protocol": "TCP"}
]
}
],
"mtu": 1380,
"multiplexing": {"level": "MULTIPLEXING_HIGH"},
"handshakeMode": "HANDSHAKE_NO_WAIT",
"trafficPattern": {
"unlockAll": false,
"tcpFragment": {"enable": true, "maxSleepMs": 10},
"nonce": {
"type": "NONCE_TYPE_PRINTABLE",
"minLen": 6,
"maxLen": 8
}
}
}
],
"activeProfile": "default",
"rpcPort": 8964,
"socks5Port": 1090,
"loggingLevel": "ERROR",
"socks5ListenLAN": false,
"httpProxyListenLAN": false
}
</syntaxhighlight>Сохраните и защитите файл.<syntaxhighlight lang="bash">
chmod 600 /etc/mieru_client_config.json
</syntaxhighlight>Ключевые отличия конфига для роутера от десктопного клиента:

* <code>socks5Port: 1090</code> — порт <code>1080</code> часто занят другими прокси (например, naive); 1090 свободен.
* <code>loggingLevel: "ERROR"</code> — overlay на роутерах маленький, ограничение логов защищает от заполнения диска.
* <code>trafficPattern</code> включён полностью — на пути «роутер → frontend» классификатор смотрит, маскировка нужна.

=== Шаг 4. Init.d-скрипт ===
OpenWrt использует procd; в отличие от mita, на OpenWrt mieru читает JSON-конфиг напрямую через переменную <code>MIERU_CONFIG_JSON_FILE</code>, и команды <code>mieru apply config</code> и <code>mieru describe config</code> '''не используются'''.<syntaxhighlight lang="bash">
nano /etc/init.d/mieru
</syntaxhighlight>Вставьте.<syntaxhighlight lang="bash">
#!/bin/sh /etc/rc.common

START=99
STOP=01

MIERU_BIN="/usr/bin/mieru"
MIERU_CONFIG="/etc/mieru_client_config.json"
PID_FILE="/var/run/mieru.pid"

start() {
echo "Starting mieru client..."
export MIERU_CONFIG_JSON_FILE=$MIERU_CONFIG
start-stop-daemon -S -b -m -p "$PID_FILE" -x "$MIERU_BIN" -- run
RC=$?
if [ $RC -eq 0 ]; then
echo "mieru client is started"
exit 0
else
echo "failed to start mieru client"
exit $RC
fi
}

stop() {
echo "Stopping mieru client..."
start-stop-daemon -K -p "$PID_FILE"
RC=$?
if [ $RC -eq 0 ]; then
echo "mieru client is stopped"
rm -f "$PID_FILE"
else
echo "failed to stop mieru client"
fi
}
</syntaxhighlight>Сохраните и сделайте исполняемым.<syntaxhighlight lang="bash">
chmod +x /etc/init.d/mieru
</syntaxhighlight>

=== Шаг 5. Запуск и автозапуск ===
<syntaxhighlight lang="bash">
/etc/init.d/mieru enable
</syntaxhighlight><syntaxhighlight lang="bash">
/etc/init.d/mieru start
</syntaxhighlight>

=== Шаг 6. Проверка ===
<syntaxhighlight lang="bash">
ps | grep mieru | grep -v grep
</syntaxhighlight>Должна быть одна строка с процессом <code>/usr/bin/mieru run</code>.<syntaxhighlight lang="bash">
netstat -tlnp 2>/dev/null | grep 1090
</syntaxhighlight>Должна быть строка <code>127.0.0.1:1090 ... LISTEN ... mieru</code>.<syntaxhighlight lang="bash">
curl -sS --max-time 30 -x socks5h://127.0.0.1:1090 https://icanhazip.com
</syntaxhighlight>Должен вернуть IP egress-узла каскада.

=== Шаг 7. Подключение podkop к локальному mieru ===
В LuCI откройте подкоп. Создайте новую секцию или измените существующую:
{| class="wikitable"
!Поле
!Значение
|-
|Тип конфига
|URL
|-
|Proxy string
|<code>socks5://127.0.0.1:1090</code>
|}
Эквивалент через <code>uci</code>:<syntaxhighlight lang="bash">
uci set podkop.10=section
uci set podkop.10.connection_type='proxy'
uci set podkop.10.proxy_config_type='url'
uci set podkop.10.proxy_string='socks5://127.0.0.1:1090'
uci commit podkop
service podkop restart
</syntaxhighlight>Подкоп отправляет mieru-серверу обычный SOCKS5-запрос на <code>127.0.0.1:1090</code>; mieru шифрует его и отправляет через каскад.
----

== Управление пользователями: скрипт <code>mieru-users.sh</code> ==

=== Зачем он нужен ===
mita-сервер хранит список учёток в файле <code>server.json</code>. Чтобы добавлять/удалять/смотреть пользователей вручную каждый раз — много шагов: jq-правка JSON, вызов <code>mita apply config</code>, генерация ссылки клиенту, опционально <code>mita delete user</code> для разрыва активных сессий. Скрипт <code>mieru-users.sh</code> автоматизирует это всё.

=== Что делает скрипт ===
{| class="wikitable"
!Пункт меню
!Действие
|-
|1. Список пользователей
|Чтение <code>server.json</code> + опрос <code>mita get connections</code> для активных сессий
|-
|2. Добавить пользователя
|Запрос имени, генерация пароля через <code>openssl rand</code>, бэкап JSON, <code>jq</code>-вставка, <code>mita apply config</code>, выдача готовых YAML и URI клиенту
|-
|3. Удалить пользователя
|<code>mita delete user</code> для разрыва сессий → <code>jq</code>-удаление из JSON → <code>apply config</code>
|-
|4. Показать URI клиента
|Сборка YAML и URI по выбранному имени
|-
|5. Статус сервера
|<code>mita status</code> + <code>get connections</code> + <code>get metrics</code>
|}

=== Установка скрипта ===
Все команды выполняются на frontend-сервере по SSH.

==== Шаг 1. Загрузка скрипта ====
<syntaxhighlight lang="bash">
nano /usr/local/bin/mieru-users.sh
</syntaxhighlight>Вставьте полное содержимое скрипта (исходный код в спойлере «Исходный код <code>mieru-users.sh</code>» в конце статьи).

Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

==== Шаг 2. Подстановка реального адреса ====
В начале скрипта есть строка <code>SERVER_IP="YOUR_FRONTEND_PUBLIC_IP"</code>. Замените её на реальный IP frontend-сервера.<syntaxhighlight lang="bash">
sed -i 's/YOUR_FRONTEND_PUBLIC_IP/198.51.100.10/' /usr/local/bin/mieru-users.sh
</syntaxhighlight>(подставьте свой IP вместо <code>198.51.100.10</code>).

==== Шаг 3. Права на исполнение ====
<syntaxhighlight lang="bash">
chmod +x /usr/local/bin/mieru-users.sh
</syntaxhighlight>

==== Шаг 4. Проверка ====
<syntaxhighlight lang="bash">
bash -n /usr/local/bin/mieru-users.sh && echo OK
</syntaxhighlight>Если выводит <code>OK</code> — скрипт установлен корректно.

=== Использование ===
<syntaxhighlight lang="bash">
sudo bash /usr/local/bin/mieru-users.sh
</syntaxhighlight>Появится меню:<pre>
╔══════════════════════════════════════╗
║ mieru User Manager ║
║ IP: 198.51.100.10 ║
╚══════════════════════════════════════╝

Пользователей в конфиге: 1

1. Список пользователей и активных сессий
2. Добавить пользователя
3. Удалить пользователя
4. Показать URI клиента
5. Статус сервера
0. Выход
</pre>После добавления пользователя скрипт выводит готовые конфиги:<pre>
=== Вариант 1: Clash / Mihomo YAML (рекомендую) ===
proxies:
- name: mieru-RU-alice
type: mieru
server: 198.51.100.10
port: 2022
username: alice
password: <автогенерированный>
multiplexing: MULTIPLEXING_HIGH

=== Вариант 2: mierus:// URI ===
mierus://alice:<пароль>@198.51.100.10?port=2022&protocol=TCP&mtu=1380&multiplexing=MULTIPLEXING_HIGH&handshake-mode=HANDSHAKE_NO_WAIT
</pre>
----

== Команды управления ==

=== На обоих серверах ===
Посмотреть логи в реальном времени.<syntaxhighlight lang="bash">
docker logs -f mita-backend # на backend
</syntaxhighlight><syntaxhighlight lang="bash">
docker logs -f mita-frontend mieru-client # на frontend
</syntaxhighlight>Перезапустить.<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml restart # на backend
</syntaxhighlight><syntaxhighlight lang="bash">
docker compose -f /opt/mieru-frontend/docker-compose.yml restart # на frontend
</syntaxhighlight>Остановить.<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml down # на backend
</syntaxhighlight><syntaxhighlight lang="bash">
docker compose -f /opt/mieru-frontend/docker-compose.yml down # на frontend
</syntaxhighlight>Обновить версию mita/mieru. Поменяйте <code>3.32.0</code> на нужную в <code>docker-compose.yml</code> и пересоберите.<syntaxhighlight lang="bash">
docker compose -f /opt/mieru-backend/docker-compose.yml build && docker compose -f /opt/mieru-backend/docker-compose.yml up -d
</syntaxhighlight>

=== Команды mita через CLI (внутри контейнера) ===
<syntaxhighlight lang="bash">
docker exec mita-backend mita status # IDLE / RUNNING
</syntaxhighlight><syntaxhighlight lang="bash">
docker exec mita-backend mita get users # список user'ов и их статистика
</syntaxhighlight><syntaxhighlight lang="bash">
docker exec mita-backend mita get connections # активные сессии
</syntaxhighlight><syntaxhighlight lang="bash">
docker exec mita-backend mita get metrics # метрики
</syntaxhighlight><syntaxhighlight lang="bash">
docker exec mita-backend mita describe config # текущий применённый конфиг
</syntaxhighlight>

=== На OpenWrt-роутере ===
<syntaxhighlight lang="bash">
/etc/init.d/mieru start | stop | restart
</syntaxhighlight><syntaxhighlight lang="bash">
ps | grep mieru | grep -v grep
</syntaxhighlight><syntaxhighlight lang="bash">
logread | grep mieru
</syntaxhighlight>
----

== Поиск проблем ==

=== Симптом: сервер показывает <code>IDLE</code>, порты не слушаются ===
mita после <code>apply config</code> остаётся в <code>IDLE</code> до явной команды <code>mita start</code>. В нашем entrypoint это происходит автоматически, но если что-то пошло не так, выполните вручную внутри контейнера:<syntaxhighlight lang="bash">
docker exec mita-backend mita start
</syntaxhighlight>

=== Симптом: <code>FATAL: getUid("mita") failed</code> ===
В образ не добавлен системный пользователь <code>mita</code>. Проверьте, что Dockerfile содержит строки <code>adduser -H -D -g "" mita</code> и <code>adduser -H -D -g "" mieru</code>, пересоберите образ.

=== Симптом: клиент подключается, но трафик не идёт ===
Проверьте на клиенте время системы. Расхождение более 4 минут с сервером приведёт к молчаливому отказу. Команда на Linux/macOS:<syntaxhighlight lang="bash">
date -u
</syntaxhighlight>Если время существенно расходится — настройте NTP.

=== Симптом: на frontend curl возвращает не egress-IP, а frontend-IP ===
Trafic идёт мимо mieru-client. Возможные причины:

* <code>egress.action</code> в frontend-конфиге — <code>DIRECT</code> вместо <code>PROXY</code>.
* mieru-client не запущен либо упал. Проверьте: <code>docker ps</code>.
* Backend не доступен. Проверьте на frontend: <code>nc -vz YOUR_BACKEND_PUBLIC_IP 2022</code>.

=== Симптом: на frontend curl возвращает frontend-IP, а должен — backend-IP ===
То же самое, что выше: трафик не доходит до backend. Дополнительно посмотрите логи:<syntaxhighlight lang="bash">
docker logs mieru-client --tail 50
</syntaxhighlight>Ошибки <code>TLS handshake</code> здесь невозможны — mieru не использует TLS. Ищите <code>auth failed</code> (неверная пара логин/пароль на mita-backend) и <code>connection refused</code> (backend не слушает).

=== Симптом: на роутере Karing/Clash подключается, но трафик не идёт ===
В первую очередь проверить YAML-конфиг: тип <code>type: mieru</code> (не <code>type: socks5</code>!), порт <code>port: 2022</code> (одиночное число, не диапазон). Многие mihomo-форки не парсят диапазон портов корректно.
----

== Исходный код <code>mieru-users.sh</code> ==
Полный текст скрипта приведён ниже. Скопируйте его целиком в <code>/usr/local/bin/mieru-users.sh</code> на frontend-сервере по инструкции выше.<syntaxhighlight lang="bash">
#!/bin/bash
# mieru-users — управление пользователями mita
# Источник истины: /opt/mieru-frontend/server.json
# Применение через mita apply config (RPC к работающему daemon).

CONFIG_FILE="/opt/mieru-frontend/server.json"
COMPOSE_DIR="/opt/mieru-frontend"
COMPOSE_SVC="mita"
BACKUP_DIR="/opt/mieru-frontend/backups"
BACKUP_KEEP=10
SERVER_IP="YOUR_FRONTEND_PUBLIC_IP"

RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'
CYAN='\033[0;36m'; BOLD='\033[1m'; NC='\033[0m'

check_root() {
if [[ $EUID -ne 0 ]]; then
echo -e "${RED}Запусти от root: sudo bash mieru-users.sh${NC}"; exit 1
fi
}

check_deps() {
for c in jq docker openssl; do
if ! command -v "$c" >/dev/null 2>&1; then
echo -e "${RED}Не найдено: $c${NC}"; exit 1
fi
done
if [[ ! -f "$CONFIG_FILE" ]]; then
echo -e "${RED}Не найден $CONFIG_FILE${NC}"; exit 1
fi
}

mita_cli() {
docker compose -f "$COMPOSE_DIR/docker-compose.yml" exec -T "$COMPOSE_SVC" mita "$@"
}

backup_config() {
mkdir -p "$BACKUP_DIR"
local stamp; stamp=$(date +%Y%m%d-%H%M%S)
cp "$CONFIG_FILE" "$BACKUP_DIR/server-$stamp.json"
ls -1t "$BACKUP_DIR"/server-*.json 2>/dev/null | tail -n +$((BACKUP_KEEP+1)) | xargs -r rm -f
}

apply_config() {
if ! mita_cli apply config /srv/server.json 2>&1; then
echo -e "${RED}mita apply config упал. Откатываюсь к последнему бэкапу.${NC}"
local last; last=$(ls -1t "$BACKUP_DIR"/server-*.json 2>/dev/null | head -1)
if [[ -n "$last" ]]; then
cp "$last" "$CONFIG_FILE"
mita_cli apply config /srv/server.json >/dev/null 2>&1 || true
fi
return 1
fi
return 0
}

press_enter() { echo ""; read -rp "Enter для возврата..."; }

generate_password() {
openssl rand -base64 24 | tr -d '=/+' | head -c 31
}

generate_uri() {
echo "mierus://${1}:${2}@${SERVER_IP}?port=2022&protocol=TCP&mtu=1380&multiplexing=MULTIPLEXING_HIGH&handshake-mode=HANDSHAKE_NO_WAIT"
}

generate_yaml() {
cat <<EOF
proxies:
- name: mieru-${1}
type: mieru
server: ${SERVER_IP}
port: 2022
username: ${1}
password: ${2}
multiplexing: MULTIPLEXING_HIGH
EOF
}

print_uri_for() {
echo ""
echo -e "${CYAN}=== Вариант 1: Clash / Mihomo YAML ===${NC}"
echo -e "${BOLD}$(generate_yaml "$1" "$2")${NC}"
echo ""
echo -e "${CYAN}=== Вариант 2: mierus:// URI ===${NC}"
echo -e "${BOLD} $(generate_uri "$1" "$2")${NC}"
echo ""
echo -e "${CYAN}user=${BOLD}${1}${NC}, pwd=${BOLD}${2}${NC}, host=${BOLD}${SERVER_IP}${NC}, port=${BOLD}2022${NC}"
}

list_users() {
echo ""
local n; n=$(jq '.users | length' "$CONFIG_FILE")
echo -e "${BOLD}${CYAN}=== Пользователей: $n ===${NC}"
jq -r '.users[] | " \(.name)\t\(.password[0:6])…"' "$CONFIG_FILE" | nl -w2 -s'. '
echo ""
echo -e "${BOLD}${CYAN}=== Активные сессии ===${NC}"
mita_cli get connections 2>&1 | head -20
press_enter
}

add_user() {
echo ""; read -rp "Имя пользователя: " name
name=$(echo "$name" | tr -d ' ')
[[ -z "$name" ]] && { echo "Пусто."; press_enter; return; }
if jq -e --arg n "$name" '.users[] | select(.name == $n)' "$CONFIG_FILE" >/dev/null; then
echo "Уже есть."; press_enter; return
fi
read -rp "Пароль (Enter — сгенерировать): " pwd
[[ -z "$pwd" ]] && pwd=$(generate_password)

backup_config
local tmp; tmp=$(mktemp)
jq --arg n "$name" --arg p "$pwd" '.users += [{"name":$n,"password":$p}]' "$CONFIG_FILE" > "$tmp" && mv "$tmp" "$CONFIG_FILE"

if apply_config; then
echo -e "${GREEN}Пользователь $name добавлен.${NC}"
print_uri_for "$name" "$pwd"
fi
press_enter
}

delete_user() {
mapfile -t users < <(jq -r '.users[].name' "$CONFIG_FILE")
[[ ${#users[@]} -eq 0 ]] && { echo "Пусто."; press_enter; return; }
for i in "${!users[@]}"; do echo " $((i+1))) ${users[$i]}"; done
echo " 0) Отмена"; read -rp "Номер: " n
[[ "$n" == "0" || -z "$n" ]] && return
local target="${users[$((n-1))]}"
read -rp "Удалить '$target'? (y/N): " yn
[[ ! "$yn" =~ ^[Yy]$ ]] && return

mita_cli delete user "$target" 2>&1
backup_config
local tmp; tmp=$(mktemp)
jq --arg n "$target" 'del(.users[] | select(.name == $n))' "$CONFIG_FILE" > "$tmp" && mv "$tmp" "$CONFIG_FILE"
apply_config && echo -e "${GREEN}Удалён.${NC}"
press_enter
}

show_uri() {
mapfile -t users < <(jq -r '.users[].name' "$CONFIG_FILE")
[[ ${#users[@]} -eq 0 ]] && { echo "Пусто."; press_enter; return; }
for i in "${!users[@]}"; do echo " $((i+1))) ${users[$i]}"; done
read -rp "Номер: " n
[[ -z "$n" ]] && return
local user="${users[$((n-1))]}"
local pwd; pwd=$(jq -r --arg n "$user" '.users[] | select(.name == $n) | .password' "$CONFIG_FILE")
print_uri_for "$user" "$pwd"
press_enter
}

server_status() {
mita_cli status 2>&1
echo
mita_cli get connections 2>&1
echo
mita_cli get metrics 2>&1 | head -30
press_enter
}

main_menu() {
check_root; check_deps
while true; do
clear
echo "╔══════════════════════════════════════╗"
echo "║ mieru User Manager ║"
echo "║ IP: $SERVER_IP"
echo "╚══════════════════════════════════════╝"
echo
echo " 1) Список пользователей"
echo " 2) Добавить"
echo " 3) Удалить"
echo " 4) URI клиента"
echo " 5) Статус сервера"
echo " 0) Выход"
read -rp "Выбор: " opt
case "$opt" in
1) list_users ;; 2) add_user ;;
3) delete_user ;; 4) show_uri ;;
5) server_status ;; 0) exit 0 ;;
esac
done
}

main_menu
</syntaxhighlight>
----

== См. также ==

* [https://github.com/enfein/mieru Официальный репозиторий mieru]
* [https://github.com/enfein/mieru/blob/master/docs/protocol.md Спецификация протокола mieru]
* [https://github.com/enfein/mieru/blob/master/docs/traffic-pattern.md Документация по traffic pattern]
* [https://github.com/enfein/mieru/blob/master/docs/security.md Руководство по безопасности]

Суверенный интернет

2026-05-10T18:40:53Z

Владимир:

Эта страница посвящается всему что связано с ограничим доступа в интернет.

На данный момент 20.04.26 мы имеем полную блокировку по белыми IP у операторов мобильной связи. И предпосылки к блокировкам на уровне провайдеров домашнего интернета.

* [[Обход НКР|Установка и настройка связки Zapret + Podkop на OpenWRT]]
* [[Hysteria 2 каскад]]
* [[Whitelist-bypass: VK Creator (headless на сервере) + Joiner (Android)]]
* [[Установка MTProto Proxy (mtg) на Linux-сервере]]
* [[VK Turn Proxy + FreeTurn + VLESS]]
* [[NaïveProxy: установка полной каскадной цепочки]]
* [[OlcRTC: туннель через WebRTC-сервисы|olcRTC: туннель через легальные WebRTC-сервисы]]
* mieru: каскадный шифрованный SOCKS5-туннель

Суверенный интернет

2026-05-09T18:22:26Z

Владимир:

Суверенный интернет

2026-05-09T18:21:43Z

Владимир:

Эта страница посвящается всему что связано с ограничим доступа в интернет.

На данный момент 20.04.26 мы имеем полную блокировку по белыми IP у операторов мобильной связи. И предпосылки к блокировкам на уровне провайдеров домашнего интернета.

* [[Обход НКР|Установка и настройка связки Zapret + Podkop на OpenWRT]]
* [[Hysteria 2 каскад]]
* [[Whitelist-bypass: VK Creator (headless на сервере) + Joiner (Android)]]
* [[Установка MTProto Proxy (mtg) на Linux-сервере]]
* [[VK Turn Proxy + FreeTurn + VLESS]]
* [[NaïveProxy: установка полной каскадной цепочки]]
* [[olcRTC: туннель через легальные WebRTC-сервисы]]

OlcRTC: туннель через WebRTC-сервисы

2026-05-09T07:56:51Z

Владимир: /* Поток данных */

= olcRTC: туннелирование SOCKS5-трафика через публичные WebRTC-сервисы =

== Введение ==

=== Что такое olcRTC ===
olcRTC — это инструмент для построения SOCKS5-туннеля поверх инфраструктуры публичных сервисов видеосвязи. В отличие от классических VPN-протоколов, которые работают через выделенные UDP/TCP-порты на собственном сервере, olcRTC использует уже существующие WebRTC-каналы общедоступных видеоконференц-сервисов в качестве несущей среды.

Поддерживаются три сервиса:
{| class="wikitable"
!Carrier
!Сервис
!Адрес
|-
|<code>wbstream</code>
|WB Stream
|<code>stream.wb.ru</code>
|-
|<code>telemost</code>
|Yandex Telemost
|<code>telemost.yandex.ru</code>
|-
|<code>jazz</code>
|SaluteJazz
|<code>salutejazz.ru</code>
|}
Сервер olcRTC выступает в роли участника виртуальной видеоконференции (с автоматически сгенерированным именем). Клиент подключается к той же конференции и через peer-connection обменивается с сервером данными — поверх этого канала идёт трафик SOCKS5-туннеля.

=== Когда применяется ===

* Канал между клиентом и обычными VPN-серверами нестабилен или имеет высокий процент потерь.
* Требуется передать данные через инфраструктуру, использующую WebRTC, а не выделенные транспортные порты.
* Нужна альтернатива, которая работает поверх стандартного для пользовательских устройств WebRTC-стека (браузер, мобильное приложение).

=== Сравнение с другими методами туннелирования ===
{| class="wikitable"
!Метод
!Транспорт
!Особенность
|-
|WireGuard
|UDP
|Прямое соединение с собственным сервером, минимальные накладные расходы
|-
|OpenVPN
|UDP/TCP
|Универсальная совместимость, выше накладные расходы
|-
|Shadowsocks
|TCP
|Шифрованный поток, маскировка под произвольный TCP
|-
|VLESS + REALITY
|TCP (TLS)
|TLS-handshake донора (стороннего сайта)
|-
|NaiveProxy
|TCP (HTTP/2)
|Использует Chrome-стек, неотличим от обычного HTTPS
|-
|Hysteria2
|UDP (QUIC)
|QUIC поверх UDP с маскировкой под HTTPS
|-
|'''olcRTC'''
|'''WebRTC поверх QUIC/UDP'''
|'''Использует существующую инфраструктуру SFU публичного сервиса видеосвязи в качестве несущей'''
|}
----

== Принципы работы ==

=== Поток данных ===
[[Файл:Olcrtc-data-flow.png|центр|мини|841x841пкс|Поток данных olcRTC: от клиентского приложения через SOCKS5, smux + ChaCha20-Poly1305, транспорт и WebRTC peer-connection в видеоконференции, до серверного outbound и целевого сайта]]

=== Слои кода ===
Кодовая база разделена на четыре независимых слоя с реестром расширений:
{| class="wikitable"
!Слой
!Ответственность
!Реализации
|-
|Carrier
|Сессия в видеосервисе: вход в конференцию, регистрация участника, peer-connection через SFU
|<code>wbstream</code>, <code>telemost</code>, <code>jazz</code>
|-
|Link
|Поверх транспорта; в текущей версии только <code>direct</code> (passthrough)
|<code>direct</code>
|-
|Transport
|Способ кодирования байтов внутри WebRTC-канала
|<code>datachannel</code>, <code>vp8channel</code>, <code>seichannel</code>, <code>videochannel</code>
|-
|Application
|Сервер (приём входящих туннелей) или клиент (локальный SOCKS5)
|<code>server</code>, <code>client</code>
|}

=== Транспорты ===
{| class="wikitable"
!Транспорт
!Несущая в WebRTC
!Идея
!Скорость
!Пинг
!WB Stream
!Telemost
!Jazz
|-
|<code>datachannel</code>
|RTCDataChannel
|Прямые байты в датаканале
|Максимум
|Минимум
|✓
|✗
|⚠
|-
|<code>vp8channel</code>
|VP8-видеотрек
|KCP-пакеты внутри валидных VP8-кадров
|Высокая
|Средний
|✓
|✓
|✓
|-
|<code>seichannel</code>
|H.264 SEI NAL
|Полезные данные в SEI-сообщениях видеопотока
|Низкая
|Низкий
|✓
|✗
|✓
|-
|<code>videochannel</code>
|Видеокадры
|QR-коды или тайлы Reed-Solomon в видеопотоке
|Минимум
|Максимум
|✓
|✓
|✓
|}
Рекомендуемая универсальная связка: <code>wbstream + vp8channel</code>. Она используется в данной статье как основная конфигурация.

=== Шифрование ===
{| class="wikitable"
!Параметр
!Значение
|-
|Алгоритм
|XChaCha20-Poly1305 (AEAD)
|-
|Длина ключа
|32 байта (64 hex-символа)
|-
|Nonce
|24 байта, случайный, на каждый фрейм, префиксится к шифротексту
|-
|Идентификация клиента
|Поле <code>client_id</code> в открытом JSON, сравнивается с серверным значением
|}
Реальная криптографическая защита — это ключ. <code>client_id</code> — лишь дополнительная проверка от случайных подключений в той же конференции, не криптографическая.

=== Smux: мультиплексирование ===
Поверх единого WebRTC-канала работает <code>xtaci/smux</code> v2. Один физический канал содержит много логических TCP-стримов: каждый запрос SOCKS5 от приложения открывается как отдельный smux-стрим.

=== Архитектурное ограничение: один сервер — один клиент ===
Это важное свойство кода, которое необходимо понимать.

Один экземпляр сервера olcRTC обслуживает '''ровно одного клиента в момент времени'''. Это не упущение, а сознательное архитектурное решение.

Причины:

* Сервер хранит '''одну''' переменную <code>clientID</code> и сравнивает с присланным значением (см. <code>internal/server/server.go:399-401</code>).
* Сервер держит '''один''' link и '''одну''' smux-сессию, не словарь по идентификатору.
* Провайдер carrier держит один RTCPeerConnection.

{| class="wikitable"
!Сценарий
!Поведение
|-
|Один владелец, разные устройства, по очереди (выключил ноутбук, включил телефон)
|Работает с одной ссылкой
|-
|Один владелец, разные устройства, одновременно
|Устройства конкурируют за peer-connection, рвут друг друга
|-
|Несколько разных людей, одна ссылка на всех, одновременно
|То же — рвут друг друга
|-
|Несколько пользователей, у каждого своя ссылка
|Работает; '''требуется отдельный контейнер на каждого пользователя'''
|}
Для предоставления доступа нескольким людям одновременно необходимо запустить несколько независимых контейнеров — каждый со своими <code>room_id</code>, <code>key</code> и <code>client_id</code>. В разделе «Управление несколькими пользователями» описан скрипт, который автоматизирует это.
----

== Что должно быть на сервере перед установкой ==

=== Минимально необходимая конфигурация ===
Перед началом установки olcRTC сервер должен находиться в следующем состоянии:
{| class="wikitable"
!№
!Требование
!Зачем
|-
|1
|Установлена операционная система Linux (Ubuntu 22.04+, Debian 12+, Fedora 38+ или сравнимая)
|Среда выполнения Docker
|-
|2
|Доступ по SSH с правами <code>root</code> (либо аккаунт с <code>sudo</code> без пароля)
|Установка пакетов и управление контейнерами
|-
|3
|Установлены Docker Engine 24.0+ и Docker Compose v2.20+
|Запуск контейнера olcRTC
|-
|4
|Установлена утилита <code>git</code>
|Скачивание исходного кода olcRTC с репозитория
|-
|5
|Установлена утилита <code>openssl</code>
|Генерация ключа шифрования
|}

=== Опциональная (но настоятельно рекомендуемая) конфигурация: egress через WARP ===
По умолчанию olcRTC сервер выходит в интернет напрямую с публичного IP вашей виртуальной машины. Все целевые сайты будут видеть именно этот адрес.

Чтобы выходной трафик уходил через Cloudflare WARP, требуется промежуточная цепочка через локальный SOCKS5-прокси. Самая распространённая реализация — панель '''3x-ui''' (web-интерфейс над xray-core).

==== Что должно быть подготовлено в 3x-ui ====
{| class="wikitable"
!№
!Параметр
!Значение для нашей статьи
!Комментарий
|-
|1
|Сама панель 3x-ui установлена и доступна
|—
|Установка описана в отдельной статье ([[Установка 3x-ui]]); если её ещё нет — выполните установку до начала
|-
|2
|Outbound в WARP активен и протестирован
|tag <code>warp</code> или аналогичный
|Должен быть настроен как WireGuard-outbound к Cloudflare WARP. Проверка: маршрут с outbound отдаёт IPv6 из диапазона <code>2a09:bac5::/29</code> или IPv4 <code>104.28.x.x</code>
|-
|3
|Inbound типа '''mixed''' (SOCKS5 + HTTP), слушающий '''только на 127.0.0.1'''
|порт <code>24365</code>
|Этот порт мы будем указывать в конфигурации olcRTC. Выберите любой свободный, мы используем 24365 как пример
|-
|4
|Аутентификация (логин/пароль) на этом mixed-inbound '''отключена'''
|—
|olcRTC-сервер умеет работать только с режимом NOAUTH; если включена авторизация, цепочка не будет работать
|-
|5
|Routing-rule в xray: трафик с inbound mixed → outbound warp
|—
|В 3x-ui это настраивается в разделе «Настройки xray → Маршрутизация»
|}

==== Как проверить, что цепочка работает ====
Команда ниже выполняется на самом сервере (не на компьютере пользователя). Она запрашивает свой IP-адрес через локальный SOCKS5-прокси, который должен направить запрос в WARP.

Замените <code>24365</code> на ваш реальный номер порта mixed-inbound.<syntaxhighlight lang="bash">
curl --socks5-hostname 127.0.0.1:24365 https://icanhazip.com
</syntaxhighlight>Ожидаемый результат: IP-адрес из диапазона Cloudflare WARP (например, <code>104.28.218.x</code> или IPv6 <code>2a09:bac5:...</code>). Если возвращается публичный IP вашего сервера — значит цепочка не сработала и трафик идёт мимо WARP. В этом случае проверьте настройки routing в 3x-ui.

Если egress через WARP вам не нужен (готовы выходить с публичного IP сервера), можно пропустить этот раздел. В дальнейших шагах указания для случая «без WARP» помечены явно.
----

== Параметры, которые нужно подготовить заранее ==
Перед началом установки заполните таблицу ниже своими значениями. На каждом шаге, где встретится плейсхолдер, мы будем ссылаться на эту таблицу.
{| class="wikitable"
!Плейсхолдер
!Что это
!Где взять
!Пример
|-
|<code>YOUR_SERVER_HOST</code>
|Адрес сервера для подключения по SSH: либо публичный IP, либо имя из <code>~/.ssh/config</code>, либо доменное имя
|У хостинг-провайдера в панели управления виртуальной машиной
|<code>198.51.100.42</code> или <code>my-vps</code>
|-
|<code>YOUR_SSH_USER</code>
|Имя пользователя SSH
|В письме от хостинга при создании VM. Чаще всего <code>root</code>
|<code>root</code>
|-
|<code>YOUR_KEY_HEX</code>
|32-байтный ключ шифрования olcRTC в hex-формате (64 символа)
|Будет сгенерирован командой на шаге 4. Сохраните в надёжное место
|<code>1c3f8a2b...d4e5f6a7</code> (64 hex-символа)
|-
|<code>YOUR_CLIENT_ID</code>
|Идентификатор клиента; должен совпадать на сервере и в клиентском приложении
|Любое имя на латинице длиной 1–32 символа: буквы, цифры, <code>_</code>, <code>-</code>
|<code>my-laptop</code>
|-
|<code>YOUR_ROOM_ID</code>
|Идентификатор виртуальной видеоконференции
|Будет получен из логов сервера на шаге 7
|<code>019e07b8-e292-73ec-a40b-6a6e4957ce01</code>
|-
|<code>YOUR_SOCKS_PORT</code>
|Порт mixed-inbound в 3x-ui для egress через WARP (опционально)
|См. раздел «Что должно быть на сервере перед установкой»
|<code>24365</code>
|}
Сохраните эту таблицу в текстовом файле — заполните по мере прохождения шагов. Особенно важно сохранить <code>YOUR_KEY_HEX</code> и <code>YOUR_ROOM_ID</code> — без них нельзя восстановить доступ к серверу после перезапуска.
----

== Установка сервера: пошаговая инструкция ==
В этом разделе все команды выполняются на сервере (через SSH). Каждое пояснение — одна команда. Если команда выдала ошибку — остановитесь, не выполняйте следующую, и сверьтесь с предыдущим шагом.

=== Шаг 1. Подключение к серверу по SSH ===
Откройте терминал на своём компьютере. На Windows можно использовать встроенный PowerShell или Windows Terminal, на macOS — Terminal, на Linux — любой эмулятор терминала.

Замените <code>YOUR_SSH_USER</code> на имя пользователя из подготовленной таблицы (обычно <code>root</code>), а <code>YOUR_SERVER_HOST</code> — на адрес или имя сервера.<syntaxhighlight lang="bash">
ssh YOUR_SSH_USER@YOUR_SERVER_HOST
</syntaxhighlight>Если подключение прошло успешно — вы увидите приглашение командной строки сервера. Все следующие команды выполняются именно в нём.

=== Шаг 2. Проверка наличия Docker ===
Прежде чем что-то ставить, проверим, есть ли Docker уже на сервере.<syntaxhighlight lang="bash">
docker --version
</syntaxhighlight>Если команда вывела что-то вроде <code>Docker version 24.0.5, build ...</code> — Docker установлен, переходите к шагу 3.

Если команда выдала <code>command not found</code> — Docker нужно установить. Выберите один из подразделов ниже в зависимости от вашего дистрибутива.

==== 2a. Установка Docker на Ubuntu / Debian ====
Обновите список пакетов.<syntaxhighlight lang="bash">
apt update
</syntaxhighlight>Установите вспомогательные утилиты.<syntaxhighlight lang="bash">
apt install -y ca-certificates curl gnupg
</syntaxhighlight>Подготовьте каталог для GPG-ключей репозитория Docker.<syntaxhighlight lang="bash">
install -m 0755 -d /etc/apt/keyrings
</syntaxhighlight>Скачайте GPG-ключ официального репозитория Docker.<syntaxhighlight lang="bash">
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
</syntaxhighlight>Дайте права на чтение всем.<syntaxhighlight lang="bash">
chmod a+r /etc/apt/keyrings/docker.gpg
</syntaxhighlight>Добавьте репозиторий Docker в систему.<syntaxhighlight lang="bash">
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
</syntaxhighlight>Снова обновите список пакетов (теперь уже с новым репозиторием).<syntaxhighlight lang="bash">
apt update
</syntaxhighlight>Установите Docker и плагины.<syntaxhighlight lang="bash">
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
</syntaxhighlight>

==== 2b. Установка Docker на Fedora / RHEL ====
Установите менеджер репозиториев.<syntaxhighlight lang="bash">
dnf -y install dnf-plugins-core
</syntaxhighlight>Подключите репозиторий Docker.<syntaxhighlight lang="bash">
dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
</syntaxhighlight>Установите Docker.<syntaxhighlight lang="bash">
dnf -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
</syntaxhighlight>Запустите и включите автозапуск Docker.<syntaxhighlight lang="bash">
systemctl enable --now docker
</syntaxhighlight>

==== 2c. Проверка установки Docker (любая ОС) ====
Проверьте, что Docker установлен и работает.<syntaxhighlight lang="bash">
docker --version
</syntaxhighlight>Должно вывести что-то вроде <code>Docker version 24.0.5</code>.

Проверьте, что плагин Compose доступен.<syntaxhighlight lang="bash">
docker compose version
</syntaxhighlight>Должно вывести что-то вроде <code>Docker Compose version v2.20.2</code>.

Если обе команды отработали без ошибок — переходите к шагу 3.

=== Шаг 3. Создание рабочего каталога ===
Создайте каталог, в котором будет лежать репозиторий olcRTC.<syntaxhighlight lang="bash">
mkdir -p /opt/olcrtc
</syntaxhighlight>Перейдите в этот каталог.<syntaxhighlight lang="bash">
cd /opt/olcrtc
</syntaxhighlight>

=== Шаг 4. Скачивание исходного кода olcRTC ===
Скачайте репозиторий вместе с подмодулями (флаг <code>--recurse-submodules</code> обязателен — без него транспорт <code>videochannel</code> не соберётся).<syntaxhighlight lang="bash">
git clone --depth 1 --recurse-submodules --branch master https://github.com/openlibrecommunity/olcrtc.git .
</syntaxhighlight>Точка в конце команды означает «скачать в текущий каталог», не создавая вложенной папки. Если вы пропустили шаг 3 (<code>cd /opt/olcrtc</code>), команда создаст репозиторий не в том месте.

Проверьте, что скачивание прошло успешно.<syntaxhighlight lang="bash">
ls /opt/olcrtc
</syntaxhighlight>В выводе должны быть файлы <code>Dockerfile</code>, <code>go.mod</code>, каталоги <code>cmd</code>, <code>internal</code>, <code>script</code> и другие.

=== Шаг 5. Генерация ключа шифрования ===
Сгенерируйте ключ командой <code>openssl</code>.<syntaxhighlight lang="bash">
openssl rand -hex 32
</syntaxhighlight>Команда выведет строку из 64 hex-символов. Например:
1c3f8a2b3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7a8b9c0d1e2
'''Скопируйте этот ключ''' и впишите его в свою таблицу подготовки как <code>YOUR_KEY_HEX</code>. Этот же ключ потом понадобится для настройки клиента.

=== Шаг 6. Создание конфигурационного файла .env ===
Файл <code>.env</code> хранит параметры запуска. Создадим его, подставив ваши значения.

Замените:

* <code>ВАШ_КЛЮЧ</code> — на значение <code>YOUR_KEY_HEX</code> из шага 5.
* <code>my-laptop</code> — на значение <code>YOUR_CLIENT_ID</code> из таблицы подготовки.

Если вы '''используете''' egress через WARP (раздел «Что должно быть на сервере перед установкой»), также замените <code>24365</code> на свой <code>YOUR_SOCKS_PORT</code>. Если '''не используете''' WARP — удалите две строки <code>OLCRTC_SOCKS_PROXY=...</code>.<syntaxhighlight lang="bash">
nano /opt/olcrtc/.env
</syntaxhighlight>В открывшемся редакторе вставьте следующее содержимое:<syntaxhighlight lang="ini">
OLCRTC_CARRIER=wbstream
OLCRTC_TRANSPORT=vp8channel
OLCRTC_ROOM_ID=any
OLCRTC_CLIENT_ID=my-laptop
OLCRTC_KEY=ВАШ_КЛЮЧ
OLCRTC_DNS=1.1.1.1:53
OLCRTC_SOCKS_PROXY=127.0.0.1
OLCRTC_SOCKS_PROXY_PORT=24365
OLCRTC_VP8_FPS=60
OLCRTC_VP8_BATCH=64
OLCRTC_DEBUG=false
</syntaxhighlight>Сохраните файл: нажмите <code>Ctrl+O</code>, затем <code>Enter</code>, затем <code>Ctrl+X</code>.

Защитите файл от чтения посторонними (он содержит ваш ключ).<syntaxhighlight lang="bash">
chmod 600 /opt/olcrtc/.env
</syntaxhighlight>Проверьте, что значения подставились правильно.<syntaxhighlight lang="bash">
cat /opt/olcrtc/.env
</syntaxhighlight>В строке <code>OLCRTC_KEY=...</code> должен быть ваш ключ, в строке <code>OLCRTC_CLIENT_ID=...</code> — ваше имя пользователя.

=== Шаг 7. Замена docker-compose.server.yml ===
Стандартный compose-файл из репозитория не использует режим <code>host</code>, который нужен для доступа к локальному xray. Заменим его на нашу версию.

Откройте файл для редактирования.<syntaxhighlight lang="bash">
nano /opt/olcrtc/docker-compose.server.yml
</syntaxhighlight>Удалите всё содержимое (зажмите <code>Ctrl+K</code> до полной очистки) и вставьте следующее:<syntaxhighlight lang="yaml">
services:
olcrtc-server:
build:
context: .
image: olcrtc/server:local
container_name: olcrtc-server
restart: unless-stopped
network_mode: host
environment:
OLCRTC_MODE: srv
OLCRTC_CARRIER: "${OLCRTC_CARRIER:?set OLCRTC_CARRIER}"
OLCRTC_TRANSPORT: "${OLCRTC_TRANSPORT:?set OLCRTC_TRANSPORT}"
OLCRTC_ROOM_ID: "${OLCRTC_ROOM_ID:?set OLCRTC_ROOM_ID}"
OLCRTC_CLIENT_ID: "${OLCRTC_CLIENT_ID:?set OLCRTC_CLIENT_ID}"
OLCRTC_KEY: "${OLCRTC_KEY:?set OLCRTC_KEY}"
OLCRTC_DNS: "${OLCRTC_DNS:-1.1.1.1:53}"
OLCRTC_SOCKS_PROXY: "${OLCRTC_SOCKS_PROXY:-}"
OLCRTC_SOCKS_PROXY_PORT: "${OLCRTC_SOCKS_PROXY_PORT:-1080}"
OLCRTC_VP8_FPS: "${OLCRTC_VP8_FPS:-60}"
OLCRTC_VP8_BATCH: "${OLCRTC_VP8_BATCH:-64}"
OLCRTC_DEBUG: "${OLCRTC_DEBUG:-false}"
volumes:
- olcrtc-state:/var/lib/olcrtc
init: true

volumes:
olcrtc-state:
</syntaxhighlight>Сохраните файл: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

=== Шаг 8. Сборка Docker-образа olcRTC ===
Перейдите в каталог проекта (если ещё не там).<syntaxhighlight lang="bash">
cd /opt/olcrtc
</syntaxhighlight>Запустите сборку.<syntaxhighlight lang="bash">
docker compose -f docker-compose.server.yml --env-file .env build
</syntaxhighlight>Сборка длится 1–3 минуты. Скачиваются зависимости Go и компилируется бинарник. Если в процессе возникает ошибка вида «context canceled» или «network unreachable» — повторите команду; первый прогон бывает прерывистым из-за нестабильности зеркал.

Когда сборка успешно завершится, в выводе появится строка <code>Image olcrtc/server:local Built</code>.

=== Шаг 9. Запуск контейнера ===
Запустите контейнер в фоновом режиме.<syntaxhighlight lang="bash">
docker compose -f docker-compose.server.yml --env-file .env up -d
</syntaxhighlight>Подождите 15–20 секунд, чтобы сервер успел подключиться к WB Stream и создать виртуальную конференцию.<syntaxhighlight lang="bash">
sleep 20
</syntaxhighlight>Посмотрите логи.<syntaxhighlight lang="bash">
docker logs olcrtc-server
</syntaxhighlight>Ожидаемый вывод:
Connecting link via direct/vp8channel/wbstream...
WB Stream room created: 019e07b8-e292-73ec-a40b-6a6e4957ce01
To connect client use: -id 019e07b8-e292-73ec-a40b-6a6e4957ce01
Link connected
'''Скопируйте идентификатор после <code>WB Stream room created:</code>''' и впишите его в таблицу подготовки как <code>YOUR_ROOM_ID</code>. Без этого значения невозможно настроить клиента.

=== Шаг 10. Фиксация room_id в .env ===
Сейчас в файле <code>.env</code> стоит <code>OLCRTC_ROOM_ID=any</code>. Это значение означает «при каждом запуске создавать новую конференцию». Если оставить его — после следующего перезапуска контейнера все ссылки клиентов перестанут работать, потому что комната окажется новой.

Зафиксируйте полученный идентификатор.

Замените <code>YOUR_ROOM_ID</code> в команде ниже на скопированное значение из шага 9.<syntaxhighlight lang="bash">
sed -i 's/^OLCRTC_ROOM_ID=any$/OLCRTC_ROOM_ID=YOUR_ROOM_ID/' /opt/olcrtc/.env
</syntaxhighlight>Перезапустите контейнер с новым значением.<syntaxhighlight lang="bash">
docker compose -f /opt/olcrtc/docker-compose.server.yml --env-file /opt/olcrtc/.env up -d
</syntaxhighlight>Подождите 10 секунд и снова проверьте логи.<syntaxhighlight lang="bash">
sleep 10 && docker logs --tail 5 olcrtc-server
</syntaxhighlight>Теперь в логе не должно быть строки <code>WB Stream room created</code> — должна быть только <code>Connecting link via direct/vp8channel/wbstream...</code> и <code>Link connected</code>. Это означает, что сервер заходит в существующую комнату, а не создаёт новую.

=== Шаг 11. Формирование ссылки для клиента ===
Ссылка имеет фиксированный текстовый формат:
olcrtc://CARRIER?TRANSPORT@ROOM_ID#KEY%CLIENT_ID$ПОДПИСЬ
Подставьте свои значения. Подпись — произвольная строка, которая отобразится в названии локации в клиентском приложении (она не влияет на работу).

Пример итоговой ссылки:<pre>
olcrtc://wbstream?vp8channel@019e07b8-e292-73ec-a40b-6a6e4957ce01#1c3f8a2b...d4e5f6a7%my-laptop$home laptop, vp8 over wbstream
</pre>
{| class="wikitable"
!Часть ссылки
!Откуда берётся
|-
|<code>wbstream</code>
|Из <code>OLCRTC_CARRIER</code> в .env
|-
|<code>vp8channel</code>
|Из <code>OLCRTC_TRANSPORT</code> в .env
|-
|<code>019e07b8-...</code>
|<code>YOUR_ROOM_ID</code> из шага 9
|-
|<code>1c3f8a2b...</code>
|<code>YOUR_KEY_HEX</code> из шага 5
|-
|<code>my-laptop</code>
|<code>YOUR_CLIENT_ID</code> из шага 6
|-
|Подпись после <code>$</code>
|Любой описательный текст
|}
Сохраните полученную ссылку в надёжное место. Её нужно будет ввести в клиентское приложение.

=== Шаг 12. Подключение клиента ===

==== 12a. Olcbox (Android, рекомендуется для смартфона) ====
Скачайте APK из репозитория [https://github.com/alananisimov/olcbox alananisimov/olcbox] (раздел Releases) и установите его на телефон.

Откройте приложение. Перейдите в раздел Locations. Нажмите Add → '''Import from clipboard'''.

Перед нажатием убедитесь, что в буфере обмена телефона лежит ваша ссылка <code>olcrtc://...</code> из шага 11. Скопируйте её любым способом — например, отправив самому себе в Telegram-секретный чат.

После импорта откройте созданную локацию и проверьте поля:

* Carrier должен быть <code>wbstream</code>.
* Transport должен быть <code>vp8channel</code>.
* VP8 FPS — установите <code>60</code> вручную (при импорте URI этот параметр сбрасывается на дефолт приложения).
* VP8 Batch — установите <code>64</code>.

Включите тумблер VPN.

==== 12b. CLI-клиент (Linux, macOS, Windows) ====
Скачайте бинарник olcrtc для своей операционной системы из релизов репозитория или соберите из исходников.

Запустите туннель. Замените все плейсхолдеры <code>YOUR_*</code> на свои значения из таблицы подготовки.<syntaxhighlight lang="bash">
./olcrtc -mode cnc -carrier wbstream -transport vp8channel -id YOUR_ROOM_ID -client-id YOUR_CLIENT_ID -key YOUR_KEY_HEX -link direct -data data -dns 1.1.1.1:53 -vp8-fps 60 -vp8-batch 64 -socks-host 127.0.0.1 -socks-port 1080
</syntaxhighlight>После запуска клиент поднимет локальный SOCKS5-прокси на <code>127.0.0.1:1080</code>.

Проверьте, что туннель работает.<syntaxhighlight lang="bash">
curl --socks5-hostname 127.0.0.1:1080 https://icanhazip.com
</syntaxhighlight>Если egress настроен через WARP — должен вернуть IP Cloudflare WARP. Если не настроен — IP вашего сервера. В обоих случаях это '''не должен быть''' IP вашего домашнего интернета.
----

== Команды управления одним сервером ==
Все команды выполняются на сервере по SSH.

Посмотреть логи в реальном времени (для выхода нажать <code>Ctrl+C</code>).<syntaxhighlight lang="bash">
docker logs -f olcrtc-server
</syntaxhighlight>Посмотреть статус контейнера.<syntaxhighlight lang="bash">
docker ps --filter name=olcrtc-server
</syntaxhighlight>Перезапустить сервер (например, после изменения .env).<syntaxhighlight lang="bash">
docker compose -f /opt/olcrtc/docker-compose.server.yml --env-file /opt/olcrtc/.env up -d
</syntaxhighlight>Остановить сервер.<syntaxhighlight lang="bash">
docker compose -f /opt/olcrtc/docker-compose.server.yml --env-file /opt/olcrtc/.env down
</syntaxhighlight>Обновить исходный код до свежей версии master.<syntaxhighlight lang="bash">
cd /opt/olcrtc && git pull --recurse-submodules
</syntaxhighlight>Пересобрать образ после обновления кода.<syntaxhighlight lang="bash">
docker compose -f /opt/olcrtc/docker-compose.server.yml --env-file /opt/olcrtc/.env build
</syntaxhighlight>Применить новый образ.<syntaxhighlight lang="bash">
docker compose -f /opt/olcrtc/docker-compose.server.yml --env-file /opt/olcrtc/.env up -d
</syntaxhighlight>
----

== Управление несколькими пользователями: скрипт <code>olcrtc-users</code> ==

=== Зачем он нужен ===
Из-за архитектурного ограничения «один сервер — один клиент» (раздел «Принципы работы → Архитектурное ограничение») для каждого пользователя нужен отдельный контейнер со своим room_id, ключом и client_id. Чтобы не повторять шаги установки руками каждый раз, написан bash-скрипт <code>olcrtc-users</code>, который автоматизирует:

* '''Создание пользователя:''' генерация ключа, создание контейнера с уникальным client_id, ловля room_id из логов, формирование готовой ссылки.
* '''Удаление пользователя:''' остановка и удаление контейнера, удаление volume и каталога.
* '''Просмотр списка и информации:''' таблица всех пользователей с возможностью получить ссылку по выбору номера.

=== Что получает каждый пользователь ===
{| class="wikitable"
!Атрибут
!Значение
|-
|Контейнер
|<code>olcrtc-user-<имя></code>
|-
|Каталог конфигурации
|<code>/opt/olcrtc-users/<имя>/</code>
|-
|Файл с переменными
|<code>/opt/olcrtc-users/<имя>/.env</code>
|-
|Compose project
|<code>olcrtc-user-<имя></code>
|-
|Docker volume
|<code>olcrtc-user-<имя>_state</code>
|-
|Виртуальная конференция
|Уникальная, создаётся при первом запуске
|-
|Ключ шифрования
|Уникальный, 32 случайных байта
|-
|Ссылка вида <code>olcrtc://...</code>
|Уникальная
|}

=== Структура каталогов ===
<pre>
/opt/olcrtc/ # репозиторий + Dockerfile (build context)
└── (код, не меняется после установки)

/opt/olcrtc-users/ # каталог менеджера пользователей
├── shared/
│ ├── docker-compose.user.yml # один шаблон compose для всех пользователей
│ └── defaults.env # значения по умолчанию для новых пользователей
├── alice/
│ └── .env # личные данные пользователя alice
├── bob/
│ └── .env
└── carol/
└── .env

/usr/local/bin/olcrtc-users # сам скрипт-меню
</pre>

=== Установка скрипта ===
Все команды выполняются на сервере по SSH.

==== Шаг 1. Создание общего каталога ====
Создайте корневой каталог для пользователей.<syntaxhighlight lang="bash">
mkdir -p /opt/olcrtc-users/shared
</syntaxhighlight>Защитите каталог.<syntaxhighlight lang="bash">
chmod 700 /opt/olcrtc-users
</syntaxhighlight>

==== Шаг 2. Создание общего шаблона docker-compose ====
Откройте файл для редактирования.<syntaxhighlight lang="bash">
nano /opt/olcrtc-users/shared/docker-compose.user.yml
</syntaxhighlight>Вставьте следующее содержимое.<syntaxhighlight lang="yaml">
services:
olcrtc:
image: olcrtc/server:local
container_name: "olcrtc-user-${OLCRTC_CLIENT_ID}"
restart: unless-stopped
network_mode: host
environment:
OLCRTC_MODE: srv
OLCRTC_CARRIER: "${OLCRTC_CARRIER}"
OLCRTC_TRANSPORT: "${OLCRTC_TRANSPORT}"
OLCRTC_ROOM_ID: "${OLCRTC_ROOM_ID}"
OLCRTC_CLIENT_ID: "${OLCRTC_CLIENT_ID}"
OLCRTC_KEY: "${OLCRTC_KEY}"
OLCRTC_DNS: "${OLCRTC_DNS}"
OLCRTC_SOCKS_PROXY: "${OLCRTC_SOCKS_PROXY}"
OLCRTC_SOCKS_PROXY_PORT: "${OLCRTC_SOCKS_PROXY_PORT}"
OLCRTC_VP8_FPS: "${OLCRTC_VP8_FPS}"
OLCRTC_VP8_BATCH: "${OLCRTC_VP8_BATCH}"
volumes:
- state:/var/lib/olcrtc
init: true

volumes:
state:
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

==== Шаг 3. Создание файла значений по умолчанию ====
Откройте файл для редактирования.<syntaxhighlight lang="bash">
nano /opt/olcrtc-users/shared/defaults.env
</syntaxhighlight>Вставьте следующее (если используете egress через WARP — оставьте порт <code>24365</code> или замените на свой <code>YOUR_SOCKS_PORT</code>).<syntaxhighlight lang="ini">
OLCRTC_CARRIER=wbstream
OLCRTC_TRANSPORT=vp8channel
OLCRTC_DNS=1.1.1.1:53
OLCRTC_SOCKS_PROXY=127.0.0.1
OLCRTC_SOCKS_PROXY_PORT=24365
OLCRTC_VP8_FPS=60
OLCRTC_VP8_BATCH=64
</syntaxhighlight>Сохраните файл: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

Защитите файл.<syntaxhighlight lang="bash">
chmod 600 /opt/olcrtc-users/shared/defaults.env
</syntaxhighlight>Если egress через WARP вам '''не нужен''', выполните дополнительную команду — она очистит поле SOCKS-прокси.<syntaxhighlight lang="bash">
sed -i 's|OLCRTC_SOCKS_PROXY=127.0.0.1|OLCRTC_SOCKS_PROXY=|' /opt/olcrtc-users/shared/defaults.env
</syntaxhighlight>

==== Шаг 4. Создание самого скрипта ====
Откройте файл скрипта в редакторе.<syntaxhighlight lang="bash">
nano /usr/local/bin/olcrtc-users
</syntaxhighlight>Вставьте полное содержимое скрипта (исходный код целиком — в спойлере «Исходный код скрипта <code>olcrtc-users</code>» в конце статьи).

Сохраните файл: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

Сделайте файл исполняемым.<syntaxhighlight lang="bash">
chmod 0755 /usr/local/bin/olcrtc-users
</syntaxhighlight>Проверьте корректность синтаксиса.<syntaxhighlight lang="bash">
bash -n /usr/local/bin/olcrtc-users && echo OK
</syntaxhighlight>Если в выводе <code>OK</code> — скрипт установлен правильно.

=== Использование скрипта ===
Запустите.<syntaxhighlight lang="bash">
olcrtc-users
</syntaxhighlight>Появится меню:<pre>
=== olcrtc users ===
1) Список пользователей (выбор → ссылка)
2) Создать пользователя
3) Удалить пользователя
0) Выход
> _
</pre>

==== Пункт 1: список пользователей ====
После выбора отобразится таблица:<pre>
# name status
--- ------------------------------ ------------
1) alice running
2) bob running
3) carol exited
</pre>Введите номер пользователя и нажмите <code>Enter</code> — появится полная карточка с готовой ссылкой <code>olcrtc://...</code>:<pre>
name : alice
status : running
carrier : wbstream
transport : vp8channel
room_id : 019e07b8-e292-73ec-a40b-6a6e4957ce01
client_id : alice
key : 1c3f8a2b...d4e5f6a7

URI for olcbox:
olcrtc://wbstream?vp8channel@019e07b8-e292-73ec-a40b-6a6e4957ce01#1c3f8a2b...d4e5f6a7%alice$alice
</pre>Чтобы пропустить выбор и вернуться в меню — нажмите <code>Enter</code> без ввода номера.

==== Пункт 2: создание пользователя ====
Скрипт спросит имя.<pre>
Имя пользователя:
</pre>Введите имя на латинице (буквы, цифры, <code>_</code>, <code>-</code>, длина 1–32 символа), например <code>alice</code>.

Затем спросит, как получить ключ.<pre>
Ключ шифрования: [a]uto / [m]anual (по умолчанию a):
</pre>Введите <code>a</code> (или просто нажмите <code>Enter</code>) — скрипт сгенерирует ключ автоматически.

Если хотите ввести ключ вручную — введите <code>m</code> и затем 64-символьный hex-ключ.

После этого скрипт сам:

* создаст каталог пользователя;
* запустит контейнер;
* подождёт создания виртуальной конференции;
* запишет полученный room_id в .env;
* перезапустит контейнер с фиксированным room_id;
* выведет готовую карточку с ссылкой.

==== Пункт 3: удаление пользователя ====
Скрипт покажет список.<pre>
1) alice
2) bob
3) carol
</pre>Введите номер удаляемого пользователя, нажмите <code>Enter</code>.

Скрипт спросит подтверждение.<pre>
Удалить пользователя "carol"? (y/N):
</pre>Введите <code>y</code> и нажмите <code>Enter</code>. Если введёте что-то другое или просто <code>Enter</code> — операция отменится.

После подтверждения:

* контейнер будет остановлен и удалён;
* docker volume будет удалён;
* каталог пользователя будет удалён;
* ссылка <code>olcrtc://...</code> у этого пользователя '''перестанет работать'''.

----

== Исходный код скрипта olcrtc-users ==
{| class="mw-collapsible mw-collapsed wikitable" width="100%"
!Развернуть полный исходный код и подробное объяснение архитектуры скрипта
|-
|
=== Полный исходный код ===
<syntaxhighlight lang="bash">
#!/usr/bin/env bash
# olcrtc-users — управление пользователями olcrtc через docker compose.
# UI: 3 пункта (список / создать / удалить), под капотом — отдельный контейнер на пользователя.

set -euo pipefail

USERS_DIR=/opt/olcrtc-users
SHARED=$USERS_DIR/shared
COMPOSE=$SHARED/docker-compose.user.yml
DEFAULTS=$SHARED/defaults.env

if [ ! -f "$COMPOSE" ] || [ ! -f "$DEFAULTS" ]; then
echo "[X] $SHARED is not initialized. Aborting." >&2
exit 1
fi

# ----- helpers -----
list_users() {
find "$USERS_DIR" -mindepth 1 -maxdepth 1 -type d ! -name shared -printf "%f\n" | sort
}

container_status() {
docker inspect -f "{{.State.Status}}" "olcrtc-user-$1" 2>/dev/null || echo "missing"
}

read_env() {
local f=$1 k=$2
grep -E "^${k}=" "$f" | cut -d= -f2-
}

build_uri() {
local f=$1
local carrier transport room key cid
carrier=$(read_env "$f" OLCRTC_CARRIER)
transport=$(read_env "$f" OLCRTC_TRANSPORT)
room=$(read_env "$f" OLCRTC_ROOM_ID)
key=$(read_env "$f" OLCRTC_KEY)
cid=$(read_env "$f" OLCRTC_CLIENT_ID)
printf "olcrtc://%s?%s@%s#%s%%%s\$%s\n" \
"$carrier" "$transport" "$room" "$key" "$cid" "$cid"
}

show_user() {
local user=$1
local f=$USERS_DIR/$user/.env
local status; status=$(container_status "$user")
echo "name : $user"
echo "status : $status"
echo "carrier : $(read_env "$f" OLCRTC_CARRIER)"
echo "transport : $(read_env "$f" OLCRTC_TRANSPORT)"
echo "room_id : $(read_env "$f" OLCRTC_ROOM_ID)"
echo "client_id : $(read_env "$f" OLCRTC_CLIENT_ID)"
echo "key : $(read_env "$f" OLCRTC_KEY)"
echo
echo "URI for olcbox:"
build_uri "$f"
}

valid_name() { [[ "$1" =~ ^[a-zA-Z0-9_-]{1,32}$ ]]; }

compose_up() {
local user=$1
docker compose -f "$COMPOSE" --env-file "$USERS_DIR/$user/.env" \
-p "olcrtc-user-$user" up -d
}

compose_down() {
local user=$1
docker compose -f "$COMPOSE" --env-file "$USERS_DIR/$user/.env" \
-p "olcrtc-user-$user" down -v
}

# ----- menu actions -----
action_list() {
mapfile -t users < <(list_users)
if [ ${#users[@]} -eq 0 ]; then
echo "(пользователей нет)"
return
fi
printf " %3s %-30s %-12s\n" "#" "name" "status"
printf " %3s %-30s %-12s\n" "---" "------------------------------" "------------"
local i
for i in "${!users[@]}"; do
printf " %3d) %-30s %-12s\n" \
"$((i+1))" "${users[$i]}" "$(container_status "${users[$i]}")"
done
echo
read -rp "Введите номер чтобы показать ссылку (Enter — пропустить): " pick
[ -z "$pick" ] && return
if ! [[ "$pick" =~ ^[0-9]+$ ]] || [ "$pick" -lt 1 ] || [ "$pick" -gt "${#users[@]}" ]; then
echo "(неверный номер)"
return
fi
echo
show_user "${users[$((pick-1))]}"
}

action_new() {
read -rp "Имя пользователя: " name
if ! valid_name "$name"; then
echo "(имя должно быть 1..32 символа, только a-z A-Z 0-9 _ -)"
return
fi
if [ -d "$USERS_DIR/$name" ]; then
echo "(пользователь \"$name\" уже существует)"
return
fi

local key
read -rp "Ключ шифрования: [a]uto / [m]anual (по умолчанию a): " mode
case "${mode:-a}" in
m|M)
read -rp "Введите 64-символьный hex-ключ: " key
if ! [[ "$key" =~ ^[0-9a-fA-F]{64}$ ]]; then
echo "(не выглядит как 64-hex)"
return
fi
;;
*)
key=$(openssl rand -hex 32)
echo "[*] сгенерирован ключ: $key"
;;
esac

mkdir -p "$USERS_DIR/$name"
# shellcheck disable=SC1090
set -a; source "$DEFAULTS"; set +a
cat > "$USERS_DIR/$name/.env" <<EOF
OLCRTC_CARRIER=$OLCRTC_CARRIER
OLCRTC_TRANSPORT=$OLCRTC_TRANSPORT
OLCRTC_ROOM_ID=any
OLCRTC_CLIENT_ID=$name
OLCRTC_KEY=$key
OLCRTC_DNS=$OLCRTC_DNS
OLCRTC_SOCKS_PROXY=$OLCRTC_SOCKS_PROXY
OLCRTC_SOCKS_PROXY_PORT=$OLCRTC_SOCKS_PROXY_PORT
OLCRTC_VP8_FPS=$OLCRTC_VP8_FPS
OLCRTC_VP8_BATCH=$OLCRTC_VP8_BATCH
EOF
chmod 600 "$USERS_DIR/$name/.env"

echo "[*] стартую контейнер..."
compose_up "$name" >/dev/null
echo "[*] жду создания комнаты WB Stream..."
local room=""
local i
for i in $(seq 1 30); do
sleep 2
room=$(docker logs "olcrtc-user-$name" 2>&1 \
| grep -oE "WB Stream room created: [0-9a-f-]+" \
| head -1 | awk "{print \$NF}")
[ -n "$room" ] && break
done
if [ -z "$room" ]; then
echo "[!] не удалось получить room_id. Логи:"
docker logs --tail 30 "olcrtc-user-$name"
return
fi
echo "[+] комната создана: $room"
sed -i "s/^OLCRTC_ROOM_ID=any\$/OLCRTC_ROOM_ID=$room/" "$USERS_DIR/$name/.env"
compose_up "$name" >/dev/null
sleep 3
echo
show_user "$name"
}

action_delete() {
mapfile -t users < <(list_users)
if [ ${#users[@]} -eq 0 ]; then
echo "(пользователей нет)"
return
fi
local i
for i in "${!users[@]}"; do
printf " %3d) %s\n" "$((i+1))" "${users[$i]}"
done
echo
read -rp "Номер удаляемого: " pick
if ! [[ "$pick" =~ ^[0-9]+$ ]] || [ "$pick" -lt 1 ] || [ "$pick" -gt "${#users[@]}" ]; then
echo "(неверный номер)"
return
fi
local user=${users[$((pick-1))]}
read -rp "Удалить пользователя \"$user\"? (y/N): " conf
if ! [[ "$conf" =~ ^[yY]$ ]]; then
echo "(отменено)"
return
fi
compose_down "$user" >/dev/null 2>&1 || true
rm -rf "${USERS_DIR:?}/$user"
echo "[+] пользователь $user удалён"
}

# ----- main -----
while true; do
echo
echo "=== olcrtc users ==="
echo " 1) Список пользователей (выбор → ссылка)"
echo " 2) Создать пользователя"
echo " 3) Удалить пользователя"
echo " 0) Выход"
read -rp "> " choice
case "$choice" in
1) action_list ;;
2) action_new ;;
3) action_delete ;;
0|q|Q|"") exit 0 ;;
*) echo "(неверный выбор)" ;;
esac
done
</syntaxhighlight>

=== Устройство скрипта ===

==== Общий принцип ====
Скрипт — это интерактивная обёртка над <code>docker compose</code>. Никакой собственной бизнес-логики у него нет — все действия сводятся к запуску и остановке контейнеров с разными параметрами.

Каждый пользователь — это отдельный compose-проект с уникальным именем <code>olcrtc-user-<имя></code>. Compose-файл единый для всех (<code>shared/docker-compose.user.yml</code>); различия задаются через <code>--env-file</code>, который указывает на личный <code>.env</code> пользователя.

==== Защитные механизмы ====

* <code>set -euo pipefail</code> — прерывание при любой ошибке, защита от использования несуществующих переменных, корректная обработка пайпов.
* Проверка наличия <code>shared/</code> в самом начале — скрипт не запустится в неинициализированной системе.
* Валидация имени по регулярному выражению <code>^[a-zA-Z0-9_-]{1,32}$</code> — защита от инъекций в имена контейнеров и путей файловой системы.
* Валидация ключа по регулярному выражению <code>^[0-9a-fA-F]{64}$</code> — защита от неправильного формата при ручном вводе.
* Подтверждение <code>(y/N)</code> при удалении — защита от случайного удаления.
* Конструкция <code>${USERS_DIR:?}</code> в <code>rm -rf</code> — защита от случайного <code>rm -rf /</code>, если переменная окажется пустой.

==== Хелперы ====
{| class="wikitable"
!Функция
!Назначение
|-
|<code>list_users()</code>
|Возвращает список всех пользователей. Использует <code>find</code> с фильтром <code>-mindepth 1 -maxdepth 1 -type d</code> и исключает каталог <code>shared</code>.
|-
|<code>container_status()</code>
|Опрашивает Docker через <code>docker inspect -f {{.State.Status}}</code>. При отсутствии контейнера возвращает строку <code>missing</code>.
|-
|<code>read_env()</code>
|Читает значение переменной из <code>.env</code> через <code>grep + cut</code>. Не использует <code>source</code>, чтобы избежать побочных эффектов от загрузки переменных.
|-
|<code>build_uri()</code>
|Конкатенирует значения переменных в URI <code>olcrtc://CARRIER?TRANSPORT@ROOM#KEY%CID$MIMO</code> через <code>printf</code>.
|-
|<code>show_user()</code>
|Полная карточка пользователя: статус, все поля, готовый URI.
|-
|<code>valid_name()</code>
|Проверка имени пользователя по регулярному выражению.
|-
|<code>compose_up()</code> / <code>compose_down()</code>
|Запуск и остановка контейнера через <code>docker compose</code> с правильными флагами <code>-f</code>, <code>--env-file</code>, <code>-p</code>.
|}

==== Действие «Список пользователей» ====

# Получает массив пользователей в переменной <code>users</code> через <code>mapfile</code>.
# Печатает заголовок таблицы.
# Для каждого пользователя печатает номер, имя и статус контейнера.
# Спрашивает номер. Пустой ввод — выход. Невалидный номер — сообщение об ошибке.
# При корректном выборе вызывает <code>show_user</code>.

==== Действие «Создать пользователя» ====

# Запрашивает имя, валидирует.
# Проверяет, что каталог <code>$USERS_DIR/$name</code> ещё не существует.
# Запрашивает режим ключа: <code>a</code> (auto, по умолчанию) или <code>m</code> (manual).
# При auto вызывает <code>openssl rand -hex 32</code>; при manual запрашивает и валидирует ввод.
# Создаёт каталог пользователя.
# Через <code>set -a; source $DEFAULTS; set +a</code> подгружает дефолты в окружение.
# Записывает <code>.env</code> пользователя через here-doc.
# Меняет права на <code>.env</code> на <code>0600</code> (только владелец).
# Запускает контейнер через <code>compose_up</code>.
# В цикле до 60 секунд (<code>30 итераций × 2 сек</code>) парсит логи контейнера регулярным выражением <code>WB Stream room created: [0-9a-f-]+</code>.
# При получении room_id обновляет <code>.env</code> через <code>sed -i</code>.
# Перезапускает контейнер с фиксированным room_id.
# Выводит карточку пользователя через <code>show_user</code>.

==== Действие «Удалить пользователя» ====

# Получает массив пользователей.
# Печатает пронумерованный список.
# Запрашивает номер, валидирует.
# Запрашивает подтверждение <code>(y/N)</code>.
# Вызывает <code>compose_down</code> с флагом <code>-v</code> — это удалит и docker volume.
# Удаляет каталог пользователя через <code>rm -rf</code>.

==== Главный цикл ====
Бесконечный цикл с <code>case</code>-разбором ввода:

* <code>1</code> → действие «Список»
* <code>2</code> → действие «Создать»
* <code>3</code> → действие «Удалить»
* <code>0</code>, <code>q</code>, <code>Q</code>, пустой ввод (Enter, Ctrl+D) → выход.
* Любой другой ввод — сообщение «неверный выбор» и продолжение цикла.

=== Возможные расширения ===
Скрипт намеренно простой и легко расширяется. Возможные улучшения:
{| class="wikitable"
!Что добавить
!Как
|-
|Перезапуск отдельного пользователя
|Новый пункт меню → <code>compose_down</code> + <code>compose_up</code>
|-
|Просмотр логов пользователя
|<code>docker logs --tail 50 olcrtc-user-$name</code>
|-
|Экспорт всех URI в файл подписки
|Цикл по <code>list_users</code>, на каждом — <code>build_uri</code>; добавить заголовок согласно <code>docs/sub.md</code> upstream-репозитория
|-
|Автоматическое обновление образа
|<code>git -C /opt/olcrtc pull --recurse-submodules</code> и <code>docker compose build</code>, затем перезапуск всех пользователей
|-
|HTTPS-эндпоинт <code>/sub</code> для раздачи конфигов
|Reverse proxy (caddy / nginx) на статический файл, который генерируется крон-задачей из <code>build_uri</code>
|}
|}
----

== FAQ ==

=== Почему «один сервер ↔ один клиент»? ===
Это архитектурное свойство кода: сервер хранит одну сессию <code>smux</code> и одно поле <code>clientID</code>, не таблицу пиров. Изменение этой модели потребовало бы существенной переработки <code>internal/server/server.go</code> и поддержки множественных peer-connection в каждом провайдере.

=== Почему рекомендуется <code>vp8channel</code>, а не <code>datachannel</code>? ===
<code>datachannel</code> быстрее и имеет минимальный пинг, но: Telemost его не поддерживает, а Jazz может ограничивать IP-адреса серверов, использующих этот тип канала. <code>vp8channel</code> работает со всеми тремя сервисами и подходит для большинства сценариев.

=== Что такое «ограничение IP» со стороны carrier? ===
Некоторые carrier-сервисы используют автоматические эвристики против ботов. После срабатывания таких эвристик подключения с конкретного IP могут перестать пропускаться в виртуальные конференции. Лечится сменой IP сервера или ожиданием снятия ограничения. На момент написания статьи WB Stream таких эвристик не применяет.

=== Сколько контейнеров можно запустить на одной виртуальной машине? ===
В простое каждый контейнер потребляет приблизительно 10–15 МБ RAM и около 0% CPU. На VM с 4 GiB RAM реалистично запустить 50–100 пользователей. Узкими местами обычно становятся пропускная способность сетевого канала и допустимое количество одновременных WebRTC-сессий со стороны carrier-сервиса.

=== Можно ли использовать одну ссылку с нескольких устройств? ===
Технически — да, но не одновременно. Если включить туннель на двух устройствах с одной ссылкой, они будут конкурировать за один peer-connection и периодически разрывать друг друга. Для параллельной работы нужны разные пользователи (разные ссылки).

=== Виден ли реальный видеосигнал участникам конференции? ===
В транспортах <code>vp8channel</code> и <code>seichannel</code> поверх WebRTC отправляется минимально валидный видеопоток, в который встроены полезные данные. Внешне это выглядит как очень тихая «моностатичная» камера. В <code>videochannel</code> отправляется реальный видеоряд (QR-коды или тайлы) — формально это видимая «картинка». Если в виртуальной конференции, кроме сервера и клиента, никого нет — это никак не проявляется.

=== Что делать, если конкретный transport перестал работать? ===
Если carrier изменил проверки SFU и какой-то transport стал ненадёжен — переключитесь на другой transport (<code>seichannel</code> или <code>videochannel</code>) или другой carrier. Меняется в <code>defaults.env</code> для новых пользователей и в личном <code>.env</code> для существующих (с последующим перезапуском контейнера).

=== Можно ли совместить olcRTC с другими методами? ===
Да. С точки зрения клиентского приложения olcRTC — это локальный SOCKS5-прокси. Его можно использовать как один из outbound в xray, sing-box и подобных инструментах. На стороне сервера выходной трафик может быть направлен через xray + WARP (опциональный шаг 11 раздела установки) для дополнительной анонимизации.
----

== Полезные ссылки ==

* [https://github.com/openlibrecommunity/olcrtc Репозиторий olcrtc на GitHub] — основной upstream проекта.
* [https://github.com/alananisimov/olcbox Olcbox] — мультиплатформенный клиент с UI (Android, macOS, Windows, Linux).
* [https://github.com/openlibrecommunity/olcrtc/blob/master/docs/uri.md docs/uri.md] — официальное описание формата URI.
* [https://github.com/openlibrecommunity/olcrtc/blob/master/docs/sub.md docs/sub.md] — формат файла подписки для нескольких локаций.
* [https://github.com/openlibrecommunity/olcrtc/blob/master/docs/settings.md docs/settings.md] — матрица совместимости carrier × transport, описание всех флагов.
* [https://github.com/MHSanaei/3x-ui 3x-ui] — панель управления xray-core (для настройки egress через WARP).

----

Файл:Olcrtc-data-flow.png

2026-05-09T07:55:30Z

Владимир: Поток данных olcRTC: от клиентского приложения через SOCKS5, smux + ChaCha20-Poly1305, транспорт и WebRTC peer-connection в видеоконференции, до серверного outbound и целевого сайта

== Краткое описание ==
Поток данных olcRTC: от клиентского приложения через SOCKS5, smux + ChaCha20-Poly1305, транспорт и WebRTC peer-connection в видеоконференции, до серверного outbound и целевого сайта

OlcRTC: туннель через WebRTC-сервисы

2026-05-09T07:42:53Z

Владимир: Новая страница: «= olcRTC: туннелирование SOCKS5-трафика через публичные WebRTC-сервисы = == Введение == === Что такое olcRTC === olcRTC — это инструмент для построения SOCKS5-туннеля поверх инфраструктуры публичных сервисов видеосвязи. В отличие от классических VPN-протоколов, которые работ...»

= olcRTC: туннелирование SOCKS5-трафика через публичные WebRTC-сервисы =

== Введение ==

=== Что такое olcRTC ===
olcRTC — это инструмент для построения SOCKS5-туннеля поверх инфраструктуры публичных сервисов видеосвязи. В отличие от классических VPN-протоколов, которые работают через выделенные UDP/TCP-порты на собственном сервере, olcRTC использует уже существующие WebRTC-каналы общедоступных видеоконференц-сервисов в качестве несущей среды.

Поддерживаются три сервиса:
{| class="wikitable"
!Carrier
!Сервис
!Адрес
|-
|<code>wbstream</code>
|WB Stream
|<code>stream.wb.ru</code>
|-
|<code>telemost</code>
|Yandex Telemost
|<code>telemost.yandex.ru</code>
|-
|<code>jazz</code>
|SaluteJazz
|<code>salutejazz.ru</code>
|}
Сервер olcRTC выступает в роли участника виртуальной видеоконференции (с автоматически сгенерированным именем). Клиент подключается к той же конференции и через peer-connection обменивается с сервером данными — поверх этого канала идёт трафик SOCKS5-туннеля.

=== Когда применяется ===

* Канал между клиентом и обычными VPN-серверами нестабилен или имеет высокий процент потерь.
* Требуется передать данные через инфраструктуру, использующую WebRTC, а не выделенные транспортные порты.
* Нужна альтернатива, которая работает поверх стандартного для пользовательских устройств WebRTC-стека (браузер, мобильное приложение).

=== Сравнение с другими методами туннелирования ===
{| class="wikitable"
!Метод
!Транспорт
!Особенность
|-
|WireGuard
|UDP
|Прямое соединение с собственным сервером, минимальные накладные расходы
|-
|OpenVPN
|UDP/TCP
|Универсальная совместимость, выше накладные расходы
|-
|Shadowsocks
|TCP
|Шифрованный поток, маскировка под произвольный TCP
|-
|VLESS + REALITY
|TCP (TLS)
|TLS-handshake донора (стороннего сайта)
|-
|NaiveProxy
|TCP (HTTP/2)
|Использует Chrome-стек, неотличим от обычного HTTPS
|-
|Hysteria2
|UDP (QUIC)
|QUIC поверх UDP с маскировкой под HTTPS
|-
|'''olcRTC'''
|'''WebRTC поверх QUIC/UDP'''
|'''Использует существующую инфраструктуру SFU публичного сервиса видеосвязи в качестве несущей'''
|}
----

== Принципы работы ==

=== Поток данных ===
<pre>
[Браузер / приложение клиента]
│
│ SOCKS5 на 127.0.0.1:1080
▼
[olcRTC client (cnc)]
│
│ smux мультиплексирование
│ ChaCha20-Poly1305 шифрование
▼
[Транспорт: datachannel / vp8 / sei / video]
│
│ WebRTC (peer-connection через SFU)
▼
[Видеоконференция WB Stream / Telemost / Jazz]
│
▲
│ тот же канал, серверная сторона
│
[Транспорт] ← [olcRTC server (srv)]
│
│ SOCKS5 (опционально, через локальный xray)
▼
[Outbound: прямой выход в интернет ИЛИ xray + WARP]
│
▼
[Целевой сайт]
</pre>

=== Слои кода ===
Кодовая база разделена на четыре независимых слоя с реестром расширений:
{| class="wikitable"
!Слой
!Ответственность
!Реализации
|-
|Carrier
|Сессия в видеосервисе: вход в конференцию, регистрация участника, peer-connection через SFU
|<code>wbstream</code>, <code>telemost</code>, <code>jazz</code>
|-
|Link
|Поверх транспорта; в текущей версии только <code>direct</code> (passthrough)
|<code>direct</code>
|-
|Transport
|Способ кодирования байтов внутри WebRTC-канала
|<code>datachannel</code>, <code>vp8channel</code>, <code>seichannel</code>, <code>videochannel</code>
|-
|Application
|Сервер (приём входящих туннелей) или клиент (локальный SOCKS5)
|<code>server</code>, <code>client</code>
|}

=== Транспорты ===
{| class="wikitable"
!Транспорт
!Несущая в WebRTC
!Идея
!Скорость
!Пинг
!WB Stream
!Telemost
!Jazz
|-
|<code>datachannel</code>
|RTCDataChannel
|Прямые байты в датаканале
|Максимум
|Минимум
|✓
|✗
|⚠
|-
|<code>vp8channel</code>
|VP8-видеотрек
|KCP-пакеты внутри валидных VP8-кадров
|Высокая
|Средний
|✓
|✓
|✓
|-
|<code>seichannel</code>
|H.264 SEI NAL
|Полезные данные в SEI-сообщениях видеопотока
|Низкая
|Низкий
|✓
|✗
|✓
|-
|<code>videochannel</code>
|Видеокадры
|QR-коды или тайлы Reed-Solomon в видеопотоке
|Минимум
|Максимум
|✓
|✓
|✓
|}
Рекомендуемая универсальная связка: <code>wbstream + vp8channel</code>. Она используется в данной статье как основная конфигурация.

=== Шифрование ===
{| class="wikitable"
!Параметр
!Значение
|-
|Алгоритм
|XChaCha20-Poly1305 (AEAD)
|-
|Длина ключа
|32 байта (64 hex-символа)
|-
|Nonce
|24 байта, случайный, на каждый фрейм, префиксится к шифротексту
|-
|Идентификация клиента
|Поле <code>client_id</code> в открытом JSON, сравнивается с серверным значением
|}
Реальная криптографическая защита — это ключ. <code>client_id</code> — лишь дополнительная проверка от случайных подключений в той же конференции, не криптографическая.

=== Smux: мультиплексирование ===
Поверх единого WebRTC-канала работает <code>xtaci/smux</code> v2. Один физический канал содержит много логических TCP-стримов: каждый запрос SOCKS5 от приложения открывается как отдельный smux-стрим.

=== Архитектурное ограничение: один сервер — один клиент ===
Это важное свойство кода, которое необходимо понимать.

Один экземпляр сервера olcRTC обслуживает '''ровно одного клиента в момент времени'''. Это не упущение, а сознательное архитектурное решение.

Причины:

* Сервер хранит '''одну''' переменную <code>clientID</code> и сравнивает с присланным значением (см. <code>internal/server/server.go:399-401</code>).
* Сервер держит '''один''' link и '''одну''' smux-сессию, не словарь по идентификатору.
* Провайдер carrier держит один RTCPeerConnection.

{| class="wikitable"
!Сценарий
!Поведение
|-
|Один владелец, разные устройства, по очереди (выключил ноутбук, включил телефон)
|Работает с одной ссылкой
|-
|Один владелец, разные устройства, одновременно
|Устройства конкурируют за peer-connection, рвут друг друга
|-
|Несколько разных людей, одна ссылка на всех, одновременно
|То же — рвут друг друга
|-
|Несколько пользователей, у каждого своя ссылка
|Работает; '''требуется отдельный контейнер на каждого пользователя'''
|}
Для предоставления доступа нескольким людям одновременно необходимо запустить несколько независимых контейнеров — каждый со своими <code>room_id</code>, <code>key</code> и <code>client_id</code>. В разделе «Управление несколькими пользователями» описан скрипт, который автоматизирует это.
----

== Что должно быть на сервере перед установкой ==

=== Минимально необходимая конфигурация ===
Перед началом установки olcRTC сервер должен находиться в следующем состоянии:
{| class="wikitable"
!№
!Требование
!Зачем
|-
|1
|Установлена операционная система Linux (Ubuntu 22.04+, Debian 12+, Fedora 38+ или сравнимая)
|Среда выполнения Docker
|-
|2
|Доступ по SSH с правами <code>root</code> (либо аккаунт с <code>sudo</code> без пароля)
|Установка пакетов и управление контейнерами
|-
|3
|Установлены Docker Engine 24.0+ и Docker Compose v2.20+
|Запуск контейнера olcRTC
|-
|4
|Установлена утилита <code>git</code>
|Скачивание исходного кода olcRTC с репозитория
|-
|5
|Установлена утилита <code>openssl</code>
|Генерация ключа шифрования
|}

=== Опциональная (но настоятельно рекомендуемая) конфигурация: egress через WARP ===
По умолчанию olcRTC сервер выходит в интернет напрямую с публичного IP вашей виртуальной машины. Все целевые сайты будут видеть именно этот адрес.

Чтобы выходной трафик уходил через Cloudflare WARP, требуется промежуточная цепочка через локальный SOCKS5-прокси. Самая распространённая реализация — панель '''3x-ui''' (web-интерфейс над xray-core).

==== Что должно быть подготовлено в 3x-ui ====
{| class="wikitable"
!№
!Параметр
!Значение для нашей статьи
!Комментарий
|-
|1
|Сама панель 3x-ui установлена и доступна
|—
|Установка описана в отдельной статье ([[Установка 3x-ui]]); если её ещё нет — выполните установку до начала
|-
|2
|Outbound в WARP активен и протестирован
|tag <code>warp</code> или аналогичный
|Должен быть настроен как WireGuard-outbound к Cloudflare WARP. Проверка: маршрут с outbound отдаёт IPv6 из диапазона <code>2a09:bac5::/29</code> или IPv4 <code>104.28.x.x</code>
|-
|3
|Inbound типа '''mixed''' (SOCKS5 + HTTP), слушающий '''только на 127.0.0.1'''
|порт <code>24365</code>
|Этот порт мы будем указывать в конфигурации olcRTC. Выберите любой свободный, мы используем 24365 как пример
|-
|4
|Аутентификация (логин/пароль) на этом mixed-inbound '''отключена'''
|—
|olcRTC-сервер умеет работать только с режимом NOAUTH; если включена авторизация, цепочка не будет работать
|-
|5
|Routing-rule в xray: трафик с inbound mixed → outbound warp
|—
|В 3x-ui это настраивается в разделе «Настройки xray → Маршрутизация»
|}

==== Как проверить, что цепочка работает ====
Команда ниже выполняется на самом сервере (не на компьютере пользователя). Она запрашивает свой IP-адрес через локальный SOCKS5-прокси, который должен направить запрос в WARP.

Замените <code>24365</code> на ваш реальный номер порта mixed-inbound.<syntaxhighlight lang="bash">
curl --socks5-hostname 127.0.0.1:24365 https://icanhazip.com
</syntaxhighlight>Ожидаемый результат: IP-адрес из диапазона Cloudflare WARP (например, <code>104.28.218.x</code> или IPv6 <code>2a09:bac5:...</code>). Если возвращается публичный IP вашего сервера — значит цепочка не сработала и трафик идёт мимо WARP. В этом случае проверьте настройки routing в 3x-ui.

Если egress через WARP вам не нужен (готовы выходить с публичного IP сервера), можно пропустить этот раздел. В дальнейших шагах указания для случая «без WARP» помечены явно.
----

== Параметры, которые нужно подготовить заранее ==
Перед началом установки заполните таблицу ниже своими значениями. На каждом шаге, где встретится плейсхолдер, мы будем ссылаться на эту таблицу.
{| class="wikitable"
!Плейсхолдер
!Что это
!Где взять
!Пример
|-
|<code>YOUR_SERVER_HOST</code>
|Адрес сервера для подключения по SSH: либо публичный IP, либо имя из <code>~/.ssh/config</code>, либо доменное имя
|У хостинг-провайдера в панели управления виртуальной машиной
|<code>198.51.100.42</code> или <code>my-vps</code>
|-
|<code>YOUR_SSH_USER</code>
|Имя пользователя SSH
|В письме от хостинга при создании VM. Чаще всего <code>root</code>
|<code>root</code>
|-
|<code>YOUR_KEY_HEX</code>
|32-байтный ключ шифрования olcRTC в hex-формате (64 символа)
|Будет сгенерирован командой на шаге 4. Сохраните в надёжное место
|<code>1c3f8a2b...d4e5f6a7</code> (64 hex-символа)
|-
|<code>YOUR_CLIENT_ID</code>
|Идентификатор клиента; должен совпадать на сервере и в клиентском приложении
|Любое имя на латинице длиной 1–32 символа: буквы, цифры, <code>_</code>, <code>-</code>
|<code>my-laptop</code>
|-
|<code>YOUR_ROOM_ID</code>
|Идентификатор виртуальной видеоконференции
|Будет получен из логов сервера на шаге 7
|<code>019e07b8-e292-73ec-a40b-6a6e4957ce01</code>
|-
|<code>YOUR_SOCKS_PORT</code>
|Порт mixed-inbound в 3x-ui для egress через WARP (опционально)
|См. раздел «Что должно быть на сервере перед установкой»
|<code>24365</code>
|}
Сохраните эту таблицу в текстовом файле — заполните по мере прохождения шагов. Особенно важно сохранить <code>YOUR_KEY_HEX</code> и <code>YOUR_ROOM_ID</code> — без них нельзя восстановить доступ к серверу после перезапуска.
----

== Установка сервера: пошаговая инструкция ==
В этом разделе все команды выполняются на сервере (через SSH). Каждое пояснение — одна команда. Если команда выдала ошибку — остановитесь, не выполняйте следующую, и сверьтесь с предыдущим шагом.

=== Шаг 1. Подключение к серверу по SSH ===
Откройте терминал на своём компьютере. На Windows можно использовать встроенный PowerShell или Windows Terminal, на macOS — Terminal, на Linux — любой эмулятор терминала.

Замените <code>YOUR_SSH_USER</code> на имя пользователя из подготовленной таблицы (обычно <code>root</code>), а <code>YOUR_SERVER_HOST</code> — на адрес или имя сервера.<syntaxhighlight lang="bash">
ssh YOUR_SSH_USER@YOUR_SERVER_HOST
</syntaxhighlight>Если подключение прошло успешно — вы увидите приглашение командной строки сервера. Все следующие команды выполняются именно в нём.

=== Шаг 2. Проверка наличия Docker ===
Прежде чем что-то ставить, проверим, есть ли Docker уже на сервере.<syntaxhighlight lang="bash">
docker --version
</syntaxhighlight>Если команда вывела что-то вроде <code>Docker version 24.0.5, build ...</code> — Docker установлен, переходите к шагу 3.

Если команда выдала <code>command not found</code> — Docker нужно установить. Выберите один из подразделов ниже в зависимости от вашего дистрибутива.

==== 2a. Установка Docker на Ubuntu / Debian ====
Обновите список пакетов.<syntaxhighlight lang="bash">
apt update
</syntaxhighlight>Установите вспомогательные утилиты.<syntaxhighlight lang="bash">
apt install -y ca-certificates curl gnupg
</syntaxhighlight>Подготовьте каталог для GPG-ключей репозитория Docker.<syntaxhighlight lang="bash">
install -m 0755 -d /etc/apt/keyrings
</syntaxhighlight>Скачайте GPG-ключ официального репозитория Docker.<syntaxhighlight lang="bash">
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
</syntaxhighlight>Дайте права на чтение всем.<syntaxhighlight lang="bash">
chmod a+r /etc/apt/keyrings/docker.gpg
</syntaxhighlight>Добавьте репозиторий Docker в систему.<syntaxhighlight lang="bash">
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
</syntaxhighlight>Снова обновите список пакетов (теперь уже с новым репозиторием).<syntaxhighlight lang="bash">
apt update
</syntaxhighlight>Установите Docker и плагины.<syntaxhighlight lang="bash">
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
</syntaxhighlight>

==== 2b. Установка Docker на Fedora / RHEL ====
Установите менеджер репозиториев.<syntaxhighlight lang="bash">
dnf -y install dnf-plugins-core
</syntaxhighlight>Подключите репозиторий Docker.<syntaxhighlight lang="bash">
dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
</syntaxhighlight>Установите Docker.<syntaxhighlight lang="bash">
dnf -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
</syntaxhighlight>Запустите и включите автозапуск Docker.<syntaxhighlight lang="bash">
systemctl enable --now docker
</syntaxhighlight>

==== 2c. Проверка установки Docker (любая ОС) ====
Проверьте, что Docker установлен и работает.<syntaxhighlight lang="bash">
docker --version
</syntaxhighlight>Должно вывести что-то вроде <code>Docker version 24.0.5</code>.

Проверьте, что плагин Compose доступен.<syntaxhighlight lang="bash">
docker compose version
</syntaxhighlight>Должно вывести что-то вроде <code>Docker Compose version v2.20.2</code>.

Если обе команды отработали без ошибок — переходите к шагу 3.

=== Шаг 3. Создание рабочего каталога ===
Создайте каталог, в котором будет лежать репозиторий olcRTC.<syntaxhighlight lang="bash">
mkdir -p /opt/olcrtc
</syntaxhighlight>Перейдите в этот каталог.<syntaxhighlight lang="bash">
cd /opt/olcrtc
</syntaxhighlight>

=== Шаг 4. Скачивание исходного кода olcRTC ===
Скачайте репозиторий вместе с подмодулями (флаг <code>--recurse-submodules</code> обязателен — без него транспорт <code>videochannel</code> не соберётся).<syntaxhighlight lang="bash">
git clone --depth 1 --recurse-submodules --branch master https://github.com/openlibrecommunity/olcrtc.git .
</syntaxhighlight>Точка в конце команды означает «скачать в текущий каталог», не создавая вложенной папки. Если вы пропустили шаг 3 (<code>cd /opt/olcrtc</code>), команда создаст репозиторий не в том месте.

Проверьте, что скачивание прошло успешно.<syntaxhighlight lang="bash">
ls /opt/olcrtc
</syntaxhighlight>В выводе должны быть файлы <code>Dockerfile</code>, <code>go.mod</code>, каталоги <code>cmd</code>, <code>internal</code>, <code>script</code> и другие.

=== Шаг 5. Генерация ключа шифрования ===
Сгенерируйте ключ командой <code>openssl</code>.<syntaxhighlight lang="bash">
openssl rand -hex 32
</syntaxhighlight>Команда выведет строку из 64 hex-символов. Например:
1c3f8a2b3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7a8b9c0d1e2
'''Скопируйте этот ключ''' и впишите его в свою таблицу подготовки как <code>YOUR_KEY_HEX</code>. Этот же ключ потом понадобится для настройки клиента.

=== Шаг 6. Создание конфигурационного файла .env ===
Файл <code>.env</code> хранит параметры запуска. Создадим его, подставив ваши значения.

Замените:

* <code>ВАШ_КЛЮЧ</code> — на значение <code>YOUR_KEY_HEX</code> из шага 5.
* <code>my-laptop</code> — на значение <code>YOUR_CLIENT_ID</code> из таблицы подготовки.

Если вы '''используете''' egress через WARP (раздел «Что должно быть на сервере перед установкой»), также замените <code>24365</code> на свой <code>YOUR_SOCKS_PORT</code>. Если '''не используете''' WARP — удалите две строки <code>OLCRTC_SOCKS_PROXY=...</code>.<syntaxhighlight lang="bash">
nano /opt/olcrtc/.env
</syntaxhighlight>В открывшемся редакторе вставьте следующее содержимое:<syntaxhighlight lang="ini">
OLCRTC_CARRIER=wbstream
OLCRTC_TRANSPORT=vp8channel
OLCRTC_ROOM_ID=any
OLCRTC_CLIENT_ID=my-laptop
OLCRTC_KEY=ВАШ_КЛЮЧ
OLCRTC_DNS=1.1.1.1:53
OLCRTC_SOCKS_PROXY=127.0.0.1
OLCRTC_SOCKS_PROXY_PORT=24365
OLCRTC_VP8_FPS=60
OLCRTC_VP8_BATCH=64
OLCRTC_DEBUG=false
</syntaxhighlight>Сохраните файл: нажмите <code>Ctrl+O</code>, затем <code>Enter</code>, затем <code>Ctrl+X</code>.

Защитите файл от чтения посторонними (он содержит ваш ключ).<syntaxhighlight lang="bash">
chmod 600 /opt/olcrtc/.env
</syntaxhighlight>Проверьте, что значения подставились правильно.<syntaxhighlight lang="bash">
cat /opt/olcrtc/.env
</syntaxhighlight>В строке <code>OLCRTC_KEY=...</code> должен быть ваш ключ, в строке <code>OLCRTC_CLIENT_ID=...</code> — ваше имя пользователя.

=== Шаг 7. Замена docker-compose.server.yml ===
Стандартный compose-файл из репозитория не использует режим <code>host</code>, который нужен для доступа к локальному xray. Заменим его на нашу версию.

Откройте файл для редактирования.<syntaxhighlight lang="bash">
nano /opt/olcrtc/docker-compose.server.yml
</syntaxhighlight>Удалите всё содержимое (зажмите <code>Ctrl+K</code> до полной очистки) и вставьте следующее:<syntaxhighlight lang="yaml">
services:
olcrtc-server:
build:
context: .
image: olcrtc/server:local
container_name: olcrtc-server
restart: unless-stopped
network_mode: host
environment:
OLCRTC_MODE: srv
OLCRTC_CARRIER: "${OLCRTC_CARRIER:?set OLCRTC_CARRIER}"
OLCRTC_TRANSPORT: "${OLCRTC_TRANSPORT:?set OLCRTC_TRANSPORT}"
OLCRTC_ROOM_ID: "${OLCRTC_ROOM_ID:?set OLCRTC_ROOM_ID}"
OLCRTC_CLIENT_ID: "${OLCRTC_CLIENT_ID:?set OLCRTC_CLIENT_ID}"
OLCRTC_KEY: "${OLCRTC_KEY:?set OLCRTC_KEY}"
OLCRTC_DNS: "${OLCRTC_DNS:-1.1.1.1:53}"
OLCRTC_SOCKS_PROXY: "${OLCRTC_SOCKS_PROXY:-}"
OLCRTC_SOCKS_PROXY_PORT: "${OLCRTC_SOCKS_PROXY_PORT:-1080}"
OLCRTC_VP8_FPS: "${OLCRTC_VP8_FPS:-60}"
OLCRTC_VP8_BATCH: "${OLCRTC_VP8_BATCH:-64}"
OLCRTC_DEBUG: "${OLCRTC_DEBUG:-false}"
volumes:
- olcrtc-state:/var/lib/olcrtc
init: true

volumes:
olcrtc-state:
</syntaxhighlight>Сохраните файл: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

=== Шаг 8. Сборка Docker-образа olcRTC ===
Перейдите в каталог проекта (если ещё не там).<syntaxhighlight lang="bash">
cd /opt/olcrtc
</syntaxhighlight>Запустите сборку.<syntaxhighlight lang="bash">
docker compose -f docker-compose.server.yml --env-file .env build
</syntaxhighlight>Сборка длится 1–3 минуты. Скачиваются зависимости Go и компилируется бинарник. Если в процессе возникает ошибка вида «context canceled» или «network unreachable» — повторите команду; первый прогон бывает прерывистым из-за нестабильности зеркал.

Когда сборка успешно завершится, в выводе появится строка <code>Image olcrtc/server:local Built</code>.

=== Шаг 9. Запуск контейнера ===
Запустите контейнер в фоновом режиме.<syntaxhighlight lang="bash">
docker compose -f docker-compose.server.yml --env-file .env up -d
</syntaxhighlight>Подождите 15–20 секунд, чтобы сервер успел подключиться к WB Stream и создать виртуальную конференцию.<syntaxhighlight lang="bash">
sleep 20
</syntaxhighlight>Посмотрите логи.<syntaxhighlight lang="bash">
docker logs olcrtc-server
</syntaxhighlight>Ожидаемый вывод:
Connecting link via direct/vp8channel/wbstream...
WB Stream room created: 019e07b8-e292-73ec-a40b-6a6e4957ce01
To connect client use: -id 019e07b8-e292-73ec-a40b-6a6e4957ce01
Link connected
'''Скопируйте идентификатор после <code>WB Stream room created:</code>''' и впишите его в таблицу подготовки как <code>YOUR_ROOM_ID</code>. Без этого значения невозможно настроить клиента.

=== Шаг 10. Фиксация room_id в .env ===
Сейчас в файле <code>.env</code> стоит <code>OLCRTC_ROOM_ID=any</code>. Это значение означает «при каждом запуске создавать новую конференцию». Если оставить его — после следующего перезапуска контейнера все ссылки клиентов перестанут работать, потому что комната окажется новой.

Зафиксируйте полученный идентификатор.

Замените <code>YOUR_ROOM_ID</code> в команде ниже на скопированное значение из шага 9.<syntaxhighlight lang="bash">
sed -i 's/^OLCRTC_ROOM_ID=any$/OLCRTC_ROOM_ID=YOUR_ROOM_ID/' /opt/olcrtc/.env
</syntaxhighlight>Перезапустите контейнер с новым значением.<syntaxhighlight lang="bash">
docker compose -f /opt/olcrtc/docker-compose.server.yml --env-file /opt/olcrtc/.env up -d
</syntaxhighlight>Подождите 10 секунд и снова проверьте логи.<syntaxhighlight lang="bash">
sleep 10 && docker logs --tail 5 olcrtc-server
</syntaxhighlight>Теперь в логе не должно быть строки <code>WB Stream room created</code> — должна быть только <code>Connecting link via direct/vp8channel/wbstream...</code> и <code>Link connected</code>. Это означает, что сервер заходит в существующую комнату, а не создаёт новую.

=== Шаг 11. Формирование ссылки для клиента ===
Ссылка имеет фиксированный текстовый формат:
olcrtc://CARRIER?TRANSPORT@ROOM_ID#KEY%CLIENT_ID$ПОДПИСЬ
Подставьте свои значения. Подпись — произвольная строка, которая отобразится в названии локации в клиентском приложении (она не влияет на работу).

Пример итоговой ссылки:<pre>
olcrtc://wbstream?vp8channel@019e07b8-e292-73ec-a40b-6a6e4957ce01#1c3f8a2b...d4e5f6a7%my-laptop$home laptop, vp8 over wbstream
</pre>
{| class="wikitable"
!Часть ссылки
!Откуда берётся
|-
|<code>wbstream</code>
|Из <code>OLCRTC_CARRIER</code> в .env
|-
|<code>vp8channel</code>
|Из <code>OLCRTC_TRANSPORT</code> в .env
|-
|<code>019e07b8-...</code>
|<code>YOUR_ROOM_ID</code> из шага 9
|-
|<code>1c3f8a2b...</code>
|<code>YOUR_KEY_HEX</code> из шага 5
|-
|<code>my-laptop</code>
|<code>YOUR_CLIENT_ID</code> из шага 6
|-
|Подпись после <code>$</code>
|Любой описательный текст
|}
Сохраните полученную ссылку в надёжное место. Её нужно будет ввести в клиентское приложение.

=== Шаг 12. Подключение клиента ===

==== 12a. Olcbox (Android, рекомендуется для смартфона) ====
Скачайте APK из репозитория [https://github.com/alananisimov/olcbox alananisimov/olcbox] (раздел Releases) и установите его на телефон.

Откройте приложение. Перейдите в раздел Locations. Нажмите Add → '''Import from clipboard'''.

Перед нажатием убедитесь, что в буфере обмена телефона лежит ваша ссылка <code>olcrtc://...</code> из шага 11. Скопируйте её любым способом — например, отправив самому себе в Telegram-секретный чат.

После импорта откройте созданную локацию и проверьте поля:

* Carrier должен быть <code>wbstream</code>.
* Transport должен быть <code>vp8channel</code>.
* VP8 FPS — установите <code>60</code> вручную (при импорте URI этот параметр сбрасывается на дефолт приложения).
* VP8 Batch — установите <code>64</code>.

Включите тумблер VPN.

==== 12b. CLI-клиент (Linux, macOS, Windows) ====
Скачайте бинарник olcrtc для своей операционной системы из релизов репозитория или соберите из исходников.

Запустите туннель. Замените все плейсхолдеры <code>YOUR_*</code> на свои значения из таблицы подготовки.<syntaxhighlight lang="bash">
./olcrtc -mode cnc -carrier wbstream -transport vp8channel -id YOUR_ROOM_ID -client-id YOUR_CLIENT_ID -key YOUR_KEY_HEX -link direct -data data -dns 1.1.1.1:53 -vp8-fps 60 -vp8-batch 64 -socks-host 127.0.0.1 -socks-port 1080
</syntaxhighlight>После запуска клиент поднимет локальный SOCKS5-прокси на <code>127.0.0.1:1080</code>.

Проверьте, что туннель работает.<syntaxhighlight lang="bash">
curl --socks5-hostname 127.0.0.1:1080 https://icanhazip.com
</syntaxhighlight>Если egress настроен через WARP — должен вернуть IP Cloudflare WARP. Если не настроен — IP вашего сервера. В обоих случаях это '''не должен быть''' IP вашего домашнего интернета.
----

== Команды управления одним сервером ==
Все команды выполняются на сервере по SSH.

Посмотреть логи в реальном времени (для выхода нажать <code>Ctrl+C</code>).<syntaxhighlight lang="bash">
docker logs -f olcrtc-server
</syntaxhighlight>Посмотреть статус контейнера.<syntaxhighlight lang="bash">
docker ps --filter name=olcrtc-server
</syntaxhighlight>Перезапустить сервер (например, после изменения .env).<syntaxhighlight lang="bash">
docker compose -f /opt/olcrtc/docker-compose.server.yml --env-file /opt/olcrtc/.env up -d
</syntaxhighlight>Остановить сервер.<syntaxhighlight lang="bash">
docker compose -f /opt/olcrtc/docker-compose.server.yml --env-file /opt/olcrtc/.env down
</syntaxhighlight>Обновить исходный код до свежей версии master.<syntaxhighlight lang="bash">
cd /opt/olcrtc && git pull --recurse-submodules
</syntaxhighlight>Пересобрать образ после обновления кода.<syntaxhighlight lang="bash">
docker compose -f /opt/olcrtc/docker-compose.server.yml --env-file /opt/olcrtc/.env build
</syntaxhighlight>Применить новый образ.<syntaxhighlight lang="bash">
docker compose -f /opt/olcrtc/docker-compose.server.yml --env-file /opt/olcrtc/.env up -d
</syntaxhighlight>
----

== Управление несколькими пользователями: скрипт <code>olcrtc-users</code> ==

=== Зачем он нужен ===
Из-за архитектурного ограничения «один сервер — один клиент» (раздел «Принципы работы → Архитектурное ограничение») для каждого пользователя нужен отдельный контейнер со своим room_id, ключом и client_id. Чтобы не повторять шаги установки руками каждый раз, написан bash-скрипт <code>olcrtc-users</code>, который автоматизирует:

* '''Создание пользователя:''' генерация ключа, создание контейнера с уникальным client_id, ловля room_id из логов, формирование готовой ссылки.
* '''Удаление пользователя:''' остановка и удаление контейнера, удаление volume и каталога.
* '''Просмотр списка и информации:''' таблица всех пользователей с возможностью получить ссылку по выбору номера.

=== Что получает каждый пользователь ===
{| class="wikitable"
!Атрибут
!Значение
|-
|Контейнер
|<code>olcrtc-user-<имя></code>
|-
|Каталог конфигурации
|<code>/opt/olcrtc-users/<имя>/</code>
|-
|Файл с переменными
|<code>/opt/olcrtc-users/<имя>/.env</code>
|-
|Compose project
|<code>olcrtc-user-<имя></code>
|-
|Docker volume
|<code>olcrtc-user-<имя>_state</code>
|-
|Виртуальная конференция
|Уникальная, создаётся при первом запуске
|-
|Ключ шифрования
|Уникальный, 32 случайных байта
|-
|Ссылка вида <code>olcrtc://...</code>
|Уникальная
|}

=== Структура каталогов ===
<pre>
/opt/olcrtc/ # репозиторий + Dockerfile (build context)
└── (код, не меняется после установки)

/opt/olcrtc-users/ # каталог менеджера пользователей
├── shared/
│ ├── docker-compose.user.yml # один шаблон compose для всех пользователей
│ └── defaults.env # значения по умолчанию для новых пользователей
├── alice/
│ └── .env # личные данные пользователя alice
├── bob/
│ └── .env
└── carol/
└── .env

/usr/local/bin/olcrtc-users # сам скрипт-меню
</pre>

=== Установка скрипта ===
Все команды выполняются на сервере по SSH.

==== Шаг 1. Создание общего каталога ====
Создайте корневой каталог для пользователей.<syntaxhighlight lang="bash">
mkdir -p /opt/olcrtc-users/shared
</syntaxhighlight>Защитите каталог.<syntaxhighlight lang="bash">
chmod 700 /opt/olcrtc-users
</syntaxhighlight>

==== Шаг 2. Создание общего шаблона docker-compose ====
Откройте файл для редактирования.<syntaxhighlight lang="bash">
nano /opt/olcrtc-users/shared/docker-compose.user.yml
</syntaxhighlight>Вставьте следующее содержимое.<syntaxhighlight lang="yaml">
services:
olcrtc:
image: olcrtc/server:local
container_name: "olcrtc-user-${OLCRTC_CLIENT_ID}"
restart: unless-stopped
network_mode: host
environment:
OLCRTC_MODE: srv
OLCRTC_CARRIER: "${OLCRTC_CARRIER}"
OLCRTC_TRANSPORT: "${OLCRTC_TRANSPORT}"
OLCRTC_ROOM_ID: "${OLCRTC_ROOM_ID}"
OLCRTC_CLIENT_ID: "${OLCRTC_CLIENT_ID}"
OLCRTC_KEY: "${OLCRTC_KEY}"
OLCRTC_DNS: "${OLCRTC_DNS}"
OLCRTC_SOCKS_PROXY: "${OLCRTC_SOCKS_PROXY}"
OLCRTC_SOCKS_PROXY_PORT: "${OLCRTC_SOCKS_PROXY_PORT}"
OLCRTC_VP8_FPS: "${OLCRTC_VP8_FPS}"
OLCRTC_VP8_BATCH: "${OLCRTC_VP8_BATCH}"
volumes:
- state:/var/lib/olcrtc
init: true

volumes:
state:
</syntaxhighlight>Сохраните: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

==== Шаг 3. Создание файла значений по умолчанию ====
Откройте файл для редактирования.<syntaxhighlight lang="bash">
nano /opt/olcrtc-users/shared/defaults.env
</syntaxhighlight>Вставьте следующее (если используете egress через WARP — оставьте порт <code>24365</code> или замените на свой <code>YOUR_SOCKS_PORT</code>).<syntaxhighlight lang="ini">
OLCRTC_CARRIER=wbstream
OLCRTC_TRANSPORT=vp8channel
OLCRTC_DNS=1.1.1.1:53
OLCRTC_SOCKS_PROXY=127.0.0.1
OLCRTC_SOCKS_PROXY_PORT=24365
OLCRTC_VP8_FPS=60
OLCRTC_VP8_BATCH=64
</syntaxhighlight>Сохраните файл: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

Защитите файл.<syntaxhighlight lang="bash">
chmod 600 /opt/olcrtc-users/shared/defaults.env
</syntaxhighlight>Если egress через WARP вам '''не нужен''', выполните дополнительную команду — она очистит поле SOCKS-прокси.<syntaxhighlight lang="bash">
sed -i 's|OLCRTC_SOCKS_PROXY=127.0.0.1|OLCRTC_SOCKS_PROXY=|' /opt/olcrtc-users/shared/defaults.env
</syntaxhighlight>

==== Шаг 4. Создание самого скрипта ====
Откройте файл скрипта в редакторе.<syntaxhighlight lang="bash">
nano /usr/local/bin/olcrtc-users
</syntaxhighlight>Вставьте полное содержимое скрипта (исходный код целиком — в спойлере «Исходный код скрипта <code>olcrtc-users</code>» в конце статьи).

Сохраните файл: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

Сделайте файл исполняемым.<syntaxhighlight lang="bash">
chmod 0755 /usr/local/bin/olcrtc-users
</syntaxhighlight>Проверьте корректность синтаксиса.<syntaxhighlight lang="bash">
bash -n /usr/local/bin/olcrtc-users && echo OK
</syntaxhighlight>Если в выводе <code>OK</code> — скрипт установлен правильно.

=== Использование скрипта ===
Запустите.<syntaxhighlight lang="bash">
olcrtc-users
</syntaxhighlight>Появится меню:<pre>
=== olcrtc users ===
1) Список пользователей (выбор → ссылка)
2) Создать пользователя
3) Удалить пользователя
0) Выход
> _
</pre>

==== Пункт 1: список пользователей ====
После выбора отобразится таблица:<pre>
# name status
--- ------------------------------ ------------
1) alice running
2) bob running
3) carol exited
</pre>Введите номер пользователя и нажмите <code>Enter</code> — появится полная карточка с готовой ссылкой <code>olcrtc://...</code>:<pre>
name : alice
status : running
carrier : wbstream
transport : vp8channel
room_id : 019e07b8-e292-73ec-a40b-6a6e4957ce01
client_id : alice
key : 1c3f8a2b...d4e5f6a7

URI for olcbox:
olcrtc://wbstream?vp8channel@019e07b8-e292-73ec-a40b-6a6e4957ce01#1c3f8a2b...d4e5f6a7%alice$alice
</pre>Чтобы пропустить выбор и вернуться в меню — нажмите <code>Enter</code> без ввода номера.

==== Пункт 2: создание пользователя ====
Скрипт спросит имя.<pre>
Имя пользователя:
</pre>Введите имя на латинице (буквы, цифры, <code>_</code>, <code>-</code>, длина 1–32 символа), например <code>alice</code>.

Затем спросит, как получить ключ.<pre>
Ключ шифрования: [a]uto / [m]anual (по умолчанию a):
</pre>Введите <code>a</code> (или просто нажмите <code>Enter</code>) — скрипт сгенерирует ключ автоматически.

Если хотите ввести ключ вручную — введите <code>m</code> и затем 64-символьный hex-ключ.

После этого скрипт сам:

* создаст каталог пользователя;
* запустит контейнер;
* подождёт создания виртуальной конференции;
* запишет полученный room_id в .env;
* перезапустит контейнер с фиксированным room_id;
* выведет готовую карточку с ссылкой.

==== Пункт 3: удаление пользователя ====
Скрипт покажет список.<pre>
1) alice
2) bob
3) carol
</pre>Введите номер удаляемого пользователя, нажмите <code>Enter</code>.

Скрипт спросит подтверждение.<pre>
Удалить пользователя "carol"? (y/N):
</pre>Введите <code>y</code> и нажмите <code>Enter</code>. Если введёте что-то другое или просто <code>Enter</code> — операция отменится.

После подтверждения:

* контейнер будет остановлен и удалён;
* docker volume будет удалён;
* каталог пользователя будет удалён;
* ссылка <code>olcrtc://...</code> у этого пользователя '''перестанет работать'''.

----

== Исходный код скрипта olcrtc-users ==
{| class="mw-collapsible mw-collapsed wikitable" width="100%"
!Развернуть полный исходный код и подробное объяснение архитектуры скрипта
|-
|
=== Полный исходный код ===
<syntaxhighlight lang="bash">
#!/usr/bin/env bash
# olcrtc-users — управление пользователями olcrtc через docker compose.
# UI: 3 пункта (список / создать / удалить), под капотом — отдельный контейнер на пользователя.

set -euo pipefail

USERS_DIR=/opt/olcrtc-users
SHARED=$USERS_DIR/shared
COMPOSE=$SHARED/docker-compose.user.yml
DEFAULTS=$SHARED/defaults.env

if [ ! -f "$COMPOSE" ] || [ ! -f "$DEFAULTS" ]; then
echo "[X] $SHARED is not initialized. Aborting." >&2
exit 1
fi

# ----- helpers -----
list_users() {
find "$USERS_DIR" -mindepth 1 -maxdepth 1 -type d ! -name shared -printf "%f\n" | sort
}

container_status() {
docker inspect -f "{{.State.Status}}" "olcrtc-user-$1" 2>/dev/null || echo "missing"
}

read_env() {
local f=$1 k=$2
grep -E "^${k}=" "$f" | cut -d= -f2-
}

build_uri() {
local f=$1
local carrier transport room key cid
carrier=$(read_env "$f" OLCRTC_CARRIER)
transport=$(read_env "$f" OLCRTC_TRANSPORT)
room=$(read_env "$f" OLCRTC_ROOM_ID)
key=$(read_env "$f" OLCRTC_KEY)
cid=$(read_env "$f" OLCRTC_CLIENT_ID)
printf "olcrtc://%s?%s@%s#%s%%%s\$%s\n" \
"$carrier" "$transport" "$room" "$key" "$cid" "$cid"
}

show_user() {
local user=$1
local f=$USERS_DIR/$user/.env
local status; status=$(container_status "$user")
echo "name : $user"
echo "status : $status"
echo "carrier : $(read_env "$f" OLCRTC_CARRIER)"
echo "transport : $(read_env "$f" OLCRTC_TRANSPORT)"
echo "room_id : $(read_env "$f" OLCRTC_ROOM_ID)"
echo "client_id : $(read_env "$f" OLCRTC_CLIENT_ID)"
echo "key : $(read_env "$f" OLCRTC_KEY)"
echo
echo "URI for olcbox:"
build_uri "$f"
}

valid_name() { [[ "$1" =~ ^[a-zA-Z0-9_-]{1,32}$ ]]; }

compose_up() {
local user=$1
docker compose -f "$COMPOSE" --env-file "$USERS_DIR/$user/.env" \
-p "olcrtc-user-$user" up -d
}

compose_down() {
local user=$1
docker compose -f "$COMPOSE" --env-file "$USERS_DIR/$user/.env" \
-p "olcrtc-user-$user" down -v
}

# ----- menu actions -----
action_list() {
mapfile -t users < <(list_users)
if [ ${#users[@]} -eq 0 ]; then
echo "(пользователей нет)"
return
fi
printf " %3s %-30s %-12s\n" "#" "name" "status"
printf " %3s %-30s %-12s\n" "---" "------------------------------" "------------"
local i
for i in "${!users[@]}"; do
printf " %3d) %-30s %-12s\n" \
"$((i+1))" "${users[$i]}" "$(container_status "${users[$i]}")"
done
echo
read -rp "Введите номер чтобы показать ссылку (Enter — пропустить): " pick
[ -z "$pick" ] && return
if ! [[ "$pick" =~ ^[0-9]+$ ]] || [ "$pick" -lt 1 ] || [ "$pick" -gt "${#users[@]}" ]; then
echo "(неверный номер)"
return
fi
echo
show_user "${users[$((pick-1))]}"
}

action_new() {
read -rp "Имя пользователя: " name
if ! valid_name "$name"; then
echo "(имя должно быть 1..32 символа, только a-z A-Z 0-9 _ -)"
return
fi
if [ -d "$USERS_DIR/$name" ]; then
echo "(пользователь \"$name\" уже существует)"
return
fi

local key
read -rp "Ключ шифрования: [a]uto / [m]anual (по умолчанию a): " mode
case "${mode:-a}" in
m|M)
read -rp "Введите 64-символьный hex-ключ: " key
if ! [[ "$key" =~ ^[0-9a-fA-F]{64}$ ]]; then
echo "(не выглядит как 64-hex)"
return
fi
;;
*)
key=$(openssl rand -hex 32)
echo "[*] сгенерирован ключ: $key"
;;
esac

mkdir -p "$USERS_DIR/$name"
# shellcheck disable=SC1090
set -a; source "$DEFAULTS"; set +a
cat > "$USERS_DIR/$name/.env" <<EOF
OLCRTC_CARRIER=$OLCRTC_CARRIER
OLCRTC_TRANSPORT=$OLCRTC_TRANSPORT
OLCRTC_ROOM_ID=any
OLCRTC_CLIENT_ID=$name
OLCRTC_KEY=$key
OLCRTC_DNS=$OLCRTC_DNS
OLCRTC_SOCKS_PROXY=$OLCRTC_SOCKS_PROXY
OLCRTC_SOCKS_PROXY_PORT=$OLCRTC_SOCKS_PROXY_PORT
OLCRTC_VP8_FPS=$OLCRTC_VP8_FPS
OLCRTC_VP8_BATCH=$OLCRTC_VP8_BATCH
EOF
chmod 600 "$USERS_DIR/$name/.env"

echo "[*] стартую контейнер..."
compose_up "$name" >/dev/null
echo "[*] жду создания комнаты WB Stream..."
local room=""
local i
for i in $(seq 1 30); do
sleep 2
room=$(docker logs "olcrtc-user-$name" 2>&1 \
| grep -oE "WB Stream room created: [0-9a-f-]+" \
| head -1 | awk "{print \$NF}")
[ -n "$room" ] && break
done
if [ -z "$room" ]; then
echo "[!] не удалось получить room_id. Логи:"
docker logs --tail 30 "olcrtc-user-$name"
return
fi
echo "[+] комната создана: $room"
sed -i "s/^OLCRTC_ROOM_ID=any\$/OLCRTC_ROOM_ID=$room/" "$USERS_DIR/$name/.env"
compose_up "$name" >/dev/null
sleep 3
echo
show_user "$name"
}

action_delete() {
mapfile -t users < <(list_users)
if [ ${#users[@]} -eq 0 ]; then
echo "(пользователей нет)"
return
fi
local i
for i in "${!users[@]}"; do
printf " %3d) %s\n" "$((i+1))" "${users[$i]}"
done
echo
read -rp "Номер удаляемого: " pick
if ! [[ "$pick" =~ ^[0-9]+$ ]] || [ "$pick" -lt 1 ] || [ "$pick" -gt "${#users[@]}" ]; then
echo "(неверный номер)"
return
fi
local user=${users[$((pick-1))]}
read -rp "Удалить пользователя \"$user\"? (y/N): " conf
if ! [[ "$conf" =~ ^[yY]$ ]]; then
echo "(отменено)"
return
fi
compose_down "$user" >/dev/null 2>&1 || true
rm -rf "${USERS_DIR:?}/$user"
echo "[+] пользователь $user удалён"
}

# ----- main -----
while true; do
echo
echo "=== olcrtc users ==="
echo " 1) Список пользователей (выбор → ссылка)"
echo " 2) Создать пользователя"
echo " 3) Удалить пользователя"
echo " 0) Выход"
read -rp "> " choice
case "$choice" in
1) action_list ;;
2) action_new ;;
3) action_delete ;;
0|q|Q|"") exit 0 ;;
*) echo "(неверный выбор)" ;;
esac
done
</syntaxhighlight>

=== Устройство скрипта ===

==== Общий принцип ====
Скрипт — это интерактивная обёртка над <code>docker compose</code>. Никакой собственной бизнес-логики у него нет — все действия сводятся к запуску и остановке контейнеров с разными параметрами.

Каждый пользователь — это отдельный compose-проект с уникальным именем <code>olcrtc-user-<имя></code>. Compose-файл единый для всех (<code>shared/docker-compose.user.yml</code>); различия задаются через <code>--env-file</code>, который указывает на личный <code>.env</code> пользователя.

==== Защитные механизмы ====

* <code>set -euo pipefail</code> — прерывание при любой ошибке, защита от использования несуществующих переменных, корректная обработка пайпов.
* Проверка наличия <code>shared/</code> в самом начале — скрипт не запустится в неинициализированной системе.
* Валидация имени по регулярному выражению <code>^[a-zA-Z0-9_-]{1,32}$</code> — защита от инъекций в имена контейнеров и путей файловой системы.
* Валидация ключа по регулярному выражению <code>^[0-9a-fA-F]{64}$</code> — защита от неправильного формата при ручном вводе.
* Подтверждение <code>(y/N)</code> при удалении — защита от случайного удаления.
* Конструкция <code>${USERS_DIR:?}</code> в <code>rm -rf</code> — защита от случайного <code>rm -rf /</code>, если переменная окажется пустой.

==== Хелперы ====
{| class="wikitable"
!Функция
!Назначение
|-
|<code>list_users()</code>
|Возвращает список всех пользователей. Использует <code>find</code> с фильтром <code>-mindepth 1 -maxdepth 1 -type d</code> и исключает каталог <code>shared</code>.
|-
|<code>container_status()</code>
|Опрашивает Docker через <code>docker inspect -f {{.State.Status}}</code>. При отсутствии контейнера возвращает строку <code>missing</code>.
|-
|<code>read_env()</code>
|Читает значение переменной из <code>.env</code> через <code>grep + cut</code>. Не использует <code>source</code>, чтобы избежать побочных эффектов от загрузки переменных.
|-
|<code>build_uri()</code>
|Конкатенирует значения переменных в URI <code>olcrtc://CARRIER?TRANSPORT@ROOM#KEY%CID$MIMO</code> через <code>printf</code>.
|-
|<code>show_user()</code>
|Полная карточка пользователя: статус, все поля, готовый URI.
|-
|<code>valid_name()</code>
|Проверка имени пользователя по регулярному выражению.
|-
|<code>compose_up()</code> / <code>compose_down()</code>
|Запуск и остановка контейнера через <code>docker compose</code> с правильными флагами <code>-f</code>, <code>--env-file</code>, <code>-p</code>.
|}

==== Действие «Список пользователей» ====

# Получает массив пользователей в переменной <code>users</code> через <code>mapfile</code>.
# Печатает заголовок таблицы.
# Для каждого пользователя печатает номер, имя и статус контейнера.
# Спрашивает номер. Пустой ввод — выход. Невалидный номер — сообщение об ошибке.
# При корректном выборе вызывает <code>show_user</code>.

==== Действие «Создать пользователя» ====

# Запрашивает имя, валидирует.
# Проверяет, что каталог <code>$USERS_DIR/$name</code> ещё не существует.
# Запрашивает режим ключа: <code>a</code> (auto, по умолчанию) или <code>m</code> (manual).
# При auto вызывает <code>openssl rand -hex 32</code>; при manual запрашивает и валидирует ввод.
# Создаёт каталог пользователя.
# Через <code>set -a; source $DEFAULTS; set +a</code> подгружает дефолты в окружение.
# Записывает <code>.env</code> пользователя через here-doc.
# Меняет права на <code>.env</code> на <code>0600</code> (только владелец).
# Запускает контейнер через <code>compose_up</code>.
# В цикле до 60 секунд (<code>30 итераций × 2 сек</code>) парсит логи контейнера регулярным выражением <code>WB Stream room created: [0-9a-f-]+</code>.
# При получении room_id обновляет <code>.env</code> через <code>sed -i</code>.
# Перезапускает контейнер с фиксированным room_id.
# Выводит карточку пользователя через <code>show_user</code>.

==== Действие «Удалить пользователя» ====

# Получает массив пользователей.
# Печатает пронумерованный список.
# Запрашивает номер, валидирует.
# Запрашивает подтверждение <code>(y/N)</code>.
# Вызывает <code>compose_down</code> с флагом <code>-v</code> — это удалит и docker volume.
# Удаляет каталог пользователя через <code>rm -rf</code>.

==== Главный цикл ====
Бесконечный цикл с <code>case</code>-разбором ввода:

* <code>1</code> → действие «Список»
* <code>2</code> → действие «Создать»
* <code>3</code> → действие «Удалить»
* <code>0</code>, <code>q</code>, <code>Q</code>, пустой ввод (Enter, Ctrl+D) → выход.
* Любой другой ввод — сообщение «неверный выбор» и продолжение цикла.

=== Возможные расширения ===
Скрипт намеренно простой и легко расширяется. Возможные улучшения:
{| class="wikitable"
!Что добавить
!Как
|-
|Перезапуск отдельного пользователя
|Новый пункт меню → <code>compose_down</code> + <code>compose_up</code>
|-
|Просмотр логов пользователя
|<code>docker logs --tail 50 olcrtc-user-$name</code>
|-
|Экспорт всех URI в файл подписки
|Цикл по <code>list_users</code>, на каждом — <code>build_uri</code>; добавить заголовок согласно <code>docs/sub.md</code> upstream-репозитория
|-
|Автоматическое обновление образа
|<code>git -C /opt/olcrtc pull --recurse-submodules</code> и <code>docker compose build</code>, затем перезапуск всех пользователей
|-
|HTTPS-эндпоинт <code>/sub</code> для раздачи конфигов
|Reverse proxy (caddy / nginx) на статический файл, который генерируется крон-задачей из <code>build_uri</code>
|}
|}
----

== FAQ ==

=== Почему «один сервер ↔ один клиент»? ===
Это архитектурное свойство кода: сервер хранит одну сессию <code>smux</code> и одно поле <code>clientID</code>, не таблицу пиров. Изменение этой модели потребовало бы существенной переработки <code>internal/server/server.go</code> и поддержки множественных peer-connection в каждом провайдере.

=== Почему рекомендуется <code>vp8channel</code>, а не <code>datachannel</code>? ===
<code>datachannel</code> быстрее и имеет минимальный пинг, но: Telemost его не поддерживает, а Jazz может ограничивать IP-адреса серверов, использующих этот тип канала. <code>vp8channel</code> работает со всеми тремя сервисами и подходит для большинства сценариев.

=== Что такое «ограничение IP» со стороны carrier? ===
Некоторые carrier-сервисы используют автоматические эвристики против ботов. После срабатывания таких эвристик подключения с конкретного IP могут перестать пропускаться в виртуальные конференции. Лечится сменой IP сервера или ожиданием снятия ограничения. На момент написания статьи WB Stream таких эвристик не применяет.

=== Сколько контейнеров можно запустить на одной виртуальной машине? ===
В простое каждый контейнер потребляет приблизительно 10–15 МБ RAM и около 0% CPU. На VM с 4 GiB RAM реалистично запустить 50–100 пользователей. Узкими местами обычно становятся пропускная способность сетевого канала и допустимое количество одновременных WebRTC-сессий со стороны carrier-сервиса.

=== Можно ли использовать одну ссылку с нескольких устройств? ===
Технически — да, но не одновременно. Если включить туннель на двух устройствах с одной ссылкой, они будут конкурировать за один peer-connection и периодически разрывать друг друга. Для параллельной работы нужны разные пользователи (разные ссылки).

=== Виден ли реальный видеосигнал участникам конференции? ===
В транспортах <code>vp8channel</code> и <code>seichannel</code> поверх WebRTC отправляется минимально валидный видеопоток, в который встроены полезные данные. Внешне это выглядит как очень тихая «моностатичная» камера. В <code>videochannel</code> отправляется реальный видеоряд (QR-коды или тайлы) — формально это видимая «картинка». Если в виртуальной конференции, кроме сервера и клиента, никого нет — это никак не проявляется.

=== Что делать, если конкретный transport перестал работать? ===
Если carrier изменил проверки SFU и какой-то transport стал ненадёжен — переключитесь на другой transport (<code>seichannel</code> или <code>videochannel</code>) или другой carrier. Меняется в <code>defaults.env</code> для новых пользователей и в личном <code>.env</code> для существующих (с последующим перезапуском контейнера).

=== Можно ли совместить olcRTC с другими методами? ===
Да. С точки зрения клиентского приложения olcRTC — это локальный SOCKS5-прокси. Его можно использовать как один из outbound в xray, sing-box и подобных инструментах. На стороне сервера выходной трафик может быть направлен через xray + WARP (опциональный шаг 11 раздела установки) для дополнительной анонимизации.
----

== Полезные ссылки ==

* [https://github.com/openlibrecommunity/olcrtc Репозиторий olcrtc на GitHub] — основной upstream проекта.
* [https://github.com/alananisimov/olcbox Olcbox] — мультиплатформенный клиент с UI (Android, macOS, Windows, Linux).
* [https://github.com/openlibrecommunity/olcrtc/blob/master/docs/uri.md docs/uri.md] — официальное описание формата URI.
* [https://github.com/openlibrecommunity/olcrtc/blob/master/docs/sub.md docs/sub.md] — формат файла подписки для нескольких локаций.
* [https://github.com/openlibrecommunity/olcrtc/blob/master/docs/settings.md docs/settings.md] — матрица совместимости carrier × transport, описание всех флагов.
* [https://github.com/MHSanaei/3x-ui 3x-ui] — панель управления xray-core (для настройки egress через WARP).

----

Суверенный интернет

2026-05-09T07:19:01Z

Владимир:

Эта страница посвящается всему что связано с ограничим доступа в интернет.

На данный момент 20.04.26 мы имеем полную блокировку по белыми IP у операторов мобильной связи. И предпосылки к блокировкам на уровне провайдеров домашнего интернета.

* [[Обход НКР|Установка и настройка связки Zapret + Podkop на OpenWRT]]
* [[Hysteria 2 каскад]]
* [[Whitelist-bypass: VK Creator (headless на сервере) + Joiner (Android)]]
* [[Установка MTProto Proxy (mtg) на Linux-сервере]]
* [[VK Turn Proxy + FreeTurn + VLESS]]
* [[NaïveProxy: установка полной каскадной цепочки]]
* olcRTC: туннель через легальные WebRTC-сервисы

Обход НКР

2026-05-07T07:03:05Z

Владимир: /* Исходный код скрипта */

= Установка и настройка связки Zapret + Podkop на OpenWRT =

== Введение ==
Данная инструкция описывает установку и настройку связки двух сервисов обхода блокировок на роутере OpenWRT:

* '''Zapret''' — утилита DPI-обхода (anti-DPI), работает без VPN

* '''Podkop''' — прокси-менеджер на базе sing-box с поддержкой VPN

=== Суть связки ===
Комбинация Zapret + Podkop позволяет реализовать оптимальную стратегию обхода блокировок:

# '''Zapret''' обрабатывает трафик '''первым''' (приоритет firewall -150/-100) и применяет DPI-обход для популярных сервисов (YouTube, Discord, Steam и др.) '''без использования VPN'''. Это обеспечивает:

#* Высокую скорость (нет шифрования VPN)

#* Сохранение геолокации РФ (важно для YouTube, Twitch и других региональных сервисов)

#* Минимальную нагрузку на роутер

# '''Podkop''' обрабатывает трафик '''вторым''' (приоритет firewall 0) и направляет через VPN/прокси '''только те домены''', которые Zapret не может обойти или требуют смены региона

<div class="mw-message-box mw-message-box-notice">
'''Важно.''' Эта архитектура позволяет '''экономить VPN-трафик''' и '''сохранять региональный контент''' (например, русскоязычные каналы YouTube), при этом имея полноценный VPN для заблокированных ресурсов.
</div>

== Требования ==

* OpenWRT версии 24 или выше

* Минимум 25 МБ свободного места в памяти роутера

* Доступ к интернету для загрузки пакетов

* Базовые навыки работы с SSH/терминалом

== Установка Zapret ==

=== Шаг 1: Установка вспомогательных пакетов ===
Через веб-интерфейс OpenWRT перейдите в '''System → Software''' и установите:

# <code>curl</code> — для скачивания установщика

# <code>luci-app-ttyd</code> — для доступа к терминалу через веб-интерфейс

После установки <code>luci-app-ttyd</code> в меню появится раздел '''Services → Terminal'''.

=== Шаг 2: Запуск установщика Zapret ===
Откройте терминал ('''Services → Terminal''') и выполните команду:<syntaxhighlight lang="bash">

curl -fsSL https://raw.githubusercontent.com/remittor/zapret-openwrt/zap1/zapret/update-pkg.sh -o /tmp/zap.sh && sh /tmp/zap.sh -u 1

</syntaxhighlight>Дождитесь завершения установки.

=== Шаг 3: Перезагрузка интерфейса ===
Выйдите из веб-интерфейса ('''Log Out''') и войдите снова. В меню '''Services''' появится раздел '''Zapret'''.

== Установка Podkop ==
Выполните команду в терминале:<syntaxhighlight lang="bash">

sh <(wget -O - https://raw.githubusercontent.com/itdoginfo/podkop/refs/heads/main/install.sh)

</syntaxhighlight>После установки '''обязательно очистите кэш браузера''' и перезайдите в LuCI. В меню '''Services''' появится раздел '''Podkop'''.

== Настройка Zapret ==

После установки пакет '''уже содержит''' нужные домены и параметры — '''ручную настройку проходить не нужно'''.

Откройте '''Services → Zapret → Service''' и проверьте только следующее:

# '''Service daemons control''' — включён (сервис Zapret активен).

# '''Service autorun control''' — включён (Zapret поднимается после перезагрузки роутера).

При необходимости можно добавить свои домены в поле '''User hostname entries''' в веб-интерфейсе (как правило — '''по одному домену на строку'''); для типовой установки это '''не обязательно'''.

== Настройка Podkop ==

=== Важное предупреждение о списках сообщества ===
<div class="mw-message-box mw-message-box-warning">
'''ПРЕДУПРЕЖДЕНИЕ:''' Не используйте готовые списки сообщества '''Russian inside''' в базовой конфигурации!
</div>'''Почему нельзя использовать готовые списки:'''

Готовые списки сообщества (например, Russian inside) включают домены YouTube, Google, Discord, которые '''уже обрабатываются Zapret'''. Если добавить их в Podkop, весь трафик этих сервисов будет принудительно направлен через VPN, что приведёт к:

* '''Увеличению расхода VPN-трафика в десятки раз''' (YouTube потребляет гигабайты данных)

* '''Смене региона''' на регион VPN-сервера (потеряете русскоязычный контент YouTube, региональные рекомендации)

* '''Конфликту с Zapret''' (один и тот же домен будет обрабатываться дважды)

=== Использование готового списка доменов ===
Для удобства мы подготовили '''готовый список доменов''' для Podkop, который:

* Основан на актуальном списке '''Russian inside''' (<code>inside-raw.lst</code>)

* '''Исключает''' все домены из <code>zapret-hosts-google.txt</code> и <code>zapret-hosts-user.txt</code>

* '''Дополнен''' специализированными доменами (торрент-трекеры, облачные сервисы, AI-инструменты и др.)

==== Шаг 1: Скопируйте список доменов ====
<div class="toccolours mw-collapsible mw-collapsed" style="width:100%; overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Список доменов для Podkop (нажмите, чтобы развернуть)</div><div class="mw-collapsible-content"><syntaxhighlight lang="text">
.ua
10minutemail.com
1337x.to
1fichier.com
24.kg
4freerussia.org
4pda.to
4pda.ws
4pna.com
529055.xyz
5sim.net
7dniv.rv.ua
7tv.app
7tv.io
9tv.co.il
a-13.1fichier.com
a-vrv.akamaized.net
abercrombie.com
abook-club.ru
academy.terrasoft.ua
activatica.org
adguard.com
adidas.com
adminforge.de
adobe.com
ads-twitter.com
adultmult.tv
agents.media
ahrefs.com
ai-chat.bsg.brave.com
ai.com
aircanada.com
akc.org
allegro.pl
alphacoders.com
alza.hu
amazfitwatchfaces.com
amdm.ru
amedia.site
amnezia.org
amplitude.com
amx.com
analog.com
andrevi.ch
anidub.com
anilib.me
anilibria.org
anilibria.top
anilibria.tv
anilibria.uno
anilibria.wtf
animaunt.org
anime-portal.su
anime1.best
animebest.org
animedia.tv
animego.org
animespirit.ru
anistar.org
anistars.ru
annas-archive.org
ansys.com
anthropic.com
any.do
aol.com
api.jetbrains.ai
api.service-kp.com
api.theins.info
api.themoviedb.org
apkmirror.com
app.zerossl.com
arbat.media
arc.net
archive.midnightchannel.net
archive.ph
archiveofourown.org
arduino.cc
as6723.net
assets.heroku.com
atlassian.com
atn.ua
att.com
attachments.f95zone.to
atv4.dnskp.cc
audiobookbay.lu
augmentcode.com
autodesk.com
avira.com
azathabar.com
azattyq.org
babook.org
baginya.org
baikal-journal.ru
bato.to
bbc.co.uk
bbc.com
bbci.co.uk
bcbits.com
bell-sw.com
bellingcat.com
bestbuy.com
bestchange.ru
bihus.info
bitdefender.com
bitnami.com
blackseanews.net
blinkshot.io
bluehost.com
booktracker.org
boominfo.org
booth.pm
booth.pximg.net
bosch.com
boschaftermarket.com
boschautoparts.com
botnadzor.org
brawlstarsgame.com
bricklink.com
broadcom.com
broncosportforum.com
bt4gprx.com
btdig.com
btod.com
buanzo.org
buf.build
bufferbloat.net
builds.parsec.app
buymeacoffee.com
byteoversea.com
canva.com
canva.dev
capacitorjs.com
capcut.com
carnegieendowment.org
carrefouruae.com
cats.com
cbilling.eu
cbilling.vip
cdn.web-platform.io
cdnbunny.org
cdninstagram.com
cdromance.org
cdw.com
censor.net
censortracker.org
chaos.com
chat.com
chat.openai.com.cdn.cloudflare.net
chatgpt.com
chaturbate.com
chenbro.com
cherta.media
chess.com
chesscomfiles.com
chub.ai
circlecrewpinkcrowd.com
cisco.com
cisecurity.org
citrix.com
clamav.net
clashofclans.com
clashroyaleapp.com
claude.ai
clevelandclinic.org
clickup.com
clip.opus.pro
cloudtorrents.com
cms-twdigitalassets.com
cnd2exp.online
cock.li
code.gist.build
codecguide.com
codeium.com
codelinaro.org
coingate.com
coinpayments.net
coinsbee.com
coldfilm.city
coldfilm.ink
coldfilm.xyz
colta.ru
community.sophos.com
connect.ngrok-agent.com
contabo.com
coomer.su
copilot.microsoft.com
corsair.com
coursera.org
cpu-monkey.com
credly.com
croxyproxy.com
crunchyroll.com
csskor.ill.in.ua
cub.red
currenttime.tv
cursorinfo.co.il
cvedetails.com
cyberghostvpn.com
cyxymu.info
daemon-tools.cc
dailylviv.com
dailymotion.com
danbooru.donmai.us
darthsternie.net
data-cdn.mbamupdates.com
data.cline.bot
deckbrew.xyz
decrypt.day
deepl.com
deepstatemap.live
deezer.com
delfi.lt
delfi.lv
delivery.2d.net.co
dell.com
dellcdn.com
depositphotos.com
designer.microsoft.com
designify.com
developer.nvidia.com
devexpress.com
deviantart.com
diabrowser.com
digash.live
digikey.com
digitalcontent.sky
digitalocean.com
discord.tools
discours.io
disctech.com
disneyplus.com
dlpsgame.com
docs.liquibase.com
document360.com
document360.io
dorama.live
doramalive.ru
doramy.club
dovod.online
download3.omnissa.com
doxa.team
dpidetector.org
dreamhost.com
dreamina.capcut.com
dub.sh
ducati.com
dumka.media
dw.com
dyson.com
e-hentai.org
e621.net
easydmarc.com
echofm.online
edemtv.me
editorx.com
edu-cisco.org
ef.com
ef.edu
eggertspiele.de
ej.ru
ekhokavkaza.com
element14.com
elements.envato.com
elevenlabs.io
elgato.com
eneba.com
epidemz.net.co
eporner.com
espreso.tv
etahub.com
etsy.com
euronews.com
euroradio.fm
eutrp.eu
everand.com
exchanger.bits.media
exler.ru
expandrive.com
expres.online
extremetech.com
f1.com
f95-zone.to
facebook.com
facebook.net
fansly.com
fast-torrent.club
fast.com
fastpic.org
fb.com
fbcdn.net
fbsbx.com
ficbook.net
filebin.net
filmitorrent.net
filmix.ac
filmix.biz
filmix.day
filmix.fan
filmix.fm
filmix.la
flibusta.is
flibusta.net
flipboard.com
flir.com
flir.eu
flisland.net
flourish.studio
fls.guru
fluke.com
flukenetworks.com
flyertalk.com
fn-volga.ru
fonge.org
footballapi.pulselive.com
force-user-content.com
force.com
forklog.com
formula1.com
fortanga.org
forum.netgate.com
forum.ru-board.com
foxnews.com
framer.com
freedomletters.org
freeimages.com
freemedia.io
freeones.com
fxnetworks.com
g2a.com
gagadget.com
gamedistribution.com
gamesrepack.com
gamestop.com
gaming.amazon.com
geforcenow.com
gelbooru.com
genspark.ai
geolocation.onetrust.com
germania.one
getoutline.com
getoutline.org
gfn.am
ghostrc.game.idtech.services
gifyu.com
git.new
glavred.info
glavred.net
global.fncstatic.com
global.platform.seconddinnertech.com
glpals.com
godaddy.com
gofile.io
gofundme.com
golosameriki.com
gonitro.com
goodreads.com

gpsonextra.net
gpu-monkey.com
gql.twitch.tv
gr-assets.com
grafana.com
grani.ru
graty.me
graylog.org
grizzlysms.com
grok.com
groq.com
groupon.com
guilded.gg
gulagu.net
habr.com
hackernoon.com
hackmd.io
halooglasi.com
hashicorp.com
haydaygame.com
hbomax.com
hc-ping.com
hchk.io
hd-rezka.tv
hdkinoteatr.com
hdrezka.ac
hdrezka.ag
hdrezka.app
hdrezka.me
hdrezka.tech
hdrezka.tv
hdrzk.org
hdstudio.org
healthline.com
hentai-foundry.com
herokucdn.com
hetzner.com
hitomi.la
hollisterco.com
holod.media
home-connect.com
home.by.me
hostgator.com
hostinger.com
hotels.com
housebrand.com
hqporner.com
hromadske.ua
hs.fi
htmhell.dev
hume.ai
hybrid-analysis.com
i.sakh.com
ibm.com
ibytedtos.com
idelreal.org
iditelesombase.org
iedb.org
ig.me
ign.com
iherb.com
iichan.hk
ikea.com
ilook.tv
image.tmdb.org
imgburn.com
imgur.com
important-stories.com
indeed.com
indiehackers.com
infineon.com
insearch.site
instagram.com
install.launcher.omniverse.nvidia.com
intel.com
intel.de
intel.nl
intelix.sophos.com
interactivebrokers.co.uk
interfax.com.ua
internalfb.com
intuit.com
intuitibits.com
ionos.com
iptv.online
is.fi
istories.media
itch.io
itninja.com
itsmycity.ru
jamf.com
jellyfin.org
jetbrains.com
jetbrains.space
jetkvm.com
jskor.ill.in.ua
jut-su.net
jut.su
jw-russia.org
jw.org
kaktus.media
kaleido.ai
kamatera.com
kara.su
kasparov.ru
kavkaz-uzel.eu
kavkazr.com
kemono.su
keysight.com
kilo.ai
kilocode.ai
kino.pub
kinogo.ec
kinogo.la
kinogo.uk
kinopub.me
kinovod.net
kinozal.guru
kinozal.me
kinozal.tv
kinozaltv.life
klarna.com
kmail-lists.com
knaben.xyz
knews.kg
knowyourmeme.com
kolsar.org
kor.ill.in.ua
korrespondent.net
kovcheg.live
krymr.com
kupujemprodajem.com
kym-cdn.com
lambdalabs.com
lamcdn.net
langdock.com
lantern.io
latestmodapks.com
ldoceonline.com
le-production.tv
leafletjs.com
legalshield.com
lgeapi.com
lgthinq.com
lib.rus.ec
libgen.li
licdn.com
lidarr.audio
lifehacker.com
liga.net
lightning.ai
linear.app
lingq.com
linkedin.com
linktr.ee
livetv.sx
liveuamap.com
locals.md
lolz.guru
lostfilm.download
lostfilm.tv
lostfilm.tw
lostfilm.uno
lostfilmtv2.site
lu4.org
lucid.app
magaz.global
mail-api.proton.me
mailerlite.com
mailfence.com
mailinator.com
mailo.com
make.com
malwarebytes.com
mangadex.org
mangahub.ru
mangapark.net
manus.im
manybooks.net
manyvids.com
marvelsnap.com
mashable.com
mattermost.com
max.com
mbk-news.appspot.com
mediazona.ca
medicalnewstoday.com
medium.com
meduza.io
mega.nz
megapeer.ru
megapeer.vip
merezha.co
meta.com
metacritic.com
metal-archives.com
metla.press
metopera.org
middlewareinventory.com
mignews.com
mintmobile.com
miracleptr.wordpress.com
mirror.jellyfin.org
mixcloud.com
modrinth.com
mongodb.com
monolisa.dev
monoprice.com
more.fm
moscowtimes.ru
mouser.com
mouser.fi
mssg.me
mullvad.net
multporn.net
muscdn.com
musical.ly
musicbrainz.org
musixmatch.com
mw2.wiki
myanimelist.net
mydoramy.club
myheritage.com
myjetbrains.com
myparallels.com
myqrcode.com
navalny.com
nba.com
neformat.com.ua
neo4j.com
netacad.com
netapp.com
netflix.ca
netflix.com
netflix.net
netflixinvestor.com
netflixtechblog.com
netlify.com
networksolutions.com
new.abb.com
newark.com
newsroom.porsche.com
newsru.co.il
newsru.com
newtimes.ru
nexus-cdn.com
nfl.com
nflxext.com
nflximg.com
nflximg.net
nflxsearch.net
nflxso.net
nflxvideo.net
ngrok.com
nhentai.com
nhentai.net
nhl.com
nih.gov
nike.com
nippon.com
nitropdf.com
nnmclub.to
nnmstatic.win
nordaccount.com
nordcdn.com
nordvpn.com
notepad-plus-plus.org
notion-emojis.s3-us-west-2.amazonaws.com
notion-static.com
notion.com
notion.new
notion.site
notion.so
novaline.fm
novaya.no
novayagazeta.eu
novayagazeta.ru
novyny.live
ntc.party
ntp.msn.com
nude-moon.org
nxp.com
oaistatic.com
oaiusercontent.com
obozrevatel.com
ocstore.com
oculus.com
ohmyswift.ru
oi.legal
okx.com
olx.ua
omnissa.com
omv-extras.org
onfastspring.com
onlinesim.io
onshape.com
open-vsx.org
openai.com
openh264.org
openmedia.io
openrouter.ai
opensanctions.org
opensea.io
opentrackr.org
openvsx.eclipsecontent.org
opposition-news.com
oracle.com
orbispatches.com
orcaslicer.com
ottplayer.tv
ovd.info
ovd.legal
ovd.news
ovdinfo.org
ozodi.org
paddle.com
paddlestatus.com
pages.dev
pandasecurity.com
pap.pl
paperpaper.io
paperpaper.ru
parallels.cn
parallels.com
parallels.net
parallelsaccess.com
paritydeals.com
patreon.com
patreonusercontent.com
patriot.dp.ua
pb.wtf
pcgamesn.com
pcmag.com
penguin.com
penguinrandomhouse.com
periscope.tv
pexels.com
phncdn.com
phncdn.com.sds.rncdn7.com
pimpletv.ru
pingdom.com
piratbit.top
pixabay.com
pkg-zone.com
pkgs.tailscale.com
platform.activestate.com
playboy.com
plugshare.com
polit.ru
politico.eu
politiken.dk
polymarket.com
pornhub.com
pornhub.org
pornolab.net
portal.lviv.ua
posle.media
posthog.com
postimees.ee
pravda.com
pravda.com.ua
premierleague.com
primevideo.com
primevue.org
privatekeys.pw
prnt.sc
production-openaicom-storage.azureedge.net
proekt.media
profitwell.com
prosleduetmedia.com
prosperopatches.com
prostovpn.org
proton.me
protonvpn.com
provereno.media
prowlarr.com
pscp.tv
psiphon.ca
psxhax.com
public.parsec.app
pvpessence.com
qdrant.io
qdrant.tech
qt.io
quadratichq.com
qualcomm.com
quicknode.com
quora.com
quora.com.cdn.cloudflare.net
qwant.com
r4.err.ee
radiojar.com
radiosakharov.org
radiosvoboda.org
rbc.ua
reactflow.dev
realbooru.com
realist.online
recraft.ai
reddxxx.com
redgifs.com
redis.io
redislabs.com
redshieldvpn.com
refactoring.guru
remna.st
remove.bg
render-state.to
rentry.co
rentry.org
repo.jellyfin.org
republic.ru
research.net
restream.io
reve.art
rezka-ua.in
rezka.ag
rezka.cc
rezka.fi
rezka.land
rezka.my
rezka.tv
rezkify.com
rezonans.media
rf.dobrochan.net
rferl.org
rima.media
riperam.org
riseup.net
roar-review.com
root-nation.com
roskomsvoboda.org
rublacklist.net
rule34.art
rule34.us
rule34.xxx
rus.delfi.ee
rus.jauns.lv
ruscryde.net
rustorka.com
rutor.info
rutor.is
rutor.org
rutracker.cc
rutracker.net
rutracker.org
rutracker.wiki
sakhalin.info
sakharovfoundation.org
salesforce-experience.com
salesforce-hub.com
salesforce-scrt.com
salesforce-setup.com
salesforce-sites.com
salesforce.com
salesforceiq.com
salesforceliveagent.com
sap.com
saverudata.net
schemas.microsoft.com
schemas.openxmlformats.org
sci-hub.se
sci-hub.st
scrollrevealjs.org
scryde.io
scryde.net
scryde.ru
scryde.world
scryde1.net
scryde10.net
scryde11.net
scryde12.net
scryde2.net
scryde3.net
scryde4.net
scryde5.net
scryde6.net
scryde7.net
scryde8.net
scryde9.net
sdxcentral.com
searchfloor.org
seasonvar.ru
selezen.org
semnasem.org
semrush.com
sentry.dev
sentry.io
sephora.com
servarr.com
severreal.org
sfdcopens.com
shikimori.me
shinyhardware.co.uk
shiza-project.com
shop.gameloft.com
showip.net
sibreal.org
signal.org
simplex.chat
simplex.im
simplix.info
singlekey-id.com
site.com
siteground.com
skat.media
sketchup.com
skiff.com
skladchik.com
sklatchiki.ru
sky.com
skycdp.com
slashlib.me
slavicsac.com
slifki.biz
smartbear.co
smartbear.com
smartdeploy.com
sms-activate.io
snapgene.com
sndcdn.com
snort.org
snyk.io
sobesednik.com
solarwinds.com
sonara.ai
sophos.com
sora.com
sotaproject.com
soundcloud.cloud
soundcloud.com
sovetromantica.com
spacelift.io
speedtest.net
spektr.press
spiceworks.com
spiegel.de
spitfireaudio.com
spotify.com
spreadthesign.com
sputnikipogrom.com
squadbustersgame.com
squareup.com
squietpc.com
startmail.com
startpage.com
static.lostfilm.top
statology.org
steamstat.info
strana.news
strana.today
strava.com
supercell.com
supersliv.biz
support.anydesk.com
support.xerox.com
surfshark.com
surveymonkey.com
suspilne.media
svidomi.in.ua
svoboda.org
svoi.kr.ua
svtv.org
swagger.io
swapd.co
swissinfo.ch
synoforum.com
t-invariant.org
t.co
tableau.com
talosintelligence.com
tampermonkey.net
tayga.info
te-st.org
teamviewer.com
techbargains.com
telegraf.by
telegraf.news
telegram.org
telegraph.co.uk
telemetr.io
tellapart.com
tempmail.plus
temu.com
terraform.io
the-village.ru
theaudiodb.com
thebarentsobserver.com
thebell.io
theins.press
theins.ru
themoviedb.org
thepiratebay.org
theporndude.com
therarbg.to
thetruestory.news
thetvdb.com
threads.net
threema.ch
ti.com
tidal.com
tik-tokapi.com
tiktok.com
tiktokcdn-eu.com
tiktokcdn-us.com
tiktokcdn.com
tiktokd.net
tiktokd.org
tiktokv.com
tiktokv.eu
tiktokv.us
tiktokw.us
timberland.de
tiptop-vpn.com
tmdb-image-prod.b-cdn.net
tmdb.com
tmdb.org
toolbox.app
torproject.org
torrenteditor.com
torrentgalaxy.to
trae.ai
trailblazer.me
trailhead.com
transferwise.com
trellix.com
tria.ge
trueblackmetalradio.com
truthsocial.com
tsmc.com
ttwstatic.com
turbobit.net
tuta.com
tuta.io
tutanota.com
tvdevinfo.com
tvfreedom.io
tvrain.ru
tvrain.tv
tweetdeck.com
twimg.com
twin.me
twinlife-systems.com
twinme.com
twirpx.com
twitpic.com
twitter.biz
twitter.com
twitter.jp
twittercommunity.com
twitterflightschool.com
twitterinc.com
twitteroauth.com
twitterstat.us
twtrdns.net
twttr.com
twttr.net
twvid.com
typing.com
uaudio.com
ui.ill.in.ua
uizard.io
ukdevilz.com
ukr.net
ukr.radio
ukrtelcdn.net
unian.ua
unscreen.com
unsplash.com
upwork.com
urlr.me
usa.one
usatoday.com
usher.ttvnw.net
uupdump.net
v.vrv.co
vagrantcloud.com
veeam.com
verstka.media
vesma.one
vesma.today
vesty.co.il
viber.com
vice.com
vine.co
vip110.vip
vipergirls.to
visualcapitalist.com
vmware.com
vndb.org
voanews.com
vod-fy.crunchyrollcdn.com
voidboost.cc
volkswagen-classic-parts.com
vot-tak.tv
vpngate.net
vpngen.org
vpnlove.me
vpnpay.io
vyos.io
w.atwiki.jp
wa.me
walmart.com
watchguard.com
watermarkremover.io
wbgames.com
weather.com
webmd.com
webnames.ca
webtoons.com
weebly.com
welt.de
whatsapp.biz
whatsapp.com
whatsapp.net
widgetapp.stream
wiki.fextralife.com
wikidot.com
wilsoncenter.org
windows10spotlight.com
windsurf.com
wise.com
wonderzine.com
wpengine.com
wunderground.com
www3.corsair.com
x.ai
x.com
xhamster.com
xhamsterlive.com
xhcdn.com
xiaomi.eu
xnxx-cdn.com
xnxx-ru.com
xnxx.com
xnxx.net
xnxx.tv
xnxx3.com
xsts.auth.xboxlive.com
xtracloud.net
xv-ru.com
xvideos-cdn.com
xvideos.com
yande.re
yeggi.com
yle.fi
youtrack.cloud
yummyani.me
z.ai
zahav.ru
zapier.com
zaxid.net
zbigz.com
zedge.net
zendesk.com
zerkalo.io
zona.media
2fa.fb.tools
pytorch.org
rutracker.cc
uvnc.com
api.pwnedpasswords.com
pwnedpasswords.com
haveibeenpwned.com
nekoray.org
cursor.directory
fedoraproject.org
jdownloader.org
oii.la
sysdig.com
lizardbyte.dev
lego.com

google.com
lookerstudio.google.com
news.google.com
googleapis.com
suggestqueries.google.com
gemini.google.com
2ip.ru
cline.bot
fragment.com
shikimori.one
thingiverse.com
rippersanime.info
forum.rippersanime.info
weloma.art
brave.com
search.brave.com
claude.com
roocode.com
unsloth.ai
sourceforge.net
trakt.tv
statics.life
openstat.net
google-analytics.com
googletagmanager.com
torrenttip220.top
529072.xyz
asnet.pw
apachetorrent.com
bangumi.moe
bigfangroup.org
bitru.org
bitsearch.to
demonoid.nl
share.dmhy.org
extratorrent.st
eztvx.to
limontorrents.vip
www.frozen-layer.com
kickass.torrentbay.st
kickass.ws
limetorrents.fun
magnetcatcat.com
newstudio.tv
ww3-nortorrent.com
nyaa.si
torrentcore.xyz
torrenttip220.top
dontorrent.cash
electro-torrent.pl
extratorrent.ninjaproxy1.com
extratorrent.proxyninja.org
extratorrent.proxyninja.net
hdrtorrent.com
ilcorsaronero.link
magnetcatcat.com
clmclm.com
8800546.xyz
torrentbay.st
torrentsbay.org
unblockninja.com
ninjaproxy1.com
proxyninja.org
proxyninja.net
newstudio.tv
nekobt.to
moviesdvdr.co
nyaa.iss.ink
nyaa.land
nyaa.mom
nyaa.unblockninja.com
zktorrent.com
zamunda.rip
yts.bz
yts.unblockninja.com
yts.ninjaproxy1.com
yts.proxyninja.org
yts.proxyninja.net
yts.torrentbay.st
yts.torrentsbay.org
mania-torrent.org
cine-torrent.org
magnet-torrent.org
mega-torrent.cc
zone-torrent.com
warez-torrent.org
wolfmax4k.com
uztracker.net
uindex.org
ygg.gratis
torrenttip219.top
torrentsome238.com
torrentqq412.com
torrentegg87.com
torrentgalaxy.one
torrentgalaxy.info
torrentgalaxy.space
torrentdownload.info
torrentcore.xyz
www5.torrent9.to
www.torrentdownloads.pro
torrentdownloads.unblockninja.com
torrentdownloads.ninjaproxy1.com
torrentdownloads.proxyninja.org
torrentdownloads.proxyninja.net
therarbg.to
therarbg.com
therar.site
rarbg.unblockninja.com
rarbg.ninjaproxy1.com
rarbg.proxyninja.org
rarbg.proxyninja.net
rarbg.torrentbay.st
thepiratebay.org
solidtorrents.eu
kickasstorrents.bz
dolby.com
repo.webosbrew.org
qt.io
cursor.com
cursor.sh
cursorapi.com
duckdns.org
funpay.com
anidub.vip
anidub.shop
skillsmp.com
reactbits.dev
mediaarea.net
mkvtoolnix.download
excalidraw.com
claudeusercontent.com
kodi.tv
githubusercontent.com
</syntaxhighlight></div></div>

==== Шаг 2: Добавьте список в Podkop ====

# Откройте веб-интерфейс Podkop: '''Services → Podkop'''

# Перейдите в раздел конфигурации секции (обычно <code>main</code>)

# Найдите параметр '''Custom Domain Lists''' (Список пользовательских доменов)

# Убедитесь, что '''Тип пользовательского списка доменов''' установлен в <code>Текстовый список</code>

# Скопируйте весь список из спойлера выше

# Вставьте его в поле '''Список пользовательских доменов'''

# Нажмите '''Save & Apply'''

=== Самостоятельная генерация списка (опционально) ===
Если вы хотите '''самостоятельно сгенерировать''' актуальный список или добавить свои домены, используйте наш скрипт.

==== Требования ====

* Python 3.6 или выше

* 4 файла:

** <code>inside-raw.lst</code> — актуальный список Russian inside

** <code>zapret-hosts-google.txt</code> — скопируйте с роутера из <code>/opt/zapret/ipset/</code>

** <code>zapret-hosts-user.txt</code> — скопируйте с роутера из <code>/opt/zapret/ipset/</code>

** <code>custom-user-list.txt</code> — ваши дополнительные домены (по одному на строку)

==== Исходный код скрипта ====
Создайте файл <code>generate_podkop_list.py</code>:<div class="toccolours mw-collapsible mw-collapsed" style="width:100%; overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Список доменов для Podkop (нажмите, чтобы развернуть)</div><div class="mw-collapsible-content"><syntaxhighlight lang="python">

#!/usr/bin/env python3

"""

Domain List Generator for Podkop

Merges inside-raw.lst with custom domains while removing duplicates from Zapret lists

"""

import sys

from pathlib import Path

def read_domains(filepath):

"""Read domains from file, cleaning and normalizing them"""

domains = set()

try:

with open(filepath, 'r', encoding='utf-8') as f:

for line in f:

# Remove comments, whitespace, and normalize

domain = line.split('#')[0].strip().lower()

if domain and not domain.startswith('['):

# Remove trailing dots

domain = domain.rstrip('.')

domains.add(domain)

except FileNotFoundError:

print(f"Warning: File {filepath} not found, skipping", file=sys.stderr)

except Exception as e:

print(f"Error reading {filepath}: {e}", file=sys.stderr)

return domains

def main():

# Define input files

inside_raw = Path('inside-raw.lst')

zapret_google = Path('zapret-hosts-google.txt')

zapret_user = Path('zapret-hosts-user.txt')

custom_list = Path('custom-user-list.txt')

output_file = Path('podkop-final-list.txt')

print("=== Podkop Domain List Generator ===\n")

# Read all domain lists

print("Reading inside-raw.lst...")

inside_domains = read_domains(inside_raw)

print(f" Loaded {len(inside_domains)} domains")

print("Reading zapret-hosts-google.txt...")

zapret_google_domains = read_domains(zapret_google)

print(f" Loaded {len(zapret_google_domains)} domains")

print("Reading zapret-hosts-user.txt...")

zapret_user_domains = read_domains(zapret_user)

print(f" Loaded {len(zapret_user_domains)} domains")

print("Reading custom-user-list.txt...")

custom_domains = read_domains(custom_list)

print(f" Loaded {len(custom_domains)} domains")

# Combine Zapret lists (domains to exclude from inside-raw)

zapret_combined = zapret_google_domains | zapret_user_domains

print(f"\nTotal Zapret domains to exclude: {len(zapret_combined)}")

# Remove Zapret domains from inside-raw

filtered_inside = inside_domains - zapret_combined

print(f"Inside-raw after filtering: {len(filtered_inside)} domains")

# Combine filtered inside-raw with custom domains

final_domains = filtered_inside | custom_domains

print(f"\nFinal domain count: {len(final_domains)} domains")

# Sort and save

sorted_domains = sorted(final_domains)

with open(output_file, 'w', encoding='utf-8') as f:

f.write("# Podkop Domain List\n")

f.write("# Generated automatically from inside-raw.lst (filtered) + custom domains\n")

f.write(f"# Total: {len(sorted_domains)} domains\n")

f.write("#\n")

f.write("# Excludes domains already handled by Zapret:\n")

f.write(f"# - zapret-hosts-google.txt ({len(zapret_google_domains)} domains)\n")

f.write(f"# - zapret-hosts-user.txt ({len(zapret_user_domains)} domains)\n")

f.write("#\n\n")

for domain in sorted_domains:

f.write(f"{domain}\n")

print(f"\n✓ Successfully created {output_file}")

print(f" Ready to use in Podkop Custom Domain Lists")

if __name__ == '__main__':

main()

</syntaxhighlight></div></div>

==== Использование скрипта ====

# Скачайте актуальный <code>inside-raw.lst</code>:

#: <syntaxhighlight lang="bash">

wget https://community.antifilter.download/list/inside-raw.lst

</syntaxhighlight>

# Скопируйте с роутера файлы <code>zapret-hosts-google.txt</code> и <code>zapret-hosts-user.txt</code> из <code>/opt/zapret/ipset/</code>

# Создайте файл <code>custom-user-list.txt</code> со своими доменами (если нужно)

# Запустите скрипт:

#: <syntaxhighlight lang="bash">

python3 generate_podkop_list.py

</syntaxhighlight>

# Используйте полученный файл <code>podkop-final-list.txt</code> в Podkop

=== Настройка прокси/VPN ===
После добавления списка доменов настройте подключение к вашему VPN/прокси-серверу.

В разделе '''Outbounds''' (в интерфейсе Podkop) настройте:

# '''Connection Type''': <code>proxy</code> или <code>vpn</code> (в зависимости от вашего сервера)

# '''Proxy String''': вставьте ссылку на ваш VPN/прокси (формат: <code>protocol://user:pass@server:port</code>)

# Или настройте '''Interface''' для WireGuard/OpenVPN

=== Применение настроек ===
Нажмите '''Save & Restart''' для применения конфигурации Podkop.

== Проверка работы ==

=== Тестирование Zapret ===

# Откройте YouTube — должен работать '''без VPN''' (регион РФ, русскоязычные рекомендации)

# Проверьте Discord — должен открываться '''через Zapret''' (без VPN)

=== Тестирование Podkop ===

# Откройте домен из вашего списка Podkop (например, <code>rutracker.org</code>)

# Проверьте смену IP (через <code>2ip.ru</code> или аналог) — должен показать IP вашего VPN-сервера

=== Диагностика ===
Если что-то не работает:

# Проверьте логи Zapret: '''Services → Zapret → Log Viewer'''

# Проверьте статус Podkop: '''Services → Podkop'''

# Убедитесь, что домен '''не находится одновременно''' в списках Zapret и Podkop

== Заключение ==
Связка Zapret + Podkop — это оптимальное решение для обхода блокировок на OpenWRT, которое позволяет:

* '''Использовать DPI-обход''' (Zapret) для потоковых сервисов (YouTube, Twitch, Discord, Steam)

* '''Оставаться в регионе РФ''' на YouTube и других сервисах (получать русскоязычный контент и рекомендации)

* '''Экономить VPN-трафик''' (95% трафика идёт через Zapret без шифрования)

* '''Использовать VPN''' (Podkop) только для действительно заблокированных ресурсов (торрент-трекеры, специализированные сервисы)

Таким образом, вы получаете '''лучшее из обоих миров''': быстрый доступ к популярным сервисам без потери региона и полноценный VPN для всего остального.

== Полезные ссылки ==

* [https://github.com/remittor/zapret-openwrt Zapret для OpenWRT (GitHub)]

* [https://github.com/itdoginfo/podkop Podkop (GitHub)]

* [https://podkop.net/ Документация Podkop]

* [https://community.antifilter.download/ Списки Russian inside]

== Дополнительно ==

=== Автоматизация обновления списков ===
Для автоматического обновления пользовательских списков доменов можно настроить cron-задачу, которая будет периодически скачивать обновлённый список и перезапускать сервисы.

=== Мониторинг ===
Рекомендуется периодически проверять:

* Логи Zapret на наличие ошибок

* Статус подключения Podkop к VPN-серверу

* Актуальность версий обоих сервисов

Hysteria 2 каскад

2026-04-26T10:14:44Z

Владимир: /* 3.4 Исходный код скрипта */

= Hysteria2: установка каскадной цепочки Entry Node → Exit Node → WARP =

== Что такое Hysteria2 и зачем он нужен ==

=== Проблема: ограничения традиционных прокси-протоколов ===

Современные системы глубокой инспекции пакетов (DPI — Deep Packet Inspection), применяемые интернет-провайдерами и регуляторами по всему миру, умеют анализировать не только адреса назначения, но и '''характер самого трафика'''. Даже зашифрованное соединение можно идентифицировать — по поведению, по паузам между пакетами, по размерам передаваемых блоков данных, по TLS-fingerprint.

Большинство прокси-протоколов работают поверх '''TCP'''. Это означает:
* Все потери пакетов обрабатываются дважды — сначала на уровне транспорта, затем внутри туннеля (head-of-line blocking).
* При нестабильном канале (мобильная сеть, спутник, VPN на слабом железе) скорость резко падает.
* TCP-fingerprint легче распознаётся и блокируется.

Hysteria2 решает эту проблему фундаментально иначе: он работает поверх '''QUIC''' — транспортного протокола на базе UDP, разработанного в Google и стандартизированного в RFC 9000.

=== Решение: QUIC/UDP с маскировкой под HTTPS ===

Hysteria2 строит зашифрованный туннель поверх UDP, используя QUIC:
* '''Нет head-of-line blocking:''' потеря одного пакета не блокирует остальные потоки.
* '''Быстрое восстановление соединения:''' QUIC переподключается за 0-RTT (без дополнительного round-trip).
* '''Маскировка под HTTPS:''' снаружи трафик Hysteria2 выглядит как обычный QUIC/HTTP3 браузерный трафик — сервер «притворяется» обычным HTTPS-сайтом и возвращает реальный веб-контент при неавторизованных запросах.
* '''Congestion control:''' поддерживает несколько алгоритмов управления перегрузкой, включая BBR.

{| class="wikitable"
|-
! Протокол !! Транспорт !! Как выглядит для DPI !! Устойчивость к блокировке !! Скорость при потерях
|-
|| Обычный VPN (WireGuard, OpenVPN) || UDP / TCP || Характерный шаблон || Низкая — fingerprint легко детектируется || Высокая (WG) / Низкая (OpenVPN)
|-
|| Shadowsocks || TCP || Случайный зашифрованный поток || Средняя — выявляется по энтропии || Средняя
|-
|| VLESS + REALITY || TCP (TLS) || TLS с реальным сертификатом стороннего сайта || Высокая || Средняя
|-
|| NaïveProxy || TCP (HTTP/2 TLS) || Неотличим от Chrome HTTPS || Очень высокая || Средняя (TCP Head-of-Line)
|-
|| '''Hysteria2''' || '''UDP (QUIC/TLS)''' || '''QUIC/HTTP3, маскировка под HTTPS''' || '''Очень высокая''' || '''Высокая — устойчив к потерям'''
|}

=== Как работает Hysteria2 технически ===

Hysteria2 использует протокол QUIC в качестве транспорта:

# Клиент устанавливает QUIC-соединение с сервером — это TLS 1.3 поверх UDP.
# Внутри QUIC-соединения открываются независимые потоки (streams) для каждого проксируемого соединения.
# Сервер обрабатывает входящий трафик: авторизует клиента (по паролю или через внешний скрипт), затем перенаправляет трафик через указанный outbound.
# Если к серверу обращаются без правильного пароля — сервер ведёт себя как обычный HTTPS-сайт ('''masquerade''') и возвращает реальный контент с заданного URL.

Особенности аутентификации в данной схеме:
* '''EU сервер:''' использует одиночный пароль — только для входящих соединений от RU клиента (не клиентских устройств).
* '''RU сервер:''' использует '''command-аутентификацию''' — при каждом подключении вызывается внешний bash-скрипт, который проверяет пароль по файлу <code>users.txt</code>. Это позволяет добавлять и удалять пользователей '''без перезапуска сервера'''.

=== Каскадная цепочка: зачем два сервера ===

В данном решении используется '''каскад из двух серверов''': Entry Node (ближайший к клиентам сервер-вход) и Exit Node (сервер-выход в интернет). Это архитектурное решение принято намеренно по нескольким причинам:

* '''Снижение риска для клиента:''' клиентские устройства подключаются только к ближайшему серверу. Соединение с соседним узлом менее заметно, чем прямое соединение с зарубежным сервером.
* '''Раздельная аутентификация:''' пароль «клиент → Entry Node» знают только конечные пользователи. Пароль «Entry Node → Exit Node» знают только серверы. Компрометация клиентского пароля не раскрывает пароль соединения между серверами.
* '''Анонимизация выхода:''' Exit Node передаёт трафик через Cloudflare WARP. Конечные сайты видят IP Cloudflare, а не IP ваших серверов.
* '''Параллельные независимые каналы:''' Hysteria2 работает рядом с NaïveProxy и 3x-ui на тех же серверах, не конфликтуя с ними. Падение одного канала не блокирует другие.

----

== Схема конкретного решения ==

=== Компоненты инфраструктуры ===

{| class="wikitable"
|-
! Компонент !! Роль !! Адрес / Домен !! ОС
|-
|| Клиентские устройства || Конечные пользователи || — || iOS, Android, Windows, macOS, Linux
|-
|| OpenWrt роутер || Прозрачный обход для всей домашней сети || — || OpenWrt 24.10 (podkop нативно поддерживает hy2 URI)
|-
|| RU сервер ('''Entry Node''') || Точка входа клиентов || <code>YOUR_RU_SERVER_IP</code> / <code>your-hy2-ru-domain.example.com</code> || Ubuntu 24.04
|-
|| EU сервер ('''Exit Node''') || Точка выхода в интернет || <code>YOUR_EU_SERVER_IP</code> / <code>your-hy2-eu-domain.example.com</code> || Ubuntu 24.04
|-
|| Cloudflare WARP || Финальный выход в интернет || IP Cloudflare || —
|}

=== Полная схема прохождения трафика ===

[[File:hysteria2-chain-traffic-flow.png|center|768x768px|Схема трафика Hysteria2: Клиенты → RU Entry Node → EU Exit Node → WARP → Интернет]]

=== Протоколы на каждом участке цепочки ===

{| class="wikitable"
|-
! Участок !! Протокол !! Шифрование !! Что видит наблюдатель
|-
|| Устройство → Роутер || Обычный TCP/UDP || Нет (локальная сеть) || Локальный трафик
|-
|| Роутер / ПК → RU сервер || QUIC / UDP (Hysteria2) || TLS 1.3 (Let's Encrypt) || HTTPS/HTTP3 трафик к обычному сайту
|-
|| RU клиент → EU сервер || QUIC / UDP (Hysteria2) || TLS 1.3 (Let's Encrypt) || HTTPS/HTTP3 трафик к обычному сайту
|-
|| EU сервер → 3x-ui inbound || SOCKS5 (localhost) || — (только на EU сервере) || Только локально
|-
|| EU 3x-ui → WARP || WireGuard (gVisor TUN) || WireGuard || Зашифрованный WireGuard к Cloudflare
|-
|| WARP → Интернет || Обычный TCP/UDP || — || IP Cloudflare
|}

=== Дополнительные каналы (параллельно Hysteria2) ===

Hysteria2 работает '''независимо''' от NaïveProxy и 3x-ui. Все три канала активны одновременно:

{| class="wikitable"
|-
! Канал !! Протокол !! Маршрут !! Статус
|-
|| 3x-ui каскад (основной) || VLESS / REALITY || Клиенты → RU 3x-ui → EU 3x-ui → Интернет || ✅ Активен
|-
|| NaïveProxy каскад || HTTP/2 naïve || Роутер/ПК → RU Caddy → EU Caddy → WARP || ✅ Активен
|-
|| '''Hysteria2 каскад (этот гайд)''' || '''QUIC/UDP hy2''' || '''Клиенты → RU hy2 → EU hy2 → WARP''' || '''✅ Активен'''
|-
|| MTProto (Telegram) || MTProto || Клиенты Telegram → EU :8443, :2443 || ✅ Активен
|}

----

== Предварительные требования ==

=== Инфраструктура ===

{| class="wikitable"
|-
! Компонент !! Требования
|-
|| EU сервер || Ubuntu 24.04, публичный IP, домен с A-записью → IP сервера
|-
|| RU сервер || Ubuntu 24.04, публичный IP, домен с A-записью → IP сервера
|-
|| 3x-ui на EU сервере || Уже установлен и работает; настроен outbound WARP
|-
|| Docker || Установлен на обоих серверах
|-
|| Порт 2053 UDP || Должен быть свободен на обоих серверах
|-
|| TLS-сертификат || Получается через Caddy (caddy-naive), либо через certbot — описано в разделе ниже
|}

=== DNS-записи (создать заранее, до установки) ===

Let's Encrypt проверяет доступность домена по HTTP (порт 80) перед выдачей сертификата. DNS-записи должны быть созданы и распространены (propagated) до первого запуска Caddy.

{| class="wikitable"
|-
! Запись !! Тип !! Значение !! Примечание
|-
|| <code>your-hy2-ru-domain.example.com</code> || A || IP RU сервера || Используется Hysteria2 сервером на RU
|-
|| <code>your-hy2-eu-domain.example.com</code> || A || IP EU сервера || Используется Hysteria2 сервером на EU
|}

'''Примечание:''' если NaïveProxy (Caddy) уже настроен на тех же серверах с теми же доменами, отдельные DNS-записи для Hysteria2 не нужны — используется тот же домен и тот же сертификат.

=== Используемые заглушки ===

В данном руководстве применяются следующие заглушки. Замени их реальными значениями перед использованием:

{| class="wikitable"
|-
! Заглушка !! Описание
|-
|| <code>YOUR_RU_SERVER_IP</code> || Публичный IP RU сервера
|-
|| <code>YOUR_EU_SERVER_IP</code> || Публичный IP EU сервера
|-
|| <code>your-hy2-ru-domain.example.com</code> || Домен для RU сервера (для TLS-сертификата)
|-
|| <code>your-hy2-eu-domain.example.com</code> || Домен для EU сервера (для TLS-сертификата)
|-
|| <code>YOUR_EMAIL@example.com</code> || Email для Let's Encrypt (уведомления об истечении сертификата)
|-
|| <code>EU_HY2_PASSWORD</code> || Пароль соединения RU клиент → EU сервер (генерируется один раз)
|}

'''Для генерации пароля EU_HY2_PASSWORD используй:'''
<syntaxhighlight lang="bash">
openssl rand -base64 18
</syntaxhighlight>
Сохрани результат — он понадобится в конфигах обоих серверов.

----

== Часть 1: EU сервер (Exit Node) ==

Цель: развернуть Hysteria2 сервер в Docker, который принимает соединения от RU клиента и перенаправляет трафик через 3x-ui → Cloudflare WARP.

'''Все команды в этом разделе выполняются на EU сервере под root.'''

=== 1.1 Установка Docker ===

Если Docker уже установлен (проверить: <code>docker --version</code>) — пропусти этот шаг.

<syntaxhighlight lang="bash">
# Обновить пакеты
apt-get update && apt-get upgrade -y

# Установить зависимости
apt-get install -y ca-certificates curl gnupg lsb-release

# Добавить GPG-ключ Docker
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

# Добавить репозиторий Docker
echo "deb [arch=$(dpkg --print-architecture) \
signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
> /etc/apt/sources.list.d/docker.list

# Установить Docker Engine
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Включить автозапуск
systemctl enable docker
systemctl start docker

# Проверить
docker --version
docker compose version
</syntaxhighlight>

Ожидаемый вывод:
<pre>
Docker version 27.x.x, build ...
Docker Compose version v2.x.x
</pre>

=== 1.2 Настройка 3x-ui: создание inbound hy2-out → WARP ===

Hysteria2 Exit Node направляет трафик через 3x-ui SOCKS5 inbound, который в свою очередь маршрутизирует его в Cloudflare WARP. Этот шаг выполняется в веб-интерфейсе 3x-ui '''до''' запуска Hysteria2.

'''Условие:''' в 3x-ui должен быть настроен outbound WARP (WireGuard/gVisor).

==== 1.2.1 Создать новый inbound в 3x-ui ====

В веб-интерфейсе 3x-ui (EU сервер) перейди в '''Inbounds → Add Inbound''' и заполни следующие поля:

{| class="wikitable"
|-
! Параметр !! Значение !! Пояснение
|-
|| Примечание (Remark) || <code>hy2-out</code> || Произвольное имя для идентификации в правилах маршрутизации
|-
|| Протокол || <code>mixed</code> || Поддерживает SOCKS5 и HTTP одновременно
|-
|| Listen IP || <code>127.0.0.1</code> || Только localhost — недоступен извне
|-
|| Порт || <code>24364</code> || Должен быть свободен; проверить: <code>ss -tlnp | grep 24364</code>
|-
|| Аутентификация || Выключена || Hysteria2 сам отвечает за авторизацию клиентов
|-
|| UDP || Включён || Требуется для DNS-запросов через туннель
|}

Нажми '''Save''' — inbound немедленно активируется.

==== 1.2.2 Создать правило маршрутизации ====

В 3x-ui перейди в '''Routing → Add Rule''' (или Settings → Routing Rules):

{| class="wikitable"
|-
! Параметр !! Значение
|-
|| Inbound Tag || <code>hy2-out</code> (тег созданного выше inbound)
|-
|| Outbound Tag || <code>warp</code> (или название твоего WARP outbound в 3x-ui)
|}

Сохрани и перезапусти Xray внутри 3x-ui.

==== 1.2.3 Проверить, что порт 24364 слушает ====

<syntaxhighlight lang="bash">
ss -tlnp | grep 24364
</syntaxhighlight>

Ожидаемый вывод:
<pre>
LISTEN 0 128 127.0.0.1:24364 0.0.0.0:* users:(("xray",...))
</pre>

=== 1.3 TLS-сертификат для Hysteria2 ===

Hysteria2 требует действующий TLS-сертификат (самоподписанный не рекомендуется — клиентам потребуется флаг <code>insecure: true</code>). В нашей схеме используется '''Let's Encrypt сертификат''', получаемый и автоматически обновляемый через Caddy (caddy-naive стек).

Caddy хранит сертификаты в именованном Docker volume <code>caddy-naive_caddy_data</code>, и Hysteria2 подключает их через bind mount (read-only) — никаких лишних сервисов, никакого дублирования.

==== Вариант А: Caddy (caddy-naive) уже установлен — рекомендуется ====

Если NaïveProxy (caddy-naive) уже настроен и работает, сертификат уже получен. Проверь:

<syntaxhighlight lang="bash">
# Найти путь к сертификату в Docker volume
DOMAIN="your-hy2-eu-domain.example.com"
CERT_DIR="/var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/${DOMAIN}"

ls -la "${CERT_DIR}/"
</syntaxhighlight>

Ожидаемый вывод — два файла:
<pre>
your-hy2-eu-domain.example.com.crt
your-hy2-eu-domain.example.com.key
</pre>

Если файлы есть — переходи к разделу '''1.4'''. Если volume или папка не существуют — сначала установи caddy-naive (NaïveProxy) или воспользуйся Вариантом Б.

==== Вариант Б: получить сертификат через certbot (если Caddy не установлен) ====

Этот вариант используется, если caddy-naive '''не установлен''' и на серверах нет другого HTTP-сервера на портах 80/443.

<syntaxhighlight lang="bash">
# Установить certbot
apt-get install -y certbot

# Получить сертификат (standalone — Certbot запустит временный HTTP-сервер на :80)
certbot certonly --standalone \
-d your-hy2-eu-domain.example.com \
--email YOUR_EMAIL@example.com \
--agree-tos --non-interactive

# Проверить
ls /etc/letsencrypt/live/your-hy2-eu-domain.example.com/
</syntaxhighlight>

Сертификаты будут по пути <code>/etc/letsencrypt/live/your-hy2-eu-domain.example.com/</code>. В этом случае в <code>docker-compose.yml</code> (раздел 1.6) замени volume на:
<syntaxhighlight lang="yaml">
- /etc/letsencrypt/live/your-hy2-eu-domain.example.com:/etc/hysteria/certs:ro
- /etc/letsencrypt/archive/your-hy2-eu-domain.example.com:/etc/letsencrypt/archive/your-hy2-eu-domain.example.com:ro
</syntaxhighlight>

И в <code>server.yaml</code> пути к файлам:
<syntaxhighlight lang="yaml">
tls:
cert: /etc/hysteria/certs/fullchain.pem
key: /etc/hysteria/certs/privkey.pem
</syntaxhighlight>

=== 1.4 Создание структуры проекта ===

<syntaxhighlight lang="bash">
mkdir -p /opt/hysteria-eu
cd /opt/hysteria-eu
</syntaxhighlight>

Итоговая структура:
<pre>
/opt/hysteria-eu/
├── docker-compose.yml
└── server.yaml
</pre>

=== 1.5 Конфигурация сервера: server.yaml ===

Создай файл конфигурации. Замени <code>EU_HY2_PASSWORD</code> сгенерированным паролем:

<syntaxhighlight lang="bash">
cat > /opt/hysteria-eu/server.yaml << 'EOF'
listen: :2053

tls:
cert: /etc/hysteria/certs/your-hy2-eu-domain.example.com.crt
key: /etc/hysteria/certs/your-hy2-eu-domain.example.com.key

auth:
type: password
password: EU_HY2_PASSWORD

ignoreClientBandwidth: true

masquerade:
type: proxy
proxy:
url: https://news.ycombinator.com/
rewriteHost: true

outbounds:
- name: warp
type: socks5
socks5:
addr: 127.0.0.1:24364

acl:
inline:
- "warp(all)"
EOF
</syntaxhighlight>

Описание ключевых параметров:

{| class="wikitable"
|-
! Параметр !! Значение !! Пояснение
|-
|| <code>listen: :2053</code> || UDP порт 2053 || Hysteria2 слушает на всех интерфейсах
|-
|| <code>tls.cert / tls.key</code> || Пути к сертификату || Берутся из caddy-naive Docker volume (bind mount)
|-
|| <code>auth.type: password</code> || Одиночный пароль || Для соединения RU клиент → EU сервер (клиентские устройства этот пароль не знают)
|-
|| <code>ignoreClientBandwidth: true</code> || Игнорировать лимит клиента || Серверная сторона управляет congestion control самостоятельно
|-
|| <code>masquerade.type: proxy</code> || Проксировать реальный сайт || Неавторизованные запросы получают реальный контент ycombinator.com — сервер выглядит как обычный HTTPS-сайт
|-
|| <code>outbounds.warp</code> || SOCKS5 на 127.0.0.1:24364 || Исходящий трафик → 3x-ui inbound "hy2-out" → WARP
|-
|| <code>acl: warp(all)</code> || Направить весь трафик в warp || Синтаксис: имя outbound в скобках, адрес/маска после
|}

=== 1.6 Конфигурация Docker Compose: docker-compose.yml ===

<syntaxhighlight lang="bash">
cat > /opt/hysteria-eu/docker-compose.yml << 'EOF'
services:
hysteria-eu:
image: tobyxdd/hysteria:latest
container_name: hysteria-eu
restart: unless-stopped
network_mode: host
command: server --config /etc/hysteria/server.yaml
volumes:
- ./server.yaml:/etc/hysteria/server.yaml:ro
- /var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/your-hy2-eu-domain.example.com:/etc/hysteria/certs:ro
EOF
</syntaxhighlight>

Важные моменты:
* <code>network_mode: host</code> — обязателен, чтобы контейнер видел <code>127.0.0.1:24364</code> (3x-ui inbound).
* <code>:ro</code> — сертификаты подключены только для чтения, Hysteria2 их не изменяет.
* Путь к сертификату — bind mount из Docker volume caddy-naive. Если используется certbot (Вариант Б) — замени путь согласно инструкции раздела 1.3.

=== 1.7 Первый запуск ===

<syntaxhighlight lang="bash">
cd /opt/hysteria-eu

# Скачать образ и запустить
docker compose pull
docker compose up -d

# Подождать 3 секунды и проверить логи
sleep 3 && docker compose logs
</syntaxhighlight>

Ожидаемый вывод в логах:
<pre>
INFO server mode
INFO server up and running {"listen": ":2053"}
</pre>

Если в логах ошибка — см. раздел «Диагностика проблем» (Часть 5).

=== 1.8 Проверка: порт и соединение ===

<syntaxhighlight lang="bash">
# Проверить, что Hysteria2 слушает на UDP :2053
ss -ulnp | grep ':2053'
</syntaxhighlight>

Ожидаемый вывод:
<pre>
UNCONN 0 0 0.0.0.0:2053 0.0.0.0:* users:(("hysteria",...))
</pre>

<syntaxhighlight lang="bash">
# Статус контейнера
docker compose ps
</syntaxhighlight>

<pre>
NAME IMAGE STATUS
hysteria-eu tobyxdd/hysteria:latest Up X minutes
</pre>

----

== Часть 2: RU сервер (Entry Node) ==

Цель: развернуть два Docker-контейнера:
* <code>hysteria-ru-server</code> — принимает соединения от клиентов, аутентифицирует по <code>users.txt</code>.
* <code>hysteria-ru-client</code> — подключается к EU серверу, слушает SOCKS5 на <code>127.0.0.1:10810</code>.

Между ними: hysteria-ru-server направляет трафик через SOCKS5 → hysteria-ru-client → EU.

'''Все команды в этом разделе выполняются на RU сервере под root.'''

=== 2.1 Установка Docker ===

Аналогично EU серверу (раздел 1.1). Если Docker уже установлен — пропусти.

<syntaxhighlight lang="bash">
apt-get update && apt-get upgrade -y
apt-get install -y ca-certificates curl gnupg lsb-release

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) \
signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
> /etc/apt/sources.list.d/docker.list

apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
systemctl enable docker && systemctl start docker

docker --version && docker compose version
</syntaxhighlight>

=== 2.2 TLS-сертификат для RU сервера ===

Аналогично EU серверу. На RU сервере также используется сертификат от Caddy (caddy-naive), если NaïveProxy настроен.

==== Вариант А: через Caddy (caddy-naive) — рекомендуется ====

<syntaxhighlight lang="bash">
DOMAIN="your-hy2-ru-domain.example.com"
CERT_DIR="/var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/${DOMAIN}"

ls -la "${CERT_DIR}/"
</syntaxhighlight>

Если файлы <code>.crt</code> и <code>.key</code> присутствуют — всё готово, переходи к разделу 2.3.

==== Вариант Б: через certbot (если Caddy не установлен) ====

<syntaxhighlight lang="bash">
apt-get install -y certbot

certbot certonly --standalone \
-d your-hy2-ru-domain.example.com \
--email YOUR_EMAIL@example.com \
--agree-tos --non-interactive

ls /etc/letsencrypt/live/your-hy2-ru-domain.example.com/
</syntaxhighlight>

=== 2.3 Создание структуры проекта ===

<syntaxhighlight lang="bash">
mkdir -p /opt/hysteria-ru/users
cd /opt/hysteria-ru
</syntaxhighlight>

Итоговая структура:
<pre>
/opt/hysteria-ru/
├── docker-compose.yml
├── server.yaml
├── client.yaml
└── users/
├── users.txt ← список пользователей (username password)
└── check-auth.sh ← скрипт авторизации, вызывается при каждом подключении
</pre>

=== 2.4 Система аутентификации пользователей ===

RU сервер использует <code>auth.type: command</code> — при каждом входящем подключении Hysteria2 вызывает внешний скрипт и передаёт ему пароль клиента в аргументах. Скрипт ищет пароль в файле <code>users.txt</code>: если совпадение найдено — выводит имя пользователя (оно попадает в логи) и завершается с кодом 0. Если нет — завершается с кодом 1 (отказ в подключении).

Преимущество этого подхода: <code>users.txt</code> можно редактировать в любой момент без перезапуска контейнера. Изменения применяются немедленно.

==== 2.4.1 Файл пользователей: users/users.txt ====

Формат: одна строка на пользователя — имя пользователя и пароль, разделённые пробелом.

<syntaxhighlight lang="bash">
# Сгенерировать первого пользователя (пример: "default")
PASS=$(openssl rand -base64 18)
echo "default $PASS" > /opt/hysteria-ru/users/users.txt
echo "Пароль пользователя default: $PASS"
</syntaxhighlight>

Формат файла:
<pre>
username1 пароль1
username2 пароль2
</pre>

'''Важно:''' не используй пробелы внутри пароля — пароль считывается по второму полю строки.

==== 2.4.2 Скрипт авторизации: users/check-auth.sh ====

Hysteria2 вызывает скрипт с тремя аргументами: <code>$1</code> — адрес клиента, <code>$2</code> — пароль, <code>$3</code> — tx bandwidth.

<syntaxhighlight lang="bash">
cat > /opt/hysteria-ru/users/check-auth.sh << 'EOF'
#!/bin/sh
AUTH_PAYLOAD="$2"
USERS_FILE="/etc/hysteria/users/users.txt"

USERNAME=$(awk -v pwd="$AUTH_PAYLOAD" '$2 == pwd {print $1; exit}' "$USERS_FILE" 2>/dev/null)

if [ -n "$USERNAME" ]; then
echo "$USERNAME"
exit 0
fi
exit 1
EOF

chmod +x /opt/hysteria-ru/users/check-auth.sh
</syntaxhighlight>

Почему используется <code>awk</code>, а не <code>grep</code>:
* Hysteria2 использует Docker-образ на базе Alpine Linux с BusyBox.
* BusyBox <code>grep</code> не поддерживает флаг <code>-P</code> (Perl-совместимые регулярки).
* <code>awk</code> доступен во всех Unix/Linux окружениях и работает стабильно.

=== 2.5 Конфигурация сервера: server.yaml ===

<syntaxhighlight lang="bash">
cat > /opt/hysteria-ru/server.yaml << 'EOF'
listen: :2053

tls:
cert: /etc/hysteria/certs/your-hy2-ru-domain.example.com.crt
key: /etc/hysteria/certs/your-hy2-ru-domain.example.com.key

auth:
type: command
command: /etc/hysteria/users/check-auth.sh

ignoreClientBandwidth: true

masquerade:
type: proxy
proxy:
url: https://news.ycombinator.com/
rewriteHost: true

outbounds:
- name: chain
type: socks5
socks5:
addr: 127.0.0.1:10810

acl:
inline:
- "chain(all)"
EOF
</syntaxhighlight>

Описание ключевых параметров:

{| class="wikitable"
|-
! Параметр !! Значение !! Пояснение
|-
|| <code>auth.type: command</code> || Внешний скрипт || При каждом подключении вызывается <code>check-auth.sh</code>
|-
|| <code>auth.command</code> || Путь внутри контейнера || Скрипт смонтирован через volume: <code>./users:/etc/hysteria/users</code>
|-
|| <code>outbounds.chain</code> || SOCKS5 на 127.0.0.1:10810 || Трафик → hysteria-ru-client → EU
|-
|| <code>acl: chain(all)</code> || Весь трафик через chain || Синтаксис: имя outbound, затем адрес в скобках
|}

=== 2.6 Конфигурация клиента: client.yaml ===

RU клиент подключается к EU серверу и поднимает SOCKS5 на <code>127.0.0.1:10810</code>.

<syntaxhighlight lang="bash">
cat > /opt/hysteria-ru/client.yaml << 'EOF'
server: your-hy2-eu-domain.example.com:2053

auth: EU_HY2_PASSWORD

socks5:
listen: 127.0.0.1:10810
EOF
</syntaxhighlight>

Замени <code>EU_HY2_PASSWORD</code> на тот же пароль, который указан в <code>server.yaml</code> EU сервера.

=== 2.7 Конфигурация Docker Compose: docker-compose.yml ===

<syntaxhighlight lang="bash">
cat > /opt/hysteria-ru/docker-compose.yml << 'EOF'
services:
hysteria-ru-server:
image: tobyxdd/hysteria:latest
container_name: hysteria-ru-server
restart: unless-stopped
network_mode: host
command: server --config /etc/hysteria/server.yaml
volumes:
- ./server.yaml:/etc/hysteria/server.yaml:ro
- ./users:/etc/hysteria/users:ro
- /var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/your-hy2-ru-domain.example.com:/etc/hysteria/certs:ro

hysteria-ru-client:
image: tobyxdd/hysteria:latest
container_name: hysteria-ru-client
restart: unless-stopped
network_mode: host
command: client --config /etc/hysteria/client.yaml
volumes:
- ./client.yaml:/etc/hysteria/client.yaml:ro
EOF
</syntaxhighlight>

'''Критически важные моменты:'''
* Директория <code>./users</code> монтируется в оба контейнера... нет, только в <code>hysteria-ru-server</code>. Клиентский контейнер видит только свой <code>client.yaml</code>.
* При изменении <code>docker-compose.yml</code> (добавлении volume) нужен пересоздать контейнер: <code>docker compose down && docker compose up -d</code>. Простой <code>restart</code> не применяет изменения volumes.

=== 2.8 Первый запуск ===

<syntaxhighlight lang="bash">
cd /opt/hysteria-ru

# Скачать образ
docker compose pull

# Запустить оба контейнера
docker compose up -d

# Подождать и проверить логи
sleep 3 && docker compose logs
</syntaxhighlight>

Ожидаемый вывод:
<pre>
hysteria-ru-server | INFO server mode
hysteria-ru-server | INFO server up and running {"listen": ":2053"}
hysteria-ru-client | INFO client mode
hysteria-ru-client | INFO connected to server {"udpEnabled": true, "count": 1}
hysteria-ru-client | INFO SOCKS5 server listening {"addr": "127.0.0.1:10810"}
</pre>

=== 2.9 Проверка цепочки с RU сервера ===

Тест: запустить временный Hysteria2 клиент на RU сервере и проверить, что трафик выходит через WARP (IP Cloudflare):

<syntaxhighlight lang="bash">
# Создать временный конфиг тест-клиента
cat > /tmp/hy2-test.yaml << EOF
server: 127.0.0.1:2053
auth: $(awk 'NR==1{print $2}' /opt/hysteria-ru/users/users.txt)
tls:
insecure: true
sni: your-hy2-ru-domain.example.com
socks5:
listen: 127.0.0.1:11080
EOF

# Запустить тест-клиент
docker run -d --name hy2-test --network host \
-v /tmp/hy2-test.yaml:/etc/hysteria/client.yaml:ro \
tobyxdd/hysteria:latest client --config /etc/hysteria/client.yaml

# Ждать 3 секунды
sleep 3

# Проверить IP выхода — должен быть Cloudflare WARP IP
echo "IP через цепочку:"
curl -s --max-time 15 -x socks5h://127.0.0.1:11080 https://ifconfig.me

# Очистить
docker rm -f hy2-test
rm -f /tmp/hy2-test.yaml
</syntaxhighlight>

Если IP вывода принадлежит Cloudflare (начинается с <code>2a09:</code> для IPv6 или относится к диапазонам WARP) — цепочка RU → EU → WARP работает корректно.

'''Примечание:''' параметр <code>insecure: true</code> и <code>sni</code> нужны в тест-клиенте, потому что он подключается по IP (<code>127.0.0.1</code>), а сертификат выдан на домен. Реальные клиенты подключаются по домену и такие параметры не требуются.

----

== Часть 3: Управление пользователями (hy2-users.sh) ==

=== 3.1 Что это и зачем ===

Для управления пользователями Hysteria2 на RU сервере предназначен скрипт <code>hy2-users.sh</code>. Он предоставляет интерактивное меню с набором операций над файлом <code>users.txt</code>.

Скрипт решает следующие задачи:

{| class="wikitable"
|-
! Операция !! Описание
|-
|| Список пользователей || Показывает всех пользователей из users.txt с маскированными паролями
|-
|| Добавить пользователя || Запрашивает имя, автоматически генерирует криптостойкий пароль, сохраняет в users.txt, показывает готовый Hysteria2 URI
|-
|| Удалить пользователя || Интерактивный выбор из списка, удаление строки из users.txt
|-
|| Показать конфиг || Генерирует и показывает Hysteria2 URI для выбранного пользователя
|}

Ключевые особенности:
* '''Нет перезапуска контейнера.''' Hysteria2 с <code>auth.type: command</code> читает файл при каждом подключении — изменения в <code>users.txt</code> применяются мгновенно.
* '''Пароли генерируются автоматически''' через <code>openssl rand</code> — случайные, криптостойкие.
* '''URI формат''' соответствует стандарту Hysteria2 и принимается всеми клиентами: NekoBox, husi, Exclave, podkop.

=== 3.2 Установка скрипта ===

Скрипт хранится в репозитории по пути <code>scripts/hy2-users.sh</code>. Установка на сервер:

<syntaxhighlight lang="bash">
# Скопировать скрипт на сервер
scp scripts/hy2-users.sh root@YOUR_RU_SERVER_IP:/usr/local/bin/hy2-users.sh

# Сделать исполняемым
ssh root@YOUR_RU_SERVER_IP "chmod +x /usr/local/bin/hy2-users.sh"
</syntaxhighlight>

Или выполнить непосредственно на RU сервере (если скрипт уже там):

<syntaxhighlight lang="bash">
chmod +x /usr/local/bin/hy2-users.sh
</syntaxhighlight>

'''Проверка переменных в начале скрипта.''' Открой скрипт и убедись, что следующие переменные указывают на правильные значения:

<syntaxhighlight lang="bash">
head -15 /usr/local/bin/hy2-users.sh
</syntaxhighlight>

Должны быть:
* <code>USERS_FILE="/opt/hysteria-ru/users/users.txt"</code>
* <code>DOMAIN="your-hy2-ru-domain.example.com"</code>
* <code>PORT="2053"</code>

Если домен указан неверно — исправь:
<syntaxhighlight lang="bash">
sed -i 's|DOMAIN=.*|DOMAIN="your-hy2-ru-domain.example.com"|' /usr/local/bin/hy2-users.sh
</syntaxhighlight>

=== 3.3 Использование ===

<syntaxhighlight lang="bash">
sudo bash /usr/local/bin/hy2-users.sh
</syntaxhighlight>

Скрипт показывает меню:
<pre>
┌─────────────────────────────────────────────┐
│ Hysteria2 — управление пользователями RU │
└─────────────────────────────────────────────┘

1. Список пользователей
2. Добавить пользователя
3. Удалить пользователя
4. Показать конфиг клиента

0. Выход

Выбери действие:
</pre>

При добавлении нового пользователя скрипт выводит готовый URI:
<pre>
hysteria2://СГЕНЕРИРОВАННЫЙ_ПАРОЛЬ@your-hy2-ru-domain.example.com:2053
</pre>

Этот URI вставляется напрямую в клиентское приложение (см. Часть 4).

=== 3.4 Исходный код скрипта ===

<div class="mw-collapsible mw-collapsed" style="width:100%">
<div style="font-weight:bold; padding:4px 0;">▶ Показать исходный код hy2-users.sh</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="bash">
#!/bin/bash
# =============================================================
# hy2-users — управление пользователями Hysteria2 на RU сервере
# users.txt: /opt/hysteria-ru/users/users.txt
# Формат: username password (по одной строке)
# Перезапуск контейнера НЕ требуется — изменения применяются мгновенно
# =============================================================

USERS_FILE="/opt/hysteria-ru/users/users.txt"
DOMAIN="your-hy2-ru-domain.example.com"
PORT="2053"

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
CYAN='\033[0;36m'
BOLD='\033[1m'
NC='\033[0m'

# --- Вспомогательные функции ---

check_root() {
if [[ $EUID -ne 0 ]]; then
echo -e "${RED}Ошибка: запусти скрипт от root (sudo bash hy2-users.sh)${NC}"
exit 1
fi
}

check_users_file() {
if [[ ! -f "$USERS_FILE" ]]; then
echo -e "${RED}Ошибка: файл пользователей не найден: $USERS_FILE${NC}"
exit 1
fi
}

get_usernames() {
awk '{print $1}' "$USERS_FILE"
}

get_password() {
local user="$1"
awk -v u="$user" '$1 == u {print $2}' "$USERS_FILE"
}

press_enter() {
echo ""
read -rp "Нажми Enter для возврата в меню..."
}

print_config_for() {
local user="$1"
local pass="$2"
echo ""
echo -e "${BOLD}┌─────────────────────────────────────────────┐${NC}"
echo -e "${BOLD}│ Hysteria2 URI для клиента │${NC}"
echo -e "${BOLD}└─────────────────────────────────────────────┘${NC}"
echo ""
echo -e "${BOLD} hysteria2://${pass}@${DOMAIN}:${PORT}${NC}"
echo ""
echo -e "${CYAN}Для podkop (OpenWrt):${NC} вставить URI как hy2 outbound"
echo -e "${CYAN}Для мобильных клиентов:${NC} NekoBox, husi, Exclave — импорт URI"
echo -e "${CYAN}Пользователь:${NC} ${user}"
}

# --- Функции меню ---

list_users() {
echo ""
echo -e "${BOLD}${CYAN}=== Список пользователей ===${NC}"
mapfile -t users < <(get_usernames)
if [[ ${#users[@]} -eq 0 ]]; then
echo -e "${YELLOW}Пользователей нет.${NC}"
else
for i in "${!users[@]}"; do
echo -e " ${BOLD}$((i+1)).${NC} ${users[$i]}"
done
echo ""
echo -e " Всего: ${#users[@]} пользователь(ей)"
fi
press_enter
}

add_user() {
echo ""
echo -e "${BOLD}${CYAN}=== Добавить пользователя ===${NC}"

read -rp "Имя пользователя: " username
username=$(echo "$username" | tr -d ' ')

if [[ -z "$username" ]]; then
echo -e "${RED}Имя не может быть пустым.${NC}"
press_enter
return
fi

if grep -q "^${username} " "$USERS_FILE" 2>/dev/null; then
echo -e "${RED}Пользователь '${username}' уже существует.${NC}"
press_enter
return
fi

read -rp "Пароль (Enter = сгенерировать автоматически): " password
if [[ -z "$password" ]]; then
password=$(openssl rand -base64 18 | tr -d '=/+' | head -c 22)
echo -e " Сгенерирован пароль: ${BOLD}${password}${NC}"
fi

echo "${username} ${password}" >> "$USERS_FILE"
echo -e "${GREEN}Пользователь '${username}' добавлен.${NC}"
echo -e "${YELLOW}Изменения применяются мгновенно — перезапуск не нужен.${NC}"

print_config_for "$username" "$password"
press_enter
}

delete_user() {
echo ""
echo -e "${BOLD}${CYAN}=== Удалить пользователя ===${NC}"
mapfile -t users < <(get_usernames)

if [[ ${#users[@]} -eq 0 ]]; then
echo -e "${YELLOW}Нет пользователей для удаления.${NC}"
press_enter
return
fi

for i in "${!users[@]}"; do
echo -e " ${BOLD}$((i+1)).${NC} ${users[$i]}"
done
echo " 0. Отмена"
echo ""
read -rp "Выбери номер для удаления: " choice

if [[ "$choice" == "0" || -z "$choice" ]]; then
return
fi

if ! [[ "$choice" =~ ^[0-9]+$ ]] || (( choice < 1 || choice > ${#users[@]} )); then
echo -e "${RED}Неверный номер.${NC}"
press_enter
return
fi

target="${users[$((choice-1))]}"
read -rp "Удалить пользователя '${target}'? (y/N): " confirm
if [[ "$confirm" =~ ^[Yy]$ ]]; then
sed -i "/^${target} /d" "$USERS_FILE"
echo -e "${GREEN}Пользователь '${target}' удалён.${NC}"
echo -e "${YELLOW}Изменения применяются мгновенно — перезапуск не нужен.${NC}"
else
echo "Отменено."
fi
press_enter
}

show_config() {
echo ""
echo -e "${BOLD}${CYAN}=== URI клиента ===${NC}"
mapfile -t users < <(get_usernames)

if [[ ${#users[@]} -eq 0 ]]; then
echo -e "${YELLOW}Нет пользователей.${NC}"
press_enter
return
fi

for i in "${!users[@]}"; do
echo -e " ${BOLD}$((i+1)).${NC} ${users[$i]}"
done
echo " 0. Отмена"
echo ""
read -rp "Выбери номер пользователя: " choice

if [[ "$choice" == "0" || -z "$choice" ]]; then
return
fi

if ! [[ "$choice" =~ ^[0-9]+$ ]] || (( choice < 1 || choice > ${#users[@]} )); then
echo -e "${RED}Неверный номер.${NC}"
press_enter
return
fi

local user="${users[$((choice-1))]}"
local pass
pass=$(get_password "$user")
print_config_for "$user" "$pass"
press_enter
}

# --- Главное меню ---

main_menu() {
check_root
check_users_file

while true; do
clear
echo -e "${BOLD}${CYAN}"
echo "╔══════════════════════════════════════╗"
echo "║ Hysteria2 User Manager (RU) ║"
echo "║ Домен: ${DOMAIN} ║"
echo "╚══════════════════════════════════════╝"
echo -e "${NC}"

mapfile -t users < <(get_usernames)
echo -e " Активных пользователей: ${BOLD}${#users[@]}${NC}"
echo ""
echo -e " ${BOLD}1.${NC} Список пользователей"
echo -e " ${BOLD}2.${NC} Добавить пользователя"
echo -e " ${BOLD}3.${NC} Удалить пользователя"
echo -e " ${BOLD}4.${NC} Показать URI клиента"
echo -e " ${BOLD}0.${NC} Выход"
echo ""
read -rp "Выбор: " option

case "$option" in
1) list_users ;;
2) add_user ;;
3) delete_user ;;
4) show_config ;;
0) echo "Выход."; exit 0 ;;
*) echo -e "${RED}Неверный выбор.${NC}"; sleep 1 ;;
esac
done
}

main_menu

</syntaxhighlight>
</div>
</div>

----

== Часть 4: Настройка клиентов ==

=== 4.1 Формат URI Hysteria2 ===

Hysteria2 использует стандартизированный URI для передачи параметров подключения клиентам:

<pre>
hysteria2://ПАРОЛЬ@ДОМЕН:ПОРТ
</pre>

Пример:
<pre>
hysteria2://aBcDeFgHiJkLmNoPqRsT@your-hy2-ru-domain.example.com:2053
</pre>

URI можно получить через скрипт <code>hy2-users.sh</code> (пункт 4 меню — «Показать конфиг клиента»).

=== 4.2 Мобильные клиенты (iOS / Android) ===

Рекомендуемые приложения с нативной поддержкой Hysteria2:

{| class="wikitable"
|-
! Приложение !! Платформа !! Как импортировать URI
|-
|| NekoBox || Android || Главный экран → + → Add → Hysteria2 → вставить URI
|-
|| husi || Android || Профили → + → Hysteria2 → вставить URI
|-
|| Exclave || iOS || Конфигурации → + → Hysteria2 → вставить URI
|-
|| Shadowrocket || iOS || Главная → + → Тип: Hysteria2 → вставить URI
|}

Все эти приложения принимают URI в формате <code>hysteria2://...</code> напрямую — через кнопку импорта, QR-код или буфер обмена.

=== 4.3 ПК-клиенты (Windows / macOS / Linux) ===

==== Вариант А: официальный бинарь Hysteria2 ====

Скачать бинарь с официального репозитория: https://github.com/apernet/hysteria/releases

Создать файл конфигурации <code>config.yaml</code>:
<syntaxhighlight lang="yaml">
server: your-hy2-ru-domain.example.com:2053

auth: ВАШ_ПАРОЛЬ

socks5:
listen: 127.0.0.1:1080

http:
listen: 127.0.0.1:8080
</syntaxhighlight>

Запустить:
<syntaxhighlight lang="bash">
# Linux / macOS
./hysteria client --config config.yaml

# Windows (PowerShell)
.\hysteria.exe client --config config.yaml
</syntaxhighlight>

После запуска:
* SOCKS5 прокси доступен на <code>127.0.0.1:1080</code>
* HTTP прокси доступен на <code>127.0.0.1:8080</code>

==== Вариант Б: через NekoRay / Hiddify Next (Windows / Linux) ====

Приложения NekoRay и Hiddify Next принимают Hysteria2 URI — импорт через меню или буфер обмена. Автоматически управляют запуском клиентского процесса.

=== 4.4 OpenWrt / podkop ===

podkop (реализация на базе sing-box) нативно поддерживает Hysteria2 URI. Никакой дополнительной установки бинарей не требуется.

В интерфейсе podkop (LuCI → Network → podkop → Outbound):
* Тип: <code>Hysteria2</code>
* URI: <code>hysteria2://ПАРОЛЬ@your-hy2-ru-domain.example.com:2053</code>

Или через UCI:
<syntaxhighlight lang="bash">
uci set podkop.main.proxy='hysteria2://ПАРОЛЬ@your-hy2-ru-domain.example.com:2053'
uci commit podkop
/etc/init.d/podkop restart
</syntaxhighlight>

После сохранения все устройства домашней сети автоматически получают обход без дополнительной настройки.

----

== Часть 5: Проверка всей цепочки ==

=== 5.1 Тест RU сервера: цепочка RU → EU → WARP ===

Выполнить на RU сервере — проверяет, что трафик выходит через WARP:

<syntaxhighlight lang="bash">
# SOCKS5 порт 10810 — это точка выхода RU клиента (= вход в EU сервер → WARP)
curl -s --max-time 20 -x socks5h://127.0.0.1:10810 https://ifconfig.me
echo ""
</syntaxhighlight>

Результат должен быть '''IP Cloudflare WARP''' — например, начинается с <code>2a09:</code> (IPv6) или принадлежит AS13335 (Cloudflare).

Проверить AS:
<syntaxhighlight lang="bash">
IP=$(curl -s --max-time 20 -x socks5h://127.0.0.1:10810 https://ifconfig.me)
curl -s "https://ipinfo.io/${IP}/org"
echo ""
</syntaxhighlight>

Ожидаемый вывод: строка содержит <code>Cloudflare</code>.

=== 5.2 Тест с реального клиента ===

После добавления пользователя через <code>hy2-users.sh</code> и получения URI:

# Вставь URI в клиентское приложение (NekoBox, husi, Shadowrocket).
# Активируй профиль.
# Открой <code>https://ifconfig.me</code> в браузере — должен отображаться IP Cloudflare WARP.
# Открой <code>https://www.whatismybrowser.com/detect/what-is-my-ip-address</code> для проверки отсутствия WebRTC утечки.

=== 5.3 Диагностика проблем ===

==== Проблема: hysteria-eu не запускается — ошибка TLS ====

<syntaxhighlight lang="bash">
docker compose -f /opt/hysteria-eu/docker-compose.yml logs hysteria-eu
</syntaxhighlight>

Возможные причины:
* Путь к сертификату неверен → проверь <code>ls</code> по пути, указанному в volumes.
* Сертификат ещё не был получен Caddy → проверь, что caddy-naive запущен и прошёл ACME-проверку.
* Caddy хранит сертификат под другим именем → выполни <code>find /var/lib/docker/volumes/caddy-naive_caddy_data/_data -name "*.crt"</code>.

==== Проблема: hysteria-ru-server выдаёт auth error ====

<syntaxhighlight lang="bash">
docker compose -f /opt/hysteria-ru/docker-compose.yml logs hysteria-ru-server
</syntaxhighlight>

Проверить вручную (на RU сервере):
<syntaxhighlight lang="bash">
# Проверить, что скрипт находится на месте внутри контейнера
docker exec hysteria-ru-server ls -la /etc/hysteria/users/

# Запустить скрипт вручную с тестовым паролем
docker exec hysteria-ru-server /etc/hysteria/users/check-auth.sh addr ТЕСТОВЫЙ_ПАРОЛЬ 0
echo "Exit code: $?"
</syntaxhighlight>

Если <code>Exit code: 0</code> — скрипт работает. Если <code>1</code> — пароль не найден в <code>users.txt</code>.

==== Проблема: hysteria-ru-client не подключается к EU ====

<syntaxhighlight lang="bash">
docker compose -f /opt/hysteria-ru/docker-compose.yml logs hysteria-ru-client
</syntaxhighlight>

Возможные причины:
* <code>EU_HY2_PASSWORD</code> в <code>client.yaml</code> не совпадает с паролем в EU <code>server.yaml</code>.
* UDP порт 2053 заблокирован на EU сервере (firewall) → проверь <code>ss -ulnp | grep 2053</code> на EU сервере.
* EU сервер ещё не запущен.

==== Проблема: ACL ошибка при запуске ====

<pre>
FATAL failed to load server config: invalid config: acl.inline: invalid syntax at line 1
</pre>

Неверный синтаксис ACL. Правильный формат: <code>"outbound_name(address)"</code>:
* ✅ <code>"warp(all)"</code> — направить всё в outbound "warp"
* ✅ <code>"chain(all)"</code> — направить всё в outbound "chain"
* ❌ <code>"outbound(warp) all"</code> — неверно

----

== Часть 6: Обслуживание ==

=== 6.1 Управление контейнерами ===

<syntaxhighlight lang="bash">
# EU сервер
cd /opt/hysteria-eu
docker compose up -d # запустить
docker compose down # остановить
docker compose restart # перезапустить
docker compose logs -f # следить за логами в реальном времени
docker compose ps # статус

# RU сервер (оба контейнера)
cd /opt/hysteria-ru
docker compose up -d
docker compose down
docker compose restart
docker compose logs -f

# RU сервер (по отдельности)
docker compose restart hysteria-ru-server # только сервер
docker compose restart hysteria-ru-client # только клиент
docker compose logs -f hysteria-ru-server # логи только сервера
docker compose logs -f hysteria-ru-client # логи только клиента
</syntaxhighlight>

=== 6.2 Обновление сертификатов ===

TLS-сертификаты обновляются Caddy автоматически (за 30 дней до истечения). После автообновления Hysteria2 начнёт использовать новый сертификат при следующем перезапуске.

Для принудительного применения нового сертификата:
<syntaxhighlight lang="bash">
# EU сервер
cd /opt/hysteria-eu && docker compose restart

# RU сервер
cd /opt/hysteria-ru && docker compose restart hysteria-ru-server
</syntaxhighlight>

Проверить дату истечения текущего сертификата:
<syntaxhighlight lang="bash">
# EU сервер
DOMAIN="your-hy2-eu-domain.example.com"
CERT="/var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/${DOMAIN}/${DOMAIN}.crt"
openssl x509 -in "${CERT}" -noout -enddate
</syntaxhighlight>

=== 6.3 Обновление Docker-образа ===

Hysteria2 активно развивается. Для обновления до последней версии:

<syntaxhighlight lang="bash">
# EU сервер
cd /opt/hysteria-eu
docker compose pull # скачать новый образ
docker compose up -d # перезапустить с новым образом
docker compose logs --tail=5 # проверить старт

# RU сервер
cd /opt/hysteria-ru
docker compose pull
docker compose up -d
docker compose logs --tail=5
</syntaxhighlight>

Старые неиспользуемые образы можно удалить:
<syntaxhighlight lang="bash">
docker image prune -f
</syntaxhighlight>

=== 6.4 Мониторинг логов ===

Hysteria2 пишет структурированные JSON-логи. Полезные паттерны для мониторинга:

<syntaxhighlight lang="bash">
# Смотреть все подключения на RU сервере
docker logs hysteria-ru-server 2>&1 | grep -E "connected|disconnected|auth"

# Смотреть ошибки
docker logs hysteria-ru-server 2>&1 | grep -i "error\|fatal\|warn"

# Считать количество уникальных пользователей (поле "id")
docker logs hysteria-ru-server 2>&1 | grep '"id"' | grep -oP '"id": "\K[^"]+' | sort -u

# Следить за логами EU сервера в реальном времени
docker logs -f hysteria-eu 2>&1
</syntaxhighlight>

Пример нормального лога RU сервера при входящем подключении:
<pre>
INFO client connected {"addr": "CLIENT_IP:PORT", "id": "username"}
INFO TCP request {"addr": "CLIENT_IP:PORT", "id": "username", "reqAddr": "example.com:443"}
INFO client disconnected {"addr": "CLIENT_IP:PORT", "id": "username", "error": "..."}
</pre>

Поле <code>"id"</code> — это имя пользователя, возвращённое скриптом <code>check-auth.sh</code>. Это позволяет отслеживать активность конкретных пользователей в логах без хранения паролей.

Hysteria 2 каскад

2026-04-26T10:12:48Z

Владимир: /* Полная схема прохождения трафика */

= Hysteria2: установка каскадной цепочки Entry Node → Exit Node → WARP =

== Что такое Hysteria2 и зачем он нужен ==

=== Проблема: ограничения традиционных прокси-протоколов ===

Современные системы глубокой инспекции пакетов (DPI — Deep Packet Inspection), применяемые интернет-провайдерами и регуляторами по всему миру, умеют анализировать не только адреса назначения, но и '''характер самого трафика'''. Даже зашифрованное соединение можно идентифицировать — по поведению, по паузам между пакетами, по размерам передаваемых блоков данных, по TLS-fingerprint.

Большинство прокси-протоколов работают поверх '''TCP'''. Это означает:
* Все потери пакетов обрабатываются дважды — сначала на уровне транспорта, затем внутри туннеля (head-of-line blocking).
* При нестабильном канале (мобильная сеть, спутник, VPN на слабом железе) скорость резко падает.
* TCP-fingerprint легче распознаётся и блокируется.

Hysteria2 решает эту проблему фундаментально иначе: он работает поверх '''QUIC''' — транспортного протокола на базе UDP, разработанного в Google и стандартизированного в RFC 9000.

=== Решение: QUIC/UDP с маскировкой под HTTPS ===

Hysteria2 строит зашифрованный туннель поверх UDP, используя QUIC:
* '''Нет head-of-line blocking:''' потеря одного пакета не блокирует остальные потоки.
* '''Быстрое восстановление соединения:''' QUIC переподключается за 0-RTT (без дополнительного round-trip).
* '''Маскировка под HTTPS:''' снаружи трафик Hysteria2 выглядит как обычный QUIC/HTTP3 браузерный трафик — сервер «притворяется» обычным HTTPS-сайтом и возвращает реальный веб-контент при неавторизованных запросах.
* '''Congestion control:''' поддерживает несколько алгоритмов управления перегрузкой, включая BBR.

{| class="wikitable"
|-
! Протокол !! Транспорт !! Как выглядит для DPI !! Устойчивость к блокировке !! Скорость при потерях
|-
|| Обычный VPN (WireGuard, OpenVPN) || UDP / TCP || Характерный шаблон || Низкая — fingerprint легко детектируется || Высокая (WG) / Низкая (OpenVPN)
|-
|| Shadowsocks || TCP || Случайный зашифрованный поток || Средняя — выявляется по энтропии || Средняя
|-
|| VLESS + REALITY || TCP (TLS) || TLS с реальным сертификатом стороннего сайта || Высокая || Средняя
|-
|| NaïveProxy || TCP (HTTP/2 TLS) || Неотличим от Chrome HTTPS || Очень высокая || Средняя (TCP Head-of-Line)
|-
|| '''Hysteria2''' || '''UDP (QUIC/TLS)''' || '''QUIC/HTTP3, маскировка под HTTPS''' || '''Очень высокая''' || '''Высокая — устойчив к потерям'''
|}

=== Как работает Hysteria2 технически ===

Hysteria2 использует протокол QUIC в качестве транспорта:

# Клиент устанавливает QUIC-соединение с сервером — это TLS 1.3 поверх UDP.
# Внутри QUIC-соединения открываются независимые потоки (streams) для каждого проксируемого соединения.
# Сервер обрабатывает входящий трафик: авторизует клиента (по паролю или через внешний скрипт), затем перенаправляет трафик через указанный outbound.
# Если к серверу обращаются без правильного пароля — сервер ведёт себя как обычный HTTPS-сайт ('''masquerade''') и возвращает реальный контент с заданного URL.

Особенности аутентификации в данной схеме:
* '''EU сервер:''' использует одиночный пароль — только для входящих соединений от RU клиента (не клиентских устройств).
* '''RU сервер:''' использует '''command-аутентификацию''' — при каждом подключении вызывается внешний bash-скрипт, который проверяет пароль по файлу <code>users.txt</code>. Это позволяет добавлять и удалять пользователей '''без перезапуска сервера'''.

=== Каскадная цепочка: зачем два сервера ===

В данном решении используется '''каскад из двух серверов''': Entry Node (ближайший к клиентам сервер-вход) и Exit Node (сервер-выход в интернет). Это архитектурное решение принято намеренно по нескольким причинам:

* '''Снижение риска для клиента:''' клиентские устройства подключаются только к ближайшему серверу. Соединение с соседним узлом менее заметно, чем прямое соединение с зарубежным сервером.
* '''Раздельная аутентификация:''' пароль «клиент → Entry Node» знают только конечные пользователи. Пароль «Entry Node → Exit Node» знают только серверы. Компрометация клиентского пароля не раскрывает пароль соединения между серверами.
* '''Анонимизация выхода:''' Exit Node передаёт трафик через Cloudflare WARP. Конечные сайты видят IP Cloudflare, а не IP ваших серверов.
* '''Параллельные независимые каналы:''' Hysteria2 работает рядом с NaïveProxy и 3x-ui на тех же серверах, не конфликтуя с ними. Падение одного канала не блокирует другие.

----

== Схема конкретного решения ==

=== Компоненты инфраструктуры ===

{| class="wikitable"
|-
! Компонент !! Роль !! Адрес / Домен !! ОС
|-
|| Клиентские устройства || Конечные пользователи || — || iOS, Android, Windows, macOS, Linux
|-
|| OpenWrt роутер || Прозрачный обход для всей домашней сети || — || OpenWrt 24.10 (podkop нативно поддерживает hy2 URI)
|-
|| RU сервер ('''Entry Node''') || Точка входа клиентов || <code>YOUR_RU_SERVER_IP</code> / <code>your-hy2-ru-domain.example.com</code> || Ubuntu 24.04
|-
|| EU сервер ('''Exit Node''') || Точка выхода в интернет || <code>YOUR_EU_SERVER_IP</code> / <code>your-hy2-eu-domain.example.com</code> || Ubuntu 24.04
|-
|| Cloudflare WARP || Финальный выход в интернет || IP Cloudflare || —
|}

=== Полная схема прохождения трафика ===

[[File:hysteria2-chain-traffic-flow.png|center|768x768px|Схема трафика Hysteria2: Клиенты → RU Entry Node → EU Exit Node → WARP → Интернет]]

=== Протоколы на каждом участке цепочки ===

{| class="wikitable"
|-
! Участок !! Протокол !! Шифрование !! Что видит наблюдатель
|-
|| Устройство → Роутер || Обычный TCP/UDP || Нет (локальная сеть) || Локальный трафик
|-
|| Роутер / ПК → RU сервер || QUIC / UDP (Hysteria2) || TLS 1.3 (Let's Encrypt) || HTTPS/HTTP3 трафик к обычному сайту
|-
|| RU клиент → EU сервер || QUIC / UDP (Hysteria2) || TLS 1.3 (Let's Encrypt) || HTTPS/HTTP3 трафик к обычному сайту
|-
|| EU сервер → 3x-ui inbound || SOCKS5 (localhost) || — (только на EU сервере) || Только локально
|-
|| EU 3x-ui → WARP || WireGuard (gVisor TUN) || WireGuard || Зашифрованный WireGuard к Cloudflare
|-
|| WARP → Интернет || Обычный TCP/UDP || — || IP Cloudflare
|}

=== Дополнительные каналы (параллельно Hysteria2) ===

Hysteria2 работает '''независимо''' от NaïveProxy и 3x-ui. Все три канала активны одновременно:

{| class="wikitable"
|-
! Канал !! Протокол !! Маршрут !! Статус
|-
|| 3x-ui каскад (основной) || VLESS / REALITY || Клиенты → RU 3x-ui → EU 3x-ui → Интернет || ✅ Активен
|-
|| NaïveProxy каскад || HTTP/2 naïve || Роутер/ПК → RU Caddy → EU Caddy → WARP || ✅ Активен
|-
|| '''Hysteria2 каскад (этот гайд)''' || '''QUIC/UDP hy2''' || '''Клиенты → RU hy2 → EU hy2 → WARP''' || '''✅ Активен'''
|-
|| MTProto (Telegram) || MTProto || Клиенты Telegram → EU :8443, :2443 || ✅ Активен
|}

----

== Предварительные требования ==

=== Инфраструктура ===

{| class="wikitable"
|-
! Компонент !! Требования
|-
|| EU сервер || Ubuntu 24.04, публичный IP, домен с A-записью → IP сервера
|-
|| RU сервер || Ubuntu 24.04, публичный IP, домен с A-записью → IP сервера
|-
|| 3x-ui на EU сервере || Уже установлен и работает; настроен outbound WARP
|-
|| Docker || Установлен на обоих серверах
|-
|| Порт 2053 UDP || Должен быть свободен на обоих серверах
|-
|| TLS-сертификат || Получается через Caddy (caddy-naive), либо через certbot — описано в разделе ниже
|}

=== DNS-записи (создать заранее, до установки) ===

Let's Encrypt проверяет доступность домена по HTTP (порт 80) перед выдачей сертификата. DNS-записи должны быть созданы и распространены (propagated) до первого запуска Caddy.

{| class="wikitable"
|-
! Запись !! Тип !! Значение !! Примечание
|-
|| <code>your-hy2-ru-domain.example.com</code> || A || IP RU сервера || Используется Hysteria2 сервером на RU
|-
|| <code>your-hy2-eu-domain.example.com</code> || A || IP EU сервера || Используется Hysteria2 сервером на EU
|}

'''Примечание:''' если NaïveProxy (Caddy) уже настроен на тех же серверах с теми же доменами, отдельные DNS-записи для Hysteria2 не нужны — используется тот же домен и тот же сертификат.

=== Используемые заглушки ===

В данном руководстве применяются следующие заглушки. Замени их реальными значениями перед использованием:

{| class="wikitable"
|-
! Заглушка !! Описание
|-
|| <code>YOUR_RU_SERVER_IP</code> || Публичный IP RU сервера
|-
|| <code>YOUR_EU_SERVER_IP</code> || Публичный IP EU сервера
|-
|| <code>your-hy2-ru-domain.example.com</code> || Домен для RU сервера (для TLS-сертификата)
|-
|| <code>your-hy2-eu-domain.example.com</code> || Домен для EU сервера (для TLS-сертификата)
|-
|| <code>YOUR_EMAIL@example.com</code> || Email для Let's Encrypt (уведомления об истечении сертификата)
|-
|| <code>EU_HY2_PASSWORD</code> || Пароль соединения RU клиент → EU сервер (генерируется один раз)
|}

'''Для генерации пароля EU_HY2_PASSWORD используй:'''
<syntaxhighlight lang="bash">
openssl rand -base64 18
</syntaxhighlight>
Сохрани результат — он понадобится в конфигах обоих серверов.

----

== Часть 1: EU сервер (Exit Node) ==

Цель: развернуть Hysteria2 сервер в Docker, который принимает соединения от RU клиента и перенаправляет трафик через 3x-ui → Cloudflare WARP.

'''Все команды в этом разделе выполняются на EU сервере под root.'''

=== 1.1 Установка Docker ===

Если Docker уже установлен (проверить: <code>docker --version</code>) — пропусти этот шаг.

<syntaxhighlight lang="bash">
# Обновить пакеты
apt-get update && apt-get upgrade -y

# Установить зависимости
apt-get install -y ca-certificates curl gnupg lsb-release

# Добавить GPG-ключ Docker
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

# Добавить репозиторий Docker
echo "deb [arch=$(dpkg --print-architecture) \
signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
> /etc/apt/sources.list.d/docker.list

# Установить Docker Engine
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Включить автозапуск
systemctl enable docker
systemctl start docker

# Проверить
docker --version
docker compose version
</syntaxhighlight>

Ожидаемый вывод:
<pre>
Docker version 27.x.x, build ...
Docker Compose version v2.x.x
</pre>

=== 1.2 Настройка 3x-ui: создание inbound hy2-out → WARP ===

Hysteria2 Exit Node направляет трафик через 3x-ui SOCKS5 inbound, который в свою очередь маршрутизирует его в Cloudflare WARP. Этот шаг выполняется в веб-интерфейсе 3x-ui '''до''' запуска Hysteria2.

'''Условие:''' в 3x-ui должен быть настроен outbound WARP (WireGuard/gVisor).

==== 1.2.1 Создать новый inbound в 3x-ui ====

В веб-интерфейсе 3x-ui (EU сервер) перейди в '''Inbounds → Add Inbound''' и заполни следующие поля:

{| class="wikitable"
|-
! Параметр !! Значение !! Пояснение
|-
|| Примечание (Remark) || <code>hy2-out</code> || Произвольное имя для идентификации в правилах маршрутизации
|-
|| Протокол || <code>mixed</code> || Поддерживает SOCKS5 и HTTP одновременно
|-
|| Listen IP || <code>127.0.0.1</code> || Только localhost — недоступен извне
|-
|| Порт || <code>24364</code> || Должен быть свободен; проверить: <code>ss -tlnp | grep 24364</code>
|-
|| Аутентификация || Выключена || Hysteria2 сам отвечает за авторизацию клиентов
|-
|| UDP || Включён || Требуется для DNS-запросов через туннель
|}

Нажми '''Save''' — inbound немедленно активируется.

==== 1.2.2 Создать правило маршрутизации ====

В 3x-ui перейди в '''Routing → Add Rule''' (или Settings → Routing Rules):

{| class="wikitable"
|-
! Параметр !! Значение
|-
|| Inbound Tag || <code>hy2-out</code> (тег созданного выше inbound)
|-
|| Outbound Tag || <code>warp</code> (или название твоего WARP outbound в 3x-ui)
|}

Сохрани и перезапусти Xray внутри 3x-ui.

==== 1.2.3 Проверить, что порт 24364 слушает ====

<syntaxhighlight lang="bash">
ss -tlnp | grep 24364
</syntaxhighlight>

Ожидаемый вывод:
<pre>
LISTEN 0 128 127.0.0.1:24364 0.0.0.0:* users:(("xray",...))
</pre>

=== 1.3 TLS-сертификат для Hysteria2 ===

Hysteria2 требует действующий TLS-сертификат (самоподписанный не рекомендуется — клиентам потребуется флаг <code>insecure: true</code>). В нашей схеме используется '''Let's Encrypt сертификат''', получаемый и автоматически обновляемый через Caddy (caddy-naive стек).

Caddy хранит сертификаты в именованном Docker volume <code>caddy-naive_caddy_data</code>, и Hysteria2 подключает их через bind mount (read-only) — никаких лишних сервисов, никакого дублирования.

==== Вариант А: Caddy (caddy-naive) уже установлен — рекомендуется ====

Если NaïveProxy (caddy-naive) уже настроен и работает, сертификат уже получен. Проверь:

<syntaxhighlight lang="bash">
# Найти путь к сертификату в Docker volume
DOMAIN="your-hy2-eu-domain.example.com"
CERT_DIR="/var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/${DOMAIN}"

ls -la "${CERT_DIR}/"
</syntaxhighlight>

Ожидаемый вывод — два файла:
<pre>
your-hy2-eu-domain.example.com.crt
your-hy2-eu-domain.example.com.key
</pre>

Если файлы есть — переходи к разделу '''1.4'''. Если volume или папка не существуют — сначала установи caddy-naive (NaïveProxy) или воспользуйся Вариантом Б.

==== Вариант Б: получить сертификат через certbot (если Caddy не установлен) ====

Этот вариант используется, если caddy-naive '''не установлен''' и на серверах нет другого HTTP-сервера на портах 80/443.

<syntaxhighlight lang="bash">
# Установить certbot
apt-get install -y certbot

# Получить сертификат (standalone — Certbot запустит временный HTTP-сервер на :80)
certbot certonly --standalone \
-d your-hy2-eu-domain.example.com \
--email YOUR_EMAIL@example.com \
--agree-tos --non-interactive

# Проверить
ls /etc/letsencrypt/live/your-hy2-eu-domain.example.com/
</syntaxhighlight>

Сертификаты будут по пути <code>/etc/letsencrypt/live/your-hy2-eu-domain.example.com/</code>. В этом случае в <code>docker-compose.yml</code> (раздел 1.6) замени volume на:
<syntaxhighlight lang="yaml">
- /etc/letsencrypt/live/your-hy2-eu-domain.example.com:/etc/hysteria/certs:ro
- /etc/letsencrypt/archive/your-hy2-eu-domain.example.com:/etc/letsencrypt/archive/your-hy2-eu-domain.example.com:ro
</syntaxhighlight>

И в <code>server.yaml</code> пути к файлам:
<syntaxhighlight lang="yaml">
tls:
cert: /etc/hysteria/certs/fullchain.pem
key: /etc/hysteria/certs/privkey.pem
</syntaxhighlight>

=== 1.4 Создание структуры проекта ===

<syntaxhighlight lang="bash">
mkdir -p /opt/hysteria-eu
cd /opt/hysteria-eu
</syntaxhighlight>

Итоговая структура:
<pre>
/opt/hysteria-eu/
├── docker-compose.yml
└── server.yaml
</pre>

=== 1.5 Конфигурация сервера: server.yaml ===

Создай файл конфигурации. Замени <code>EU_HY2_PASSWORD</code> сгенерированным паролем:

<syntaxhighlight lang="bash">
cat > /opt/hysteria-eu/server.yaml << 'EOF'
listen: :2053

tls:
cert: /etc/hysteria/certs/your-hy2-eu-domain.example.com.crt
key: /etc/hysteria/certs/your-hy2-eu-domain.example.com.key

auth:
type: password
password: EU_HY2_PASSWORD

ignoreClientBandwidth: true

masquerade:
type: proxy
proxy:
url: https://news.ycombinator.com/
rewriteHost: true

outbounds:
- name: warp
type: socks5
socks5:
addr: 127.0.0.1:24364

acl:
inline:
- "warp(all)"
EOF
</syntaxhighlight>

Описание ключевых параметров:

{| class="wikitable"
|-
! Параметр !! Значение !! Пояснение
|-
|| <code>listen: :2053</code> || UDP порт 2053 || Hysteria2 слушает на всех интерфейсах
|-
|| <code>tls.cert / tls.key</code> || Пути к сертификату || Берутся из caddy-naive Docker volume (bind mount)
|-
|| <code>auth.type: password</code> || Одиночный пароль || Для соединения RU клиент → EU сервер (клиентские устройства этот пароль не знают)
|-
|| <code>ignoreClientBandwidth: true</code> || Игнорировать лимит клиента || Серверная сторона управляет congestion control самостоятельно
|-
|| <code>masquerade.type: proxy</code> || Проксировать реальный сайт || Неавторизованные запросы получают реальный контент ycombinator.com — сервер выглядит как обычный HTTPS-сайт
|-
|| <code>outbounds.warp</code> || SOCKS5 на 127.0.0.1:24364 || Исходящий трафик → 3x-ui inbound "hy2-out" → WARP
|-
|| <code>acl: warp(all)</code> || Направить весь трафик в warp || Синтаксис: имя outbound в скобках, адрес/маска после
|}

=== 1.6 Конфигурация Docker Compose: docker-compose.yml ===

<syntaxhighlight lang="bash">
cat > /opt/hysteria-eu/docker-compose.yml << 'EOF'
services:
hysteria-eu:
image: tobyxdd/hysteria:latest
container_name: hysteria-eu
restart: unless-stopped
network_mode: host
command: server --config /etc/hysteria/server.yaml
volumes:
- ./server.yaml:/etc/hysteria/server.yaml:ro
- /var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/your-hy2-eu-domain.example.com:/etc/hysteria/certs:ro
EOF
</syntaxhighlight>

Важные моменты:
* <code>network_mode: host</code> — обязателен, чтобы контейнер видел <code>127.0.0.1:24364</code> (3x-ui inbound).
* <code>:ro</code> — сертификаты подключены только для чтения, Hysteria2 их не изменяет.
* Путь к сертификату — bind mount из Docker volume caddy-naive. Если используется certbot (Вариант Б) — замени путь согласно инструкции раздела 1.3.

=== 1.7 Первый запуск ===

<syntaxhighlight lang="bash">
cd /opt/hysteria-eu

# Скачать образ и запустить
docker compose pull
docker compose up -d

# Подождать 3 секунды и проверить логи
sleep 3 && docker compose logs
</syntaxhighlight>

Ожидаемый вывод в логах:
<pre>
INFO server mode
INFO server up and running {"listen": ":2053"}
</pre>

Если в логах ошибка — см. раздел «Диагностика проблем» (Часть 5).

=== 1.8 Проверка: порт и соединение ===

<syntaxhighlight lang="bash">
# Проверить, что Hysteria2 слушает на UDP :2053
ss -ulnp | grep ':2053'
</syntaxhighlight>

Ожидаемый вывод:
<pre>
UNCONN 0 0 0.0.0.0:2053 0.0.0.0:* users:(("hysteria",...))
</pre>

<syntaxhighlight lang="bash">
# Статус контейнера
docker compose ps
</syntaxhighlight>

<pre>
NAME IMAGE STATUS
hysteria-eu tobyxdd/hysteria:latest Up X minutes
</pre>

----

== Часть 2: RU сервер (Entry Node) ==

Цель: развернуть два Docker-контейнера:
* <code>hysteria-ru-server</code> — принимает соединения от клиентов, аутентифицирует по <code>users.txt</code>.
* <code>hysteria-ru-client</code> — подключается к EU серверу, слушает SOCKS5 на <code>127.0.0.1:10810</code>.

Между ними: hysteria-ru-server направляет трафик через SOCKS5 → hysteria-ru-client → EU.

'''Все команды в этом разделе выполняются на RU сервере под root.'''

=== 2.1 Установка Docker ===

Аналогично EU серверу (раздел 1.1). Если Docker уже установлен — пропусти.

<syntaxhighlight lang="bash">
apt-get update && apt-get upgrade -y
apt-get install -y ca-certificates curl gnupg lsb-release

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) \
signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
> /etc/apt/sources.list.d/docker.list

apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
systemctl enable docker && systemctl start docker

docker --version && docker compose version
</syntaxhighlight>

=== 2.2 TLS-сертификат для RU сервера ===

Аналогично EU серверу. На RU сервере также используется сертификат от Caddy (caddy-naive), если NaïveProxy настроен.

==== Вариант А: через Caddy (caddy-naive) — рекомендуется ====

<syntaxhighlight lang="bash">
DOMAIN="your-hy2-ru-domain.example.com"
CERT_DIR="/var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/${DOMAIN}"

ls -la "${CERT_DIR}/"
</syntaxhighlight>

Если файлы <code>.crt</code> и <code>.key</code> присутствуют — всё готово, переходи к разделу 2.3.

==== Вариант Б: через certbot (если Caddy не установлен) ====

<syntaxhighlight lang="bash">
apt-get install -y certbot

certbot certonly --standalone \
-d your-hy2-ru-domain.example.com \
--email YOUR_EMAIL@example.com \
--agree-tos --non-interactive

ls /etc/letsencrypt/live/your-hy2-ru-domain.example.com/
</syntaxhighlight>

=== 2.3 Создание структуры проекта ===

<syntaxhighlight lang="bash">
mkdir -p /opt/hysteria-ru/users
cd /opt/hysteria-ru
</syntaxhighlight>

Итоговая структура:
<pre>
/opt/hysteria-ru/
├── docker-compose.yml
├── server.yaml
├── client.yaml
└── users/
├── users.txt ← список пользователей (username password)
└── check-auth.sh ← скрипт авторизации, вызывается при каждом подключении
</pre>

=== 2.4 Система аутентификации пользователей ===

RU сервер использует <code>auth.type: command</code> — при каждом входящем подключении Hysteria2 вызывает внешний скрипт и передаёт ему пароль клиента в аргументах. Скрипт ищет пароль в файле <code>users.txt</code>: если совпадение найдено — выводит имя пользователя (оно попадает в логи) и завершается с кодом 0. Если нет — завершается с кодом 1 (отказ в подключении).

Преимущество этого подхода: <code>users.txt</code> можно редактировать в любой момент без перезапуска контейнера. Изменения применяются немедленно.

==== 2.4.1 Файл пользователей: users/users.txt ====

Формат: одна строка на пользователя — имя пользователя и пароль, разделённые пробелом.

<syntaxhighlight lang="bash">
# Сгенерировать первого пользователя (пример: "default")
PASS=$(openssl rand -base64 18)
echo "default $PASS" > /opt/hysteria-ru/users/users.txt
echo "Пароль пользователя default: $PASS"
</syntaxhighlight>

Формат файла:
<pre>
username1 пароль1
username2 пароль2
</pre>

'''Важно:''' не используй пробелы внутри пароля — пароль считывается по второму полю строки.

==== 2.4.2 Скрипт авторизации: users/check-auth.sh ====

Hysteria2 вызывает скрипт с тремя аргументами: <code>$1</code> — адрес клиента, <code>$2</code> — пароль, <code>$3</code> — tx bandwidth.

<syntaxhighlight lang="bash">
cat > /opt/hysteria-ru/users/check-auth.sh << 'EOF'
#!/bin/sh
AUTH_PAYLOAD="$2"
USERS_FILE="/etc/hysteria/users/users.txt"

USERNAME=$(awk -v pwd="$AUTH_PAYLOAD" '$2 == pwd {print $1; exit}' "$USERS_FILE" 2>/dev/null)

if [ -n "$USERNAME" ]; then
echo "$USERNAME"
exit 0
fi
exit 1
EOF

chmod +x /opt/hysteria-ru/users/check-auth.sh
</syntaxhighlight>

Почему используется <code>awk</code>, а не <code>grep</code>:
* Hysteria2 использует Docker-образ на базе Alpine Linux с BusyBox.
* BusyBox <code>grep</code> не поддерживает флаг <code>-P</code> (Perl-совместимые регулярки).
* <code>awk</code> доступен во всех Unix/Linux окружениях и работает стабильно.

=== 2.5 Конфигурация сервера: server.yaml ===

<syntaxhighlight lang="bash">
cat > /opt/hysteria-ru/server.yaml << 'EOF'
listen: :2053

tls:
cert: /etc/hysteria/certs/your-hy2-ru-domain.example.com.crt
key: /etc/hysteria/certs/your-hy2-ru-domain.example.com.key

auth:
type: command
command: /etc/hysteria/users/check-auth.sh

ignoreClientBandwidth: true

masquerade:
type: proxy
proxy:
url: https://news.ycombinator.com/
rewriteHost: true

outbounds:
- name: chain
type: socks5
socks5:
addr: 127.0.0.1:10810

acl:
inline:
- "chain(all)"
EOF
</syntaxhighlight>

Описание ключевых параметров:

{| class="wikitable"
|-
! Параметр !! Значение !! Пояснение
|-
|| <code>auth.type: command</code> || Внешний скрипт || При каждом подключении вызывается <code>check-auth.sh</code>
|-
|| <code>auth.command</code> || Путь внутри контейнера || Скрипт смонтирован через volume: <code>./users:/etc/hysteria/users</code>
|-
|| <code>outbounds.chain</code> || SOCKS5 на 127.0.0.1:10810 || Трафик → hysteria-ru-client → EU
|-
|| <code>acl: chain(all)</code> || Весь трафик через chain || Синтаксис: имя outbound, затем адрес в скобках
|}

=== 2.6 Конфигурация клиента: client.yaml ===

RU клиент подключается к EU серверу и поднимает SOCKS5 на <code>127.0.0.1:10810</code>.

<syntaxhighlight lang="bash">
cat > /opt/hysteria-ru/client.yaml << 'EOF'
server: your-hy2-eu-domain.example.com:2053

auth: EU_HY2_PASSWORD

socks5:
listen: 127.0.0.1:10810
EOF
</syntaxhighlight>

Замени <code>EU_HY2_PASSWORD</code> на тот же пароль, который указан в <code>server.yaml</code> EU сервера.

=== 2.7 Конфигурация Docker Compose: docker-compose.yml ===

<syntaxhighlight lang="bash">
cat > /opt/hysteria-ru/docker-compose.yml << 'EOF'
services:
hysteria-ru-server:
image: tobyxdd/hysteria:latest
container_name: hysteria-ru-server
restart: unless-stopped
network_mode: host
command: server --config /etc/hysteria/server.yaml
volumes:
- ./server.yaml:/etc/hysteria/server.yaml:ro
- ./users:/etc/hysteria/users:ro
- /var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/your-hy2-ru-domain.example.com:/etc/hysteria/certs:ro

hysteria-ru-client:
image: tobyxdd/hysteria:latest
container_name: hysteria-ru-client
restart: unless-stopped
network_mode: host
command: client --config /etc/hysteria/client.yaml
volumes:
- ./client.yaml:/etc/hysteria/client.yaml:ro
EOF
</syntaxhighlight>

'''Критически важные моменты:'''
* Директория <code>./users</code> монтируется в оба контейнера... нет, только в <code>hysteria-ru-server</code>. Клиентский контейнер видит только свой <code>client.yaml</code>.
* При изменении <code>docker-compose.yml</code> (добавлении volume) нужен пересоздать контейнер: <code>docker compose down && docker compose up -d</code>. Простой <code>restart</code> не применяет изменения volumes.

=== 2.8 Первый запуск ===

<syntaxhighlight lang="bash">
cd /opt/hysteria-ru

# Скачать образ
docker compose pull

# Запустить оба контейнера
docker compose up -d

# Подождать и проверить логи
sleep 3 && docker compose logs
</syntaxhighlight>

Ожидаемый вывод:
<pre>
hysteria-ru-server | INFO server mode
hysteria-ru-server | INFO server up and running {"listen": ":2053"}
hysteria-ru-client | INFO client mode
hysteria-ru-client | INFO connected to server {"udpEnabled": true, "count": 1}
hysteria-ru-client | INFO SOCKS5 server listening {"addr": "127.0.0.1:10810"}
</pre>

=== 2.9 Проверка цепочки с RU сервера ===

Тест: запустить временный Hysteria2 клиент на RU сервере и проверить, что трафик выходит через WARP (IP Cloudflare):

<syntaxhighlight lang="bash">
# Создать временный конфиг тест-клиента
cat > /tmp/hy2-test.yaml << EOF
server: 127.0.0.1:2053
auth: $(awk 'NR==1{print $2}' /opt/hysteria-ru/users/users.txt)
tls:
insecure: true
sni: your-hy2-ru-domain.example.com
socks5:
listen: 127.0.0.1:11080
EOF

# Запустить тест-клиент
docker run -d --name hy2-test --network host \
-v /tmp/hy2-test.yaml:/etc/hysteria/client.yaml:ro \
tobyxdd/hysteria:latest client --config /etc/hysteria/client.yaml

# Ждать 3 секунды
sleep 3

# Проверить IP выхода — должен быть Cloudflare WARP IP
echo "IP через цепочку:"
curl -s --max-time 15 -x socks5h://127.0.0.1:11080 https://ifconfig.me

# Очистить
docker rm -f hy2-test
rm -f /tmp/hy2-test.yaml
</syntaxhighlight>

Если IP вывода принадлежит Cloudflare (начинается с <code>2a09:</code> для IPv6 или относится к диапазонам WARP) — цепочка RU → EU → WARP работает корректно.

'''Примечание:''' параметр <code>insecure: true</code> и <code>sni</code> нужны в тест-клиенте, потому что он подключается по IP (<code>127.0.0.1</code>), а сертификат выдан на домен. Реальные клиенты подключаются по домену и такие параметры не требуются.

----

== Часть 3: Управление пользователями (hy2-users.sh) ==

=== 3.1 Что это и зачем ===

Для управления пользователями Hysteria2 на RU сервере предназначен скрипт <code>hy2-users.sh</code>. Он предоставляет интерактивное меню с набором операций над файлом <code>users.txt</code>.

Скрипт решает следующие задачи:

{| class="wikitable"
|-
! Операция !! Описание
|-
|| Список пользователей || Показывает всех пользователей из users.txt с маскированными паролями
|-
|| Добавить пользователя || Запрашивает имя, автоматически генерирует криптостойкий пароль, сохраняет в users.txt, показывает готовый Hysteria2 URI
|-
|| Удалить пользователя || Интерактивный выбор из списка, удаление строки из users.txt
|-
|| Показать конфиг || Генерирует и показывает Hysteria2 URI для выбранного пользователя
|}

Ключевые особенности:
* '''Нет перезапуска контейнера.''' Hysteria2 с <code>auth.type: command</code> читает файл при каждом подключении — изменения в <code>users.txt</code> применяются мгновенно.
* '''Пароли генерируются автоматически''' через <code>openssl rand</code> — случайные, криптостойкие.
* '''URI формат''' соответствует стандарту Hysteria2 и принимается всеми клиентами: NekoBox, husi, Exclave, podkop.

=== 3.2 Установка скрипта ===

Скрипт хранится в репозитории по пути <code>scripts/hy2-users.sh</code>. Установка на сервер:

<syntaxhighlight lang="bash">
# Скопировать скрипт на сервер
scp scripts/hy2-users.sh root@YOUR_RU_SERVER_IP:/usr/local/bin/hy2-users.sh

# Сделать исполняемым
ssh root@YOUR_RU_SERVER_IP "chmod +x /usr/local/bin/hy2-users.sh"
</syntaxhighlight>

Или выполнить непосредственно на RU сервере (если скрипт уже там):

<syntaxhighlight lang="bash">
chmod +x /usr/local/bin/hy2-users.sh
</syntaxhighlight>

'''Проверка переменных в начале скрипта.''' Открой скрипт и убедись, что следующие переменные указывают на правильные значения:

<syntaxhighlight lang="bash">
head -15 /usr/local/bin/hy2-users.sh
</syntaxhighlight>

Должны быть:
* <code>USERS_FILE="/opt/hysteria-ru/users/users.txt"</code>
* <code>DOMAIN="your-hy2-ru-domain.example.com"</code>
* <code>PORT="2053"</code>

Если домен указан неверно — исправь:
<syntaxhighlight lang="bash">
sed -i 's|DOMAIN=.*|DOMAIN="your-hy2-ru-domain.example.com"|' /usr/local/bin/hy2-users.sh
</syntaxhighlight>

=== 3.3 Использование ===

<syntaxhighlight lang="bash">
sudo bash /usr/local/bin/hy2-users.sh
</syntaxhighlight>

Скрипт показывает меню:
<pre>
┌─────────────────────────────────────────────┐
│ Hysteria2 — управление пользователями RU │
└─────────────────────────────────────────────┘

1. Список пользователей
2. Добавить пользователя
3. Удалить пользователя
4. Показать конфиг клиента

0. Выход

Выбери действие:
</pre>

При добавлении нового пользователя скрипт выводит готовый URI:
<pre>
hysteria2://СГЕНЕРИРОВАННЫЙ_ПАРОЛЬ@your-hy2-ru-domain.example.com:2053
</pre>

Этот URI вставляется напрямую в клиентское приложение (см. Часть 4).

=== 3.4 Исходный код скрипта ===

<div class="mw-collapsible mw-collapsed" style="width:100%">
<div style="font-weight:bold; padding:4px 0;">▶ Показать исходный код hy2-users.sh</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="bash">
# --- ИСХОДНЫЙ КОД СКРИПТА hy2-users.sh ---
# (вставить содержимое файла scripts/hy2-users.sh)
</syntaxhighlight>
</div>
</div>

----

== Часть 4: Настройка клиентов ==

=== 4.1 Формат URI Hysteria2 ===

Hysteria2 использует стандартизированный URI для передачи параметров подключения клиентам:

<pre>
hysteria2://ПАРОЛЬ@ДОМЕН:ПОРТ
</pre>

Пример:
<pre>
hysteria2://aBcDeFgHiJkLmNoPqRsT@your-hy2-ru-domain.example.com:2053
</pre>

URI можно получить через скрипт <code>hy2-users.sh</code> (пункт 4 меню — «Показать конфиг клиента»).

=== 4.2 Мобильные клиенты (iOS / Android) ===

Рекомендуемые приложения с нативной поддержкой Hysteria2:

{| class="wikitable"
|-
! Приложение !! Платформа !! Как импортировать URI
|-
|| NekoBox || Android || Главный экран → + → Add → Hysteria2 → вставить URI
|-
|| husi || Android || Профили → + → Hysteria2 → вставить URI
|-
|| Exclave || iOS || Конфигурации → + → Hysteria2 → вставить URI
|-
|| Shadowrocket || iOS || Главная → + → Тип: Hysteria2 → вставить URI
|}

Все эти приложения принимают URI в формате <code>hysteria2://...</code> напрямую — через кнопку импорта, QR-код или буфер обмена.

=== 4.3 ПК-клиенты (Windows / macOS / Linux) ===

==== Вариант А: официальный бинарь Hysteria2 ====

Скачать бинарь с официального репозитория: https://github.com/apernet/hysteria/releases

Создать файл конфигурации <code>config.yaml</code>:
<syntaxhighlight lang="yaml">
server: your-hy2-ru-domain.example.com:2053

auth: ВАШ_ПАРОЛЬ

socks5:
listen: 127.0.0.1:1080

http:
listen: 127.0.0.1:8080
</syntaxhighlight>

Запустить:
<syntaxhighlight lang="bash">
# Linux / macOS
./hysteria client --config config.yaml

# Windows (PowerShell)
.\hysteria.exe client --config config.yaml
</syntaxhighlight>

После запуска:
* SOCKS5 прокси доступен на <code>127.0.0.1:1080</code>
* HTTP прокси доступен на <code>127.0.0.1:8080</code>

==== Вариант Б: через NekoRay / Hiddify Next (Windows / Linux) ====

Приложения NekoRay и Hiddify Next принимают Hysteria2 URI — импорт через меню или буфер обмена. Автоматически управляют запуском клиентского процесса.

=== 4.4 OpenWrt / podkop ===

podkop (реализация на базе sing-box) нативно поддерживает Hysteria2 URI. Никакой дополнительной установки бинарей не требуется.

В интерфейсе podkop (LuCI → Network → podkop → Outbound):
* Тип: <code>Hysteria2</code>
* URI: <code>hysteria2://ПАРОЛЬ@your-hy2-ru-domain.example.com:2053</code>

Или через UCI:
<syntaxhighlight lang="bash">
uci set podkop.main.proxy='hysteria2://ПАРОЛЬ@your-hy2-ru-domain.example.com:2053'
uci commit podkop
/etc/init.d/podkop restart
</syntaxhighlight>

После сохранения все устройства домашней сети автоматически получают обход без дополнительной настройки.

----

== Часть 5: Проверка всей цепочки ==

=== 5.1 Тест RU сервера: цепочка RU → EU → WARP ===

Выполнить на RU сервере — проверяет, что трафик выходит через WARP:

<syntaxhighlight lang="bash">
# SOCKS5 порт 10810 — это точка выхода RU клиента (= вход в EU сервер → WARP)
curl -s --max-time 20 -x socks5h://127.0.0.1:10810 https://ifconfig.me
echo ""
</syntaxhighlight>

Результат должен быть '''IP Cloudflare WARP''' — например, начинается с <code>2a09:</code> (IPv6) или принадлежит AS13335 (Cloudflare).

Проверить AS:
<syntaxhighlight lang="bash">
IP=$(curl -s --max-time 20 -x socks5h://127.0.0.1:10810 https://ifconfig.me)
curl -s "https://ipinfo.io/${IP}/org"
echo ""
</syntaxhighlight>

Ожидаемый вывод: строка содержит <code>Cloudflare</code>.

=== 5.2 Тест с реального клиента ===

После добавления пользователя через <code>hy2-users.sh</code> и получения URI:

# Вставь URI в клиентское приложение (NekoBox, husi, Shadowrocket).
# Активируй профиль.
# Открой <code>https://ifconfig.me</code> в браузере — должен отображаться IP Cloudflare WARP.
# Открой <code>https://www.whatismybrowser.com/detect/what-is-my-ip-address</code> для проверки отсутствия WebRTC утечки.

=== 5.3 Диагностика проблем ===

==== Проблема: hysteria-eu не запускается — ошибка TLS ====

<syntaxhighlight lang="bash">
docker compose -f /opt/hysteria-eu/docker-compose.yml logs hysteria-eu
</syntaxhighlight>

Возможные причины:
* Путь к сертификату неверен → проверь <code>ls</code> по пути, указанному в volumes.
* Сертификат ещё не был получен Caddy → проверь, что caddy-naive запущен и прошёл ACME-проверку.
* Caddy хранит сертификат под другим именем → выполни <code>find /var/lib/docker/volumes/caddy-naive_caddy_data/_data -name "*.crt"</code>.

==== Проблема: hysteria-ru-server выдаёт auth error ====

<syntaxhighlight lang="bash">
docker compose -f /opt/hysteria-ru/docker-compose.yml logs hysteria-ru-server
</syntaxhighlight>

Проверить вручную (на RU сервере):
<syntaxhighlight lang="bash">
# Проверить, что скрипт находится на месте внутри контейнера
docker exec hysteria-ru-server ls -la /etc/hysteria/users/

# Запустить скрипт вручную с тестовым паролем
docker exec hysteria-ru-server /etc/hysteria/users/check-auth.sh addr ТЕСТОВЫЙ_ПАРОЛЬ 0
echo "Exit code: $?"
</syntaxhighlight>

Если <code>Exit code: 0</code> — скрипт работает. Если <code>1</code> — пароль не найден в <code>users.txt</code>.

==== Проблема: hysteria-ru-client не подключается к EU ====

<syntaxhighlight lang="bash">
docker compose -f /opt/hysteria-ru/docker-compose.yml logs hysteria-ru-client
</syntaxhighlight>

Возможные причины:
* <code>EU_HY2_PASSWORD</code> в <code>client.yaml</code> не совпадает с паролем в EU <code>server.yaml</code>.
* UDP порт 2053 заблокирован на EU сервере (firewall) → проверь <code>ss -ulnp | grep 2053</code> на EU сервере.
* EU сервер ещё не запущен.

==== Проблема: ACL ошибка при запуске ====

<pre>
FATAL failed to load server config: invalid config: acl.inline: invalid syntax at line 1
</pre>

Неверный синтаксис ACL. Правильный формат: <code>"outbound_name(address)"</code>:
* ✅ <code>"warp(all)"</code> — направить всё в outbound "warp"
* ✅ <code>"chain(all)"</code> — направить всё в outbound "chain"
* ❌ <code>"outbound(warp) all"</code> — неверно

----

== Часть 6: Обслуживание ==

=== 6.1 Управление контейнерами ===

<syntaxhighlight lang="bash">
# EU сервер
cd /opt/hysteria-eu
docker compose up -d # запустить
docker compose down # остановить
docker compose restart # перезапустить
docker compose logs -f # следить за логами в реальном времени
docker compose ps # статус

# RU сервер (оба контейнера)
cd /opt/hysteria-ru
docker compose up -d
docker compose down
docker compose restart
docker compose logs -f

# RU сервер (по отдельности)
docker compose restart hysteria-ru-server # только сервер
docker compose restart hysteria-ru-client # только клиент
docker compose logs -f hysteria-ru-server # логи только сервера
docker compose logs -f hysteria-ru-client # логи только клиента
</syntaxhighlight>

=== 6.2 Обновление сертификатов ===

TLS-сертификаты обновляются Caddy автоматически (за 30 дней до истечения). После автообновления Hysteria2 начнёт использовать новый сертификат при следующем перезапуске.

Для принудительного применения нового сертификата:
<syntaxhighlight lang="bash">
# EU сервер
cd /opt/hysteria-eu && docker compose restart

# RU сервер
cd /opt/hysteria-ru && docker compose restart hysteria-ru-server
</syntaxhighlight>

Проверить дату истечения текущего сертификата:
<syntaxhighlight lang="bash">
# EU сервер
DOMAIN="your-hy2-eu-domain.example.com"
CERT="/var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/${DOMAIN}/${DOMAIN}.crt"
openssl x509 -in "${CERT}" -noout -enddate
</syntaxhighlight>

=== 6.3 Обновление Docker-образа ===

Hysteria2 активно развивается. Для обновления до последней версии:

<syntaxhighlight lang="bash">
# EU сервер
cd /opt/hysteria-eu
docker compose pull # скачать новый образ
docker compose up -d # перезапустить с новым образом
docker compose logs --tail=5 # проверить старт

# RU сервер
cd /opt/hysteria-ru
docker compose pull
docker compose up -d
docker compose logs --tail=5
</syntaxhighlight>

Старые неиспользуемые образы можно удалить:
<syntaxhighlight lang="bash">
docker image prune -f
</syntaxhighlight>

=== 6.4 Мониторинг логов ===

Hysteria2 пишет структурированные JSON-логи. Полезные паттерны для мониторинга:

<syntaxhighlight lang="bash">
# Смотреть все подключения на RU сервере
docker logs hysteria-ru-server 2>&1 | grep -E "connected|disconnected|auth"

# Смотреть ошибки
docker logs hysteria-ru-server 2>&1 | grep -i "error\|fatal\|warn"

# Считать количество уникальных пользователей (поле "id")
docker logs hysteria-ru-server 2>&1 | grep '"id"' | grep -oP '"id": "\K[^"]+' | sort -u

# Следить за логами EU сервера в реальном времени
docker logs -f hysteria-eu 2>&1
</syntaxhighlight>

Пример нормального лога RU сервера при входящем подключении:
<pre>
INFO client connected {"addr": "CLIENT_IP:PORT", "id": "username"}
INFO TCP request {"addr": "CLIENT_IP:PORT", "id": "username", "reqAddr": "example.com:443"}
INFO client disconnected {"addr": "CLIENT_IP:PORT", "id": "username", "error": "..."}
</pre>

Поле <code>"id"</code> — это имя пользователя, возвращённое скриптом <code>check-auth.sh</code>. Это позволяет отслеживать активность конкретных пользователей в логах без хранения паролей.

Файл:Hysteria2-chain-traffic-flow.png

2026-04-26T10:12:03Z

Владимир: Владимир загрузил новую версию Файл:Hysteria2-chain-traffic-flow.png

Hysteria 2 каскад

2026-04-26T10:01:45Z

Владимир:

= Hysteria2: установка каскадной цепочки Entry Node → Exit Node → WARP =

== Что такое Hysteria2 и зачем он нужен ==

=== Проблема: ограничения традиционных прокси-протоколов ===

Современные системы глубокой инспекции пакетов (DPI — Deep Packet Inspection), применяемые интернет-провайдерами и регуляторами по всему миру, умеют анализировать не только адреса назначения, но и '''характер самого трафика'''. Даже зашифрованное соединение можно идентифицировать — по поведению, по паузам между пакетами, по размерам передаваемых блоков данных, по TLS-fingerprint.

Большинство прокси-протоколов работают поверх '''TCP'''. Это означает:
* Все потери пакетов обрабатываются дважды — сначала на уровне транспорта, затем внутри туннеля (head-of-line blocking).
* При нестабильном канале (мобильная сеть, спутник, VPN на слабом железе) скорость резко падает.
* TCP-fingerprint легче распознаётся и блокируется.

Hysteria2 решает эту проблему фундаментально иначе: он работает поверх '''QUIC''' — транспортного протокола на базе UDP, разработанного в Google и стандартизированного в RFC 9000.

=== Решение: QUIC/UDP с маскировкой под HTTPS ===

Hysteria2 строит зашифрованный туннель поверх UDP, используя QUIC:
* '''Нет head-of-line blocking:''' потеря одного пакета не блокирует остальные потоки.
* '''Быстрое восстановление соединения:''' QUIC переподключается за 0-RTT (без дополнительного round-trip).
* '''Маскировка под HTTPS:''' снаружи трафик Hysteria2 выглядит как обычный QUIC/HTTP3 браузерный трафик — сервер «притворяется» обычным HTTPS-сайтом и возвращает реальный веб-контент при неавторизованных запросах.
* '''Congestion control:''' поддерживает несколько алгоритмов управления перегрузкой, включая BBR.

{| class="wikitable"
|-
! Протокол !! Транспорт !! Как выглядит для DPI !! Устойчивость к блокировке !! Скорость при потерях
|-
|| Обычный VPN (WireGuard, OpenVPN) || UDP / TCP || Характерный шаблон || Низкая — fingerprint легко детектируется || Высокая (WG) / Низкая (OpenVPN)
|-
|| Shadowsocks || TCP || Случайный зашифрованный поток || Средняя — выявляется по энтропии || Средняя
|-
|| VLESS + REALITY || TCP (TLS) || TLS с реальным сертификатом стороннего сайта || Высокая || Средняя
|-
|| NaïveProxy || TCP (HTTP/2 TLS) || Неотличим от Chrome HTTPS || Очень высокая || Средняя (TCP Head-of-Line)
|-
|| '''Hysteria2''' || '''UDP (QUIC/TLS)''' || '''QUIC/HTTP3, маскировка под HTTPS''' || '''Очень высокая''' || '''Высокая — устойчив к потерям'''
|}

=== Как работает Hysteria2 технически ===

Hysteria2 использует протокол QUIC в качестве транспорта:

# Клиент устанавливает QUIC-соединение с сервером — это TLS 1.3 поверх UDP.
# Внутри QUIC-соединения открываются независимые потоки (streams) для каждого проксируемого соединения.
# Сервер обрабатывает входящий трафик: авторизует клиента (по паролю или через внешний скрипт), затем перенаправляет трафик через указанный outbound.
# Если к серверу обращаются без правильного пароля — сервер ведёт себя как обычный HTTPS-сайт ('''masquerade''') и возвращает реальный контент с заданного URL.

Особенности аутентификации в данной схеме:
* '''EU сервер:''' использует одиночный пароль — только для входящих соединений от RU клиента (не клиентских устройств).
* '''RU сервер:''' использует '''command-аутентификацию''' — при каждом подключении вызывается внешний bash-скрипт, который проверяет пароль по файлу <code>users.txt</code>. Это позволяет добавлять и удалять пользователей '''без перезапуска сервера'''.

=== Каскадная цепочка: зачем два сервера ===

В данном решении используется '''каскад из двух серверов''': Entry Node (ближайший к клиентам сервер-вход) и Exit Node (сервер-выход в интернет). Это архитектурное решение принято намеренно по нескольким причинам:

* '''Снижение риска для клиента:''' клиентские устройства подключаются только к ближайшему серверу. Соединение с соседним узлом менее заметно, чем прямое соединение с зарубежным сервером.
* '''Раздельная аутентификация:''' пароль «клиент → Entry Node» знают только конечные пользователи. Пароль «Entry Node → Exit Node» знают только серверы. Компрометация клиентского пароля не раскрывает пароль соединения между серверами.
* '''Анонимизация выхода:''' Exit Node передаёт трафик через Cloudflare WARP. Конечные сайты видят IP Cloudflare, а не IP ваших серверов.
* '''Параллельные независимые каналы:''' Hysteria2 работает рядом с NaïveProxy и 3x-ui на тех же серверах, не конфликтуя с ними. Падение одного канала не блокирует другие.

----

== Схема конкретного решения ==

=== Компоненты инфраструктуры ===

{| class="wikitable"
|-
! Компонент !! Роль !! Адрес / Домен !! ОС
|-
|| Клиентские устройства || Конечные пользователи || — || iOS, Android, Windows, macOS, Linux
|-
|| OpenWrt роутер || Прозрачный обход для всей домашней сети || — || OpenWrt 24.10 (podkop нативно поддерживает hy2 URI)
|-
|| RU сервер ('''Entry Node''') || Точка входа клиентов || <code>YOUR_RU_SERVER_IP</code> / <code>your-hy2-ru-domain.example.com</code> || Ubuntu 24.04
|-
|| EU сервер ('''Exit Node''') || Точка выхода в интернет || <code>YOUR_EU_SERVER_IP</code> / <code>your-hy2-eu-domain.example.com</code> || Ubuntu 24.04
|-
|| Cloudflare WARP || Финальный выход в интернет || IP Cloudflare || —
|}

=== Полная схема прохождения трафика ===

[[File:hysteria2-chain-traffic-flow.png|center|900px|Схема трафика Hysteria2: Клиенты → RU Entry Node → EU Exit Node → WARP → Интернет]]

=== Протоколы на каждом участке цепочки ===

{| class="wikitable"
|-
! Участок !! Протокол !! Шифрование !! Что видит наблюдатель
|-
|| Устройство → Роутер || Обычный TCP/UDP || Нет (локальная сеть) || Локальный трафик
|-
|| Роутер / ПК → RU сервер || QUIC / UDP (Hysteria2) || TLS 1.3 (Let's Encrypt) || HTTPS/HTTP3 трафик к обычному сайту
|-
|| RU клиент → EU сервер || QUIC / UDP (Hysteria2) || TLS 1.3 (Let's Encrypt) || HTTPS/HTTP3 трафик к обычному сайту
|-
|| EU сервер → 3x-ui inbound || SOCKS5 (localhost) || — (только на EU сервере) || Только локально
|-
|| EU 3x-ui → WARP || WireGuard (gVisor TUN) || WireGuard || Зашифрованный WireGuard к Cloudflare
|-
|| WARP → Интернет || Обычный TCP/UDP || — || IP Cloudflare
|}

=== Дополнительные каналы (параллельно Hysteria2) ===

Hysteria2 работает '''независимо''' от NaïveProxy и 3x-ui. Все три канала активны одновременно:

{| class="wikitable"
|-
! Канал !! Протокол !! Маршрут !! Статус
|-
|| 3x-ui каскад (основной) || VLESS / REALITY || Клиенты → RU 3x-ui → EU 3x-ui → Интернет || ✅ Активен
|-
|| NaïveProxy каскад || HTTP/2 naïve || Роутер/ПК → RU Caddy → EU Caddy → WARP || ✅ Активен
|-
|| '''Hysteria2 каскад (этот гайд)''' || '''QUIC/UDP hy2''' || '''Клиенты → RU hy2 → EU hy2 → WARP''' || '''✅ Активен'''
|-
|| MTProto (Telegram) || MTProto || Клиенты Telegram → EU :8443, :2443 || ✅ Активен
|}

----

== Предварительные требования ==

=== Инфраструктура ===

{| class="wikitable"
|-
! Компонент !! Требования
|-
|| EU сервер || Ubuntu 24.04, публичный IP, домен с A-записью → IP сервера
|-
|| RU сервер || Ubuntu 24.04, публичный IP, домен с A-записью → IP сервера
|-
|| 3x-ui на EU сервере || Уже установлен и работает; настроен outbound WARP
|-
|| Docker || Установлен на обоих серверах
|-
|| Порт 2053 UDP || Должен быть свободен на обоих серверах
|-
|| TLS-сертификат || Получается через Caddy (caddy-naive), либо через certbot — описано в разделе ниже
|}

=== DNS-записи (создать заранее, до установки) ===

Let's Encrypt проверяет доступность домена по HTTP (порт 80) перед выдачей сертификата. DNS-записи должны быть созданы и распространены (propagated) до первого запуска Caddy.

{| class="wikitable"
|-
! Запись !! Тип !! Значение !! Примечание
|-
|| <code>your-hy2-ru-domain.example.com</code> || A || IP RU сервера || Используется Hysteria2 сервером на RU
|-
|| <code>your-hy2-eu-domain.example.com</code> || A || IP EU сервера || Используется Hysteria2 сервером на EU
|}

'''Примечание:''' если NaïveProxy (Caddy) уже настроен на тех же серверах с теми же доменами, отдельные DNS-записи для Hysteria2 не нужны — используется тот же домен и тот же сертификат.

=== Используемые заглушки ===

В данном руководстве применяются следующие заглушки. Замени их реальными значениями перед использованием:

{| class="wikitable"
|-
! Заглушка !! Описание
|-
|| <code>YOUR_RU_SERVER_IP</code> || Публичный IP RU сервера
|-
|| <code>YOUR_EU_SERVER_IP</code> || Публичный IP EU сервера
|-
|| <code>your-hy2-ru-domain.example.com</code> || Домен для RU сервера (для TLS-сертификата)
|-
|| <code>your-hy2-eu-domain.example.com</code> || Домен для EU сервера (для TLS-сертификата)
|-
|| <code>YOUR_EMAIL@example.com</code> || Email для Let's Encrypt (уведомления об истечении сертификата)
|-
|| <code>EU_HY2_PASSWORD</code> || Пароль соединения RU клиент → EU сервер (генерируется один раз)
|}

'''Для генерации пароля EU_HY2_PASSWORD используй:'''
<syntaxhighlight lang="bash">
openssl rand -base64 18
</syntaxhighlight>
Сохрани результат — он понадобится в конфигах обоих серверов.

----

== Часть 1: EU сервер (Exit Node) ==

Цель: развернуть Hysteria2 сервер в Docker, который принимает соединения от RU клиента и перенаправляет трафик через 3x-ui → Cloudflare WARP.

'''Все команды в этом разделе выполняются на EU сервере под root.'''

=== 1.1 Установка Docker ===

Если Docker уже установлен (проверить: <code>docker --version</code>) — пропусти этот шаг.

<syntaxhighlight lang="bash">
# Обновить пакеты
apt-get update && apt-get upgrade -y

# Установить зависимости
apt-get install -y ca-certificates curl gnupg lsb-release

# Добавить GPG-ключ Docker
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

# Добавить репозиторий Docker
echo "deb [arch=$(dpkg --print-architecture) \
signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
> /etc/apt/sources.list.d/docker.list

# Установить Docker Engine
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Включить автозапуск
systemctl enable docker
systemctl start docker

# Проверить
docker --version
docker compose version
</syntaxhighlight>

Ожидаемый вывод:
<pre>
Docker version 27.x.x, build ...
Docker Compose version v2.x.x
</pre>

=== 1.2 Настройка 3x-ui: создание inbound hy2-out → WARP ===

Hysteria2 Exit Node направляет трафик через 3x-ui SOCKS5 inbound, который в свою очередь маршрутизирует его в Cloudflare WARP. Этот шаг выполняется в веб-интерфейсе 3x-ui '''до''' запуска Hysteria2.

'''Условие:''' в 3x-ui должен быть настроен outbound WARP (WireGuard/gVisor).

==== 1.2.1 Создать новый inbound в 3x-ui ====

В веб-интерфейсе 3x-ui (EU сервер) перейди в '''Inbounds → Add Inbound''' и заполни следующие поля:

{| class="wikitable"
|-
! Параметр !! Значение !! Пояснение
|-
|| Примечание (Remark) || <code>hy2-out</code> || Произвольное имя для идентификации в правилах маршрутизации
|-
|| Протокол || <code>mixed</code> || Поддерживает SOCKS5 и HTTP одновременно
|-
|| Listen IP || <code>127.0.0.1</code> || Только localhost — недоступен извне
|-
|| Порт || <code>24364</code> || Должен быть свободен; проверить: <code>ss -tlnp | grep 24364</code>
|-
|| Аутентификация || Выключена || Hysteria2 сам отвечает за авторизацию клиентов
|-
|| UDP || Включён || Требуется для DNS-запросов через туннель
|}

Нажми '''Save''' — inbound немедленно активируется.

==== 1.2.2 Создать правило маршрутизации ====

В 3x-ui перейди в '''Routing → Add Rule''' (или Settings → Routing Rules):

{| class="wikitable"
|-
! Параметр !! Значение
|-
|| Inbound Tag || <code>hy2-out</code> (тег созданного выше inbound)
|-
|| Outbound Tag || <code>warp</code> (или название твоего WARP outbound в 3x-ui)
|}

Сохрани и перезапусти Xray внутри 3x-ui.

==== 1.2.3 Проверить, что порт 24364 слушает ====

<syntaxhighlight lang="bash">
ss -tlnp | grep 24364
</syntaxhighlight>

Ожидаемый вывод:
<pre>
LISTEN 0 128 127.0.0.1:24364 0.0.0.0:* users:(("xray",...))
</pre>

=== 1.3 TLS-сертификат для Hysteria2 ===

Hysteria2 требует действующий TLS-сертификат (самоподписанный не рекомендуется — клиентам потребуется флаг <code>insecure: true</code>). В нашей схеме используется '''Let's Encrypt сертификат''', получаемый и автоматически обновляемый через Caddy (caddy-naive стек).

Caddy хранит сертификаты в именованном Docker volume <code>caddy-naive_caddy_data</code>, и Hysteria2 подключает их через bind mount (read-only) — никаких лишних сервисов, никакого дублирования.

==== Вариант А: Caddy (caddy-naive) уже установлен — рекомендуется ====

Если NaïveProxy (caddy-naive) уже настроен и работает, сертификат уже получен. Проверь:

<syntaxhighlight lang="bash">
# Найти путь к сертификату в Docker volume
DOMAIN="your-hy2-eu-domain.example.com"
CERT_DIR="/var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/${DOMAIN}"

ls -la "${CERT_DIR}/"
</syntaxhighlight>

Ожидаемый вывод — два файла:
<pre>
your-hy2-eu-domain.example.com.crt
your-hy2-eu-domain.example.com.key
</pre>

Если файлы есть — переходи к разделу '''1.4'''. Если volume или папка не существуют — сначала установи caddy-naive (NaïveProxy) или воспользуйся Вариантом Б.

==== Вариант Б: получить сертификат через certbot (если Caddy не установлен) ====

Этот вариант используется, если caddy-naive '''не установлен''' и на серверах нет другого HTTP-сервера на портах 80/443.

<syntaxhighlight lang="bash">
# Установить certbot
apt-get install -y certbot

# Получить сертификат (standalone — Certbot запустит временный HTTP-сервер на :80)
certbot certonly --standalone \
-d your-hy2-eu-domain.example.com \
--email YOUR_EMAIL@example.com \
--agree-tos --non-interactive

# Проверить
ls /etc/letsencrypt/live/your-hy2-eu-domain.example.com/
</syntaxhighlight>

Сертификаты будут по пути <code>/etc/letsencrypt/live/your-hy2-eu-domain.example.com/</code>. В этом случае в <code>docker-compose.yml</code> (раздел 1.6) замени volume на:
<syntaxhighlight lang="yaml">
- /etc/letsencrypt/live/your-hy2-eu-domain.example.com:/etc/hysteria/certs:ro
- /etc/letsencrypt/archive/your-hy2-eu-domain.example.com:/etc/letsencrypt/archive/your-hy2-eu-domain.example.com:ro
</syntaxhighlight>

И в <code>server.yaml</code> пути к файлам:
<syntaxhighlight lang="yaml">
tls:
cert: /etc/hysteria/certs/fullchain.pem
key: /etc/hysteria/certs/privkey.pem
</syntaxhighlight>

=== 1.4 Создание структуры проекта ===

<syntaxhighlight lang="bash">
mkdir -p /opt/hysteria-eu
cd /opt/hysteria-eu
</syntaxhighlight>

Итоговая структура:
<pre>
/opt/hysteria-eu/
├── docker-compose.yml
└── server.yaml
</pre>

=== 1.5 Конфигурация сервера: server.yaml ===

Создай файл конфигурации. Замени <code>EU_HY2_PASSWORD</code> сгенерированным паролем:

<syntaxhighlight lang="bash">
cat > /opt/hysteria-eu/server.yaml << 'EOF'
listen: :2053

tls:
cert: /etc/hysteria/certs/your-hy2-eu-domain.example.com.crt
key: /etc/hysteria/certs/your-hy2-eu-domain.example.com.key

auth:
type: password
password: EU_HY2_PASSWORD

ignoreClientBandwidth: true

masquerade:
type: proxy
proxy:
url: https://news.ycombinator.com/
rewriteHost: true

outbounds:
- name: warp
type: socks5
socks5:
addr: 127.0.0.1:24364

acl:
inline:
- "warp(all)"
EOF
</syntaxhighlight>

Описание ключевых параметров:

{| class="wikitable"
|-
! Параметр !! Значение !! Пояснение
|-
|| <code>listen: :2053</code> || UDP порт 2053 || Hysteria2 слушает на всех интерфейсах
|-
|| <code>tls.cert / tls.key</code> || Пути к сертификату || Берутся из caddy-naive Docker volume (bind mount)
|-
|| <code>auth.type: password</code> || Одиночный пароль || Для соединения RU клиент → EU сервер (клиентские устройства этот пароль не знают)
|-
|| <code>ignoreClientBandwidth: true</code> || Игнорировать лимит клиента || Серверная сторона управляет congestion control самостоятельно
|-
|| <code>masquerade.type: proxy</code> || Проксировать реальный сайт || Неавторизованные запросы получают реальный контент ycombinator.com — сервер выглядит как обычный HTTPS-сайт
|-
|| <code>outbounds.warp</code> || SOCKS5 на 127.0.0.1:24364 || Исходящий трафик → 3x-ui inbound "hy2-out" → WARP
|-
|| <code>acl: warp(all)</code> || Направить весь трафик в warp || Синтаксис: имя outbound в скобках, адрес/маска после
|}

=== 1.6 Конфигурация Docker Compose: docker-compose.yml ===

<syntaxhighlight lang="bash">
cat > /opt/hysteria-eu/docker-compose.yml << 'EOF'
services:
hysteria-eu:
image: tobyxdd/hysteria:latest
container_name: hysteria-eu
restart: unless-stopped
network_mode: host
command: server --config /etc/hysteria/server.yaml
volumes:
- ./server.yaml:/etc/hysteria/server.yaml:ro
- /var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/your-hy2-eu-domain.example.com:/etc/hysteria/certs:ro
EOF
</syntaxhighlight>

Важные моменты:
* <code>network_mode: host</code> — обязателен, чтобы контейнер видел <code>127.0.0.1:24364</code> (3x-ui inbound).
* <code>:ro</code> — сертификаты подключены только для чтения, Hysteria2 их не изменяет.
* Путь к сертификату — bind mount из Docker volume caddy-naive. Если используется certbot (Вариант Б) — замени путь согласно инструкции раздела 1.3.

=== 1.7 Первый запуск ===

<syntaxhighlight lang="bash">
cd /opt/hysteria-eu

# Скачать образ и запустить
docker compose pull
docker compose up -d

# Подождать 3 секунды и проверить логи
sleep 3 && docker compose logs
</syntaxhighlight>

Ожидаемый вывод в логах:
<pre>
INFO server mode
INFO server up and running {"listen": ":2053"}
</pre>

Если в логах ошибка — см. раздел «Диагностика проблем» (Часть 5).

=== 1.8 Проверка: порт и соединение ===

<syntaxhighlight lang="bash">
# Проверить, что Hysteria2 слушает на UDP :2053
ss -ulnp | grep ':2053'
</syntaxhighlight>

Ожидаемый вывод:
<pre>
UNCONN 0 0 0.0.0.0:2053 0.0.0.0:* users:(("hysteria",...))
</pre>

<syntaxhighlight lang="bash">
# Статус контейнера
docker compose ps
</syntaxhighlight>

<pre>
NAME IMAGE STATUS
hysteria-eu tobyxdd/hysteria:latest Up X minutes
</pre>

----

== Часть 2: RU сервер (Entry Node) ==

Цель: развернуть два Docker-контейнера:
* <code>hysteria-ru-server</code> — принимает соединения от клиентов, аутентифицирует по <code>users.txt</code>.
* <code>hysteria-ru-client</code> — подключается к EU серверу, слушает SOCKS5 на <code>127.0.0.1:10810</code>.

Между ними: hysteria-ru-server направляет трафик через SOCKS5 → hysteria-ru-client → EU.

'''Все команды в этом разделе выполняются на RU сервере под root.'''

=== 2.1 Установка Docker ===

Аналогично EU серверу (раздел 1.1). Если Docker уже установлен — пропусти.

<syntaxhighlight lang="bash">
apt-get update && apt-get upgrade -y
apt-get install -y ca-certificates curl gnupg lsb-release

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) \
signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
> /etc/apt/sources.list.d/docker.list

apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
systemctl enable docker && systemctl start docker

docker --version && docker compose version
</syntaxhighlight>

=== 2.2 TLS-сертификат для RU сервера ===

Аналогично EU серверу. На RU сервере также используется сертификат от Caddy (caddy-naive), если NaïveProxy настроен.

==== Вариант А: через Caddy (caddy-naive) — рекомендуется ====

<syntaxhighlight lang="bash">
DOMAIN="your-hy2-ru-domain.example.com"
CERT_DIR="/var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/${DOMAIN}"

ls -la "${CERT_DIR}/"
</syntaxhighlight>

Если файлы <code>.crt</code> и <code>.key</code> присутствуют — всё готово, переходи к разделу 2.3.

==== Вариант Б: через certbot (если Caddy не установлен) ====

<syntaxhighlight lang="bash">
apt-get install -y certbot

certbot certonly --standalone \
-d your-hy2-ru-domain.example.com \
--email YOUR_EMAIL@example.com \
--agree-tos --non-interactive

ls /etc/letsencrypt/live/your-hy2-ru-domain.example.com/
</syntaxhighlight>

=== 2.3 Создание структуры проекта ===

<syntaxhighlight lang="bash">
mkdir -p /opt/hysteria-ru/users
cd /opt/hysteria-ru
</syntaxhighlight>

Итоговая структура:
<pre>
/opt/hysteria-ru/
├── docker-compose.yml
├── server.yaml
├── client.yaml
└── users/
├── users.txt ← список пользователей (username password)
└── check-auth.sh ← скрипт авторизации, вызывается при каждом подключении
</pre>

=== 2.4 Система аутентификации пользователей ===

RU сервер использует <code>auth.type: command</code> — при каждом входящем подключении Hysteria2 вызывает внешний скрипт и передаёт ему пароль клиента в аргументах. Скрипт ищет пароль в файле <code>users.txt</code>: если совпадение найдено — выводит имя пользователя (оно попадает в логи) и завершается с кодом 0. Если нет — завершается с кодом 1 (отказ в подключении).

Преимущество этого подхода: <code>users.txt</code> можно редактировать в любой момент без перезапуска контейнера. Изменения применяются немедленно.

==== 2.4.1 Файл пользователей: users/users.txt ====

Формат: одна строка на пользователя — имя пользователя и пароль, разделённые пробелом.

<syntaxhighlight lang="bash">
# Сгенерировать первого пользователя (пример: "default")
PASS=$(openssl rand -base64 18)
echo "default $PASS" > /opt/hysteria-ru/users/users.txt
echo "Пароль пользователя default: $PASS"
</syntaxhighlight>

Формат файла:
<pre>
username1 пароль1
username2 пароль2
</pre>

'''Важно:''' не используй пробелы внутри пароля — пароль считывается по второму полю строки.

==== 2.4.2 Скрипт авторизации: users/check-auth.sh ====

Hysteria2 вызывает скрипт с тремя аргументами: <code>$1</code> — адрес клиента, <code>$2</code> — пароль, <code>$3</code> — tx bandwidth.

<syntaxhighlight lang="bash">
cat > /opt/hysteria-ru/users/check-auth.sh << 'EOF'
#!/bin/sh
AUTH_PAYLOAD="$2"
USERS_FILE="/etc/hysteria/users/users.txt"

USERNAME=$(awk -v pwd="$AUTH_PAYLOAD" '$2 == pwd {print $1; exit}' "$USERS_FILE" 2>/dev/null)

if [ -n "$USERNAME" ]; then
echo "$USERNAME"
exit 0
fi
exit 1
EOF

chmod +x /opt/hysteria-ru/users/check-auth.sh
</syntaxhighlight>

Почему используется <code>awk</code>, а не <code>grep</code>:
* Hysteria2 использует Docker-образ на базе Alpine Linux с BusyBox.
* BusyBox <code>grep</code> не поддерживает флаг <code>-P</code> (Perl-совместимые регулярки).
* <code>awk</code> доступен во всех Unix/Linux окружениях и работает стабильно.

=== 2.5 Конфигурация сервера: server.yaml ===

<syntaxhighlight lang="bash">
cat > /opt/hysteria-ru/server.yaml << 'EOF'
listen: :2053

tls:
cert: /etc/hysteria/certs/your-hy2-ru-domain.example.com.crt
key: /etc/hysteria/certs/your-hy2-ru-domain.example.com.key

auth:
type: command
command: /etc/hysteria/users/check-auth.sh

ignoreClientBandwidth: true

masquerade:
type: proxy
proxy:
url: https://news.ycombinator.com/
rewriteHost: true

outbounds:
- name: chain
type: socks5
socks5:
addr: 127.0.0.1:10810

acl:
inline:
- "chain(all)"
EOF
</syntaxhighlight>

Описание ключевых параметров:

{| class="wikitable"
|-
! Параметр !! Значение !! Пояснение
|-
|| <code>auth.type: command</code> || Внешний скрипт || При каждом подключении вызывается <code>check-auth.sh</code>
|-
|| <code>auth.command</code> || Путь внутри контейнера || Скрипт смонтирован через volume: <code>./users:/etc/hysteria/users</code>
|-
|| <code>outbounds.chain</code> || SOCKS5 на 127.0.0.1:10810 || Трафик → hysteria-ru-client → EU
|-
|| <code>acl: chain(all)</code> || Весь трафик через chain || Синтаксис: имя outbound, затем адрес в скобках
|}

=== 2.6 Конфигурация клиента: client.yaml ===

RU клиент подключается к EU серверу и поднимает SOCKS5 на <code>127.0.0.1:10810</code>.

<syntaxhighlight lang="bash">
cat > /opt/hysteria-ru/client.yaml << 'EOF'
server: your-hy2-eu-domain.example.com:2053

auth: EU_HY2_PASSWORD

socks5:
listen: 127.0.0.1:10810
EOF
</syntaxhighlight>

Замени <code>EU_HY2_PASSWORD</code> на тот же пароль, который указан в <code>server.yaml</code> EU сервера.

=== 2.7 Конфигурация Docker Compose: docker-compose.yml ===

<syntaxhighlight lang="bash">
cat > /opt/hysteria-ru/docker-compose.yml << 'EOF'
services:
hysteria-ru-server:
image: tobyxdd/hysteria:latest
container_name: hysteria-ru-server
restart: unless-stopped
network_mode: host
command: server --config /etc/hysteria/server.yaml
volumes:
- ./server.yaml:/etc/hysteria/server.yaml:ro
- ./users:/etc/hysteria/users:ro
- /var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/your-hy2-ru-domain.example.com:/etc/hysteria/certs:ro

hysteria-ru-client:
image: tobyxdd/hysteria:latest
container_name: hysteria-ru-client
restart: unless-stopped
network_mode: host
command: client --config /etc/hysteria/client.yaml
volumes:
- ./client.yaml:/etc/hysteria/client.yaml:ro
EOF
</syntaxhighlight>

'''Критически важные моменты:'''
* Директория <code>./users</code> монтируется в оба контейнера... нет, только в <code>hysteria-ru-server</code>. Клиентский контейнер видит только свой <code>client.yaml</code>.
* При изменении <code>docker-compose.yml</code> (добавлении volume) нужен пересоздать контейнер: <code>docker compose down && docker compose up -d</code>. Простой <code>restart</code> не применяет изменения volumes.

=== 2.8 Первый запуск ===

<syntaxhighlight lang="bash">
cd /opt/hysteria-ru

# Скачать образ
docker compose pull

# Запустить оба контейнера
docker compose up -d

# Подождать и проверить логи
sleep 3 && docker compose logs
</syntaxhighlight>

Ожидаемый вывод:
<pre>
hysteria-ru-server | INFO server mode
hysteria-ru-server | INFO server up and running {"listen": ":2053"}
hysteria-ru-client | INFO client mode
hysteria-ru-client | INFO connected to server {"udpEnabled": true, "count": 1}
hysteria-ru-client | INFO SOCKS5 server listening {"addr": "127.0.0.1:10810"}
</pre>

=== 2.9 Проверка цепочки с RU сервера ===

Тест: запустить временный Hysteria2 клиент на RU сервере и проверить, что трафик выходит через WARP (IP Cloudflare):

<syntaxhighlight lang="bash">
# Создать временный конфиг тест-клиента
cat > /tmp/hy2-test.yaml << EOF
server: 127.0.0.1:2053
auth: $(awk 'NR==1{print $2}' /opt/hysteria-ru/users/users.txt)
tls:
insecure: true
sni: your-hy2-ru-domain.example.com
socks5:
listen: 127.0.0.1:11080
EOF

# Запустить тест-клиент
docker run -d --name hy2-test --network host \
-v /tmp/hy2-test.yaml:/etc/hysteria/client.yaml:ro \
tobyxdd/hysteria:latest client --config /etc/hysteria/client.yaml

# Ждать 3 секунды
sleep 3

# Проверить IP выхода — должен быть Cloudflare WARP IP
echo "IP через цепочку:"
curl -s --max-time 15 -x socks5h://127.0.0.1:11080 https://ifconfig.me

# Очистить
docker rm -f hy2-test
rm -f /tmp/hy2-test.yaml
</syntaxhighlight>

Если IP вывода принадлежит Cloudflare (начинается с <code>2a09:</code> для IPv6 или относится к диапазонам WARP) — цепочка RU → EU → WARP работает корректно.

'''Примечание:''' параметр <code>insecure: true</code> и <code>sni</code> нужны в тест-клиенте, потому что он подключается по IP (<code>127.0.0.1</code>), а сертификат выдан на домен. Реальные клиенты подключаются по домену и такие параметры не требуются.

----

== Часть 3: Управление пользователями (hy2-users.sh) ==

=== 3.1 Что это и зачем ===

Для управления пользователями Hysteria2 на RU сервере предназначен скрипт <code>hy2-users.sh</code>. Он предоставляет интерактивное меню с набором операций над файлом <code>users.txt</code>.

Скрипт решает следующие задачи:

{| class="wikitable"
|-
! Операция !! Описание
|-
|| Список пользователей || Показывает всех пользователей из users.txt с маскированными паролями
|-
|| Добавить пользователя || Запрашивает имя, автоматически генерирует криптостойкий пароль, сохраняет в users.txt, показывает готовый Hysteria2 URI
|-
|| Удалить пользователя || Интерактивный выбор из списка, удаление строки из users.txt
|-
|| Показать конфиг || Генерирует и показывает Hysteria2 URI для выбранного пользователя
|}

Ключевые особенности:
* '''Нет перезапуска контейнера.''' Hysteria2 с <code>auth.type: command</code> читает файл при каждом подключении — изменения в <code>users.txt</code> применяются мгновенно.
* '''Пароли генерируются автоматически''' через <code>openssl rand</code> — случайные, криптостойкие.
* '''URI формат''' соответствует стандарту Hysteria2 и принимается всеми клиентами: NekoBox, husi, Exclave, podkop.

=== 3.2 Установка скрипта ===

Скрипт хранится в репозитории по пути <code>scripts/hy2-users.sh</code>. Установка на сервер:

<syntaxhighlight lang="bash">
# Скопировать скрипт на сервер
scp scripts/hy2-users.sh root@YOUR_RU_SERVER_IP:/usr/local/bin/hy2-users.sh

# Сделать исполняемым
ssh root@YOUR_RU_SERVER_IP "chmod +x /usr/local/bin/hy2-users.sh"
</syntaxhighlight>

Или выполнить непосредственно на RU сервере (если скрипт уже там):

<syntaxhighlight lang="bash">
chmod +x /usr/local/bin/hy2-users.sh
</syntaxhighlight>

'''Проверка переменных в начале скрипта.''' Открой скрипт и убедись, что следующие переменные указывают на правильные значения:

<syntaxhighlight lang="bash">
head -15 /usr/local/bin/hy2-users.sh
</syntaxhighlight>

Должны быть:
* <code>USERS_FILE="/opt/hysteria-ru/users/users.txt"</code>
* <code>DOMAIN="your-hy2-ru-domain.example.com"</code>
* <code>PORT="2053"</code>

Если домен указан неверно — исправь:
<syntaxhighlight lang="bash">
sed -i 's|DOMAIN=.*|DOMAIN="your-hy2-ru-domain.example.com"|' /usr/local/bin/hy2-users.sh
</syntaxhighlight>

=== 3.3 Использование ===

<syntaxhighlight lang="bash">
sudo bash /usr/local/bin/hy2-users.sh
</syntaxhighlight>

Скрипт показывает меню:
<pre>
┌─────────────────────────────────────────────┐
│ Hysteria2 — управление пользователями RU │
└─────────────────────────────────────────────┘

1. Список пользователей
2. Добавить пользователя
3. Удалить пользователя
4. Показать конфиг клиента

0. Выход

Выбери действие:
</pre>

При добавлении нового пользователя скрипт выводит готовый URI:
<pre>
hysteria2://СГЕНЕРИРОВАННЫЙ_ПАРОЛЬ@your-hy2-ru-domain.example.com:2053
</pre>

Этот URI вставляется напрямую в клиентское приложение (см. Часть 4).

=== 3.4 Исходный код скрипта ===

<div class="mw-collapsible mw-collapsed" style="width:100%">
<div style="font-weight:bold; padding:4px 0;">▶ Показать исходный код hy2-users.sh</div>
<div class="mw-collapsible-content">
<syntaxhighlight lang="bash">
# --- ИСХОДНЫЙ КОД СКРИПТА hy2-users.sh ---
# (вставить содержимое файла scripts/hy2-users.sh)
</syntaxhighlight>
</div>
</div>

----

== Часть 4: Настройка клиентов ==

=== 4.1 Формат URI Hysteria2 ===

Hysteria2 использует стандартизированный URI для передачи параметров подключения клиентам:

<pre>
hysteria2://ПАРОЛЬ@ДОМЕН:ПОРТ
</pre>

Пример:
<pre>
hysteria2://aBcDeFgHiJkLmNoPqRsT@your-hy2-ru-domain.example.com:2053
</pre>

URI можно получить через скрипт <code>hy2-users.sh</code> (пункт 4 меню — «Показать конфиг клиента»).

=== 4.2 Мобильные клиенты (iOS / Android) ===

Рекомендуемые приложения с нативной поддержкой Hysteria2:

{| class="wikitable"
|-
! Приложение !! Платформа !! Как импортировать URI
|-
|| NekoBox || Android || Главный экран → + → Add → Hysteria2 → вставить URI
|-
|| husi || Android || Профили → + → Hysteria2 → вставить URI
|-
|| Exclave || iOS || Конфигурации → + → Hysteria2 → вставить URI
|-
|| Shadowrocket || iOS || Главная → + → Тип: Hysteria2 → вставить URI
|}

Все эти приложения принимают URI в формате <code>hysteria2://...</code> напрямую — через кнопку импорта, QR-код или буфер обмена.

=== 4.3 ПК-клиенты (Windows / macOS / Linux) ===

==== Вариант А: официальный бинарь Hysteria2 ====

Скачать бинарь с официального репозитория: https://github.com/apernet/hysteria/releases

Создать файл конфигурации <code>config.yaml</code>:
<syntaxhighlight lang="yaml">
server: your-hy2-ru-domain.example.com:2053

auth: ВАШ_ПАРОЛЬ

socks5:
listen: 127.0.0.1:1080

http:
listen: 127.0.0.1:8080
</syntaxhighlight>

Запустить:
<syntaxhighlight lang="bash">
# Linux / macOS
./hysteria client --config config.yaml

# Windows (PowerShell)
.\hysteria.exe client --config config.yaml
</syntaxhighlight>

После запуска:
* SOCKS5 прокси доступен на <code>127.0.0.1:1080</code>
* HTTP прокси доступен на <code>127.0.0.1:8080</code>

==== Вариант Б: через NekoRay / Hiddify Next (Windows / Linux) ====

Приложения NekoRay и Hiddify Next принимают Hysteria2 URI — импорт через меню или буфер обмена. Автоматически управляют запуском клиентского процесса.

=== 4.4 OpenWrt / podkop ===

podkop (реализация на базе sing-box) нативно поддерживает Hysteria2 URI. Никакой дополнительной установки бинарей не требуется.

В интерфейсе podkop (LuCI → Network → podkop → Outbound):
* Тип: <code>Hysteria2</code>
* URI: <code>hysteria2://ПАРОЛЬ@your-hy2-ru-domain.example.com:2053</code>

Или через UCI:
<syntaxhighlight lang="bash">
uci set podkop.main.proxy='hysteria2://ПАРОЛЬ@your-hy2-ru-domain.example.com:2053'
uci commit podkop
/etc/init.d/podkop restart
</syntaxhighlight>

После сохранения все устройства домашней сети автоматически получают обход без дополнительной настройки.

----

== Часть 5: Проверка всей цепочки ==

=== 5.1 Тест RU сервера: цепочка RU → EU → WARP ===

Выполнить на RU сервере — проверяет, что трафик выходит через WARP:

<syntaxhighlight lang="bash">
# SOCKS5 порт 10810 — это точка выхода RU клиента (= вход в EU сервер → WARP)
curl -s --max-time 20 -x socks5h://127.0.0.1:10810 https://ifconfig.me
echo ""
</syntaxhighlight>

Результат должен быть '''IP Cloudflare WARP''' — например, начинается с <code>2a09:</code> (IPv6) или принадлежит AS13335 (Cloudflare).

Проверить AS:
<syntaxhighlight lang="bash">
IP=$(curl -s --max-time 20 -x socks5h://127.0.0.1:10810 https://ifconfig.me)
curl -s "https://ipinfo.io/${IP}/org"
echo ""
</syntaxhighlight>

Ожидаемый вывод: строка содержит <code>Cloudflare</code>.

=== 5.2 Тест с реального клиента ===

После добавления пользователя через <code>hy2-users.sh</code> и получения URI:

# Вставь URI в клиентское приложение (NekoBox, husi, Shadowrocket).
# Активируй профиль.
# Открой <code>https://ifconfig.me</code> в браузере — должен отображаться IP Cloudflare WARP.
# Открой <code>https://www.whatismybrowser.com/detect/what-is-my-ip-address</code> для проверки отсутствия WebRTC утечки.

=== 5.3 Диагностика проблем ===

==== Проблема: hysteria-eu не запускается — ошибка TLS ====

<syntaxhighlight lang="bash">
docker compose -f /opt/hysteria-eu/docker-compose.yml logs hysteria-eu
</syntaxhighlight>

Возможные причины:
* Путь к сертификату неверен → проверь <code>ls</code> по пути, указанному в volumes.
* Сертификат ещё не был получен Caddy → проверь, что caddy-naive запущен и прошёл ACME-проверку.
* Caddy хранит сертификат под другим именем → выполни <code>find /var/lib/docker/volumes/caddy-naive_caddy_data/_data -name "*.crt"</code>.

==== Проблема: hysteria-ru-server выдаёт auth error ====

<syntaxhighlight lang="bash">
docker compose -f /opt/hysteria-ru/docker-compose.yml logs hysteria-ru-server
</syntaxhighlight>

Проверить вручную (на RU сервере):
<syntaxhighlight lang="bash">
# Проверить, что скрипт находится на месте внутри контейнера
docker exec hysteria-ru-server ls -la /etc/hysteria/users/

# Запустить скрипт вручную с тестовым паролем
docker exec hysteria-ru-server /etc/hysteria/users/check-auth.sh addr ТЕСТОВЫЙ_ПАРОЛЬ 0
echo "Exit code: $?"
</syntaxhighlight>

Если <code>Exit code: 0</code> — скрипт работает. Если <code>1</code> — пароль не найден в <code>users.txt</code>.

==== Проблема: hysteria-ru-client не подключается к EU ====

<syntaxhighlight lang="bash">
docker compose -f /opt/hysteria-ru/docker-compose.yml logs hysteria-ru-client
</syntaxhighlight>

Возможные причины:
* <code>EU_HY2_PASSWORD</code> в <code>client.yaml</code> не совпадает с паролем в EU <code>server.yaml</code>.
* UDP порт 2053 заблокирован на EU сервере (firewall) → проверь <code>ss -ulnp | grep 2053</code> на EU сервере.
* EU сервер ещё не запущен.

==== Проблема: ACL ошибка при запуске ====

<pre>
FATAL failed to load server config: invalid config: acl.inline: invalid syntax at line 1
</pre>

Неверный синтаксис ACL. Правильный формат: <code>"outbound_name(address)"</code>:
* ✅ <code>"warp(all)"</code> — направить всё в outbound "warp"
* ✅ <code>"chain(all)"</code> — направить всё в outbound "chain"
* ❌ <code>"outbound(warp) all"</code> — неверно

----

== Часть 6: Обслуживание ==

=== 6.1 Управление контейнерами ===

<syntaxhighlight lang="bash">
# EU сервер
cd /opt/hysteria-eu
docker compose up -d # запустить
docker compose down # остановить
docker compose restart # перезапустить
docker compose logs -f # следить за логами в реальном времени
docker compose ps # статус

# RU сервер (оба контейнера)
cd /opt/hysteria-ru
docker compose up -d
docker compose down
docker compose restart
docker compose logs -f

# RU сервер (по отдельности)
docker compose restart hysteria-ru-server # только сервер
docker compose restart hysteria-ru-client # только клиент
docker compose logs -f hysteria-ru-server # логи только сервера
docker compose logs -f hysteria-ru-client # логи только клиента
</syntaxhighlight>

=== 6.2 Обновление сертификатов ===

TLS-сертификаты обновляются Caddy автоматически (за 30 дней до истечения). После автообновления Hysteria2 начнёт использовать новый сертификат при следующем перезапуске.

Для принудительного применения нового сертификата:
<syntaxhighlight lang="bash">
# EU сервер
cd /opt/hysteria-eu && docker compose restart

# RU сервер
cd /opt/hysteria-ru && docker compose restart hysteria-ru-server
</syntaxhighlight>

Проверить дату истечения текущего сертификата:
<syntaxhighlight lang="bash">
# EU сервер
DOMAIN="your-hy2-eu-domain.example.com"
CERT="/var/lib/docker/volumes/caddy-naive_caddy_data/_data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/${DOMAIN}/${DOMAIN}.crt"
openssl x509 -in "${CERT}" -noout -enddate
</syntaxhighlight>

=== 6.3 Обновление Docker-образа ===

Hysteria2 активно развивается. Для обновления до последней версии:

<syntaxhighlight lang="bash">
# EU сервер
cd /opt/hysteria-eu
docker compose pull # скачать новый образ
docker compose up -d # перезапустить с новым образом
docker compose logs --tail=5 # проверить старт

# RU сервер
cd /opt/hysteria-ru
docker compose pull
docker compose up -d
docker compose logs --tail=5
</syntaxhighlight>

Старые неиспользуемые образы можно удалить:
<syntaxhighlight lang="bash">
docker image prune -f
</syntaxhighlight>

=== 6.4 Мониторинг логов ===

Hysteria2 пишет структурированные JSON-логи. Полезные паттерны для мониторинга:

<syntaxhighlight lang="bash">
# Смотреть все подключения на RU сервере
docker logs hysteria-ru-server 2>&1 | grep -E "connected|disconnected|auth"

# Смотреть ошибки
docker logs hysteria-ru-server 2>&1 | grep -i "error\|fatal\|warn"

# Считать количество уникальных пользователей (поле "id")
docker logs hysteria-ru-server 2>&1 | grep '"id"' | grep -oP '"id": "\K[^"]+' | sort -u

# Следить за логами EU сервера в реальном времени
docker logs -f hysteria-eu 2>&1
</syntaxhighlight>

Пример нормального лога RU сервера при входящем подключении:
<pre>
INFO client connected {"addr": "CLIENT_IP:PORT", "id": "username"}
INFO TCP request {"addr": "CLIENT_IP:PORT", "id": "username", "reqAddr": "example.com:443"}
INFO client disconnected {"addr": "CLIENT_IP:PORT", "id": "username", "error": "..."}
</pre>

Поле <code>"id"</code> — это имя пользователя, возвращённое скриптом <code>check-auth.sh</code>. Это позволяет отслеживать активность конкретных пользователей в логах без хранения паролей.