basforge

Ищем по названиям, тексту и разборам «Если не работает».

    EN
    ОбзорHomelabTraefik

    Traefik: что это и когда его брать

    Traefik — обратный прокси: принимает все запросы к серверу на портах 80 и 443 и раздаёт их контейнерам по имени сайта. Сертификаты Let's Encrypt он получает и продлевает сам, а новые контейнеры подхватывает по лейблам в их compose-файлах — без правки конфига прокси и без его перезапуска.

    Какую задачу решает

    На одном VPS живут несколько сервисов в контейнерах, каждый на своём порту: заметки memos — 5230, мониторинг pulse — 7655, ещё есть сайт. Снаружи хочется другого: имена на обычном 443-м порту, настоящий сертификат и закрытые порты самих сервисов.

    Без прокси

    • http://203.0.113.10:5230 — memos
    • http://203.0.113.10:7655 — pulse
    • http://203.0.113.10:8080 — сайт

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

    С обратным прокси

    • https://memos.example.org
    • https://pulse.example.org
    • https://example.org

    Снаружи открыты только 80 и 443. Сертификаты, бан, пароль на админки и журнал запросов — в одном месте.

    Порт 443 на сервере может занять только одна программа. Поэтому впереди ставят одну, которая принимает все запросы, смотрит, к какому имени обращаются, и передаёт запрос нужному контейнеру. Это и есть обратный прокси. Раз весь трафик идёт через него, в нём же держат и остальное общее: сертификаты, редирект с HTTP на HTTPS, бан атакующих адресов, пароль на админки, лимит запросов и один журнал на все сервисы.

    Обратных прокси много, сравнение — ниже. Отличие Traefik в том, что маршруты он берёт у самого Docker: сервис объявляет своё имя лейблами в своём compose-файле, и Traefik видит его, как только контейнер запущен.

    Путь запроса: точка входа, роутер, middleware, сервис

    На этих четырёх понятиях держится весь конфиг. Запрос проходит их по порядку:

    браузер · https://memos.example.org

    1. Точка входаhttps · :443Порт, который слушает Traefik. Принимает соединение и отдаёт сертификат; здесь же общий редирект с HTTP.
    2. РоутерHost(`memos.example.org`)Правило «какие запросы мои». Не совпал ни один роутер — Traefik отвечает 404 page not found.
    3. Middlewarecrowdsec, ratelimitПроверки по дороге, в порядке перечисления: бан — 403, лимит — 429, пароль, заголовки.
    4. Сервисmemos:5230Куда отдать: адрес контейнера и порт. Контейнеров несколько — Traefik делит запросы между ними.

    контейнер memos · сеть proxy · порт наружу не опубликован

    Два вида конфига

    Настройки Traefik делятся на две части, и правила у них разные. Большинство вопросов «почему не применилось» отсюда.

    Статический

    traefik.yml
    • Задаёт точки входа, откуда брать маршруты, сертификаты, логи, плагины.
    • Применяется только при запуске: правка — перезапуск Traefik, все сайты моргают.
    • Переменные ${…} не подставляются («traefik.yml не подставляет переменные»).

    Динамический

    лейблы, dynamic/*.yml
    • Задаёт роутеры, middleware, сервисы, TLS-опции.
    • Применяется на лету: Traefik следит за Docker и за файлами.
    • Переменные в лейблах подставляет compose.

    Динамический конфиг Traefik берёт у провайдеров. На одном сервере с compose хватает двух: docker читает лейблы запущенных контейнеров через docker.sock, file — YAML-файлы из каталога dynamic/. Туда кладут то, что нужно многим сервисам сразу: общий middleware бана, лимиты, TLS-опции. Ещё есть провайдеры для Kubernetes, Swarm, Consul и других.

    Имя объекта несёт провайдера суффиксом: crowdsec@file — middleware из файла, memos@docker — роутер из лейблов. Ссылка на объект из чужого провайдера пишется с суффиксом, иначе Traefik ищет его у себя и не находит.

    Где его применяют

    Основной случай

    Свой сервер с сервисами в Docker

    Каждый стек в /opt/<имя>/ сам объявляет имя и защиту в своём compose-файле. Удалили стек — исчез и маршрут.

    Несколько доменов на одном сервере

    Wildcard-сертификат на каждый домен запрашивается на точке входа и обслуживает все поддомены сразу («Traefik и Let's Encrypt»).

    Защита в одной точке

    Бан CrowdSec плагином («CrowdSec с Traefik за Cloudflare»), Basic Auth на админках, лимит запросов — middleware, которые подключаются к роутеру одной строкой.

    Журнал всех запросов

    Access-лог в JSON читают CrowdSec, vector и Loki («Логи Traefik»).

    TCP-сервисы по имени

    Бывает, что трафик нужно пропустить как есть, без расшифровки: TCP-роутер с HostSNI и tls.passthrough выбирает получателя по имени из TLS-рукопожатия на том же 443-м порту.

    Kubernetes и Swarm

    Контроллер Ingress и Gateway API, в k3s стоит по умолчанию. Ingress NGINX в марте 2026 перестал получать обновления, и часть кластеров переезжает.

    Чем ещё решают эту задачу

    Аналоги описаны по их документации на октябрь 2026, на сервере не проверялись.

    Где маршруты Сертификаты Видит контейнеры
    Traefik лейблы в compose каждого сервиса и YAML-файлы Let’s Encrypt встроен: HTTP-01, TLS-ALPN-01, DNS-01; Cloudflare и другие DNS-провайдеры — в стандартном образе да
    Caddy один Caddyfile, на сайт 2–3 строки: memos.example.org { reverse_proxy memos:5230 } HTTPS по умолчанию для любого имени в конфиге, Let’s Encrypt и ZeroSSL; wildcard — только со сборкой под свой DNS-провайдер через сторонний caddy-docker-proxy
    nginx файлы server { … }, применение — nginx -s reload отдельно: certbot или acme.sh со своим таймером нет
    Nginx Proxy Manager веб-интерфейс на порту 81 поверх nginx, настройки — в его базе SQLite Let’s Encrypt кнопкой в интерфейсе нет
    HAProxy haproxy.cfg: фронтенды и бэкенды руками ACME с 3.2 (HTTP-01), DNS-01 — с 3.3 через Data Plane API нет
    Если… Берём
    сервисы живут в Docker, добавляются и меняются, маршрут хочется держать рядом с сервисом Traefik
    сайтов два-три и хочется один короткий файл Caddy
    nginx уже стоит или нужен ещё и веб-сервер статики с настройкой кэша nginx + certbot
    конфиги руками писать не будем, сервисов единицы; настройки живут в базе, в git их не положить («Конфиги серверов в git») Nginx Proxy Manager
    нагрузку делим между многими серверами и тонко настраиваем TCP HAProxy

    Что получаем и чем платим

    Получаем

    • Маршрут рядом с сервисом. Новый стек приносит свои лейблы, общий конфиг прокси не трогаем.
    • Без перезапуска. Traefik слушает события Docker и каталог dynamic/ и пересобирает маршруты не чаще раза в 2 с (providersThrottleDuration). Остальные сайты при этом не прерываются.
    • Сертификаты сам. Получает, хранит в acme.json и продлевает за 30 дней до конца срока. Wildcard через Cloudflare работает на официальном образе traefik:v3.7, своя сборка не нужна («Traefik и Let's Encrypt»).
    • Middleware из коробки: пароль, лимит запросов, редиректы, заголовки, список разрешённых адресов, сжатие. Чего нет — добавляют плагины, например bouncer CrowdSec («CrowdSec с Traefik за Cloudflare»).
    • Журнал в JSON — готовый источник для CrowdSec и Loki («Логи Traefik»).

    Платим

    • Лейблы никто не сверяет. Опечатку в имени роутера Traefik принимает молча и создаёт ещё один роутер («Middleware на несуществующем роутере»), второй лейбл с тем же ключом затирает первый («Middleware роутера — одной строкой»). Ошибку видно только в дашборде или в логе.
    • Конфиг разнесён по стекам. Чтобы ответить «что сейчас открыто наружу», приходится пройти все compose-файлы или включить дашборд.
    • Два вида конфига с разными правилами: статический — только перезапуском и без переменных («traefik.yml не подставляет переменные»). Первый сервис поднимается дольше, чем в Caddy, где хватает двух строк.
    • Нужен docker.sock, а доступ к сокету — это root на хосте («docker.sock»).
    • Обновления ломают. v3 сменил синтаксис правил: HostRegexp теперь на регулярках Go, Headers стал Header. С Docker 29 Traefik до 3.6.1 перестал видеть контейнеры. Поэтому минорную версию фиксируем в теге: traefik:v3.7.

    С чего начать

    1. Обзорэта страницаTraefik: что это и когда его брать
    2. МануалTraefik с нуля: первый сервис по имени и HTTPSПоднимаем прокси и открываем первые два сервиса. Здесь же — какие правки применяются на лету, а какие перезапуском.
    3. Конфигtraefik.yml по блокам: что значит каждая настройкаУ каждой строки — значение по умолчанию и когда его меняют.
    4. ШпаргалкаЛейблы Traefik: роутер, middleware, сервисНа каждый день: подключаем сервис, пароль, лимит, TCP.
    5. МануалTraefik и Let's Encrypt: wildcard, ACME, сертификат для соседейОдин сертификат на все поддомены, DNS-challenge.
    6. МануалCrowdSecCrowdSec с Traefik за Cloudflare: два bouncer'а и X-Forwarded-ForБан на уровне прокси, сайты за Cloudflare.
    7. МануалЛогиЛоги Traefik: CrowdSec, vector, Loki, ротацияКто читает access-лог и как не терять строки при ротации.

    Если не работает

    Вместо сайта — белая страница 404 page not found

    Причина
    Ни один роутер не совпал: у контейнера нет traefik.enable=true (при exposedByDefault: false без него Traefik контейнер не видит), опечатка в Host, контейнер не запущен или роутер отключён из-за ошибки — например, ссылки на несуществующий middleware.
    Делаем
    Смотрим docker logs traefik --since 10m 2>&1 | grep -iE 'err|error' и сверяем имя в правиле с адресной строкой.

    Браузер ругается на сертификат, в нём TRAEFIK DEFAULT CERT

    Причина
    Подходящего сертификата нет, и Traefik отдал свой самоподписанный: закрыт порт 80 для HTTP-01, у токена DNS нет прав или исчерпан лимит Let's Encrypt (5 неудачных проверок на имя в час).
    Делаем
    Смотрим docker logs traefik 2>&1 | grep -i acme | tail -20; подробно — «Traefik и Let's Encrypt».

    Gateway Timeout секунд через 30

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

    Bad Gateway сразу

    Причина
    Сеть в порядке, но по этому порту никто не слушает: в loadbalancer.server.port не тот порт или сервис внутри контейнера ещё не поднялся.
    Делаем
    Сверяем порт с документацией образа и смотрим docker logs сервиса.

    После обновления Docker все сайты отдают 404, в логе Traefik client version 1.24 is too old

    Причина
    Docker 29 поднял минимальную версию API до 1.44, а Traefik до 3.6.1 договаривается на 1.24.
    Делаем
    Ставим образ traefik:v3.6.1 или новее: в 3.6.1 появилось автосогласование версии API.

    Правка в traefik.yml не действует

    Причина
    Статический конфиг Traefik читает только при запуске.
    Делаем
    docker compose restart traefik.

    Загрузка большого файла обрывается примерно на минуте

    Причина
    У точки входа readTimeout по умолчанию 60 с — за это время Traefik должен прочитать весь запрос вместе с телом.
    Делаем
    Поднимаем transport.respondingTimeouts.readTimeout на точке входа («traefik.yml по блокам») и перезапускаем Traefik.