Если что-то пошло не так
Сначала — журнал службы: journalctl -u netknownsthat -n 100 на хосте, journalctl -u netknownsthat-hub -n 100 на хабе, docker compose logs hub в Docker. Ошибки заданий — в разделе «Задания» с полным журналом; неудачные действия — в журнале действий.
Хост
| Симптом | Причина и что делать |
|---|---|
| Не пускает после входа, cookie не сохраняется | Открыто по HTTP, а NKT_COOKIE_SECURE=true. Для SSH-туннеля — NKT_COOKIE_SECURE=false, иначе HTTPS (NKT_TLS_ENABLED или прокси) |
403 cross-origin request refused | Запрос пришёл с другого origin: прокси не передаёт исходный Host или интерфейс открыт по другому имени. Передавайте Host, дополнительные origin — в NKT_CORS_ORIGINS |
| Страница «frontend не собран» | Бинарник собран раньше интерфейса: npm run build в web/, затем go build заново — go:embed запекает файлы при компиляции |
production mode only works on Linux | Рабочий режим — только Linux; для знакомства NKT_MODE=fixtures |
snapshot directory ... not found | Включён fixtures, а снапшота рядом нет. На сервере нужен local (он по умолчанию — значит, переменная задана явно); для разработки — запуск из корня репозитория или NKT_FIXTURES_ROOT |
could not create data directory /var/lib/netknownsthat | Запущено не от root: sudo или свой NKT_DATA_DIR |
Источники firewall и services недоступны | Нужен root: запускайте службой из deploy/ |
failed to connect to the docker API | Docker не запущен или другой сокет — NKT_DOCKER_SOCKET |
| Забыт пароль | sudo nkt passwd (или sudo nkt passwd <логин>). В крайнем случае — остановить службу и удалить /var/lib/netknownsthat/netknownsthat.db |
bind: address already in use | Порт занят — ошибка называет процесс (port already held by: nginx (pid 812)). Остановите его или смените NKT_ADDR |
nginx -t отклоняет исправный конфиг: open() "/var/log/nginx/error.log" failed (13: Permission denied) | Старый юнит без /var/log/{nginx,haproxy,caddy} в ReadWritePaths и CAP_DAC_OVERRIDE. Перезалейте юнит (sudo make install, «обновить» с хаба или вручную deploy/netknownsthat.service) и systemctl daemon-reload && systemctl restart netknownsthat |
Правки конфига: Read-only file system | Каталог только для чтения или нет доступа на запись в каталог логов, который открывает nginx -t |
| Кнопки неактивны, изменения отклоняются | Роль viewer или NKT_ALLOW_MUTATIONS=false |
Терминал: nsenter: reassociate to namespaces failed: Operation not permitted | util-linux 2.41 (Debian 13) входит в пространство имён через pidfd, песочница юнита это отклоняет. Исправлено в nkt 1.8.83 — обновите; обходится и установкой dbus |
| Терминал или установки не могут писать в систему | Нет D-Bus и нет запасного пути. Страница «Терминал» предложит «Установить dbus»; на хосте под хабом — «обновить», чтобы залить актуальный юнит |
| Вход системной учётной записью не работает | Нужен unix_chkpwd, учётка — в группе sudo/wheel/admin (root — всегда). Выключается NKT_SYSTEM_LOGIN=false; в хабе недоступен |
| Графики доступности и нагрузки пустые | Не работает планировщик: служба не запущена или NKT_SCHEDULER_ENABLED=false. TUI историю не собирает |
| «Файлы» показывают пустые папки | Старый юнит с ProtectHome=yes или PrivateTmp=yes — обновите nkt на хосте, юнит перепишется |
| Нечитаемые символы в консоли Windows | chcp 65001 |
После make build сломалась нативная сборка интерфейса | make web ставит в node_modules линуксовые сборки. npm install заново в web/ |
Хаб и хосты
| Симптом | Причина и что делать |
|---|---|
| Не пускает по SSH при добавлении | Проверьте вручную ssh -p <порт> <пользователь>@<адрес> с теми же данными. При «хаб сгенерирует ключ» чаще всего ключ ещё не в authorized_keys нужного пользователя |
| Ошибка ключа: «не похоже на PEM», «формат PuTTY», «защищён паролем» | Вставлен .pub, .ppk (экспорт в OpenSSH через puttygen) или ключ с паролем (ssh-keygen -p). Проще — «хаб сгенерирует ключ» |
| «ключ SSH хоста изменился» | Хост переустановлен — «забыть ключ хоста» в форме «изменить». Если не переустанавливали — разберитесь, кто отвечает на этом адресе |
permission denied при заливке, упоминание пароля или sudoers | У пользователя нет NOPASSWD. Выполните на хосте команды из текста ошибки: echo 'ИМЯ ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/nkt-hub и sudo chmod 0440 /etc/sudoers.d/nkt-hub — или укажите root |
| «исходники nkt не найдены (нет go.mod …)» и скачать не удалось | Хаб не нашёл клон (NKT_HUB_SOURCE_ROOT) и не смог скачать релиз с GitHub (нет доступа к github.com или версия не выпущена). Задайте путь к клону в hub.env или откройте исходящий доступ |
Настроенный go не запускается (snap под юнитом) | Ничего делать не нужно: хаб скачает свой Go в NKT_DATA_DIR/go-toolchain (нужен доступ к go.dev). В изолированной сети — поставьте Go и задайте NKT_HUB_GO_BIN |
| «неподдерживаемая архитектура» | Хост не Linux amd64/arm64/arm |
| «Job for netknownsthat.service failed» | В сообщении — хвост journalctl с хоста. Частое: status=226/NAMESPACE из-за отсутствующего /etc/haproxy в старом юните — обновите хаб, юнит перезальётся |
| Установка висит на «Жду, пока сервис ответит…» | На хосте нет systemd или порт API занят — systemctl status netknownsthat на хосте; свой «порт API» в форме хоста |
| Хост «недоступен», но SSH отвечает | Служба nkt не поднялась после обновления пакетов — ошибка прикладывает диагностику (юнит, порт, журнал). «Обновить» переустановит и перезапустит |
| Хост завис на «установка» | «Отменить» рядом с кнопкой. После перезапуска хаба чинится само |
| Колонка «Канал» всегда серая «не подключён» | Хаб не дозванивается на 8078 (NKT_HUB_TUNNEL_PORT): откройте порт с адреса хаба, проверьте, что nkt на хосте запущен и порт не занят |
| Загрузка файлов: часть не сохранилась | Соединение с хостом умерло в пуле (NAT, перезапуск sshd). Хаб меняет мёртвое соединение и повторяет файл до трёх раз; остальное — «повторить неудачные». Галочка «без скрытых» не шлёт .git, .env и игнорируемое |
| Забыт пароль администратора хаба | Docker: docker compose exec hub nkt passwd -random. systemd: sudo systemctl stop netknownsthat-hub && sudo env NKT_MODE=hub NKT_DATA_DIR=/var/lib/netknownsthat-hub nkt passwd -random && sudo systemctl start netknownsthat-hub. Пароль печатается только в терминал — с перенаправленным выводом (или docker compose exec -T) команда откажется |
| Хаб в Docker не стартует: том принадлежит root | Хаб в контейнере — uid 1000: docker run --rm -v <том>:/data alpine chown -R 1000:1000 /data |
| «Обновить» в «О системе» нет | Хаб не запущен systemd-юнитом (Docker, Kubernetes или ручной запуск) — обновляйте образ или поставьте хаб службой |
Задания
| Симптом | Причина и что делать |
|---|---|
| «Служба перезапустилась — продолжаю с сохранённого места» | Хаб или хост перезапускался посреди задания; задания, которые умеют продолжаться (установки, кластеры, сценарии), продолжаются сами |
| «задание прервано: служба перезапускалась посреди него больше 3 раз» | Задание, похоже, само роняет службу — хаб прекратил его продолжать, чтобы не уйти в цикл перезапусков. Посмотрите журнал службы (journalctl -u netknownsthat-hub) и сообщите об ошибке; повтор — кнопкой «попробовать снова» после обновления |
| «внутренняя ошибка исполнителя: …» | Ошибка в самом nkt при выполнении шага: задание остановлено, служба продолжает работать. Текст ошибки — в журнале задания; сообщите о ней |
| «попробовать снова» не предлагается | Задание этого вида не умеет продолжаться с места остановки — запустите действие заново |
| «Не удалось выполнить запрос. Failed to fetch» | Служба перезапускается или недоступна — подождите и обновите страницу |
Kubernetes и выкладки
| Симптом | Причина и что делать |
|---|---|
| «Открыть в браузере» у пода: страница без скриптов или стилей | Выключен отдельный порт пробросов (NKT_FORWARD_ADDR=off) — приложение в песочнице. Включите порт 8446 и пробросьте его в туннеле или за прокси (NKT_FORWARD_PUBLIC_URL) |
| Проброс не открывается через SSH-туннель | Пробросьте и 8446: ssh -L 8077:127.0.0.1:8077 -L 8446:127.0.0.1:8446 … |
Helm на хосте не установлен | Вкладка Kubernetes узла → Helm → «Установить Helm» |
| Выкладка не срабатывает | Таблица на странице Выкладки |
| nkt-edge «нет связи» | Таблица на странице nkt-edge |
API, вебхуки и боты
| Симптом | Причина и что делать |
|---|---|
| 401 «Неверный API-токен или подпись запроса» | Токен отозван или заменён («Новый секрет»), в строке не хватает части, или подпись считается не от того пути: путь — как его видит хаб, с ?запросом |
| 401 «Подпись запроса устарела» | Часы клиента и хаба расходятся больше чем на 5 минут — включите синхронизацию времени |
| 403 «API-токену недоступен вызов» | Вызов закрыт токенам (управление хабом, терминал, файлы) или нужна роль «администратор» |
| 403 «API-токену запрещён адрес» | Адрес не в списке токена. За обратным прокси хаб берёт адрес из X-Forwarded-For только с loopback — прокси должен быть на той же машине |
| 403 «не разрешён доступ через nkt-edge» | У токена нет галочки «через nkt-edge» |
| Исходящий вебхук: «ошибка» в последней доставке | Подсказка — у значка: адресат не ответил 2xx, недоступен или не принял подпись (секрет после «Новый секрет» — вставить заново) |
| Бот Telegram «нет связи» | Ошибка — в карточке: неверный токен, нет выхода к api.telegram.org, или тот же токен опрашивает другой хаб |
| Бот Telegram молчит в чате | Чата нет в списке (на /start бот назовёт номер), или команда без / |
| Slack: «dispatch_failed» или «operation_timeout» | Slack не достучался: нет edge с ролью «колбэки» (или он не подключён), неверный Request URL, хаб недоступен |
| Slack: 401 «bad signature» | Не тот Signing Secret, или часы хаба сбиты |