# Хаб: запуск по шагам Хаб показывает статистику двух серверов Technitium DNS (`dns.shnt.top` и `ndns.shnt.top`) в одной консоли. Это один маленький контейнер. Он отдаёт ту же консоль и сам ходит в API обоих серверов по их токенам: - запрос «All servers» хаб отправляет на оба сервера и складывает ответы; - запрос к одному серверу хаб пересылает только ему; - запись хаб не выполняет никогда. Серверы Technitium не меняются, кластер не нужен. В инструкции хаб ставится на хост, где уже работают Traefik и `technitium-smart` (`docs/compose.shnt.example.yaml`). Адрес хаба: `https://hub.shnt.top`. ``` браузер ─► Traefik (hub.shnt.top, TLS) ─► technitium-hub:8080 ├─► https://dns.shnt.top/api/... (DNS_TOKEN) └─► https://ndns.shnt.top/api/... (NDNS_TOKEN) ``` Что хаб показывает: Dashboard (сумма или один сервер), Logs (View Logs и Query Logs, объединённые с колонкой Server) и About. Остальные разделы скрыты, ими управляют в консоли каждого сервера. --- ## Шаг 0. Образ хаба в реестре Образ `git.shx.one/denozord/technitium-hub` собирает отдельный workflow `.gitea/workflows/hub.yaml`. 1. Отправьте коммиты хаба на `git.shx.one`: ```bash git push origin main ``` 2. В репозитории на `git.shx.one` откройте **Actions** и дождитесь зелёного прогона **Hub**: - job `check` проверяет типы и тесты хаба; - job `image` собирает образ и кладёт его в реестр. 3. Убедитесь, что образ появился: в репозитории или профиле откройте **Packages**, там должен быть `technitium-hub` с тегом `latest`. Если job `image` упал на входе в реестр, проверьте секрет `ACTION_PAT` (или `ACTIONS_PAT`) в настройках репозитория: это токен Gitea с правом `write:package`. Он тот же, что использует образ консоли. Выпуск версии с номером (необязательно): ```bash git tag hub-v1.0.0 && git push origin hub-v1.0.0 ``` Тег даёт образы `1.0.0` и `1.0` в дополнение к `latest`. --- ## Шаг 1. Пользователь только для чтения на каждом сервере Сделайте это **на обоих серверах**: `https://dns.shnt.top` и `https://ndns.shnt.top`. Войдите в консоль сервера как администратор. 1. **Группа.** Administration › Groups › **Add Group**: имя `hub-readers`, описание любое. 2. **Права группы.** Administration › Permissions: у группы `hub-readers` отметьте только **View** в четырёх разделах: | Раздел | Зачем хабу | |---|---| | Dashboard | статистика, топы, график по часам, живые метрики | | Logs | список файлов логов и Query Logs | | Apps | список приложений логирования, из которых Query Logs читает записи | | Settings | состояние блокировки на Dashboard | Modify и Delete не отмечайте нигде. Остальные разделы оставьте без прав. 3. **Пользователь.** Administration › Users › **Add User**: имя `hub-reader`, длинный случайный пароль. Затем в карточке пользователя добавьте его в группу `hub-readers`. Из группы `Everyone` можно убрать, если у неё есть лишние права. 4. **API-токен.** Нужен токен именно для `hub-reader`, а не для администратора: - выйдите из консоли и войдите под `hub-reader`; - в меню пользователя внизу слева выберите **Create API Token**, имя токена `hub`; - скопируйте токен сразу: его показывают один раз. Можно и под администратором: Administration › Sessions › **Create Token**, пользователь `hub-reader`. 5. Проверьте токен с любой машины. В ответе должно быть `"status":"ok"`: ```bash curl -s "https://dns.shnt.top/api/dashboard/stats/get?type=LastHour&token=ТОКЕН" | head -c 200 ``` - `"status":"invalid-token"` значит, что скопирован не тот токен; - `"status":"error"` с сообщением об отказе в доступе значит, что у группы не хватает права View. Результат шага: два токена, `DNS_TOKEN` (с `dns.shnt.top`) и `NDNS_TOKEN` (с `ndns.shnt.top`). --- ## Шаг 2. DNS-запись для hub.shnt.top В Cloudflare (зона `shnt.top`) создайте запись `hub` той же формы, что `dns`: `A` на IP хоста или `CNAME` на `dns.shnt.top`. Сертификат Traefik получит сам. В compose уже настроен `certresolver=myresolver` с DNS-challenge через Cloudflare (`CF_DNS_API_TOKEN`), отдельно открывать порт 80 для проверки не нужно. --- ## Шаг 3. Файл .env На хосте в каталоге с `docker-compose.yml` откройте `.env` (там уже лежат `CF_DNS_API_TOKEN` и `DNS_SERVER_ADMIN_PASSWORD`) и добавьте: ```dotenv # Хаб: токены пользователей hub-reader с шага 1 DNS_TOKEN=вставьте_токен_dns NDNS_TOKEN=вставьте_токен_ndns # Вход в сам хаб (это НЕ логин Technitium) HUB_USER=admin HUB_PASSWORD=длинный_случайный_пароль ``` Пароль хаба нужен длинный: у хаба нет ограничения числа попыток входа. Сгенерировать можно так: ```bash openssl rand -base64 24 ``` Закройте `.env` от посторонних: ```bash chmod 600 .env ``` --- ## Шаг 4. Сервис в compose Добавьте в `docker-compose.yml` в раздел `services:` блок из `docs/compose.hub.example.yaml`: ```yaml technitium-hub: image: git.shx.one/denozord/technitium-hub:latest container_name: technitium-hub restart: unless-stopped networks: - dns-net environment: # id=адрес, по порядку; токен каждого берётся из _TOKEN - HUB_SERVERS=dns=https://dns.shnt.top,ndns=https://ndns.shnt.top - DNS_TOKEN=${DNS_TOKEN} - NDNS_TOKEN=${NDNS_TOKEN} - HUB_USER=${HUB_USER} - HUB_PASSWORD=${HUB_PASSWORD} - HUB_DOMAIN=hub.shnt.top - TZ=Asia/Novosibirsk labels: - "traefik.enable=true" - "traefik.docker.network=dns-net" - "traefik.http.routers.hub.rule=Host(`hub.shnt.top`)" - "traefik.http.routers.hub.entrypoints=websecure" - "traefik.http.routers.hub.tls.certresolver=myresolver" - "traefik.http.routers.hub.service=hub-svc" - "traefik.http.services.hub-svc.loadbalancer.server.port=8080" ``` Если хаб стоит в том же файле, что Traefik, отдельный блок `networks:` с `external: true` из примера не нужен: сеть `dns-net` в этом файле уже объявлена. Про имена в `HUB_SERVERS`: - имя слева от `=` видно в консоли в селекторе «Server»; - из имени получается переменная токена: `dns` даёт `DNS_TOKEN`, `ndns` даёт `NDNS_TOKEN`, `my-dns` дал бы `MY_DNS_TOKEN`; - первый в списке сервер считается основным. Адреса серверов указываются публичные (`https://dns.shnt.top`). API Technitium доступно по тому же адресу, что и консоль (роутер `panel-old` в Traefik), отдельный порт не нужен. --- ## Шаг 5. Запуск Если реестр закрытый, один раз войдите в него. Нужен токен Gitea с правом `read:package`: ```bash docker login git.shx.one ``` Скачайте образ и запустите хаб: ```bash docker compose pull technitium-hub docker compose up -d technitium-hub ``` Проверьте контейнер: ```bash docker compose ps technitium-hub # STATUS: Up ... (healthy) docker compose logs -f technitium-hub ``` В логе при старте не должно быть ошибок конфигурации. Если чего-то не хватает, хаб не запустится и назовёт переменную, например `NDNS_TOKEN is required for the server "ndns".` --- ## Шаг 6. Проверка 1. Откройте `https://hub.shnt.top` и войдите с `HUB_USER` / `HUB_PASSWORD` из `.env`. 2. На Dashboard над заголовком должен быть селектор **Server: All servers**. 3. Сверьте цифры. Total Queries в «All servers» должна равняться сумме значений в консолях `dns.shnt.top` и `ndns.shnt.top` за тот же период. Расхождение в пределах минуты нормально: хаб кеширует ответы на 15 секунд, а Last Hour обновляется на ходу. 4. Выберите в селекторе `dns`, затем `ndns`: цифры каждого сервера должны совпасть с его собственной консолью. 5. Откройте Logs › Query Logs, нажмите **Query**. Записи обоих серверов идут вместе, в колонке **Server** видно, чья запись. 6. Кнопка статуса справа в шапке показывает `hub.shnt.top`. Если какой-то сервер не ответил, там будет «1 server not answering», а по нажатию появится причина. Проверка без браузера (подставьте пароль хаба): ```bash T=$(curl -s -X POST https://hub.shnt.top/api/user/login \ --data-urlencode "user=admin" --data-urlencode "pass=ПАРОЛЬ_ХАБА" | sed -E 's/.*"token":"([^"]+)".*/\1/') curl -s -H "Authorization: Bearer $T" "https://hub.shnt.top/api/dashboard/stats/get?type=LastHour" | head -c 300 curl -s -H "Authorization: Bearer $T" "https://hub.shnt.top/api/dashboard/stats/get?type=LastHour&node=ndns" | head -c 300 ``` --- ## Обновление После нового прогона **Hub** в Actions: ```bash docker compose pull technitium-hub && docker compose up -d technitium-hub ``` Сессии хаба хранятся в памяти: после перезапуска контейнера нужно войти заново. Чтобы закрепить версию, укажите в compose тег вместо `latest`, например `technitium-hub:1.0.0`. ## Остановка и удаление ```bash docker compose stop technitium-hub # остановить docker compose rm -f technitium-hub # удалить контейнер ``` Чтобы отозвать доступ хаба к серверам, на каждом сервере удалите токен в Administration › Sessions или отключите пользователя `hub-reader`. --- ## Настройки хаба | Переменная | По умолчанию | Что задаёт | |---|---|---| | `HUB_SERVERS` | обязательна | Серверы по порядку: `id=https://адрес,...` | | `_TOKEN` | обязательна для каждого | API-токен сервера (`DNS_TOKEN`, `NDNS_TOKEN`, ...) | | `HUB_USER`, `HUB_PASSWORD` | обязательны | Вход в хаб | | `HUB_DOMAIN` | `hub` | Имя, которое консоль показывает как имя сервера | | `HUB_CACHE_SECONDS` | `15` | Сколько секунд хранить ответы серверов (0 выключает кеш) | | `HUB_TIMEOUT_MS` | `8000` | Сколько ждать ответа сервера, мс | | `HUB_PORT` | `8080` | Порт внутри контейнера | Третий сервер добавляется строкой в `HUB_SERVERS` и его токеном: ```yaml - HUB_SERVERS=dns=https://dns.shnt.top,ndns=https://ndns.shnt.top,lab=https://lab.shnt.top - LAB_TOKEN=${LAB_TOKEN} ``` --- ## Если что-то не так | Признак | Причина и что делать | |---|---| | Контейнер сразу завершается | В `docker compose logs technitium-hub` будет названа недостающая переменная. Проверьте `.env` и что compose его видит (`docker compose config \| grep TOKEN`). | | `https://hub.shnt.top` не открывается, ошибка сертификата | Нет DNS-записи `hub` (шаг 2) или Traefik ещё получает сертификат: смотрите `docker logs traefik`. | | 404 от Traefik | Контейнер не в сети `dns-net` или опечатка в `Host(\`hub.shnt.top\`)`. | | Вход в хаб: «Invalid username or password» | Неверные `HUB_USER`/`HUB_PASSWORD` в `.env`. После правки `.env` нужен `docker compose up -d technitium-hub`. | | В шапке «1 server not answering», в подсказке `ndns: its API token was refused` | Токен `NDNS_TOKEN` отозван или скопирован с ошибкой. Создайте новый (шаг 1.4) и перезапустите хаб. | | В подсказке `... did not answer: ...` или `ECONNREFUSED` / `timeout` | Хаб не достучался до сервера. Проверьте с хоста хаба: `docker exec technitium-hub node -e "fetch('https://ndns.shnt.top/api/status').then(r=>console.log(r.status))"`. | | В подсказке `ndns: ...` с сообщением об отказе в доступе | У группы `hub-readers` на этом сервере не хватает View в каком-то разделе (шаг 1.2). | | Query Logs пустой или «нет приложения» | На сервере не установлено приложение логирования (Query Logs (Sqlite) и подобные) или нет права View на Apps. | | Цифры «All servers» больше суммы на 1-2 клиента | Clients считается по каждому серверу отдельно: клиент, который ходит на оба сервера, учтён дважды. Это ожидаемо. | | Нажатие на что-то пишет «The hub is read-only.» | Хаб только читает. Изменения делаются в консоли нужного сервера. | ## Безопасность - Хаб только читает: любая запись получает отказ ещё в хабе, а токены выданы пользователю с одними правами View. - Токены лежат только в `.env` на хосте и в памяти контейнера. В браузер они не попадают, в ответы и логи хаба не пишутся. - У хаба один общий логин и нет ограничения попыток входа. Нужен длинный пароль, а если хаб не должен быть виден из интернета, добавьте к роутеру `hub` в Traefik `ipallowlist` или `basicAuth`.