Почему после обновления пропала связь
После обновления Beszel сервер показывает Offline, хотя сайт и SSH продолжают работать? Начните с логов агента. С версии 0.19.0 Beszel проверяет сертификат HTTPS-соединения с Hub. Если сертификат выпущен частным центром сертификации, агенту нужно передать доверенный сертификат через CA_CERT_FILE. Но у первой базовой Docker-сборки агента 0.19.0 была и отдельная ошибка: в образе отсутствовали корневые сертификаты, поэтому не проходила проверка даже обычного публичного сертификата.
Порядок действий зависит от причины: исправить образ, настроить доверие к своему CA или устранить ошибку в сертификате Hub. Сам статус Offline означает потерю связи в мониторинге и ещё не доказывает, что сервер выключен.
Ниже — инструкция для Linux с агентом в Docker Compose или службой systemd. Hub — центральная панель Beszel, агент — программа на наблюдаемом сервере. Понадобятся доступ к конфигурации агента, его журналам и, при необходимости, настройкам HTTPS-прокси перед Hub. Все домены и пути в примерах условные.
1. Найдите ошибку в логах агента
В каталоге вашего Compose-проекта выполните команды. Здесь сервис и контейнер называются beszel-agent; если у вас другие имена, замените их.
docker compose ps -a beszel-agent
docker compose logs --since=15m --tail=100 beszel-agentДля установки через systemd:
sudo systemctl status beszel-agent --no-pager
sudo journalctl -u beszel-agent --since "15 minutes ago" --no-pagerНайдите свежую ошибку подключения. Работающий процесс или состояние контейнера Up ещё не означают, что метрики доходят до Hub.
| Сообщение или симптом | Что оно означает | Следующее действие |
|---|---|---|
x509: certificate signed by unknown authority |
Агент не смог построить цепочку доверия к сертификату. | Проверьте тип сертификата, образ агента и полноту цепочки на HTTPS-прокси. |
certificate is valid for ..., ошибка IP SAN или legacy Common Name |
Сертификат не подходит имени или IP-адресу из HUB_URL. |
Исправьте адрес Hub либо перевыпустите серверный сертификат с нужным SAN. |
certificate has expired or is not yet valid |
Неверное время на машине агента либо сертификат вне срока действия. | Сверьте время и даты сертификата. |
read CA_CERT_FILE, permission denied, does not contain any valid PEM certificates |
Файл не найден, недоступен или не содержит подходящего PEM-сертификата. | Проверьте путь внутри среды агента, права и содержимое файла. |
no such host, connection refused, i/o timeout |
Есть проблема с DNS, портом или сетевым соединением; эти сообщения сами по себе не указывают на CA. | Проверьте адрес, разрешение имени и доступность нужного порта. |
Ответ HTTP 401/403 или ошибка WebSocket-подключения без x509 |
Возможна проблема с авторизацией Beszel или правилами прокси. | Перейдите к разделу о проверке результата и маршрута подключения. |
Эта инструкция про соединение агент → Hub по HTTPS/WebSocket, которое задаётся через HUB_URL. При отдельном SSH-соединении Hub сам обращается к агенту, обычно на порт 45876: доверие к HTTPS-сертификату эту связь не исправляет. Если используются оба способа, смотрите, какой именно перестал работать.
Зафиксируйте версии Hub и агента. У работающего официального Docker-агента версию можно получить командой docker compose exec beszel-agent /agent --version. Для systemd найдите путь к исполняемому файлу в ExecStart службы и запустите этот файл с --version. Версия Hub видна в интерфейсе; тег latest в Compose не показывает, какая сборка уже запущена.
2. Проверьте адрес Hub, время и выданный сертификат
В конфигурации агента найдите HUB_URL. Это должен быть реальный адрес Hub со схемой, например https://monitor.example.com, а при размещении в подкаталоге — также с его путём. Для Docker фактически переданные значения можно посмотреть без вывода токена:
docker inspect beszel-agent --format '{{range .Config.Env}}{{println .}}{{end}}' |
grep -E '^(BESZEL_AGENT_)?(HUB_URL|CA_CERT_FILE)='У переменных с префиксом BESZEL_AGENT_ есть приоритет. Например, оставшийся BESZEL_AGENT_CA_CERT_FILE может перекрыть новое значение CA_CERT_FILE. Уберите противоречащие друг другу настройки и затем примените конфигурацию способом из следующих разделов.
На машине агента проверьте время и HTTPS. Подставьте свой адрес целиком:
date -u
timedatectl status
curl --connect-timeout 5 --max-time 15 -sS -o /dev/null \
-w 'HTTP %{http_code}\n' https://monitor.example.com/Команда curl без ошибки сертификата и с ответом HTTP подтверждает проверку TLS — защищённого соединения — для этого запроса. Даже HTTP 403 означает, что до HTTP-сервера удалось добраться, но доступ ограничен. Ошибка curl 60 требует разобраться с сертификатом; ошибки 6, 7 или 28 направляют к DNS, подключению или тайм-ауту.
Проверка с хоста — предварительная: контейнер может использовать другое хранилище доверенных сертификатов и другое разрешение имён. Открывающаяся панель в браузере тоже не подтверждает, что агент доверяет её сертификату.
Посмотрите, какой серверный сертификат действительно выдаётся на нужном домене. Команда ниже рассчитана на OpenSSL 1.1.1 или новее и порт 443:
openssl s_client -connect monitor.example.com:443 \
-servername monitor.example.com -showcerts </dev/null 2>/dev/null |
openssl x509 -noout -subject -issuer -dates -ext subjectAltNameЭто просмотр сертификата, а не доказательство его подлинности. В результате проверьте:
notBeforeиnotAfter: текущее время должно попадать в этот интервал. Если часы сбились, восстановите синхронизацию времени средствами вашей ОС; если срок истёк, обновите сертификат на HTTPS-прокси и повторите проверку.Subject Alternative Name, или SAN: список имён и IP-адресов, для которых выдан сертификат. ДляHUB_URL=https://monitor.example.comнужно подходящее DNS-имя в SAN. При подключении по IP нужен именно IP SAN; одного поля Common Name недостаточно.issuer: кто выпустил сертификат. Если это ваш частный CA, переходите к настройкеCA_CERT_FILE. Само название издателя ещё не подтверждает доверие к нему.
При публичном сертификате проверьте и промежуточные сертификаты на прокси. В Nginx директива ssl_certificate должна указывать на файл с серверным сертификатом и нужной промежуточной цепочкой, обычно fullchain.pem. Сохраните исходный конфиг и выполните sudo nginx -t после изменения. Если проверка успешна и Nginx работает как служба systemd, примените её командой sudo systemctl reload nginx. Браузер иногда достраивает цепочку из своего кэша, тогда как агент получает ошибку.
Если цепочка публичного сертификата корректна, а нативный агент всё ещё не доверяет ей, проверьте системный набор CA. Для Debian и Ubuntu установить или обновить его можно так:
sudo apt-get update
sudo apt-get install ca-certificates
sudo update-ca-certificates
sudo systemctl restart beszel-agentПосле успешного выполнения повторите запрос curl и прочитайте свежие логи агента. Обновление CA на Docker-хосте само по себе не обновляет содержимое контейнера.
Если ошибка возникает ещё при docker compose pull и в ней указан registry-1.docker.io или auth.docker.io, проверку выполняет Docker, а не Beszel. В GitHub issue #2123 пользователь сначала пробовал подключить сертификаты в контейнер, но затем обнаружил неверную дату на сервере. CA_CERT_FILE агента на загрузку образов не влияет.
3. Если у вас Docker 0.19.0 и публичный сертификат
В обсуждении GitHub #2291 подтверждена ошибка первой базовой сборки агента 0.19.0: в образ не попали корневые CA. Пользователям помогали подключение системного набора сертификатов с хоста и переход на вариант :alpine. Разработчик исправил основной образ 3 сентября 2026 года; затем несколько участников подтвердили восстановление после повторной загрузки образа и пересоздания контейнера.
Поэтому при таком сочетании версии и ошибки сначала получите исправленную сборку. Сохраните Compose-файл, запишите текущий тег или digest образа и сохраните имеющиеся подключения каталогов данных. Проверьте поле image: при теге latest команда загрузит текущий релиз, а закреплённый старый digest продолжит указывать на старую сборку. Выберите нужную версию осознанно.
docker compose pull beszel-agent
docker compose up -d --no-deps --force-recreate beszel-agent
docker compose logs --since=5m --tail=100 beszel-agentЕсли загрузка завершилась с ошибкой, сначала устраните её. Обычный docker compose restart не загружает образ и не применяет новые переменные окружения. Пересоздание агента кратковременно прерывает сбор метрик; удалять систему из Hub, каталоги данных или запускать docker compose down -v для этого не требуется.
Исправление отсутствующих CA также указано в релизе 0.20.0 от 19 сентября 2026 года. Если свежий образ с публичным сертификатом продолжает выдавать unknown authority, вернитесь к проверке цепочки, DNS и сертификата, который реально получает агент. Для частного CA одного обновления образа недостаточно.
4. Подготовьте доверенный CA-сертификат
CA — центр сертификации, который подписывает серверные сертификаты. Для внутреннего Hub получите у администратора вашей инфраструктуры публичный сертификат доверенного CA в формате PEM. Такой файл содержит блок -----BEGIN CERTIFICATE-----. Закрытый ключ CA или HTTPS-сервера агенту не нужен.
Сохраните файл как hub-ca.crt и проверьте его:
openssl x509 -in ./hub-ca.crt -noout \
-subject -issuer -dates -fingerprint -sha256Команда должна вывести сведения о сертификате. Ошибка чтения означает, что файл отсутствует, повреждён или имеет другой формат. SHA-256-отпечаток сверяйте с данными администратора по доверенному каналу. Автоматически доверять сертификату, скачанному с адреса, который сейчас не проходит проверку, нельзя.
CA_CERT_FILE принимает файл с одним или несколькими CA-сертификатами и добавляет их к системным доверенным сертификатам агента. Для внутренней инфраструктуры передавайте сертификат корневого CA, к которому ведёт цепочка Hub; нужные промежуточные сертификаты должен отдавать HTTPS-сервер. Если у Hub самостоятельный самоподписанный серверный сертификат без отдельного CA, потребуется доверять именно этому проверенному сертификату; после его замены доверие придётся обновить.
До изменения агента выполните пробный запрос с полученным файлом:
curl --cacert ./hub-ca.crt --connect-timeout 5 --max-time 15 \
-sS -o /dev/null -w 'HTTP %{http_code}\n' https://monitor.example.com/Если обычный curl выдавал ошибку доверия, а запрос с этим CA проходит, выбранный файл подходит для проверяемой цепочки. Если осталась ошибка имени или срока действия, исправляйте серверный сертификат либо HUB_URL: добавление CA такие ошибки не устраняет.
5. Передайте CA агенту в Docker Compose
Положите проверенный hub-ca.crt рядом с основным Compose-файлом. Добавьте следующие поля в уже существующий сервис агента, сохранив его image, KEY, TOKEN, сеть и остальные volumes. Это фрагмент для дополнения конфигурации:
services:
beszel-agent:
environment:
HUB_URL: https://monitor.example.com
CA_CERT_FILE: /etc/beszel/hub-ca.crt
volumes:
- type: bind
source: ./hub-ca.crt
target: /etc/beszel/hub-ca.crt
read_only: true
bind:
create_host_path: falsesource — путь на Docker-хосте, target — путь внутри контейнера. Значение CA_CERT_FILE должно совпадать с target. Параметр create_host_path: false помогает обнаружить опечатку: Compose завершится с ошибкой, если исходного файла нет, вместо создания каталога с таким именем.
Проверьте синтаксис и, только если проверка прошла, пересоздайте агент:
docker compose config -q
docker compose up -d --no-deps --force-recreate beszel-agent
docker compose logs --since=5m --tail=100 beszel-agentОтсутствие вывода у первой команды при успешном завершении означает, что Compose-конфигурация корректна. Это ещё не проверка сертификата: её выполнит агент при запуске и подключении.
Если агент перестал запускаться, смотрите точную ошибку CA_CERT_FILE. Проверьте, что исходный файл существует, содержит PEM и доступен пользователю контейнера. Для диагностики сопоставьте пути командой docker inspect beszel-agent --format '{{json .Mounts}}'. В базовом образе нет shell и curl, поэтому команда вида docker exec beszel-agent sh здесь не поможет.
Для отмены ошибочной правки восстановите сохранённый Compose-файл и повторите команду пересоздания агента. Это возвращает конфигурацию до изменения; исходную проблему доверия к частному CA всё равно нужно устранить.
6. Настройте CA для агента под systemd
Сначала посмотрите конфигурацию службы:
sudo systemctl cat beszel-agent
sudo systemctl show beszel-agent -p User --valueНайдите HUB_URL, возможные переменные с префиксом BESZEL_AGENT_ и строку EnvironmentFile, если она есть. Вывод может содержать токен: не публикуйте его целиком. Перед изменением сохраните копии редактируемых файлов.
Разместите проверенный публичный CA-сертификат в доступном службе каталоге:
sudo install -d -m 0755 /etc/beszel
sudo install -m 0644 ./hub-ca.crt /etc/beszel/hub-ca.crt
sudo systemctl edit beszel-agentВ открывшийся файл дополнений службы добавьте:
[Service]
Environment="CA_CERT_FILE=/etc/beszel/hub-ca.crt"Если это значение уже задаётся в файле из EnvironmentFile, исправьте его там: значения из такого файла имеют приоритет над Environment=. Убедитесь также, что HUB_URL содержит нужный адрес.
Пользователь из поля User должен иметь право читать сертификат. Например, для User=beszel:
sudo -u beszel test -r /etc/beszel/hub-ca.crt && echo "CA readable"При успешной проверке появится CA readable. Если вывода нет, проверьте права на файл и проход по родительским каталогам. Затем примените настройки:
sudo systemctl daemon-reload
sudo systemctl restart beszel-agent
sudo systemctl status beszel-agent --no-pager
sudo journalctl -u beszel-agent --since "5 minutes ago" --no-pagerОжидаемый результат — служба работает и новых ошибок сертификата нет. Если правка вызвала ошибку запуска, восстановите изменённый файл или уберите только добавленную настройку, затем снова выполните daemon-reload и перезапуск.
7. Убедитесь, что метрики снова поступают
Проверьте результат на трёх уровнях: агент стабильно работает, в свежих логах нет повторяющихся TLS-ошибок, а в Hub обновляются показатели и время последних данных. Понаблюдайте несколько минут. Единственной зелёной отметки сразу после запуска недостаточно, если затем снова идут обрывы.
Если ошибки x509 исчезли, но сервер остаётся Offline, откройте журналы Hub в PocketBase по пути /_/#/logs. Сопоставьте события по времени с журналом агента:
- 401/403 или переход на страницу входа. Проверьте
KEYиTOKENпо настройкам существующей системы в Hub, а также внешнюю авторизацию прокси. Агент обращается к/api/beszel/agent-connect; при установке в подкаталог перед этим путём будет соответствующий префикс. Для него не должно быть интерактивной формы входа или проверки браузера. В обсуждении #1163 пользователь подтвердил, что исключение этого маршрута из авторизации Pangolin восстановило подключение. Собственная авторизация Beszel при этом сохраняется. - Панель открывается, WebSocket не работает. Проверьте передачу WebSocket через прокси. Для Nginx в обслуживающем Hub блоке
locationпроверьте директивыproxy_http_version 1.1;,proxy_set_header Upgrade $http_upgrade;иproxy_set_header Connection "upgrade";. Официальный пример Beszel также задаётproxy_read_timeout 360s;. После правки выполнитеsudo nginx -t, примените конфигурацию и перечитайте журналы. - Ошибка DNS или подключения. Команда
getent ahosts monitor.example.comдолжна показать ожидаемые адреса. Для HTTPS агенту нужен исходящий доступ к порту Hub, обычно 443; открытие входящего порта 45876 относится к другому, SSH-способу связи. Учитывайте DNS и сеть самого контейнера.
Если текущие метрики поступают, но не открываются исторические графики, переходите к проверке интерфейса и API. В обсуждении Beszel + NPMPlus причиной оказались блокировки ModSecurity. Проверяйте журнал защитного фильтра и конкретный заблокированный запрос, прежде чем менять настройки сертификатов.
Для дальнейшего разбора подготовьте версии Hub и агента, способ установки, тег и digest образа, свежую ошибку и схему проксирования. Токены и закрытые ключи из диагностических материалов удалите.
Как избежать повторного Offline из-за сертификатов
При продлении серверного сертификата тем же доверенным CA обычно достаточно обновить сертификат и цепочку на HTTPS-прокси. При смене самого CA заранее передайте новый доверенный сертификат всем агентам и перезапустите их. В Docker после замены примонтированного файла надёжнее пересоздать контейнер, чтобы он прочитал актуальный файл.
Для публичного домена сертификат общедоверенного CA упрощает настройку агентов. Частный CA удобен для внутренней инфраструктуры, но требует распространения доверия и контроля обновлений. Настройка CA_CERT_FILE сама по себе не требует платной услуги; основные затраты — время администратора. Отключение проверки TLS, запросы с curl -k и переход на HTTP через интернет не подтверждают исправность HTTPS.
Если Hub работает на том же сервере, который он наблюдает, имеет смысл вынести мониторинг на отдельную машину. Для этого можно выбрать VPS HSTQ; при выборе размещения учитывайте общие точки отказа. Настройку Beszel можно выполнить самостоятельно, а необходимые работы по администрированию согласовать отдельно.
