Если self-hosted runner становится offline после перезагрузки, чаще всего агент запускался вручную, служба не включена, изменилась рабочая директория или не поднялась зависимость вроде Docker и сети.
Проверьте статус системной службы, журнал текущей загрузки и пользователя процесса. Не перерегистрируйте runner, пока не ясно, сохранилась ли существующая конфигурация.
Коротко: что сделать
- Проверить systemctl status runner-службы
- Проверить enable и автозапуск
- Посмотреть journalctl -b
- Проверить пользователя и права каталога
- Проверить сеть, DNS и Docker после boot
Почему возникает проблема
Runner состоит из агента, локальной конфигурации и внешней регистрации. Повторная регистрация не исправляет локальный сбой запуска и может создать дубликаты.
- Агент запускался в tmux или shell
- Unit существует, но не включен
- WorkingDirectory находится на поздно монтируемом диске
- Секрет или токен недоступен пользователю службы
- Docker socket еще не готов
- Firewall или DNS блокирует соединение после старта
Пошаговая диагностика
Проверку лучше проводить на одном воспроизводимом примере и фиксировать результат каждого шага. Так можно быстро отделить первопричину от побочных ошибок и не менять несколько компонентов одновременно.
- Проверить имя и состояние unit
- Посмотреть exit code и первые ошибки загрузки
- Запустить агент от имени сервисного пользователя
- Проверить доступ к рабочему каталогу и socket Docker
- Проверить исходящий HTTPS к CI-платформе
- Проверить labels и scope runner в панели
Как исправить
Надежное решение — оформить агент как ограниченную службу с корректными зависимостями и постоянным рабочим каталогом.
- Установить официальный service unit
- Включить systemctl enable
- Добавить After=network-online.target и нужные dependencies
- Исправить владельца рабочего каталога
- Настроить Restart=on-failure с разумной задержкой
- Оставить одну актуальную регистрацию runner
Как проверить результат
- Перезапустить службу и выполнить тестовый pipeline
- Сделать контролируемый reboot
- Проверить автоматическое появление online
- Проверить job с Docker и артефактами
- Убедиться, что runner работает не от root без причины
Как не допустить повторения
Runner должен восстанавливаться после reboot без ручного входа на сервер.
- Мониторить offline-состояние
- Хранить unit и настройки в конфигурационном управлении
- Очищать рабочий каталог по политике
- Планово обновлять runner
Чего не стоит делать
- Не создавать новый runner при каждом reboot
- Не хранить registration token в открытом unit
- Не запускать произвольные внешние задания с привилегированного runner
- Не использовать Restart=always без анализа постоянной ошибки
Что подготовить для диагностики
- Платформа CI и версия runner
- Вывод systemctl status
- Журнал текущей загрузки
- Unit-файл без секретов
- Список зависимостей job
Частые вопросы
Нужно ли заново регистрировать runner?
Только если регистрация действительно удалена или токен отозван. Сначала проверьте локальную конфигурацию и службу.
Почему он стартует вручную, но не как service?
Служба работает с другим пользователем, окружением, PATH и рабочей директорией.
Можно ли запускать runner от root?
Технически можно, но это резко увеличивает последствия уязвимого или ошибочного pipeline. Лучше отдельный ограниченный пользователь.
Когда стоит обратиться за помощью
Помощь нужна, если runner выполняет production-деплой, использует Docker-in-Docker, закрытую сеть или после reboot запускается с неполными правами.
Итог
Self-hosted runner должен быть управляемой службой с корректным порядком загрузки и минимальными правами. Настроить стабильный CI/CD можно через @rabotator_support.