0x25/bbrkn
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Рефакторинг

Browse source
This commit is contained in:
goodvin 2026-03-21 09:46:15 +03:00
parent 64e5744f5c
commit 537ae61f63
6 changed files with 525 additions and 274 deletions
Download patch file Download diff file Expand all files Collapse all files

348
README.md
View file

@ -1,176 +1,221 @@
# DNS Bypass Config Generator
# bbrkn — DNS Bypass Config Generator
Этот проект автоматизирует генерацию конфигураций для **Pi-hole / dnsmasq**, чтобы маршрутизировать трафик к заблокированным доменам через VPN-туннель (WireGuard).
Автоматизирует генерацию конфигураций **Pi-hole / dnsmasq** для маршрутизации трафика заблокированных доменов через VPN-туннель (WireGuard).
Скрипт `generate-configs.sh`:
- нормализует входные доменные имена;
- для каждого домена запрашивает внешний API (Chromium headless service);
- определяет, является ли домен **сайтом** (site), **сервисом** (service) или **мертвым**;
- формирует конфиги:
- `91-ipset-bbrkn.conf` — правила `ipset` для маркировки трафика;
- `92-resolve-bbrkn.conf` — правила `server=` для резолвинга через Google DNS.
---
## Классификация доменов
1. **Сайт (site)**
API возвращает JSON с полем `relatedDomains`.
В конфиги попадает **сам домен** + все связанные домены.
2. **Сервис (service)**
API возвращает ошибку:
- `ERR_CERT_COMMON_NAME_INVALID`
- `ERR_CONNECTION_REFUSED`
В конфиги попадает только **сам домен**.
3. **Мертвый домен**
API возвращает ошибку:
- `ERR_NAME_NOT_RESOLVED`
- `Timeout`
Такие домены полностью исключаются из конфигов.
---
## Переменные окружения
| Переменная | Значение (по умолчанию) | Описание |
|----------------|-------------------------|----------|
| `DOMAINS_FILE` | `domains.txt` | Входной файл со списком доменов |
| `IPSET_CONF` | `/tmp/91-ipset-bbrkn.conf` | Файл с правилами ipset |
| `RESOLVE_CONF` | `/tmp/92-resolve-bbrkn.conf` | Файл с правилами server= |
| `CHROME_SERVER`| `http://127.0.0.1:3000` | Адрес API headless Chromium |
| `DNS_SERVER` | `8.8.8.8` | DNS для резолвинга через VPN |
| `DEBUG` | `0` | Включить (1) / выключить (0) отладку |
| `DEBUG_LOG` | `/tmp/generate-configs.debug.log` | Файл для подробного лога |
---
## Запуск
```bash
# обычный запуск
./generate-configs.sh
# отладочный режим
DEBUG=1 ./generate-configs.sh
# dry-run (ничего не пишет в файлы)
./generate-configs.sh --dry-run
````
После запуска будут сгенерированы файлы:
* `$IPSET_CONF` — список правил ipset;
* `$RESOLVE_CONF` — список правил server=.
---
## Интеграция в CI/CD
Переменные окружения передаются в `make` и далее в скрипт:
```yaml
jobs:
generate-configs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run generator
run: |
make generate-configs
env:
DOMAINS_FILE: domains.txt
IPSET_CONF: ./out/91-ipset-bbrkn.conf
RESOLVE_CONF: ./out/92-resolve-bbrkn.conf
CHROME_SERVER: http://chrome-headless:3000
DNS_SERVER: 8.8.8.8
```
Файл `Makefile` прокидывает переменные дальше:
```make
generate-configs:
./generate-configs.sh
```
---
## Архитектура решения
## Как это работает
```mermaid
flowchart TD
A[Клиент в локальной сети] -->|DNS запрос| B[Pi-hole DNS на шлюзе]
B -->|если домен заблокирован| C[Google DNS 8.8.8.8 через VPN]
C --> D[Ответ с IP]
D --> B
B -->|IP в ipset| E[iptables / netfilter]
E -->|маршрутизация по mark| F[VPN WireGuard]
F --> G[Интернет ресурс]
A[domains.txt] --> B[generate-configs.sh]
B -->|кэш .cache/api| B
B -->|MISS / EXPIRED| C[Chromium headless API]
C --> B
B --> D[91-ipset-bbrkn.conf]
B --> E[92-resolve-bbrkn.conf]
D --> F[deploy-to-gateway.sh]
E --> F
F -->|backup + copy| G[Pi-hole dnsmasq.d/]
F -->|docker restart| H[Pi-hole container]
F -->|DNS health check| H
H -->|rollback если упал| G
subgraph "CI/CD"
X[domains.txt] --> Y[generate-configs.sh]
Y --> P1[ipset conf]
Y --> P2[resolve conf]
subgraph "Трафик клиента"
K[Клиент] -->|DNS запрос| H
H -->|домен в ipset → mark| I[iptables]
I --> J[WireGuard VPN]
J --> L[Интернет]
end
```
---
## Диаграмма потока обработки
## Классификация доменов
```mermaid
sequenceDiagram
participant Client
participant PiHole
participant ChromeAPI
participant VPN
participant Internet
Для каждого домена из `domains.txt` скрипт обращается к Chromium headless API и классифицирует результат:
Client->>PiHole: DNS-запрос к домену
PiHole->>ChromeAPI: Проверка домена
ChromeAPI-->>PiHole: relatedDomains / error
PiHole->>VPN: Резолвинг через 8.8.8.8 (для заблокированных)
VPN->>Internet: Запрос к сайту
Internet-->>VPN: Ответ
VPN-->>PiHole: IP-адрес
PiHole-->>Client: Ответ DNS
Client->>Internet: Трафик с IP через VPN
| Результат API | Действие |
|---|---|
| JSON с `relatedDomains` | **Сайт** — добавляется домен + все связанные субдомены |
| JSON с `error: ERR_NAME_NOT_RESOLVED` или `Timeout` | **Мёртвый домен** — пропускается, в конфиг не попадает |
| JSON с любой другой ошибкой (`ERR_CERT_*`, `ERR_CONNECTION_REFUSED` и т.д.) | **Сервис** — добавляется только сам домен без субдоменов (не HTTP-сервис: SMTP, VPN, игровой сервер и т.п.) |
| API недоступен (не 200 / не JSON после всех попыток) | **Fallback** — домен всё равно добавляется без субдоменов; фиксируется в разделе отчёта `API FAILURES` |
> Любой домен из `domains.txt` гарантированно попадает в финальный конфиг, даже если API недоступен.
### Формат выходных файлов
Домены группируются по базовому домену с комментарием:
```
# example.com — 4 subdomains
ipset=/example.com/bbrkn
ipset=/static.example.com/bbrkn
ipset=/api.example.com/bbrkn
...
# some-service.com — 0 subdomains
ipset=/some-service.com/bbrkn
```
---
## Отчёт после запуска
## Структура проекта
Скрипт выводит статистику:
* количество строк во входном файле;
* сколько доменов нормализовано / отброшено;
* сколько API-ответов успешные, сервисные, мёртвые;
* список **валидных основных сайтов**.
```
bbrkn/
├── domains.txt # список доменов для обхода
├── Makefile # управление сборкой и деплоем
├── scripts/
│ ├── generate-configs.sh # генерация dnsmasq-конфигов
│ └── deploy-to-gateway.sh # деплой в Pi-hole + rollback
└── .forgejo/workflows/deploy.yaml # CI/CD на self-hosted runner
```
---
## Пример
## Makefile
```bash
make all # generate + deploy (полный цикл)
make generate # только сгенерировать конфиги
make deploy # только задеплоить в Pi-hole
make clean # удалить сгенерированные конфиги из /tmp
make cache-clean # очистить кэш API-ответов (.cache/api/)
make check # проверить синтаксис domains.txt
```
---
## Переменные окружения
### generate-configs.sh
| Переменная | По умолчанию | Описание |
|---|---|---|
| `DOMAINS_FILE` | `domains.txt` | Входной файл со списком доменов |
| `IPSET_CONF` | `/tmp/91-ipset-bbrkn.conf` | Выходной файл правил ipset |
| `RESOLVE_CONF` | `/tmp/92-resolve-bbrkn.conf` | Выходной файл правил server= |
| `CHROME_SERVER` | `http://127.0.0.1:3000` | Адрес Chromium headless API |
| `DNS_SERVER` | `8.8.8.8` | DNS-сервер для резолвинга через VPN |
| `IGNORE_PARTS` | _(пусто)_ | Подстроки через пробел — домены с совпадением игнорируются |
| `CACHE_DIR` | `.cache/api` | Директория кэша API-ответов |
| `CACHE_TTL_DAYS` | `15` | Время жизни кэша в днях; `0` — отключить кэш |
| `STRICT_MODE` | `0` | `1` — завершать с кодом 1 при любых ошибках API |
| `DEBUG` | `0` | `1` — включить подробный лог |
| `DEBUG_LOG` | `/tmp/generate-configs.debug.log` | Путь к файлу отладочного лога |
### deploy-to-gateway.sh
| Переменная | По умолчанию | Описание |
|---|---|---|
| `TARGET_DIR` | `/opt/appdata/pihole/etc/dnsmasq.d` | Директория dnsmasq в Pi-hole |
| `IPSET_CONF` | `/tmp/91-ipset-bbrkn.conf` | Сгенерированный файл ipset |
| `RESOLVE_CONF` | `/tmp/92-resolve-bbrkn.conf` | Сгенерированный файл server= |
| `DOCKER_CONTAINER` | `pihole` | Имя Docker-контейнера Pi-hole |
| `DNS_LISTEN_ADDR` | `127.0.0.1` | Адрес, на котором Pi-hole слушает DNS |
| `DNS_CHECK_DOMAIN` | `google.com` | Домен для DNS health check после рестарта |
---
## Кэш API-ответов
При каждом запуске ответы Chromium API сохраняются в `$CACHE_DIR/<domain>.json`. При повторном запуске:
- Если файл кэша **свежее** `CACHE_TTL_DAYS` дней → ответ берётся из кэша, Chromium не запускается.
- Если файл **старше** TTL → перезапрашивается и кэш обновляется.
- Если кэш **повреждён** (невалидный JSON) → перезапрашивается автоматически.
На self-hosted runner workspace сохраняется между запусками, поэтому повторные CI-запуски значительно быстрее.
```bash
# Сбросить кэш и запросить всё заново
make cache-clean && make generate
# Отключить кэш для одного запуска
CACHE_TTL_DAYS=0 make generate
```
---
## Деплой и автооткат
`deploy-to-gateway.sh` выполняет следующие шаги:
1. Проверяет наличие сгенерированных конфигов.
2. Создаёт timestamped-бэкапы текущих конфигов в `TARGET_DIR`.
3. Копирует новые конфиги в `TARGET_DIR`.
4. Перезапускает контейнер Pi-hole.
5. Ждёт запуска (до 30 секунд, polling через `docker inspect`).
6. Выполняет DNS health check через `dig` / `nslookup`.
7. При ошибке на шагах 5 или 6 — **автоматически откатывается**: восстанавливает бэкапы и перезапускает контейнер со старой конфигурацией.
---
## Запуск вручную
```bash
# Полный цикл
make all
# Только генерация (без деплоя)
make generate
# Dry-run — проверить что будет сгенерировано, ничего не записывать
./scripts/generate-configs.sh --dry-run
# Отладочный режим
DEBUG=1 make generate
# Строгий режим — завершить с ошибкой если часть доменов не опросилась
STRICT_MODE=1 make generate
```
---
## CI/CD
Workflow запускается при push в `main`, а также **вручную из UI** (`workflow_dispatch`).
```
push → main
└─ make clean
└─ make all
├─ generate-configs.sh (генерация с кэшем)
└─ deploy-to-gateway.sh (деплой + rollback)
└─ upload artifacts (конфиги + debug-лог, даже при падении)
```
Self-hosted runner работает непосредственно на шлюзе, поэтому деплой происходит локально без SSH.
---
## Пример отчёта
```
===== DEBUG REPORT =====
Input file: domains.txt
Raw input lines: 100
Processed lines: 100
Normalized OK: 97
Normalized skipped: 3
Input file: domains.txt
Raw input lines: 170
Processed lines: 170
Normalized OK: 165
Normalized skipped: 5
Ignored (IGNORE_PARTS): 12
API success (sites): 25
API error/ignored: 5
Related domains added: 122
Final unique domains: 140
Cache hits: 148 (TTL: 15d, dir: .cache/api)
Cache expired/refetched: 3
API success (sites): 11
API error/failed: 3
Related domains added: 87
Final unique domains: 256
---- VALID BASE SITES ----
example1.com
example2.org
example3.info
example.com
another-site.org
...
---- API FAILURES (added without subdomains) ----
some-domain.com → api_failed_added_without_subdomains
...
===== END DEBUG REPORT =====
```
@ -178,9 +223,14 @@ example3.info
## Зависимости
* `bash`
* `curl`
* `jq`
| Инструмент | Где используется |
|---|---|
| `bash` 4.2+ | оба скрипта |
| `curl` | запросы к Chromium API |
| `jq` | парсинг JSON-ответов |
| `docker` | перезапуск Pi-hole |
| `ipset` | сброс маршрутов после деплоя |
| `dig` или `nslookup` | DNS health check (опционально) |
---