docs: подробный README (разбор проекта при переносе в Gitea)

2026-08-20 04:19:13 +09:00
@@ -0,0 +1,89 @@
+# pistar — скрипты интеграции Pi-Star с XLX-рефлекторами
+
+Набор bash-скриптов для хотспотов на Pi-Star (Raspberry Pi + MMDVM). Скрипты прописывают в системные host-файлы Pi-Star адреса частных XLX-рефлекторов (YKT — Якутия, SMK — Смоленск, ARK — Москва), подменяют базу DMR ID на сборку с локальными якутскими записями и ставят systemd-таймер, который обновляет всё это каждые 10 минут. Предназначены для конечных пользователей хотспотов, которых подключают к этим рефлекторам: пользователь один раз выполняет одну команду по SSH, дальше обновления идут автоматически.
+
+Скрипты рассчитаны на распространение через HTTP: рабочая копия лежит на `https://xlx.dmrykt.ru/pistar/`, репозиторий — исходник для этой публикации. Скрипты скачивают друг друга с того же адреса, поэтому локальный `git clone` сам по себе установку не выполняет.
+
+## Стек
+
+- Bash (Pi-Star / Raspberry Pi OS, работа от root).
+- systemd (`.service` + `.timer`).
+- `wget`, `sed`, `mount -o remount,rw` (Pi-Star держит корень в read-only).
+- Внешняя зависимость: HTTP-хранилище `https://xlx.dmrykt.ru/pistar/` с этими же скриптами и файлами `DMRIds.dat`, `DMRIdsYKT.dat`.
+- Изменяемые файлы Pi-Star: `/usr/local/etc/XLXHosts.txt`, `YSFHosts.txt`, `DMR_Hosts.txt`, `P25Hosts.txt`, `DMRIds.dat`, `/usr/local/sbin/pistar-daily.cron`.
+
+## Структура
+
+| Файл | Назначение |
+|---|---|
+| `xlx.sh` | Точка входа для пользователя. Качает `xlx-del.sh` и `xlx-get.sh` с сервера, запускает их, затем последовательно `xlx-cron`, `xlx-gethost`, `xlx-getdmrid`, `xlx-update`, печатает прогресс 1/5…5/5 и `FINISH`. |
+| `get.sh` | Создаёт `/xlx/{scripts,temp,data,unit}`, качает скрипты и unit-файлы, делает симлинки в `/usr/local/bin/` (`xlx-cron`, `xlx-gethost`, `xlx-getdmrid`, `xlx-update`, `xlx-del`). |
+| `cron.sh` | Дописывает вызовы `xlx-gethost;xlx-rw;xlx-getdmrid-force` в `/usr/local/sbin/pistar-daily.cron`, создаёт симлинки на `xlx.service` и `xlx.timer` в `/etc/systemd/system`, включает и запускает таймер. |
+| `gethost.sh` | Основная логика. Через `sed`+`echo` прописывает записи рефлекторов в host-файлы Pi-Star: XLX 114/391/780 и алиасы YKT/SMK/ARK (порт 4004), YSF-рефлекторы (порт 42000), DMR-мастера (порты 62030/62032), P25 (порт 41000). Дублирует те же строки в `/root/`. |
+| `getdmrid.sh` | Качает `DMRIds.dat` и `DMRIdsYKT.dat`, вырезает из общей базы записи с префиксом `103`, склеивает с локальной якутской базой в `/usr/local/etc/DMRIds.dat`. |
+| `update.sh` | Обновляет сами скрипты и unit-файлы из HTTP-хранилища. |
+| `del.sh` | Деинсталлятор: выключает и удаляет юниты, откатывает `pistar-daily.cron`, удаляет симлинки `ykt-*` и старые файлы прошлой версии (`ykt-*`, `DMRIdsYKT.dat`), возвращает стоковый `DMRIds.dat`. |
+| `unit/xlx.service` | oneshot-юнит: `xlx-update`, `xlx-getdmrid`, `xlx-gethost`. |
+| `unit/xlx.timer` | Таймер `OnCalendar=*-*-* *:00/10:00` — запуск каждые 10 минут. |
+| `index.html` | HTML-инструкция для пользователя (публикуется рядом со скриптами): как зайти в Pi-Star, включить SSH и выполнить установочную команду. |
+| `unit/index.html` | Заглушка-индекс для каталога `unit/` на веб-сервере. |
+
+## Как запустить
+
+Установка на хотспоте (из `index.html`, выполняется по SSH под `pi-star`):
+
+```bash
+rpi-rw
+wget --user=yktsrv --ask-password https://xlx.dmrykt.ru/pistar/xlx.sh
+chmod +x ./xlx.sh
+sudo /home/pi-star/xlx.sh
+```
+
+Пароль для скачивания выдаётся владельцем при регистрации на рефлекторе, в репозитории его нет.
+
+Отдельные операции после установки:
+
+```bash
+sudo xlx-gethost     # переписать host-файлы Pi-Star
+sudo xlx-getdmrid    # обновить базу DMR ID
+sudo xlx-update      # обновить сами скрипты
+sudo xlx-del         # удалить всё, откатить настройки
+```
+
+Проверка автообновления:
+
+```bash
+systemctl status xlx.timer
+systemctl list-timers xlx.timer
+```
+
+Установка напрямую из этого репозитория не восстанавливается: `xlx.sh` и `get.sh` жёстко скачивают файлы с `xlx.dmrykt.ru`, а не используют локальные копии.
+
+## Конфигурация
+
+Переменных окружения нет, конфигурационных файлов нет. Все параметры зашиты в код:
+
+| Параметр | Где | Значение |
+|---|---|---|
+| Каталог установки | все скрипты | `XLXFOLDER=/xlx` |
+| Источник скриптов и данных | `get.sh`, `update.sh`, `getdmrid.sh`, `xlx.sh` | `https://xlx.dmrykt.ru/pistar/` |
+| Адреса рефлекторов | `gethost.sh` | XLX 114 / YKT — `89.111.154.99`, XLX 391 / SMK — `212.3.149.253`, XLX 780 / ARK — `46.138.248.163` |
+| Порты | `gethost.sh` | XLX 4004, YSF 42000, P25 41000, DMR master 62030 и 62032 |
+| Префикс, вырезаемый из общей базы DMR ID | `getdmrid.sh` | `103` (заменяется записями из `DMRIdsYKT.dat`) |
+| Пароль DMR-мастера | `gethost.sh` | строка `passw0rd` в `DMR_Hosts.txt` — значение по умолчанию, которое Pi-Star подставляет в MMDVMHost |
+
+## Состояние
+
+Рабочий, но замороженный набор скриптов. Последний коммит — 2025-07-31, всего 10 коммитов. Первый коммит — массовая загрузка файлов, остальные девять — переименование `xlx-*.sh` в короткие имена и мелкие правки. После июля 2025 работа не велась.
+
+Развитие темы перешло в репозиторий `xlx` (собственный XLX-сервер с веб-панелью и платной регистрацией), который делает то же самое со стороны сервера, а не хотспота.
+
+## Что не доделано
+
+- Переименование файлов не доведено до конца: `get.sh` и `xlx.sh` по-прежнему качают старые имена `xlx-cron.sh`, `xlx-getdmrid.sh`, `xlx-gethost.sh`, `xlx-update.sh`, `xlx-del.sh`, а `update.sh` — уже новые (`cron.sh`, `del.sh`, …). На сервере должны лежать оба комплекта, иначе первичная установка или обновление сломаются.
+- `del.sh` написан под прошлое поколение скриптов: выключает юниты `ykt.service`/`ykt.timer` и удаляет симлинки `ykt-*`, тогда как текущая версия ставит `xlx.service`/`xlx.timer` и `xlx-*`. Полной деинсталляции текущей версии он не делает.
+- В `del.sh` есть строка `if [ -d /xlx ]; then rm -rf /tmp; fi` — судя по контексту, имелся в виду `/xlx/temp`. В текущем виде удаляется системный каталог `/tmp`.
+- `cron.sh` прописывает в `pistar-daily.cron` команды `xlx-rw` и `xlx-getdmrid-force`, которых в репозитории нет — либо они существуют только на сервере, либо вызовы нерабочие.
+- В `gethost.sh` есть заведомо неточные шаблоны `sed`: `/^114*/d`, `/^391*/d`, `/^780*/d` в `P25Hosts.txt` (без точки перед `*`) удаляют больше строк, чем задумано.
+- Нет проверок ошибок `wget`, нет тестов, нет версионирования скриптов.
+- TODO/FIXME в коде отсутствуют.