Устранение неполадок

У каждого сбоя, о котором сообщает Signal Lab, есть код; сообщение для каждого — в сообщениях об ошибках. Сетевые сбои — это коды transport: refused, timeout, dns, unreachable, reset, address_in_use, address_unavailable, denied, tls, target_invalid, failed. Ниже — самые частые проблемы.

Ничего не приходит

Сначала выясните, доходит ли что-нибудь до Signal Lab вообще: откройте вкладку Инспектор в нижней панели и нажмите Включить захват. Там перечислены все датаграммы, запросы и сообщения, которые отправляет или принимает любой инструмент, с указанием, откуда они пришли.

Адрес прослушивания

• Значение поля Адрес прослушивания 0.0.0.0:<port> слушает на всех сетевых картах; 127.0.0.1:<port> слышит только эту машину. Оборудованию в сети нужно первое.
• Устройство должно отправлять на адрес этой машины и на порт, который вы слушаете. Шапка показывает имя и адрес этой машины.
• Адрес, который не принадлежит этой машине, даёт address_unavailable.

Брандмауэр

Трафик на 127.0.0.1 никогда не фильтруется, поэтому тест на одной машине работает, а тот же тест с другой машины ничего не получает.

Windows. Брандмауэр Windows решает для каждой программы отдельно. Обычно Windows спрашивает один раз, когда программа впервые начинает слушать, — и нажатие Отмена там оставляет правило, которое блокирует её и сильнее любого разрешающего. В сети, которую Windows считает публичной (часто это Wi-Fi площадки), он может не спросить вовсе.

• Настольное приложение смотрит на брандмауэр один раз, когда монитор, приёмник обнаружения, реле, запуск или эмулятор начинает слушать. Если брандмауэр мешает, приложение сообщает об этом в уведомлении с кнопкой Разрешить — а в публичной сети с кнопкой Разрешить, и в публичных сетях. Windows запрашивает права администратора, после чего входящие правила программы, включая блокирующее, заменяются одним разрешающим. Кнопка Не сейчас скрывает уведомление.
• Из терминала: signallab doctor показывает, что мешает, а signallab firewall allow исправляет это (--public — и для публичных сетей) с тем же запросом прав администратора.
• Установщик (.exe), установленный для всех, сам добавляет разрешающие правила (частные и доменные сети), если его не запускали с /NOFIREWALL. Установщик для меня этого сделать не может, а .msi оставляет брандмауэр тому, кто развёртывает.
• Сервер никогда не меняет брандмауэр своего хоста: порты открывает его администратор (скрипт установки предлагает это сделать через ufw или firewalld).

Linux. Брандмауэр вроде ufw или firewalld работает по портам, а не по программам. signallab doctor называет тот, что включён, и способ открыть порт, например sudo ufw allow 9000/udp.

Широковещание и multicast

• Маршрутизаторы не пересылают широковещание: 255.255.255.255 и x.x.x.255 доходят только до сегмента сети, в котором находится отправляющая карта. Если карт несколько, укажите адрес карты в поле Локальный адрес (источник) (в разделе параметры сокета), например 10.0.0.5:0.
• Датаграмма multicast доходит только до слушателей, которые присоединились к её группе, — в приёмнике обнаружения это поле Подписка на multicast-группы. При значении 1 в поле TTL / хопы (по умолчанию) она остаётся в этой сети.
• Чтобы слышать собственный multicast на той же машине, оставьте включённым параметр возвращать копию на этот хост.

Устройство не отвечает

У UDP нет подтверждения доставки: датаграмма, отправленная на порт, который никто не слушает, всё равно считается отправленной. Windows затем сообщает полученное в ответ ICMP port unreachable как сброс соединения при следующем приёме на этом сокете; мониторы, слушатели, реле и ожидания Signal Lab его игнорируют и продолжают слушать. Поэтому, если ответ не приходит, ожидание завершается ошибкой wait.timeout по истечении своего времени, а не ошибкой отправки. Проверьте в Инспектор, что сообщение ушло по нужному адресу, а затем проверьте устройство.

Отправка отклоняется до выхода в сеть

Это проверяется в первую очередь, и если проверка не пройдена, ничего не отправляется:

Код	Почему	Что делать
transport.target_invalid	У адресата нет порта, или он не IP:port и не host:port	Укажите и то, и другое, например 192.0.2.20:9000
transport.dns	Имя хоста не разрешается на этой машине	Проверьте имя или используйте адрес. Имя с адресом IPv4 достигается по IPv4, поэтому localhost:9000 находит приёмник на 127.0.0.1
node.osc_address	Адрес OSC не начинается с / — в отправителе, генераторе, сигнале или шаге	Начните его с /, например /cue/go
node.topic_wildcard	В топике публикации MQTT есть + или # — и на соединении экрана, и везде	Публикуйте в один топик; подстановочные знаки нужны для подписки
node.too_long для сообщения WebSocket	Сообщение больше 16 МиБ	Отправьте меньше; соединение остаётся открытым

Порт уже занят

transport.address_in_use: другая программа — или другая задача Signal Lab — уже слушает на этом порту.

• Монитор и запуск. Запуск открывает порты своих ожиданий, эмуляторов и реле до первого шага, поэтому порт, занятый блоком Монитор, приёмником обнаружения или задачей эмулятора, приводит к ошибке запуска до его начала. Сначала остановите эту задачу; кнопка Остановить всё останавливает все.
• Два эмулятора в одном запуске не могут делить порт одного транспорта: эмуляторы HTTP, MQTT и TCP слушают на TCP, а OSC и UDP — на UDP (emulator.bind_taken).
• Слушать рядом с настоящей службой. Приёмник обнаружения может делить порт с программой, которая его уже занимает: оставьте включённым делить порт. В Linux та программа тоже должна допускать общий порт. Без этого занятый порт — это broadcast.port_shared.
• Только что остановлено. Порт, который держал остановленный эмулятор или запуск, освобождается через мгновение; эмулятор, запущенный сразу снова, недолго его ждёт.
• Порты ниже 1024 в Linux требуют прав администратора (denied). Образ сервера работает без них, поэтому используйте порт 1024 или выше.

Сервер в Docker не достаёт до сети

Широковещание, multicast и обнаружение достигают физической сети только при сети хоста — network_mode: host в файле compose или docker run --network host — и только на хосте Linux. Она же позволяет мониторам, ожиданиям и эмуляторам слушать на собственных портах хоста. В сети-мосте Docker по умолчанию контейнер находится в собственной сети: широковещание и multicast не покидают её, а достигают контейнера только опубликованные вами порты.

В Windows и macOS сеть хоста Docker не достаёт до физической сети: используйте настольное приложение в Windows или запустите сервер на хосте Linux.

SmartScreen предупреждает об установщике

Установщики пока не подписаны, поэтому Windows SmartScreen пишет, что не знает издателя. Выберите Подробнее, затем Выполнить в любом случае. Скачивайте установщики только со страницы релизов проекта на GitHub.

Сервер не запускается

signal-lab-server проверяет свои настройки до того, как начнёт слушать, и завершается с сообщением в поток ошибок:

Код выхода	Сообщение	Что делать
2	refusing to listen on … without a token	Серверу, до которого могут добраться другие, нужен токен: --token-file или SIGNALLAB_TOKEN (создайте его командой signal-lab-server token) либо --generate-token. Или слушайте на 127.0.0.1
2	the token has N characters; it needs at least 24	Используйте токен подлиннее
2	the token must not contain spaces or line breaks	Файл токена может заканчиваться переводом строки; больше ничего
2	give the token once	Используйте --token/SIGNALLAB_TOKEN или --token-file/SIGNALLAB_TOKEN_FILE, но не оба
2	--generate-token keeps the token in the data folder	Задайте --data-dir или SIGNALLAB_DATA_DIR
2	… it does not hold a valid token; remove it to have a new one made	Файл token в папке данных повреждён
2	cannot read the token file …	Файл, названный в --token-file, отсутствует или недоступен для чтения этому пользователю
2	cannot save the new token in …	--generate-token не смог записать token в папку данных: сделайте папку доступной для записи этому пользователю
1	cannot listen on …	Адрес не принадлежит этой машине или порт занят
1	the data folder … must be writable by this user	В Docker примонтированная папка должна быть доступна для записи uid 10001

Токен, созданный через --generate-token, печатается один раз при первом запуске (docker logs signallab его покажет) и хранится в token в папке данных: docker exec signallab cat /data/token. См. сервер.

Не удаётся войти на сервер

Что вы видите	Почему	Что делать
Токен не подходит.	Неверный токен	Скопируйте его заново оттуда, где его хранит сервер; ответ занимает секунду намеренно
auth.host	Сервер не отвечает на имя из адресной строки	Откройте его по имени, которое он принимает. Имена loopback (localhost, 127.x.x.x, [::1]) проходят всегда. Без токена сервер отвечает только на них и на имена из --allowed-host; с токеном — на любые имена, если --allowed-host их не сужает
auth.origin	Запрос пришёл со страницы другого источника	За обратным прокси передавайте серверу Host браузера (nginx: proxy_set_header Host $host;), чтобы Origin и Host совпадали
После входа снова страница входа	Браузер не сохранил cookie сессии	С --secure-cookie к серверу нужно обращаться по HTTPS
Через какое-то время вас вывело из системы	Сессии живут 7 дней и заканчиваются при перезапуске сервера; сверх 1024 сессий самая старая уходит	Войдите снова

Соединение с сервером постоянно обрывается

Связь с сервером потеряна — переподключаюсь… означает, что закрылся сокет событий страницы, /api/events. Страница переподключается сама — через полсекунды, затем реже, до одного раза в 15 с. То, что произошло за это время, заново не воспроизводится: работающие задачи сообщают о себе снова по мере работы. За обратным прокси убедитесь, что он пропускает переходы на WebSocket для /api/events и не закрывает тихие соединения быстрее чем за 20 с (сервер отправляет ping каждые 20 с). Страница, которая сообщает, что у сервера нет такого адреса (api.not_found), старше сервера: перезагрузите её.

MQTT не подключается

Signal Lab говорит по MQTT 3.1.1 поверх обычного TCP. Он подключается и ждёт ответа брокера (CONNACK), прежде чем сообщить об успехе, поэтому причина указана на кнопке подключения:

Код	Почему	Что делать
transport.refused	На этом порту ничего не слушает	Проверьте порт: обычно это 1883
transport.timeout	Нет соединения TCP за 6 с	Проверьте адрес, сеть, брандмауэр брокера
transport.dns	Имя хоста не разрешается	Проверьте имя или используйте адрес
transport.unreachable	Нет маршрута до брокера	Проверьте сеть и адрес
transport.reset	Брокер сразу закрыл соединение	Часто это порт TLS (8883) — Signal Lab не говорит по MQTT поверх TLS
mqtt.no_answer	Порт открыт, но CONNACK не пришёл за 6 с	Часто это порт WebSocket — Signal Lab не говорит по MQTT поверх WebSocket
mqtt.protocol	Ответил не брокер MQTT	Проверьте порт
mqtt.refused_protocol	Брокер не принимает MQTT 3.1.1	Включите 3.1.1 на брокере
mqtt.refused_client_id	Брокер отклоняет идентификатор клиента	Используйте другой идентификатор клиента
mqtt.refused_unavailable	Брокер недоступен	Повторите позже
mqtt.refused_credentials	Неверное имя пользователя или пароль	Проверьте их
mqtt.refused_not_authorized	Пользователю нельзя подключаться	Проверьте правила доступа брокера
mqtt.client_id_required	Идентификатор клиента пуст	Заполните его

Брокер разрывает более старое из двух соединений с одним идентификатором клиента: если соединение постоянно закрывается, поищите другого клиента с тем же идентификатором.

Сертификату не доверяют

transport.tls, для https:// или wss://: сертификату сервера не доверяют, он не называет запрошенный вами хост, либо не удалось договориться о TLS. Signal Lab проверяет сертификаты так же, как система, и не имеет переключателя, который пропускал бы проверку. HTTPS и WSS доверяют одним и тем же сертификатам: сертификатам операционной системы, где работает движок, — хранилищу сертификатов Windows в Windows, системным сертификатам ЦС в Linux и в образе сервера. Для самоподписанного сертификата или вашего собственного ЦС добавьте его в доверенные сертификаты этой машины (для образа сервера — в образ, собранный на его основе и добавляющий сертификат) и подключайтесь по имени, которое несёт сертификат.

Секрета нет

secret.missing: эксперимент использует {{secret.NAME}}, а под этим именем там, где он выполняется, значение не сохранено.

• Настольное приложение в Windows: задайте его в окне Секреты внутри окна Параметры редактора. Оно хранится в Диспетчере учётных данных Windows, поэтому на новой машине его нужно задать снова.
• Сервер: положите значение в файл /run/secrets/signallab/NAME (или в папку, названную в --secrets-dir) либо в переменную окружения SIGNALLAB_SECRET_NAME. Сервер не может задавать секреты со страницы (secret.read_only).
• В настольном приложении в Linux нет хранилища секретов (secret.unsupported). Выполняйте такой эксперимент через signallab run, который читает секреты из файлов и переменных, или на сервере.

См. файлы.

Запуск останавливается через пять минут

Запуск, который идёт дольше 300 с, завершается ошибкой run.timeout; это самое долгое, что может длиться запуск. Более короткий предел можно задать запуску через API (timeout в /api/run) или командную строку (signallab run --timeout).

Приложение не обновляется

• Настольное приложение ищет новую версию раз в день, пока включён параметр Проверять раз в день, и когда вы нажимаете Проверить обновления в окне О программе.
• Сначала оно спрашивает узел студии (hub), а когда он недоступен — GitHub. Когда сеть блокирует и то и другое, Проверить обновления отвечает сообщением Не удалось проверить обновления; ежедневная проверка терпит неудачу молча.
• Ему предлагаются только опубликованные релизы, никогда не черновики и не предварительные версии.
• Новый релиз доходит до приложения, когда его предлагает hub, и это может случиться спустя какое-то время после появления на GitHub: hub раскатывает релиз по долям установок.
• Оно устанавливается только когда вы нажимаете Установить и перезапустить — работающие задачи сначала останавливаются — и только для релиза, подпись которого сходится; иначе появляется сообщение Обновление не установлено.
• Сервер обновляется вместе со своим образом: docker compose pull && docker compose up -d в папке его файла compose.

Где журналы

• Настольное приложение: оно не пишет файлов журнала. Вкладка Консоль в нижней панели перечисляет, что сделал каждый инструмент и что пошло не так, а кнопка Написать разработчикам прикладывает её к сообщению разработчикам (без имени этого компьютера, его адреса и ваших папок). Отчёт каждого запуска лежит в runs/ в папке данных.
• Сервер: он пишет в стандартный вывод и вывод ошибок — в Docker это docker logs signallab. Каждый старт задачи записывается с адресом клиента, который его запросил. --log (или SIGNALLAB_LOG) задаёт уровень: error, warn, info (по умолчанию) или debug; --log-format json (или SIGNALLAB_LOG_FORMAT) пишет по одному объекту JSON на строку.
• Командная строка: signallab пишет свои сообщения в вывод ошибок; см. командную строку.