pyrschtjag/xray-manager
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: updated readme to v0.2.2

Browse Source
This commit is contained in:
pyrschtjag
2026-07-14 01:49:33 +04:00
parent 46d3b3bd48
commit 2ff1d647fa
1 changed files with 140 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+140 -117
View File
@@ -1,30 +1,32 @@
# xray-manager
**xray-manager** — это легковесный Shell-скрипт (Ash) для OpenWrt, предназначенный для автоматического управления списками маршрутизации (IP-адреса и домены) через `nftables` и `tproxy`.
**xray-manager** — лёгкий shell-скрипт (ash) для OpenWrt, который автоматически управляет списками маршрутизации (IP-адреса и домены) через `nftables` и `tproxy`.
Скрипт позволяет гибко распределять трафик: направлять нужные ресурсы через Xray, создавать исключения и автоматически поддерживать списки в актуальном состоянии.
Скрипт гибко распределяет трафик: направляет нужные ресурсы через Xray, создаёт исключения, поддерживает списки в актуальном состоянии и умеет строить изолированные цепочки правил для отдельных устройств или групп устройств.
## Основные функции
* **Мульти-ссылочные секции**: Возможность указать несколько URL в одной категории — скрипт сам скачает их, объединит и удалит дубликаты.
* **Поддержка `auto-merge`**: Автоматическое решение конфликтов пересекающихся подсетей на уровне ядра (nftables), что предотвращает ошибки при загрузке больших списков.
* **Умное обновление DNS**: Сервис `dnsmasq` перезапускается только при реальном изменении списков доменов, минимизируя разрывы соединений.
* **Проверка изменений (Hashing)**: Скрипт отслеживает изменения в конфигурации URL и уведомляет о необходимости запуска обновления при использовании `reload`.
* **Гибкая маршрутизация**: Поддержка фильтрации по источнику (`src`) и назначению (`dst`).
* **Автоматическая очистка**: Удаление устаревших кэш-файлов и правил при изменении структуры конфигурации.
* **Персональные цепочки**: Возможность завернуть абсолютно весь трафик конкретного устройства в прокси с созданием изолированной цепочки правил.
* **Изолированные исключения**: Поддержка параметра parent, который позволяет назначать списки исключений только для конкретных групп или устройств, не влияя на общую маршрутизацию.
* **Защита от петель**: Автоматическое исключение IP-адресов самих прокси-серверов из обработки, что гарантирует стабильность соединения.
* **Мульти-ссылочные секции** — можно указать несколько URL в одном списке, скрипт скачает, объединит и уберёт дубликаты.
* **`auto-merge`** — пересекающиеся подсети в списках IP разрешаются на уровне ядра (nftables), большие списки не вызывают ошибок загрузки.
* **Умное обновление dnsmasq** — сервис перезапускается только если реально изменились списки доменов.
* **Хеширование содержимого** — скрипт отслеживает изменения в скачанных списках и, если содержимое не поменялось, не трогает nft-таблицы; при `reload` только предупреждает, что нужен `update`.
* **Сигнатуры контекстов** — каждая цепочка (глобальная и для каждого выделенного источника) имеет свою MD5-сигнатуру состава; пересборка nft-цепочки происходит только если реально что-то изменилось в структуре.
* **Вложенные источники (parent)** — `xray-src`/`xray-dst` могут ссылаться на несколько родителей (`list parent`), что позволяет строить исключения и назначения только внутри области конкретной группы устройств.
* **Автоочистка** — устаревшие файлы, hash-кэши и «осиротевшие» nft-сеты/цепочки удаляются автоматически при изменении конфига.
* **Поддержка прокси-серверов** — встроенная возможность использования SOCKS5/HTTP прокси для скачивания внешних списков (через curl), что позволяет успешно обновлять правила даже при блокировках основных репозиториев (GitHub и др.).
> В текущей версии нет отдельной опции `proxy_ip` для автоисключения IP прокси-серверов — вместо этого их IP просто добавляются как обычные записи в exclude-секцию `xray-out` (см. пример `vps` ниже).
## Установка
### 1. Зависимостиa
### 1. Зависимости
Убедитесь, что установлены необходимые пакеты:
```bash
opkg update && opkg install kmod-nf-tproxy kmod-nft-tproxy git git-http curl
```
Для полноценной работы со списками доменов необходима полная версия dnsmasq:
Для работы со списками доменов нужна полная версия dnsmasq:
```bash
opkg remove dnsmasq
echo "nameserver 1.1.1.1" > /etc/resolv.conf
@@ -33,149 +35,170 @@ opkg install dnsmasq-full
### 2. Клонирование репозитория
Рекомендуется устанавливать в директорию `/opt/.xray-manager`:
```bash
git clone https://gitea.oyacoi.ru/pyrschtjag/xray-manager.git /opt/.xray-manager
```
### 3. Интеграция скрипта
### 3. Интеграция
Для интеграции скрипта в систему выполните следующие команды:
```Bash
# Конфигурационный файл
```bash
cp /opt/.xray-manager/config/xray-manager.example /etc/config/xray-manager
# Инит-скрипт для управления сервисом
ln -s /opt/.xray-manager/init.d/xray-manager /etc/init.d/xray-manager
```
## Команды управления
Скрипт интегрирован в систему и поддерживает стандартные методы управления OpenWrt. Основное различие между командами заключается в работе с сетью и кэшем.
* **`start`** — холодный запуск. Полная инициализация: создаются таблица `nftables`, базовые цепочки и правила. Списки по URL скачиваются, если кэша ещё нет.
* **`reload`** — локальное применение изменений конфига (например, новых секций/списков `ip`/`domain`) **без обращения к сети**. Если менялись `url_ip`/`url_domain`, скрипт выдаст предупреждение, что нужно запустить `update`.
* **`update`** — синхронизация с сетью: опрашивает все внешние URL (с ETag-кэшированием), пересобирает только те наборы, которые реально изменились.
* **`stop`** — удаляет таблицу и цепочки `nftables`, чистит временные файлы, возвращает маршрутизацию в исходное состояние.
* **`restart`** — `stop` + `start`.
* **/etc/init.d/xray-manager start** — **Холодный запуск** <br> Полная инициализация системы: создание таблиц nftables, цепочек и правил. При первом запуске скрипт автоматически скачает все списки из URL. Если списки уже есть в кэше — применит их.
* **/etc/init.d/xray-manager reload** — **Локальное обновление** <br> Применяет изменения, внесенные в конфигурационный файл /etc/config/xray-manager (например, изменение портов или добавление новых секций), но не обращается к сети. Если вы изменили URL в конфиге, скрипт выдаст предупреждение о необходимости запуска update.
* **/etc/init.d/xray-manager update** — **Умная синхронизация** <br> Скрипт опрашивает все внешние URL. Благодаря системе хеширования (Hashing), загрузка и пересборка правил произойдет только для тех списков, которые реально изменились на удаленном сервере. Это экономит трафик и минимизирует нагрузку на процессор роутера.
* **/etc/init.d/xray-manager stop** — **Полная очистка** <br> Удаляет все таблицы и цепочки из nftables, очищает временные файлы и возвращает маршрутизацию в исходное состояние. Полезно для диагностики или временного отключения проксирования.
* **/etc/init.d/xray-manager restart** — **Перезапуск** <br> Последовательное выполнение команд stop и start.
**Важно:** изменения базовых параметров секции `main` (порт, марки, приоритеты, имя таблицы) применяются только при **полной пересборке** (`start`/`restart`, либо когда сама таблица `nftables` отсутствует). Команды `reload`/`update` переиспользуют существующую таблицу и не подхватят такие изменения.
## Конфигурация
### Глобальные параметры (`section main`)
### Глобальные параметры (`config xray-manager 'main'`)
| Параметр | Тип | По умолчанию | Описание |
| :--- | :--- | :--- | :--- |
| **table_name** | `string` | `xray` | Имя основной таблицы в `nftables`. |
| **tproxy_port** | `int` | `61219` | Порт, на котором Xray/Sing-box слушает TProxy входящие соединения. |
| **tproxy_mark** | `string` | `10` | Метка (`fwmark`), используемая для маршрутизации пакетов в таблицу 110. |
| **client_mark** | `string` | `103` | Внутренняя метка ct mark для идентификации трафика, подлежащего проксированию.
| **timeout** | `string` | `1h` | Время жизни динамических записей в сетах (для доменов). |
| **ipnet_dir** | `string` | `/tmp/ipnet` | Директория для хранения списков IP-адресов в формате `.lst`. |
| **dnsmasq_dir** | `string` | `/tmp/dnsmasq.d` | Директория для `.conf` файлов dnsmasq (автоматически добавляется в `confdir` по пути `/etc/config/dhcp`). |
| **cache_dir** | `string` | `/tmp/.xray-manager/cache` | Место хранения хэш-файлов для отслеживания изменений в списках. |
| **active_list** | `string` | `/tmp/.xray-manager/active_files` | Файл-индекс для автоматической очистки «осиротевших» (удаленных) списков. |
| **proxy_ip** | `list` | | Список IP прокси-серверов. Они будут автоматически добавлены в исключения, чтобы роутер не пытался проксировать соединение к самому прокси. |
Пример:
| Параметр | По умолчанию | Описание |
| :--- | :--- | :--- |
| **table_name** | — | Имя таблицы в `nftables`. |
| **tproxy_port** | — | Порт, на котором Xray/Sing-box слушает TProxy. |
| **tproxy_mark** | — | `fwmark`, используемая для маршрутизации в отдельную таблицу маршрутизации. |
| **client_mark** | — | `ct mark`, которой помечается проксируемое соединение (используется для connection tracking). |
| **rt_table** | — | Номер/имя таблицы маршрутизации ядра (`ip rule`/`ip route`) для TProxy. |
| **timeout** | — | TTL динамических записей в сетах доменов (например `1h`). |
| **exclude_mark** | `0x1` | Марка, которой помечаются пакеты, явно исключённые из проксирования. Не должна совпадать с `tproxy_mark`/`client_mark`. |
| **prio_exc** | `-200` | Приоритет hook-цепочки предварительных исключений (`prerouting_exc`). |
| **prio_proxy** | `-150` | Приоритет hook-цепочки проксирования (`prerouting_proxy`). |
| **prio_output** | `-100` | Приоритет hook-цепочки для собственного трафика роутера (`output`). |
| **ipnet_dir** | `/tmp/.xray-manager/ipnet` | Каталог списков IP (`.lst`). |
| **dnsmasq_dir** | `/tmp/.xray-manager/dnsmasq.d` | Каталог `.conf`-файлов для dnsmasq (должен быть прописан в `confdir` в `/etc/config/dhcp`). |
| **cache_dir** | `/tmp/.xray-manager/cache` | Хеши, ETag-кэш скачанных списков, служебные маркеры. |
| **active_list** | `/tmp/.xray-manager/active_files` | Индекс активных файлов для автоочистки «осиротевших» списков. |
| **domstage_dir** | `$cache_dir/domstage` | Промежуточный каталог для списков доменов перед сборкой dnsmasq-конфига. |
| **ctx_dir** | `$cache_dir/ctx` | Сигнатуры и состояние контекстов (вложенных src-цепочек). |
| **curl_proxy** | — | Прокси-сервер для загрузки внешних списков (например, `socks5h://127.0.0.1:1080`) |
| **curl_proxy_user** | — | Имя пользователя для аутентификации на прокси (если требуется) |
| **curl_proxy_pass** | — | Пароль для аутентификации на прокси |
```bash
config xray-manager 'main'
option table_name 'xray'
option tproxy_port '61219'
option tproxy_mark '10'
option timeout '1h'
option ipnet_dir '/tmp/ipnet'
option dnsmasq_dir '/tmp/dnsmasq.d'
option cache_dir '/tmp/.xray-manager/cache'
option active_list '/tmp/.xray-manager/active_files'
option table_name 'xray'
option tproxy_port '61219'
option tproxy_mark '10'
option client_mark '103'
option rt_table '110'
option timeout '1h'
option curl_proxy 'socks5h://127.0.0.1:1080'
option curl_proxy_user 'myuser'
option curl_proxy_pass 'mypassword'
```
### Списки маршрутов (List)
### Секции списков
Каждая секция `config xray-list` определяет, какой именно трафик будет перехвачен или пропущен.
Вместо одной универсальной секции с опцией `direction` используются три отдельных типа UCI-секций:
| Параметр | Значение | Описание |
| :--- | :--- | :--- |
| **name** | `string` | Уникальное имя. Используется для названия сета в `nftables` (например, `@v2ray_udom`) и имени файла в `/tmp`. |
| **direction** | `dst`, `src`, `out`, `force_src` | **Направление фильтрации**: <br> `dst`: проверка IP назначения. <br> `src`: проверка IP отправителя. <br> `out`: трафик самого роутера (Self-traffic). <br> `force_src`: принудительный прокси для устройства (весь трафик). |
| **exclude** | `bool` | **Тип правила**: <br> `0`: Направлять трафик в прокси. <br> `1`: Пропускать трафик напрямую (исключение). |
| **parent** | `string` | Имя родительской секции (`force_src`). Если указан, то данное исключение (`exclude 1`) будет работать только для этого родителя. |
| Тип секции | Смысл |
| :--- | :--- |
| **`xray-src`** | Фильтр по **источнику** (IP клиента в сети). |
| **`xray-dst`** | Фильтр по **назначению** (куда идёт трафик). |
| **`xray-out`** | Собственный трафик роутера (self-traffic). |
Внутри каждой секции можно комбинировать разные типы данных:
Общие опции внутри секций:
| Тип записи | Формат | Описание |
| :--- | :--- | :--- |
| **list ip** | `1.1.1.1` или `CIDR` | Статический IP или подсеть. Заносится напрямую в `nftables`. |
| **list domain** | `example.com` | Домен. Создает правило dnsmasq для динамического добавления IP в сет. |
| **list url_ip** | `http(s)://...` | Ссылка на сырой текстовый файл с IP. Скрипт скачает и объединит данные. |
| **list url_domain** | `http(s)://...` | Ссылка на сырой текстовый файл с доменами. Готовит данные для dnsmasq. |
| Параметр | Описание |
| :--- | :--- |
| **name** | Уникальное имя секции (для `xray-src` — обязательно уникально глобально, так как используется как имя nft-цепочки). |
| **exclude** | `0` — направлять в прокси (по умолчанию); `1` — исключение, пропускать напрямую. |
| **parent** | Список (можно несколько `list parent`) имён `xray-src`-секций, ограничивающих область действия данной секции только этим источником/группой. Без `parent` секция действует глобально. |
| **list ip** | Статический IP/CIDR. |
| **list domain** | Домен — динамически резолвится через dnsmasq (`nftset=`), IP добавляется в сет с TTL. |
| **list url_ip** | Ссылка на текстовый список IP/CIDR — скачивается и объединяется. |
| **list url_domain** | Ссылка на текстовый список доменов — так же резолвится динамически через dnsmasq. |
### Прокси для самого роутера
### Примеры
В этом примере завернём запросы до DNS-серверов Cloudflare в прокси:
**Собственный трафик роутера через прокси:**
```bash
config xray-list
option name 'router_self'
option direction 'out' # Трафик роутера
option exclude '0'
list ip '1.1.1.1'
list ip '1.0.0.1'
config xray-out
option name 'cloudflare'
list ip '1.1.1.1'
list ip '1.0.0.1'
config xray-out
option name 'vps'
option exclude '1'
list ip '178.123.123.123'
list domain 'proxy.domain.tld'
```
### Проксировать весь трафик от клиента с поддержкой исключений
Завернём в прокси весь трафик от клиента, исключив 2ip.ru:
**Локальные/служебные сети и IP самих прокси-серверов — всегда исключение:**
```bash
# Проксировать весь трафик от клиента 10.2.0.4
config xray-list
option name 'my_pc'
option direction 'force_src'
list ip '10.2.0.4'
# Исключение для my_pc
config xray-list
option name 'my_pc_exc'
option direction 'dst'
option exclude '1'
option parent 'my_pc' # Привязка к родителю
list domain '2ip.ru'
config xray-dst
option name 'private'
option exclude '1'
list ip '127.0.0.0/8'
list ip '10.0.0.0/8'
list ip '172.16.0.0/12'
list ip '192.168.0.0/16'
```
### Практический пример по выборочной маршрутизации
**Весь трафик конкретного устройства через прокси (аналог старого `force_src`):**
**Задача**: Направить трафик конкретного устройства (10.1.0.2) через прокси только при обращении к ресурсам Spotify, не затрагивая остальных клиентов сети.
Раньше для этого была отдельная опция `direction 'force_src'`. Теперь то же самое достигается связкой `xray-src` (без `exclude`) + `xray-dst` с `parent` на этот источник и `list ip '0.0.0.0/0'`:
#### Шаг 1: Определение источника (src)
```bash
config xray-src
option name 'lan-pc'
list ip '10.1.0.2'
list ip '10.1.0.3'
Сначала мы указываем «доверенную» группу устройств, которым разрешен доступ к проксированию. Для этого создается секция с типом фильтрации по источнику:
```Bash
config xray-list
option name 'my_pc' # Уникальное имя группы
option direction 'src' # Фильтр отправителя (Source)
option exclude '0' # Направлять в прокси
list ip '10.1.0.2' # IP адрес вашего устройства
config xray-dst
option name 'lan-pc-rule'
list parent 'lan-pc'
list ip '0.0.0.0/0'
```
#### Шаг 2: Определение назначения (dst)
Исключение внутри этой же группы (например, российские сервисы — напрямую):
Затем мы загружаем список ресурсов, которые должны перехватываться. В данном случае используем домены Spotify из внешнего репозитория:
```Bash
config xray-list
option name 'spotify'
option direction 'dst' # Фильтр назначения (Destination)
option exclude '0' # Направлять в прокси
list url_domain 'https://raw.githubusercontent.com/v2ray/domain-list-community/master/data/spotify'
```bash
config xray-dst
option name 'russian-whitelist'
list parent 'lan-pc'
option exclude '1'
list url_ip 'https://raw.githubusercontent.com/hxehex/russia-mobile-internet-whitelist/refs/heads/main/cidrwhitelist.txt'
```
Как это работает (Логика связки):
1. Пакет приходит на роутер с IP 10.1.0.2.
2. Скрипт видит совпадение в секции src и ставит пакету внутреннюю метку (mark).
3. Далее роутер проверяет адрес назначения этого помеченного пакета.
4. Если домен соответствует списку spotify, пакет перенаправляется в TProxy. <br>Если домен не в списке — пакет уходит через провайдера.
**Выборочная маршрутизация (только определённые ресурсы для группы устройств):**
```bash
config xray-src
option name 'lan'
list ip '10.1.0.0/24'
config xray-src
option name 'wlan-main'
list ip '10.2.0.0/24'
config xray-dst
option name 'v2ray'
list parent 'lan'
list parent 'wlan-main'
list url_domain 'https://raw.githubusercontent.com/v2ray/domain-list-community/refs/heads/master/data/spotify'
```
Логика: пакет от `10.1.0.0/24` или `10.2.0.0/24` попадает в цепочку соответствующего источника → там проверяется адрес назначения → если он совпал со списком `v2ray`, пакет заворачивается в TProxy, иначе уходит напрямую через провайдера.
**Исключение конкретных хостов из общей group-цепочки** (чтобы не проксировать их дважды, если у них уже есть своя отдельная секция `xray-dst`/`xray-src`):
```bash
config xray-src
option name 'lan-pc-exc'
option exclude '1'
list parent 'lan-pc'
list ip '10.1.0.2'
list ip '10.1.0.3'
```