basforge

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

    EN
    ШпаргалкаHomelabTraefik

    Лейблы Traefik: роутер, middleware, сервис

    Лейблы, которыми сервис подключается к Traefik, и команды, чтобы проверить, что Traefik их понял. memos в примерах — имя роутера и сервиса, оно одинаковое во всех строках одного сервиса.

    Подключить контейнер

    Лейбл Что делает
    traefik.enable=true контейнер виден Traefik
    traefik.docker.network=proxy ходить к контейнеру через сеть proxy
    traefik.http.routers.memos.rule=Host(`memos.example.org`) какие запросы — этому роутеру
    traefik.http.routers.memos.entrypoints=https слушать только на 443
    traefik.http.services.memos.loadbalancer.server.port=5230 порт внутри контейнера

    Правила роутера

    Правило Что ловит
    Host(`memos.example.org`) одно имя
    Host(`example.org`) || Host(`www.example.org`) два имени, один сервис
    Host(`example.org`) && PathPrefix(`/api`) только адреса с /api
    HostRegexp(`^.+\.example\.org$`) любой поддомен; в v3 — регулярка Go
    ClientIP(`192.168.0.0/16`) только запросы из домашней сети

    Если запрос подходит под два роутера, выигрывает тот, у кого правило длиннее: Host(`example.org`) && PathPrefix(`/api`) перекрывает Host(`example.org`) без всяких настроек. Явно — traefik.http.routers.memos.priority=100, больше — главнее.

    TLS и сертификат

    Лейбл Что делает
    traefik.http.routers.memos.tls=true включить TLS на роутере
    traefik.http.routers.memos.tls.certresolver=letsencrypt сертификат — от этого резолвера
    traefik.http.routers.memos.tls.domains[0].main=example.org wildcard на роутере; лучше — на точке входа («Traefik и Let's Encrypt»)

    Если у точки входа https в traefik.yml задан http.tls.certResolver, все три строки не нужны («traefik.yml по блокам»).

    Middleware

    Подключаются к роутеру одной строкой, через запятую. Порядок в строке — порядок проверок; второй лейбл middlewares затрёт первый («Middleware роутера — одной строкой»).

    Лейбл Что делает
    traefik.http.routers.memos.middlewares=crowdsec@file,global-ratelimit@file бан, потом лимит
    traefik.http.middlewares.memos-auth.basicauth.users=admin:$$2y$$05$$… пароль на вход
    traefik.http.middlewares.memos-ip.ipallowlist.sourcerange=192.168.0.0/16 пускать только из домашней сети
    traefik.http.middlewares.memos-strip.stripprefix.prefixes=/memos срезать префикс перед сервисом
    traefik.http.middlewares.memos-hdr.headers.customrequestheaders.X-Forwarded-Proto=https заголовок для сервиса
    traefik.http.middlewares.memos-gz.compress=true сжимать ответы
    traefik.http.middlewares.memos-rl.ratelimit.average=20 свой лимит: 20 в секунду

    @file — middleware из dynamic/, без суффикса — из лейблов. В v3 ipwhitelist переименован в ipallowlist, старое имя не работает.

    Хэш пароля для Basic Auth — htpasswd из пакета apache2-utils:

    htpasswd -nB admin | sed -e 's/\$/\$\$/g'     # для лейбла прямо в compose: $ удвоен
    htpasswd -nB admin                             # для .env: одинарный $, значение в одинарных кавычках

    Почему по-разному — «Знак $».

    Сервис

    Лейбл Что делает
    traefik.http.services.memos.loadbalancer.server.port=5230 порт приложения
    traefik.http.services.memos.loadbalancer.server.scheme=https сервис сам отдаёт HTTPS
    traefik.http.services.memos.loadbalancer.passhostheader=false не передавать сервису исходный Host
    traefik.http.routers.memos.service=memos явно связать роутер с сервисом

    Если у контейнера один сервис, routers.<имя>.service можно не писать — Traefik свяжет сам. Если сервисов два и больше (два порта), связь пишем явно.

    TCP: пропустить трафик без расшифровки

    Лейбл Что делает
    traefik.tcp.routers.app.rule=HostSNI(`app.example.org`) выбрать по имени из TLS-рукопожатия
    traefik.tcp.routers.app.entrypoints=https на том же 443, что сайты
    traefik.tcp.routers.app.tls.passthrough=true не расшифровывать, переслать как есть
    traefik.tcp.services.app.loadbalancer.server.port=5558 куда пересылать

    С passthrough сертификат отдаёт сам сервис, а HTTP-middleware — бан, пароль — к такому роутеру не применяются.

    Применить и проверить

    Команда Что делает
    docker compose up -d применить лейблы: пересоздаёт контейнер
    docker inspect memos --format '{{json .Config.Labels}}' | jq какие лейблы видит Traefik
    docker logs traefik --since 5m 2>&1 | grep -iE 'err|error' на что Traefik ругнулся
    docker network inspect proxy --format '{{range .Containers}}{{.Name}} {{end}}' кто в общей сети
    curl -sI https://memos.example.org | head -1 роутер отвечает
    curl -s https://whoami.example.org | grep -i '^X-Real-Ip' какой адрес видит сервис

    docker compose restart лейблы не применяет: он перезапускает контейнер со старыми лейблами. Нужен up -d — он пересоздаёт контейнер, если compose-файл изменился.