basforge

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

    EN
    МануалHomelabTraefik

    Traefik с нуля: первый сервис по имени и HTTPS

    Поднимаем Traefik отдельным compose-стеком, открываем через него проверочный сервис и memos по именам с сертификатом Let's Encrypt и разбираем, какие правки применяются на лету, а какие — только перезапуском. Понадобятся домен, A-записи на адрес сервера и свободные порты 80 и 443.

    Что получится

    /opt/traefik/                       стек прокси
      docker-compose.yaml
      data/traefik.yml                  статический конфиг: точки входа, провайдеры, сертификаты
      data/acme.json                    сертификаты и ключ аккаунта (права 600, не в git)
      data/dynamic/                     динамический конфиг: общие middleware, TLS-опции
    /opt/whoami/docker-compose.yaml     проверочный сервис: показывает, что пришло в запросе
    /opt/memos/docker-compose.yaml      первый настоящий сервис
    
    сеть proxy — общая: в ней Traefik и все сервисы, которые он открывает
    наружу открыты только 80 и 443; порты сервисов не публикуются

    Настройка

    1. DNS: имена смотрят на сервер

      Заводим A-записи whoami.example.org и memos.example.org на адрес сервера. Пока настраиваем, записи — без прокси Cloudflare (серое облако): так Let’s Encrypt проверяет сервер напрямую. Как жить за прокси Cloudflare — «CrowdSec с Traefik за Cloudflare» и «Traefik и Let's Encrypt».

      dig +short whoami.example.org
      # 203.0.113.10
    2. Порты 80 и 443 свободны

      ss -tlnp | grep -E ':(80|443) '
      # пусто — порты свободны

      Если там nginx или apache — останавливаем и убираем из автозапуска, иначе контейнер Traefik не поднимется: Bind for 0.0.0.0:80 failed: port is already allocated.

      Порт 80 нужен и после настройки: на него Let’s Encrypt приходит с проверкой HTTP-01.

    3. Общая сеть

      docker network create proxy

      Сеть создаём отдельно от стеков, поэтому в compose-файлах она external: true. Пересоздали стек Traefik — сеть осталась, и сервисы от неё не отцепились.

    4. Каталоги и файл для сертификатов

      mkdir -p /opt/traefik/data/dynamic /opt/traefik/data/logs
      touch /opt/traefik/data/acme.json
      chmod 600 /opt/traefik/data/acme.json

      touch обязателен: если файла нет, Docker при монтировании создаст на его месте пустой каталог («Несуществующий путь в томе»), и Traefik не сможет сохранить сертификаты. Права 600 Traefik проверяет сам.

    5. Статический конфиг

      /opt/traefik/data/traefik.yml
      global:
        checkNewVersion: false
        sendAnonymousUsage: false

      Проверку новой версии выключаем: версию задаёт тег образа.

      log:
        level: INFO
      
      accesslog:
        format: json
        filePath: /logs/access.log

      Лог Traefik — в stdout, читается docker logs traefik. Журнал запросов — в JSON-файл, его потом читают CrowdSec и Loki («Логи Traefik»).

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

      Все запросы на 80 уводятся на HTTPS сразу, на точке входа. Отдельные http-роутеры и middleware редиректа в лейблах сервисов после этого не нужны.

        https:
          address: ":443"
          http:
            aliasHeadersStrategy: delete
            tls:
              certResolver: letsencrypt

      Резолвер на точке входа: сертификат получит каждый роутер на ней, tls=true в лейблах можно не писать. aliasHeadersStrategy: delete — на обеих точках: заголовки с _ или . в имени отбрасываются. PHP и nginx читают X_Auth_User как X-Auth-User, и посетитель подделал бы заголовок, который ставит Traefik. Без строки Traefik 3.7 пишет предупреждение на каждую точку входа.

      providers:
        docker:
          exposedByDefault: false
          network: proxy
        file:
          directory: /dynamic/
          watch: true

      Открываются только контейнеры с traefik.enable=true. К ним Traefik ходит через сеть proxy, даже если они состоят ещё в своих.

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

      Адрес пишем буквами: ${…} в этом файле не подставляется («traefik.yml не подставляет переменные»). HTTP-01 — проверка через порт 80.

      Что значит каждая строка и что ещё бывает — «traefik.yml по блокам».

    6. Compose прокси

      /opt/traefik/docker-compose.yaml
      services:
        traefik:
          image: traefik:v3.7
          container_name: traefik
          restart: unless-stopped
          security_opt:
            - no-new-privileges:true

      Тег v3.7 фиксирует минорную версию: исправления приходят с docker compose pull, а смена синтаксиса между минорными версиями — только когда меняем тег сами.

          ports:
            - 80:80
            - 443:443
      Главное

      Порты публикует только Traefik: на 80 приходят редирект и проверка Let's Encrypt, на 443 — сайты. У сервисов ports: нет.

          volumes:
            - /var/run/docker.sock:/var/run/docker.sock:ro
            - ./data/traefik.yml:/traefik.yml:ro
            - ./data/acme.json:/acme.json
            - ./data/dynamic/:/dynamic/:ro
            - ./data/logs/:/logs/

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

          networks:
            - proxy
      
      networks:
        proxy:
          external: true

      Сеть proxy создана на шаге 3, поэтому здесь она external: true.

      Запускаем и смотрим, нет ли в логе ошибок и предупреждений:

      cd /opt/traefik && docker compose up -d
      docker logs traefik 2>&1 | grep -E 'ERR|WRN'
      # … WRN Traefik can reject some encoded characters in the request path. …

      Одно предупреждение остаётся, и это справка, а не ошибка. Traefik пропускает в пути закодированные символы (%2F, %00, %3B и ещё четыре), а запретить их можно в encodedCharacters точки входа. Обычным сайтам это ничего не меняет, конфиг не трогаем. Любая другая строка с ERR или WRN — разбираем до следующего шага.

    7. Проверочный сервис

      traefik/whoami отвечает текстом: какие заголовки и с какого адреса пришли. На нём проверяем маршрут, сертификат и X-Forwarded-For, пока настоящий сервис не подключён.

      /opt/whoami/docker-compose.yaml
      services:
        whoami:
          image: traefik/whoami
          container_name: whoami
          restart: unless-stopped
          labels:
            - "traefik.enable=true"
            - "traefik.http.routers.whoami.rule=Host(`whoami.example.org`)"
            - "traefik.http.routers.whoami.entrypoints=https"
      Главное

      Порт не указан: образ открывает один порт, 80, и Traefik берёт его сам. Сервис тоже не объявлен — Traefik создаёт его и привязывает к роутеру.

          networks:
            - proxy
      
      networks:
        proxy:
          external: true

      ports: нет: снаружи whoami доступен только через Traefik.

      cd /opt/whoami && docker compose up -d
      curl -s https://whoami.example.org | grep -E '^(Host|X-Forwarded-Proto|X-Real-Ip):'
      # Host: whoami.example.org
      # X-Forwarded-Proto: https
      # X-Real-Ip: <адрес, с которого запускали curl>

      Первый запрос к новому имени может занять 10–30 с: Traefik в это время получает сертификат. Пока не получил, браузер видит TRAEFIK DEFAULT CERT.

    8. Первый настоящий сервис

      /opt/memos/docker-compose.yaml
      services:
        memos:
          image: neosmemo/memos:stable
          container_name: memos
          restart: unless-stopped
          volumes:
            - ./data:/var/opt/memos

      Данные — в ./data рядом с compose, то есть в /opt/memos/data.

          labels:
            - "traefik.enable=true"
            - "traefik.http.routers.memos.rule=Host(`memos.example.org`)"
            - "traefik.http.routers.memos.entrypoints=https"
            - "traefik.http.services.memos.loadbalancer.server.port=5230"
      Главное

      Здесь порт указан явно: memos слушает 5230. Если образ открывает несколько портов, Traefik берёт наименьший — не всегда тот, что нужен.

          networks:
            - proxy
      
      networks:
        proxy:
          external: true

      Имя роутера (memos) пишем одинаково во всех его лейблах. Опечатка не даст ошибки: Traefik создаст второй роутер, и настройки разъедутся («Middleware на несуществующем роутере»).

    9. Общий middleware из файла

      То, что нужно многим сервисам, держим в data/dynamic/ и подключаем по имени с суффиксом @file.

      # /opt/traefik/data/dynamic/middlewares.yml
      http:
        middlewares:
          global-ratelimit:
            rateLimit:
              average: 100
              burst: 50
              period: 1s

      Лимит считается на каждый адрес отдельно: 100 запросов в секунду в среднем и до 50 сверх этого всплеском. Превысивший получает 429. Если перед Traefik стоит Cloudflare, нужен ещё sourceCriterion.ipStrategy.depth: 1, иначе лимит делят все посетители, пришедшие через один узел Cloudflare («traefik.yml по блокам»).

      Файл подхватывается при сохранении. Подключаем к memos ещё одним лейблом и пересоздаём контейнер:

            - "traefik.http.routers.memos.middlewares=global-ratelimit@file"
      cd /opt/memos && docker compose up -d

    Как вносить изменения

    Что меняем Где Как применить Что прерывается
    общие middleware, TLS-опции data/dynamic/*.yml сохранить файл ничего
    имя, middleware, порт сервиса лейблы в compose сервиса docker compose up -d в каталоге сервиса: контейнер пересоздаётся, Traefik видит событие только этот сервис, на время пересоздания
    точки входа, провайдеры, сертификаты, логи, плагины data/traefik.yml docker compose restart traefik все сайты, меньше секунды: сначала соединение отклоняется, потом 404, пока Traefik заново читает лейблы
    порты, тома, образ Traefik compose прокси docker compose up -d в /opt/traefik все сайты, пока контейнер пересоздаётся
    сертификаты acme.json руками не правим —

    Ошибка в файле из dynamic/ — в синтаксисе YAML или неизвестное поле — пишется в лог, а Traefik продолжает работать на прежнем конфиге. Но только до перезапуска: стартовав со сломанным файлом, Traefik не берёт из него ничего, и роутеры с middleware из этого файла отдают 404. Ошибка в traefik.yml опаснее: Traefik не стартует, и лежат все сайты сразу.

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

    В логе permissions 644 for /acme.json are too open, please use 600, сертификатов нет

    Причина
    Файл создан с правами по умолчанию.
    Делаем
    chmod 600 /opt/traefik/data/acme.json и docker compose restart traefik.

    В логе про acme.json — is a directory

    Причина
    Файла не было при первом запуске, и Docker создал на его месте каталог («Несуществующий путь в томе»).
    Делаем
    docker compose down, rmdir data/acme.json, touch и chmod 600 из шага 4, docker compose up -d.

    Сертификат не выпускается, в логе ошибка acme с connection или timeout

    Причина
    Let's Encrypt не достучался до порта 80: его закрывает фаервол провайдера или правило на сервере.
    Делаем
    Проверяем с телефона по мобильному интернету: http://whoami.example.org должен отвечать редиректом. Если порт 80 открыть нельзя — DNS-challenge («Traefik и Let's Encrypt»).

    В логе too many failed authorizations recently

    Причина
    Пять неудачных проверок на имя за час — дальше Let's Encrypt отказывает этому аккаунту на это имя, пока не пройдёт час.
    Делаем
    На время экспериментов переключаемся на тестовый сервер: caServer: https://acme-staging-v02.api.letsencrypt.org/directory. Потом убираем строку, очищаем acme.json и перезапускаем.

    404 page not found на whoami или memos

    Причина
    Нет traefik.enable=true, опечатка в имени в Host или контейнер не запущен.
    Делаем
    Смотрим docker ps --filter name=memos и сверяем лейблы.

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

    Причина
    Контейнер не в сети proxy: в его compose нет блока networks.
    Делаем
    Добавляем сеть; кто в ней — docker network inspect proxy --format '{{range .Containers}}{{.Name}} {{end}}'.

    Traefik не видит ни одного контейнера, в логе client version 1.24 is too old

    Причина
    Docker 29 и Traefik старше 3.6.1.
    Делаем
    Обновляем образ: traefik:v3.7.

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

    Сначала редирект с HTTP. На GET Traefik отвечает 301, на остальные методы — 308, чтобы метод и тело запроса не потерялись. curl -I шлёт HEAD, поэтому в проверке — 308:

    # HTTP уводит на HTTPS
    curl -sI http://whoami.example.org | head -3
    # HTTP/1.1 308 Permanent Redirect
    # Location: https://whoami.example.org/
    # сертификат — от Let's Encrypt, а не TRAEFIK DEFAULT CERT
    echo | openssl s_client -connect whoami.example.org:443 -servername whoami.example.org 2>/dev/null \
      | openssl x509 -noout -issuer -enddate
    # issuer=C = US, O = Let's Encrypt, CN = …
    # notAfter=…

    Срок — около 90 дней от сегодняшнего дня.

    # порт memos снаружи закрыт: сервис открывается только по имени
    curl -m 5 -s http://203.0.113.10:5230 || echo "закрыт"
    # закрыт