mirror of
https://github.com/LowderPlay/cheburcheck.git
synced 2026-10-01 03:07:56 +03:00
LowderPlay
6bf1fb4db2
* feat: probes aggregation layout * feat: rework map * feat: complaints * feat: probe contribution * fix: single verdict voting * feat: probe caching * chore: bump version * fix: merge conflict
305 lines
14 KiB
Markdown
305 lines
14 KiB
Markdown
# Cheburcheck Probe
|
||
|
||
[](https://github.com/LowderPlay/cheburcheck/actions/workflows/probe-build.yml)
|
||
|
||
Cheburcheck Probe (`cheburprobe`) — динамический сетевой сканер. Он подключается к Cheburcheck, получает задания на проверку доменов, выполняет их из вашей сети и отправляет технические результаты обратно.
|
||
|
||
Сканер помогает проверять доступность из разных сетей, регионов и хостингов. Он не принимает итоговое решение сам: Cheburcheck использует собранные им признаки при формировании результата.
|
||
|
||
## Быстрый старт
|
||
|
||
### 1. Получите ID и токен
|
||
|
||
Для запуска нужны `PROBE_ID` и `PROBE_TOKEN`. Чтобы получить их, [заполните форму](https://forms.gle/nZqBfXC65GebUKWB9).
|
||
|
||
Не публикуйте полученный токен и не добавляйте его в систему контроля версий.
|
||
|
||
### 2. Выберите способ установки
|
||
|
||
Готовые пакеты и бинарные файлы находятся на [странице релизов](https://github.com/LowderPlay/cheburcheck/releases), Docker-образ — в GitHub Container Registry: `ghcr.io/lowderplay/cheburcheck-probe`.
|
||
|
||
| Среда | Что использовать |
|
||
| --- | --- |
|
||
| Debian, Ubuntu и производные | `.deb` для amd64 или arm64 |
|
||
| Docker на Linux | образ для amd64 или arm64 |
|
||
| OpenWrt с `apk` (25.12+) | основной `.apk` и пакет LuCI `.apk` |
|
||
| OpenWrt с `opkg` | основной `.ipk` и пакет LuCI `.ipk` |
|
||
| Windows | экспериментальная standalone-сборка для x86-64 |
|
||
|
||
> [!WARNING]
|
||
> Поддержка Windows нестабильна. DPI-трассировка использует raw ICMP-сокеты, доставка
|
||
> ответов в которые зависит от Windows Firewall и сетевого драйвера. В частности,
|
||
> IPv6-прыжки могут отображаться как таймауты, даже если пакеты ICMPv6 Time Exceeded
|
||
> видны в анализаторе трафика. Для постоянной работы рекомендуется Linux.
|
||
|
||
### 3. Автоматическая установка Debian/OpenWrt
|
||
|
||
Интерактивный мастер определяет ОС, архитектуру и пакетный менеджер, получает список пакетов через сервер `cheburcheck.ru`, показывает текущую и доступную версии, а затем запрашивает подтверждение установки или обновления. Данные авторизации можно указать сразу или настроить позднее.
|
||
|
||
На Debian/Ubuntu выполните:
|
||
|
||
```shell
|
||
curl -fsSL https://cheburcheck.ru/install-probe.sh | sudo sh
|
||
```
|
||
|
||
На OpenWrt выполните от имени `root`:
|
||
|
||
```shell
|
||
wget -qO- https://cheburcheck.ru/install-probe.sh | sh
|
||
```
|
||
|
||
Перед запуском можно скачать и просмотреть скрипт отдельно:
|
||
|
||
```shell
|
||
curl -fSLO https://cheburcheck.ru/install-probe.sh
|
||
less install.sh
|
||
sudo sh install.sh
|
||
```
|
||
|
||
Если Cheburprobe уже установлен, мастер покажет установленную и последнюю версии и спросит разрешение на обновление. Существующие настройки авторизации можно сохранить.
|
||
|
||
Для автоматизированной установки передайте `PROBE_ID`, `PROBE_TOKEN` и `CHEBURPROBE_ASSUME_YES=1`.
|
||
|
||
По умолчанию в OpenWrt также устанавливается интерфейс LuCI. Чтобы установить только сервис, передайте `CHEBURPROBE_WITH_LUCI=0`. Для установки конкретного релиза можно передать `CHEBURPROBE_VERSION`, например `CHEBURPROBE_VERSION=0.5.0`.
|
||
|
||
## Debian и Ubuntu
|
||
|
||
1. На [странице релизов](https://github.com/LowderPlay/cheburcheck/releases) скачайте файл `cheburprobe_*.deb` для архитектуры вашей системы. Проверить архитектуру можно командой `dpkg --print-architecture`.
|
||
|
||
2. Установите пакет:
|
||
|
||
```shell
|
||
sudo apt install ./cheburprobe_*.deb
|
||
```
|
||
|
||
3. Откройте файл настроек:
|
||
|
||
```shell
|
||
sudo nano /etc/default/cheburprobe
|
||
```
|
||
|
||
Укажите выданные ID и токен. Адрес брокера обычно менять не требуется:
|
||
|
||
```shell
|
||
PROBE_ID=1
|
||
PROBE_TOKEN=ваш-токен
|
||
MQTT_HOST=wss://cheburcheck.ru/mqtt
|
||
MQTT_PORT=443
|
||
```
|
||
|
||
4. Запустите сервис и добавьте его в автозагрузку:
|
||
|
||
```shell
|
||
sudo systemctl enable --now cheburprobe.service
|
||
```
|
||
|
||
5. Убедитесь, что сканер работает:
|
||
|
||
```shell
|
||
systemctl status cheburprobe.service
|
||
journalctl -u cheburprobe.service -f
|
||
```
|
||
|
||
Пакет устанавливает systemd-сервис `cheburprobe.service`. Сервис работает без root-доступа и получает только capability `CAP_NET_RAW`, необходимую для traceroute.
|
||
|
||
## Docker
|
||
|
||
Образ `ghcr.io/lowderplay/cheburcheck-probe:latest` доступен для Linux amd64 и arm64. Скачайте его и запустите контейнер:
|
||
|
||
```shell
|
||
docker pull ghcr.io/lowderplay/cheburcheck-probe:latest
|
||
|
||
docker run -d \
|
||
--name cheburprobe \
|
||
--restart unless-stopped \
|
||
--cap-add NET_RAW \
|
||
-e PROBE_ID=1 \
|
||
-e PROBE_TOKEN=ваш-токен \
|
||
ghcr.io/lowderplay/cheburcheck-probe:latest
|
||
```
|
||
|
||
Проверьте состояние и логи:
|
||
|
||
```shell
|
||
docker ps --filter name=cheburprobe
|
||
docker logs -f cheburprobe
|
||
```
|
||
|
||
Для постоянной установки удобнее хранить параметры в отдельном файле, например `cheburprobe.env`, ограничить доступ к нему и передать Docker через `--env-file cheburprobe.env`; либо использовать Docker Compose.
|
||
|
||
## OpenWrt
|
||
|
||
Готовые пакеты выпускаются для `aarch64_generic`, `aarch64_cortex-a53` и `aarch64_cortex-a72`. Со [страницы релиза](https://github.com/LowderPlay/cheburcheck/releases) нужно скачать два файла: основной пакет `cheburprobe` для архитектуры роутера и универсальный пакет интерфейса `luci-app-cheburprobe`.
|
||
|
||
Сначала определите, какой пакетный менеджер используется:
|
||
|
||
```shell
|
||
command -v apk || command -v opkg
|
||
```
|
||
|
||
### OpenWrt с `apk`
|
||
|
||
Узнайте архитектуру:
|
||
|
||
```shell
|
||
apk --print-arch
|
||
```
|
||
|
||
Например, для `aarch64_cortex-a53` выберите основной файл с `_aarch64_cortex-a53.apk` в имени. Пакеты релиза не подписаны ключом вашего OpenWrt, поэтому при локальной установке требуется `--allow-untrusted`:
|
||
|
||
```shell
|
||
apk --allow-untrusted add \
|
||
./cheburprobe-*_<АРХИТЕКТУРА>.apk \
|
||
./luci-app-cheburprobe-*.apk
|
||
```
|
||
|
||
### OpenWrt с `opkg`
|
||
|
||
Посмотрите список поддерживаемых архитектур:
|
||
|
||
```shell
|
||
opkg print-architecture
|
||
```
|
||
|
||
Выберите архитектуру процессора, например `aarch64_cortex-a53`, а не универсальную `all`, и установите оба пакета:
|
||
|
||
```shell
|
||
opkg install \
|
||
./cheburprobe_*_<АРХИТЕКТУРА>.ipk \
|
||
./luci-app-cheburprobe_*_all.ipk
|
||
```
|
||
|
||
### Настройка OpenWrt
|
||
|
||
После установки откройте **Службы → Cheburprobe** в LuCI:
|
||
|
||
1. укажите **Probe ID** и **Probe token**;
|
||
2. включите **Enable service**;
|
||
3. нажмите **Сохранить и применить**.
|
||
|
||
Настройки также доступны через UCI в `/etc/config/cheburprobe`. Файл создаётся с правами `0600`, потому что токен хранится в открытом виде. Для проверки используйте:
|
||
|
||
```shell
|
||
/etc/init.d/cheburprobe status
|
||
logread -e cheburprobe
|
||
```
|
||
|
||
## Общие настройки
|
||
|
||
Параметры можно передавать через переменные окружения или аргументы командной строки. В Debian переменные задаются в `/etc/default/cheburprobe`, в Docker — через `-e` или `--env-file`. OpenWrt настраивается через LuCI/UCI.
|
||
|
||
| Аргумент / переменная | Назначение | По умолчанию |
|
||
| --- | --- | --- |
|
||
| `--probe-id`, `PROBE_ID` | ID сканера | обязательный параметр |
|
||
| `--probe-token`, `PROBE_TOKEN` | Секретный токен | обязательный параметр |
|
||
| `--mqtt-host`, `MQTT_HOST` | URL MQTT-брокера; `ws://` или `wss://` | `wss://cheburcheck.ru/mqtt` |
|
||
| `--mqtt-port`, `MQTT_PORT` | Порт MQTT-брокера | `443` |
|
||
| `--mqtt-connection-timeout-secs`, `MQTT_CONNECTION_TIMEOUT_SECS` | Таймаут подключения, секунды | `30` |
|
||
| `--max-concurrent-tasks`, `MAX_CONCURRENT_TASKS` | Максимум одновременных заданий | `8` |
|
||
| `--traceroute-retries`, `TRACEROUTE_RETRIES` | Число одновременных TCP-попыток на каждом TTL | `3` |
|
||
| `RUST_LOG` | Уровень логирования | `info` |
|
||
|
||
`MAX_CONCURRENT_TASKS` и `TRACEROUTE_RETRIES` должны быть больше нуля.
|
||
|
||
## Автоматические обновления
|
||
|
||
Пакеты Debian и OpenWrt каждые шесть часов проверяют последний опубликованный релиз. Манифест и файлы обновления загружаются через `https://cheburcheck.ru`, поэтому хосту со сканером не требуется доступ к GitHub. При появлении новой версии пакет обновляется, а сервис перезапускается. В OpenWrt пакет LuCI обновляется вместе с основным.
|
||
|
||
Автообновления включены по умолчанию. Отключить их в Debian можно командой:
|
||
|
||
```shell
|
||
sudo systemctl disable --now cheburprobe-update.timer
|
||
```
|
||
|
||
В OpenWrt используйте переключатель в LuCI или команды:
|
||
|
||
```shell
|
||
uci set cheburprobe.main.auto_update='0'
|
||
uci commit cheburprobe
|
||
/etc/init.d/cheburprobe-updater restart
|
||
```
|
||
|
||
Интервал проверки OpenWrt задаётся параметром `update_interval` в `/etc/config/cheburprobe`. Ручная проверка доступна независимо от настроек:
|
||
|
||
```shell
|
||
/usr/bin/cheburprobe update
|
||
```
|
||
|
||
На Windows updater скачивает новую версию и заменяет текущий executable:
|
||
|
||
```powershell
|
||
cheburprobe.exe update
|
||
```
|
||
|
||
Standalone-сборки Linux и Windows обновляются только ручной командой `cheburprobe update`.
|
||
|
||
Docker-контейнер не обновляет образ автоматически. Для обновления скачайте новый образ и пересоздайте контейнер с прежними параметрами.
|
||
|
||
## Диагностика
|
||
|
||
Если сканер не подключается:
|
||
|
||
- проверьте `PROBE_ID` и `PROBE_TOKEN`;
|
||
- убедитесь, что `MQTT_HOST` начинается с `ws://` или `wss://`;
|
||
- проверьте доступность `MQTT_HOST:MQTT_PORT` из сети сканера;
|
||
- изучите логи (`journalctl`, `docker logs` или `logread` — в зависимости от установки);
|
||
- временно задайте `RUST_LOG=debug`.
|
||
|
||
## Для разработчиков
|
||
|
||
### Запуск из исходников
|
||
|
||
Из корня репозитория:
|
||
|
||
```shell
|
||
PROBE_ID=1 \
|
||
PROBE_TOKEN=ваш-токен \
|
||
MQTT_HOST=wss://cheburcheck.ru/mqtt \
|
||
MQTT_PORT=443 \
|
||
cargo run --package probe --bin cheburprobe
|
||
```
|
||
|
||
Те же обязательные параметры можно передать аргументами:
|
||
|
||
```shell
|
||
cargo run --package probe --bin cheburprobe -- \
|
||
--probe-id <ID_СКАНЕРА> \
|
||
--probe-token <ТОКЕН_СКАНЕРА>
|
||
```
|
||
|
||
### Сборка пакетов
|
||
|
||
Debian-пакет собирается через `cargo-deb`:
|
||
|
||
```shell
|
||
cargo deb --package probe -- --bin cheburprobe
|
||
```
|
||
|
||
Docker-образ собирается из корня репозитория:
|
||
|
||
```shell
|
||
docker build -f probe/Dockerfile -t cheburprobe:local .
|
||
```
|
||
|
||
Для сборки OpenWrt-пакета другой архитектуры задайте `OPENWRT_ARCH`:
|
||
|
||
```shell
|
||
OPENWRT_ARCH=aarch64_cortex-a53 \
|
||
probe/openwrt/build-apk.sh <binary> <output-dir>
|
||
|
||
OPENWRT_ARCH=aarch64_cortex-a53 \
|
||
probe/openwrt/build-ipk.sh <binary> <output-dir>
|
||
```
|
||
|
||
### Как работает проверка
|
||
|
||
После подключения сканер:
|
||
|
||
1. публикует retained-статус `online` в MQTT;
|
||
2. подписывается на конфигурацию динамического сканирования;
|
||
3. получает задания на проверку доменов и IP-адресов;
|
||
4. параллельно запускает SNI-проверки для доменов и TCP traceroute до цели, начиная со следующего после DPI узла;
|
||
5. отправляет результат обратно в Cheburcheck.
|
||
|
||
Для каждого тестового хоста сканер открывает TCP-соединение, начинает TLS-handshake с проверяемым доменом в SNI, затем отправляет простой HTTP GET-запрос. Валидация TLS-сертификата намеренно отключена: измеряется доступность соединения, а не доверие к сертификату.
|