Диагностика проблем подключения Jenkins: сетевые проблемы и проблемы с агентами

Jenkins сильно зависит от надежной связи между центральным контроллером и его средами выполнения (агентами или узлами). Когда это соединение нарушается, сборки останавливаются, конвейеры замирают, и непрерывная интеграция прекращается. Диагностика этих проблем требует системного подхода, часто начиная с топологии сети, затем переходя к конфигурации агентов и ошибкам протоколов.

Это подробное руководство содержит пошаговые инструкции по устранению наиболее распространенных проблем подключения Jenkins, включая неуловимые проблемы с брандмауэрами, неправильно настроенные порты JNLP и ошибки запуска агентов, помогая быстро восстановить стабильную работу и надежные конвейеры CI/CD.

---

1. Понимание связи контроллера и агента Jenkins

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

1.1 Протокол запуска сетевых приложений Java (JNLP)

В модели JNLP агент Jenkins инициирует соединение с контроллером. Это рекомендуемый и наиболее распространенный подход. Агент подключается к определенному порту на контроллере, который теперь обычно называется портом TCP входящего агента.

• Направление: Агент подключается к контроллеру.
• Требуемый порт: Порт TCP входящего агента контроллера (по умолчанию часто 50000 или назначается динамически).

1.2 Secure Shell (SSH)

В модели SSH контроллер Jenkins инициирует соединение с агентом. Это требует, чтобы на машине агента был запущен SSH-сервер.

• Направление: Контроллер подключается К агенту.
• Требуемый порт: SSH-порт агента (обычно 22).
• Требование: Учетные данные SSH (ключи или пароли) должны быть правильно настроены в Jenkins.

2. Первоначальная диагностика сети и брандмауэра

Сетевые проблемы, особенно ограничения брандмауэра, являются наиболее частой причиной проблем с подключением. Если агент внезапно отключается или новый агент не может подключиться, начните здесь.

2.1 Проверка открытых портов

Вы должны убедиться, что трафик может проходить через необходимые порты в соответствии с вашей моделью связи.

Тип подключения	Источник	Назначение	Требуемый порт	Проверка состояния
Веб-интерфейс	Пользователь/Агент	Контроллер	8080 (или пользовательский)	Доступ через браузер
Входящий агент	Агент	Контроллер	50000 (или пользовательский)	telnet или nc
SSH (Контроллер -> Агент)	Контроллер	Агент	22 (или пользовательский)	ssh или telnet

2.2 Использование Telnet/Netcat для проверки доступности

Используйте telnet или nc (Netcat) с подключающейся машины на целевую машину на требуемом порту. Успешное подключение подтверждает сетевую доступность и то, что локальный брандмауэр не блокирует порт.

Проверка доступности входящего агента (от агента к контроллеру)

# Замените <CONTROLLER_IP> и <JNLP_PORT>
telnet <CONTROLLER_IP> 50000

# Ожидаемый успешный вывод:
# Connected to <CONTROLLER_IP>.
# Escape character is '^]'.

# Ожидаемый вывод при ошибке:
# Trying <CONTROLLER_IP>...
# telnet: connect to address <CONTROLLER_IP>: Connection refused

Совет: Ошибка "Connection Refused" указывает на то, что сетевой путь открыт, но служба (Jenkins) не прослушивает этот порт, или локальный брандмауэр на контроллере блокирует его. Если соединение истекает по тайм-ауту, вероятно, виноват брандмауэр между машинами.

2.3 Установка фиксированного порта JNLP

Если вы используете JNLP, рекомендуется настроить фиксированный порт, чтобы избежать неоднозначности и упростить правила брандмауэра. Jenkins может использовать случайный порт входящего агента, если вы не установите фиксированный, что усложняет настройки безопасности.

1. Перейдите в Manage Jenkins > Security (или Configure Global Security в старых версиях Jenkins).
2. В разделе Agents найдите опцию TCP port for inbound agents.
3. Выберите Fixed и укажите порт (например, 50000).
4. Убедитесь, что этот порт открыт в брандмауэре операционной системы хоста (например, iptables, firewalld или брандмауэр Windows) на машине контроллера.

3. Устранение неполадок с агентом JNLP

Если проверки сети пройдены, проблема обычно связана с аутентификацией, конфигурацией или несоответствием среды.

3.1 Проверка журналов агента на контроллере

При попытке запустить агент JNLP просмотрите журналы, предоставляемые самим Jenkins. Перейдите на страницу конфигурации конкретного агента и просмотрите раздел Log. Это часто дает наиболее понятное сообщение об ошибке.

• Ищите распространенные ошибки, такие как java.net.ConnectException или hudson.remoting.ChannelClosedException.

3.2 Проверка правильности аргументов агента

При ручном запуске агента с помощью команды, предоставленной Jenkins (команда java -jar agent.jar ...), убедитесь, что параметры верны.

# Пример структуры команды для запуска JNLP
java -jar agent.jar -jnlpUrl http://<JENKINS_URL>/computer/<AGENT_NAME>/slave-agent.jnlp -secret <SECRET_TOKEN> -workDir "/path/to/workspace"

• Проверьте URL JNLP: Убедитесь, что URL использует правильное имя хоста и порт контроллера. Если Jenkins находится за обратным прокси, убедитесь, что конфигурация URL Jenkins отражает внешний URL.
• Проверьте секретный токен: Токены истекают или изменяются, если узел перенастраивается. Загрузите последнюю версию .jar и используйте последний секрет, указанный на странице запуска агента.

4. Устранение неполадок с агентом SSH

Если вы используете SSH для запуска агентов, проблемы с подключением обычно связаны с аутентификацией или проблемами в среде оболочки.

4.1 Проверка SSH-подключения вне Jenkins

Попробуйте подключиться к машине агента с контроллера, используя точное имя пользователя и учетные данные, настроенные в Jenkins.

ssh -i /path/to/keyfile jenkins_user@<AGENT_IP>

• Если это не удается, проблема в среде: либо служба SSH не работает, либо неверны учетные данные/ключи пользователя, либо разрешения ключа слишком свободные (chmod 600 keyfile.pem).

4.2 Проверка метода аутентификации SSH

1. Ключи: Убедитесь, что открытый ключ, соответствующий закрытому ключу, хранящемуся в диспетчере учетных данных Jenkins, правильно добавлен в файл ~/.ssh/authorized_keys пользователя агента.
2. Пароли: Если используются пароли, убедитесь, что SSH-сервер на агенте настроен на разрешение аутентификации по паролю (не рекомендуется по соображениям безопасности).

4.3 Тайм-аут запуска SSH-агента

Если SSH-подключение установлено, но агент не запускается, возможно, Jenkins превышает время ожидания при попытке выполнить скрипты инициализации. Увеличьте время ожидания SSH-подключения в настройках конфигурации агента.

5. Распространенные ошибки среды агента

После установления сетевого подключения агент все еще может выйти из строя, если его операционная среда неверна.

5.1 Среда Java (критически важно)

Агенту Jenkins требуется совместимая среда выполнения Java (JRE/JDK) для выполнения файла agent.jar.

• Проверьте наличие Java: Выполните java -version на машине агента.
• Проверьте JAVA_HOME: Убедитесь, что переменная JAVA_HOME или Path to JDK в конфигурации агента Jenkins указывает на действительный каталог установки Java на машине агента.

5.2 Рабочее пространство и разрешения пользователя

Учетная запись пользователя, которую Jenkins использует для запуска агента (либо через SSH-логин, либо как системная служба), должна иметь права на чтение и запись в определенный удаленный корневой каталог (рабочее пространство).

• Действие: Проверьте владельца и разрешения удаленного корневого каталога (например, /home/jenkins/workspace).

5.3 Синхронизация времени

Хотя это и редкость, значительное расхождение времени между контроллером и машиной агента может вызвать сбои рукопожатия SSL/TLS, что приведет к разрыву соединения или отказу. Убедитесь, что обе машины синхронизированы по протоколу сетевого времени (NTP).

Выводы и контрольный список

Устранение неполадок подключения Jenkins — это процесс исключения, начиная с периметра сети и двигаясь внутрь. Систематически проверяя брандмауэры, проверяя доступность портов с помощью таких инструментов, как telnet, и подтверждая, что протоколы связи (JNLP или SSH) правильно аутентифицированы и настроены, вы можете быстро определить и устранить проблемы с подключением.

Контрольный список для устранения неполадок:

1. Сетевой брандмауэр: Разрешен ли трафик в обоих направлениях на требуемом порту (50000+ для JNLP, 22 для SSH)?
2. Локальный брандмауэр: Не блокирует ли порт брандмауэр ОС (Windows/Linux), запущенный на контроллере/агенте?
3. Тест протокола: Успешно ли выполняется telnet с подключающейся машины к месту назначения на соответствующем порту?
4. Java: Установлена ли на агенте совместимая версия Java и правильный ли путь к ней?
5. Аутентификация: Действительны ли ключи/пароли SSH или актуален ли секретный токен JNLP?

Если все попытки подключения не удаются, проверьте журналы контроллера Jenkins, часто доступные из журнала службы или /var/log/jenkins/jenkins.log, на предмет трассировок удаленного взаимодействия и Java.