Traefik на сервере: частые ошибки и решения

MAATRIX

Traefik подкупает автоматизацией, но именно из-за неё ошибки бывают неочевидными: на все запросы прилетает 404, сертификат не выпускается без внятной причины, а сервис виден в дашборде, но не отвечает. Эти ошибки Traefik на сервере почти всегда сводятся к нескольким типовым причинам — метки, сеть, права на файл сертификатов. Разберём их по схеме «симптом — причина — решение».

Как читать логи и дашборд Traefik

Диагностика Traefik держится на двух источниках: логах контейнера и дашборде. Сначала логи — там видно и ошибки выпуска сертификатов, и проблемы обнаружения сервисов:

docker compose logs -f traefik

Полезно на время отладки повысить уровень логирования, добавив в команду запуска --log.level=DEBUG — тогда Traefik подробно расскажет, какие контейнеры он видит, какие метки прочитал и почему не построил маршрут. Второй источник — дашборд, где наглядно показаны текущие роутеры, сервисы и их состояние. Если сервис есть в дашборде, но со значком ошибки, проблема в его конфигурации; если сервиса нет вовсе — Traefik его не обнаружил.

Именно это разделение — «сервис не виден» против «сервис виден, но не работает» — задаёт направление поиска. Не виден: проблема в метках, включении или сети. Виден, но ошибка: проблема в правиле маршрута, порте сервиса или сертификате. Держа перед глазами логи и дашборд, вы быстро отнесёте свою проблему к одной из категорий. Дальше — разбор частых симптомов.

На все запросы приходит 404

Самый частый симптом у начинающих: Traefik запущен, но любой запрос к домену возвращает 404. Это означает, что Traefik принял соединение, но не нашёл подходящего маршрута. Причин несколько, и все связаны с метками.

Первая и самая частая — не выставлена метка traefik.enable=true на сервисе. Если в конфиге Traefik стоит exposedbydefault=false (а так и должно быть для безопасности), то без явного включения контейнер не проксируется. Проверьте метки:

docker inspect app | grep -A20 Labels

Вторая причина — ошибка в правиле Host. Домен в метке traefik.http.routers.app.rule=Host(...) должен точно совпадать с тем, по которому вы обращаетесь, включая поддомен. Опечатка или несовпадение — и маршрут не срабатывает, отдаётся 404. Третья — сервис не подключён к той сети Docker, за которой следит Traefik. Даже с правильными метками контейнер в другой сети для прокси невидим. Об этом отдельный раздел ниже, потому что это очень частая причина.

Сервис не в той сети Docker

Симптом коварный: метки правильные, traefik.enable=true стоит, а сервис либо не появляется в дашборде, либо появляется с ошибкой недоступности бэкенда. В большинстве случаев виновата сеть. Traefik проксирует только контейнеры из сети, к которой подключён сам, и если сервис поднят в другой сети (например, в дефолтной сети своего compose-проекта), прокси до него не дотянется.

Убедитесь, что и Traefik, и сервис подключены к одной общей сети:

docker network inspect web

В выводе должны быть перечислены оба контейнера. Если сервиса там нет, добавьте общую сеть в его compose-описание и объявите её внешней:

services:
  app:
    networks:
      - web
networks:
  web:
    external: true

Ещё одна тонкость: если контейнер подключён к нескольким сетям, Traefik может не угадать, через какую с ним связываться, и тогда нужно явной меткой указать сеть — traefik.docker.network=web. После приведения сетей в порядок сервис становится виден прокси, и маршрут начинает работать.

Сертификат Let's Encrypt не выпускается

Частая и раздражающая ошибка: маршрут работает по HTTP, а HTTPS не поднимается, в логах — сообщения о неудаче ACME. Первая причина, специфичная именно для Traefik, — права на файл acme.json, где хранятся ключи сертификатов. Traefik требует строгих прав и с более открытыми откажется использовать хранилище:

chmod 600 letsencrypt/acme.json
docker compose restart traefik

Это буквально самая частая причина «сертификат не выпускается» у новичков — файл создан с правами по умолчанию, и Traefik его игнорирует. Остальные причины общие для любого ACME. Домен должен A-записью указывать на этот сервер — проверьте dig +short app.example.com. Порт 80 должен быть открыт и доступен снаружи, потому что по нему идёт HTTP-проверка; если вы пускаете весь трафик только по 443, проверка не пройдёт. И убедитесь, что в метках указан правильный резолвер tls.certresolver=le, совпадающий с именем из конфига Traefik. Несовпадение имени резолвера — тихая ошибка, которую легко пропустить.

Сервис виден, но отдаёт 502 или 504

Симптом: маршрут построен, сертификат есть, но при обращении Traefik отдаёт 502 Bad Gateway или 504. Это значит, что прокси нашёл сервис, но не смог получить от него ответ. Причина почти всегда в порте бэкенда.

По умолчанию Traefik пытается обратиться к контейнеру по порту, который тот открывает (EXPOSE). Если сервис слушает нестандартный порт или открывает несколько, Traefik может выбрать не тот. Укажите порт явно меткой:

labels:
  - "traefik.http.services.app.loadbalancer.server.port=8080"

Здесь 8080 — порт, который слушает приложение внутри контейнера (именно внутренний порт, а не опубликованный наружу). Вторая причина 502 — само приложение внутри упало или ещё не готово: проверьте его логи и состояние отдельно от Traefik. Третья, более тонкая — приложение слушает 127.0.0.1 внутри контейнера вместо 0.0.0.0, и тогда оно недоступно другим контейнерам, включая прокси. В этом случае приложение нужно настроить слушать все интерфейсы внутри контейнера.

Профилактика и обновление версий

Большинство ошибок Traefik уходит, если соблюсти базовые правила с самого начала. Держите все проксируемые сервисы в одной внешней сети с Traefik. Ставьте traefik.enable=true осознанно и проверяйте точное совпадение домена в правиле Host. Сразу задавайте chmod 600 на acme.json и следите, чтобы порт 80 был открыт для ACME. Дашборд закрывайте аутентификацией и не выставляйте наружу без защиты.

Отдельная и коварная категория проблем — обновление версий. Синтаксис меток, параметров и резолверов между крупными версиями Traefik заметно менялся, и рабочий конфиг после мажорного апдейта может перестать работать. Перед обновлением всегда читайте примечания к версии и держите под рукой возможность отката на прежний тег образа. Фиксируйте конкретную версию (traefik:v3.1), а не latest, чтобы обновление было контролируемым. И помните, что часть проблем — не в Traefik, а в ресурсах: под растущим числом контейнеров сервер упирается в память и процессор, и тогда нужен VPS помощнее. У MAATRIX такие серверы доступны в локациях RU, US и UK с оплатой из России картой или криптой.

Частые вопросы