basforge

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

    EN
    КонфигHomelabTraefik

    traefik.yml по блокам: что значит каждая настройка

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

    Что в этом файле и чего в нём нет

    traefik.yml — статический конфиг: точки входа, откуда брать маршруты, как получать сертификаты, логи, плагины. Traefik читает его один раз, при запуске, поэтому любая правка — это docker compose restart traefik и несколько секунд, когда не открывается ни один сайт.

    Роутеров, middleware и сервисов здесь нет — это динамический конфиг: лейблы контейнеров («Лейблы Traefik») и файлы в dynamic/ (в конце этого материала). Переменные ${…} в traefik.yml не подставляются: файл читает сам Traefik, а не compose («traefik.yml не подставляет переменные»).

    Файл по блокам

    Домены заменены на example.org и example.net, списки сетей Cloudflare сокращены.

    /opt/traefik/data/traefik.yml
    experimental:
      plugins:
        crowdsec-bouncer-traefik-plugin:
          moduleName: "github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin"
          version: "v1.8.1"

    Плагин bouncer'а CrowdSec: имя слева — то, под которым его подключают в dynamic/crowdsec.yml («CrowdSec с Traefik за Cloudflare»). Traefik скачивает плагин с GitHub при каждом запуске, версию фиксируем тегом.

    по умолчанию плагинов нет

    global:
      checkNewVersion: false
      sendAnonymousUsage: false

    Без проверки новой версии: версию задаёт тег образа, а Traefik иначе сам ходит за обновлениями и пишет о них в лог. Анонимная статистика выключена и так — строка для того, кто читает.

    по умолчанию:checkNewVersion truesendAnonymousUsage false

    api:
      dashboard: false
      debug: false

    Дашборд — страница со всеми роутерами и их ошибками. Сам наружу не открыт: нужен роутер на api@internal с паролем и баном. Включаем на время отладки; api.insecure: true открыл бы его на порту 8080 без защиты.

    по умолчанию:dashboard trueinsecure false

    log:
      level: INFO
      filePath: "/logs/traefik.log"

    INFO добавляет события: какие сертификаты получены, какие провайдеры подключены. DEBUG — на время разбора, лог растёт быстро. С filePath лог идёт только в файл, docker logs traefik пустой.

    по умолчанию:level ERRORfilePath stdout

      maxSize: 10
      maxBackups: 5
      maxAge: 7
      compress: true

    Ротация встроенная: новый файл после 10 МБ, 5 старых, не дольше 7 дней, старые — в gzip. В logrotate traefik.log не добавляем: два механизма на один файл мешают друг другу («Логи Traefik»).

    по умолчанию:maxSize 100maxBackups 0 — всеmaxAge 0 — без срокаcompress false

    accesslog:
      addInternals: true
      format: json
      filePath: "/logs/access.log"

    Журнал запросов в JSON — по строке на запрос: адрес, роутер, код ответа, время. Из него берут события программы разбора логов — например CrowdSec или vector («Логи Traefik»). Файл, а не stdout: читателей может быть несколько; ротирует logrotate с сигналом USR1.

    по умолчанию:format commonaddInternals false

    entryPoints:
      http:
        address: ":80"
        http:
          aliasHeadersStrategy: delete
          redirections:
            entryPoint:
              to: https
              scheme: https
    Главное

    Все запросы на 80 уводятся на HTTPS. Приоритет редиректа выше любого роутера, поэтому http-роутеры и redirectscheme в лейблах сервисов уже не нужны. Имена http и https — любые, на них ссылаются лейблы. aliasHeadersStrategy — в следующем блоке.

    по умолчанию:permanent truepriority MaxInt−1

      https:
        address: ":443"
        http:
          aliasHeadersStrategy: delete
          tls:
            certResolver: cloudflare
            domains:
              - main: "example.org"
                sans:
                  - "*.example.org"
              - main: "example.net"
                sans:
                  - "*.example.net"

    Каждый роутер на этой точке входа получает TLS и сертификат от резолвера cloudflare. Wildcard запрашивается здесь, а не на роутере: сертификат не зависит ни от одного сервиса («Traefik и Let's Encrypt»). aliasHeadersStrategy: delete отбрасывает заголовки с _ или . в имени: PHP и nginx читают X_Auth_User как X-Auth-User, и посетитель подделал бы заголовок, который ставит Traefik. reject вместо delete отвечает на такой запрос 400. Без строки Traefik 3.7 пишет предупреждение на каждую точку входа.

    по умолчанию:aliasHeadersStrategy keep

        forwardedHeaders:
          trustedIPs:
            # Cloudflare IPv4
            - 173.245.48.0/20
            - 103.21.244.0/22
            # … ещё 13 сетей IPv4
            # Cloudflare IPv6
            - 2400:cb00::/32
            # … ещё 6 сетей IPv6

    X-Forwarded-* Traefik принимает только от этих адресов, от остальных перезаписывает — иначе любой посетитель представился бы чужим адресом. Без блока в журнале и в CrowdSec вместо посетителей — Cloudflare. Список — cloudflare.com/ips.

    providers:
      docker:
        endpoint: "unix:///var/run/docker.sock"
        exposedByDefault: false
        watch: true

    Открываются только контейнеры с traefik.enable=true. С умолчанием наружу попал бы каждый контейнер с портом, под своим именем. Маршруты пересобираются по событиям Docker не чаще раза в 2 с.

    по умолчанию:exposedByDefault truewatch true

      file:
        directory: /dynamic/
        watch: true

    Каталог, а не один файл: отдельно смонтированный файл не видит правок после git pull («Монтирование отдельного файла»). Правка в dynamic/ действует без перезапуска.

    certificatesResolvers:
      cloudflare:
        acme:
          email: [email protected]
          storage: acme.json

    Адрес аккаунта Let's Encrypt — буквами («traefik.yml не подставляет переменные»). acme.json — ключ аккаунта и все сертификаты: права 600, в git — никогда, в бэкап — да.

    по умолчанию:storage acme.json

          caServer: https://acme-v02.api.letsencrypt.org/directory
          # caServer: https://acme-staging-v02.api.letsencrypt.org/directory

    Основной сервер Let's Encrypt — выдаёт сертификаты, которым доверяют браузеры. Тестовый (staging) — для экспериментов: лимиты выше, сертификаты недоверенные; после переключения обратно очищаем acme.json.

    по умолчанию основной сервер

          dnsChallenge:
            provider: cloudflare
            resolvers:
              - "1.1.1.1:53"
              - "1.0.0.1:53"

    DNS-01: Traefik сам создаёт TXT-запись через API Cloudflare — только так выдают wildcard. Токен — CF_DNS_API_TOKEN_FILE из Docker secret («Секреты в Docker-стеках»). Наличие записи проверяем у DNS Cloudflare: они видят её раньше остальных.

    Чего в файле нет, но нужно часто

    traefik.ymlна сервере не включено
    entryPoints:
      https:
        transport:
          respondingTimeouts:
            readTimeout: 600s

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

    по умолчанию:readTimeout 60swriteTimeout 0idleTimeout 180s

        http3: {}

    HTTP/3 поверх QUIC. Нужен ещё UDP-порт: - 443:443/udp в compose. Работает только для роутеров с TLS.

        proxyProtocol:
          trustedIPs: ["10.0.0.5"]

    PROXY protocol — когда перед Traefik стоит TCP-балансировщик, который передаёт адрес посетителя в начале соединения. Только с адресов балансировщика.

    serversTransport:
      insecureSkipVerify: true

    Не проверять сертификат у сервисов за Traefik — если сервис сам отдаёт HTTPS с самоподписанным сертификатом. Здесь действует на все сервисы сразу; точечно — serversTransport в динамическом конфиге, а сервис ссылается на него по имени с провайдером: serversTransport: insecure@file.

    по умолчанию false

    ping: {}
    metrics:
      prometheus: {}

    /ping — для healthcheck в compose: traefik healthcheck --ping. Метрики — запросы, коды ответов и время по роутерам, для Grafana. Оба на точке входа traefik (8080), наружу не публикуем.

    providers:
      docker:
        network: proxy

    Сеть, через которую Traefik ходит к контейнерам. На сервере она в каждом сервисе лейблом traefik.docker.network; одна строка здесь заменяет их все.

    по умолчанию:network пусто — сеть выбирает Traefik

    certificatesResolvers:
      letsencrypt:
        acme:
          email: [email protected]
          storage: acme.json
          httpChallenge:
            entryPoint: http

    Без wildcard DNS-01 не нужен: HTTP-01 проверяет через порт 80, tlsChallenge: {} — через 443.

    по умолчанию:keyType RSA4096certificatesDuration 2160 ч

          dnsChallenge:
            propagation:
              delayBeforeChecks: 60s

    Пауза и отказ от проверки распространения TXT-записи, если Cloudflare отвечает медленно. В старых конфигах — delayBeforeCheck и disablePropagationCheck: Traefik 3.7 их ещё понимает, но пишет в лог предупреждение об устаревших именах.

    по умолчанию:delayBeforeChecks 0sdisableChecks false

    Рядом: что лежит в dynamic/

    Динамический конфиг подхватывается без перезапуска. На сервере в data/dynamic/ три файла: TLS-опции, лимиты и middleware бана (crowdsec.yml, разобран в «CrowdSec с Traefik за Cloudflare»).

    dynamic/dynamic.yml
    tls:
      options:
        default:
          sniStrict: true

    Соединение без имени сайта или с чужим именем Traefik обрывает, вместо того чтобы отдать TRAEFIK DEFAULT CERT: сканер, который ходит по адресу сервера, не узнает, какие сайты на нём живут.

    по умолчанию false

    dynamic/rate-limit.yml
    http:
      middlewares:
        global-ratelimit:
          rateLimit:
            average: 100
            burst: 50
            period: 1s

    В среднем 100 запросов за period с одного адреса и до 50 сверх этого всплеском. Лимит считается на каждый адрес отдельно, а не на весь роутер.

    по умолчанию:average 0 — выключенburst 1period 1s

            sourceCriterion:
              ipStrategy:
                depth: 1
    Главное

    Адрес посетителя — первый справа в X-Forwarded-For: его дописал Cloudflare. Без depth лимит считался бы по адресам Cloudflare и делился на всех, кто пришёл через один узел.

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

    После правки traefik.yml контейнер перезапускается по кругу

    Причина
    Ошибка в статическом конфиге — Traefik не стартует.
    Делаем
    docker logs traefik --tail 20 покажет строку; если быстро не найти — git checkout -- data/traefik.yml && docker compose restart traefik.

    docker logs traefik пустой

    Причина
    Задан log.filePath — лог пишется в файл.
    Делаем
    tail -f /opt/traefik/data/logs/traefik.log.

    В журнале запросов и в CrowdSec — только адреса Cloudflare

    Причина
    Нет forwardedHeaders.trustedIPs на точке входа или список сетей Cloudflare устарел.
    Делаем
    Сверяем список с cloudflare.com/ips.

    Лимит запросов срабатывает на всех сразу

    Причина
    У rateLimit нет ipStrategy.depth: 1, и лимит общий на узел Cloudflare.
    Делаем
    Добавляем sourceCriterion.ipStrategy.depth: 1.

    Новый сервис открыт наружу, хотя traefik.enable у него нет

    Причина
    exposedByDefault не задан и остался true.
    Делаем
    Ставим exposedByDefault: false и перезапускаем Traefik.

    Wildcard не выпускается, в логе — про распространение TXT-записи

    Причина
    Cloudflare не успел разнести запись до проверки.
    Делаем
    Добавляем propagation.delayBeforeChecks: 60s; подробно — «Traefik и Let's Encrypt».

    Как проверить

    # порты контейнера Traefik — 80 и 443
    docker port traefik
    # 80/tcp -> 0.0.0.0:80
    # 443/tcp -> 0.0.0.0:443
    # сертификат — wildcard, от Let's Encrypt
    echo | openssl s_client -connect whoami.example.org:443 -servername whoami.example.org 2>/dev/null \
      | openssl x509 -noout -subject -ext subjectAltName
    # DNS:*.example.org, DNS:example.org
    # без имени сайта соединение обрывается (sniStrict)
    echo | openssl s_client -connect 203.0.113.10:443 2>&1 | grep -iE 'alert|error' | head -2
    # за Cloudflare Traefik видит адрес посетителя, а не Cloudflare
    curl -s https://whoami.example.org | grep -i '^X-Real-Ip'