Traefik как обратный прокси: пошаговая настройка с примерами YAML | AdminWiki
Logo

Traefik как обратный прокси: пошаговая настройка с примерами YAML

02 августа 2026 12 мин. чтения
Содержание статьи

Traefik - это обратный прокси и балансировщик нагрузки, созданный для работы в контейнерных и микросервисных средах. В отличие от классических решений, он автоматически обнаруживает новые сервисы, динамически обновляет конфигурацию без перезагрузки и встроенными средствами выпускает SSL-сертификаты от Let's Encrypt. В этом руководстве вы настроите Traefik для маршрутизации трафика к Nextcloud, 3x UI и другим приложениям, получите готовые YAML-конфигурации и разберётесь, как избежать типичных ошибок при внедрении.

Мы пройдём полный цикл: от подготовки сервера и написания файла traefik.yaml до запуска в Docker и отладки. Все примеры проверены на практике. Если вы ищете способ быстро закрыть вопрос с HTTPS и маршрутизацией для self-hosted сервисов - эта инструкция даст вам рабочее решение за один вечер.

Почему Traefik? Ключевые преимущества для вашей инфраструктуры

Выбор обратного прокси определяет, сколько времени вы потратите на его обслуживание в будущем. Nginx и HAProxy - проверенные инструменты, но их конфигурация статична: каждое изменение правил маршрутизации требует перезагрузки или сигнала reload. В среде, где контейнеры появляются и исчезают постоянно, это создаёт операционную нагрузку.

Traefik решает эту проблему через провайдеры. Он подключается к Docker-сокету, Kubernetes API или читает файлы и в реальном времени отслеживает изменения. Запустили новый контейнер с корректными метками - Traefik тут же добавил маршрут и запросил сертификат. Остановили контейнер - маршрут исчез. Никаких ручных правок конфигов и перезапусков.

Встроенная поддержка Let's Encrypt - второй критический плюс. Вам не нужно ставить certbot, писать cron-задания для обновления сертификатов и настраивать их передачу в прокси. Traefik делает это сам: запрашивает, проверяет, продлевает за 30 дней до истечения. Для сравнения, в связке Nginx + cert-manager или HAProxy + acme.sh требуется настройка минимум двух дополнительных компонентов.

Третий фактор - единый формат конфигурации. Правила маршрутизации, middleware для изменения запросов, TLS-настройки описываются в YAML или через метки Docker. Это снижает когнитивную нагрузку: вам не нужно переключаться между синтаксисом nginx.conf, haproxy.cfg и отдельными инструментами автоматизации. Если вы работаете с микросервисами, оцените детальное сравнение Nginx, HAProxy и Traefik по производительности и поддержке HTTP/3 в актуальных версиях 2026 года.

Подготовка среды: что нужно перед установкой Traefik

Перед запуском Traefik убедитесь, что окружение соответствует минимальным требованиям. Пропуск этого шага - причина 80% проблем с SSL и маршрутизацией, с которыми сталкиваются при первом развёртывании.

Вам потребуется:

  • Сервер с установленным Docker Engine версии 24.0 или новее и Docker Compose v2.
  • Доменное имя, для которого вы можете управлять DNS-записями.
  • Порты 80 и 443, открытые на файрволе и не занятые другими процессами.
  • Статический внешний IP-адрес сервера.

Traefik будет принимать соединения на портах 80 (HTTP) и 443 (HTTPS). Если на сервере уже работает Nginx, Apache или другой веб-сервер, остановите их или перенастройте на другие порты. Проверить, что порты свободны, можно командой:

ss -tlnp | grep -E ':80|:443'

Пустой вывод означает, что порты свободны. Если видите строки с процессом - освободите порты перед продолжением.

Настройка DNS и проверка доступности портов

Для каждого сервиса, который вы планируете проксировать, создайте A-запись, указывающую на IP вашего сервера. Например, для Nextcloud и 3x UI:

nextcloud.example.com.  IN A  203.0.113.50
3x-ui.example.com.      IN A  203.0.113.50

После добавления записей дождитесь их распространения. Время зависит от TTL, обычно от 5 минут до часа. Проверьте резолвинг:

nslookup nextcloud.example.com
ping -c 2 nextcloud.example.com

Ответ должен содержать IP вашего сервера. Если nslookup возвращает NXDOMAIN - записи ещё не применились, подождите. Если возвращает другой IP - проверьте настройки у регистратора или хостинг-провайдера DNS.

Проверьте доступность портов извне. С клиентской машины выполните:

telnet 203.0.113.50 80
telnet 203.0.113.50 443

Успешное подключение означает, что порты открыты. Если соединение отклоняется - проверьте файрвол (iptables, ufw, firewalld) и настройки облачного провайдера (Security Groups в AWS, правила фаервола в DigitalOcean). Для Let's Encrypt критически важен порт 80: через него проходит HTTP-челлендж, подтверждающий владение доменом.

Структура traefik.yaml: разбираем основной конфигурационный файл

Файл traefik.yaml - это статическая конфигурация, которая читается при старте и определяет фундаментальные параметры: точки входа, провайдеры и резолверы сертификатов. Изменения в нём требуют перезапуска Traefik. Динамическая конфигурация (маршруты, сервисы, middleware) живёт отдельно - в метках Docker или файлах, которые Traefik отслеживает автоматически.

Минимальный рабочий traefik.yaml выглядит так:

# Статическая конфигурация Traefik
entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
  file:
    filename: "/etc/traefik/dynamic.yaml"
    watch: true

certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@example.com
      storage: "/letsencrypt/acme.json"
      httpChallenge:
        entryPoint: web

log:
  level: INFO

api:
  dashboard: true
  insecure: false

Разберём каждую секцию.

EntryPoints: определение портов для HTTP и HTTPS

EntryPoints - это сетевые точки входа, на которых Traefik слушает входящие соединения. В примере определены две:

  • web на порту 80 - для HTTP-трафика и челленджей Let's Encrypt.
  • websecure на порту 443 - для HTTPS-трафика.

Имена произвольны, но их нужно указывать в правилах маршрутизации. По умолчанию Traefik не перенаправляет HTTP на HTTPS. Это настраивается отдельно через middleware redirectScheme, который мы добавим позже в динамическую конфигурацию.

Если вам нужен дополнительный порт для внутренних сервисов (например, метрики Prometheus на 8082), добавьте третий entryPoint:

entryPoints:
  metrics:
    address: ":8082"

Providers: как Traefik узнает о ваших сервисах

Providers - источники динамической конфигурации. Traefik подписывается на них и получает информацию о роутерах, сервисах и middleware. В нашем примере два провайдера:

Docker provider подключается к сокету Docker и отслеживает контейнеры. Параметр exposedByDefault: false означает, что Traefik не будет автоматически проксировать все контейнеры подряд - только те, у которых явно указана метка traefik.enable=true. Это защищает от случайного проброса внутренних сервисов наружу.

File provider читает конфигурацию из указанного YAML-файла. watch: true включает отслеживание изменений: поправили файл - Traefik применил новые правила без перезапуска. Файловый провайдер удобен для сервисов, которые работают вне Docker: legacy-приложения на хосте, внешние API, базы данных с веб-интерфейсами.

CertificatesResolvers: автоматический выпуск SSL от Let's Encrypt

Секция certificatesResolvers настраивает взаимодействие с Let's Encrypt. Ключевые параметры:

  • email - адрес для уведомлений от Let's Encrypt (истечение сертификата, проблемы с продлением).
  • storage - файл acme.json, где Traefik хранит приватные ключи и сертификаты. Этот файл критически важен: его потеря означает повторный выпуск всех сертификатов, а частые перевыпуски могут привести к временной блокировке по лимитам Let's Encrypt (5 сертификатов на домен в неделю).
  • httpChallenge - метод подтверждения владения доменом. Traefik временно отвечает на запрос по пути /.well-known/acme-challenge/ на порту 80. Это самый надёжный метод, работающий за любыми NAT и файрволами, в отличие от TLS-ALPN-01, который требует прямой доступности порта 443 без проксирования.

Для production-среды укажите реальный email. Для тестов используйте staging-окружение Let's Encrypt, добавив caServer: "https://acme-staging-v02.api.letsencrypt.org/directory" - это позволит отлаживать конфигурацию, не упираясь в лимиты.

Запуск Traefik в Docker: docker-compose.yml и первый запуск

Создайте директорию проекта и разместите в ней файлы. Структура:

traefik/
├── docker-compose.yml
├── traefik.yaml
├── dynamic.yaml
└── letsencrypt/
    └── acme.json  (создаётся автоматически)

docker-compose.yml для запуска Traefik:

version: '3.8'

services:
  traefik:
    image: traefik:v3.1
    container_name: traefik
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik.yaml:/etc/traefik/traefik.yaml:ro
      - ./dynamic.yaml:/etc/traefik/dynamic.yaml:ro
      - ./letsencrypt:/letsencrypt
    networks:
      - proxy

networks:
  proxy:
    name: proxy
    external: false

Разбор важных моментов:

  • Docker-сокет монтируется с флагом :ro (read-only). Traefik нужен только для чтения списка контейнеров и их меток. Монтирование на запись создаёт угрозу безопасности: скомпрометированный Traefik сможет управлять демоном Docker.
  • Файлы конфигурации тоже монтируются только для чтения.
  • Директория letsencrypt монтируется на запись - сюда сохраняется acme.json с сертификатами.
  • Сеть proxy создаётся как внешняя (или с external: false при первом запуске). Все сервисы, которые Traefik должен проксировать, будут подключаться к этой же сети.

Перед запуском создайте пустой acme.json и установите права:

touch letsencrypt/acme.json
chmod 600 letsencrypt/acme.json

Traefik проверяет права доступа к этому файлу и откажется стартовать, если они слишком широкие. Запустите стек:

docker compose up -d

Проверьте логи:

docker logs traefik

Успешный запуск сопровождается строками о старте entryPoints и подключении провайдеров. Ошибки конфигурации выводятся с указанием строки и причины.

Маршрутизация к сервисам: настройка роутеров и сервисов для Nextcloud и 3x UI

В Traefik маршрутизация строится на двух сущностях: роутеры (routers) определяют правила входящих запросов, сервисы (services) - куда эти запросы направлять. Роутер анализирует HTTP-заголовки, хост, путь и на основе правил выбирает сервис. Один роутер может ссылаться на несколько middleware для модификации запроса перед отправкой.

Конфигурацию можно задать двумя способами: через метки Docker на контейнере сервиса или через файл динамической конфигурации. Первый способ удобен, когда сервис уже в Docker. Второй - когда сервис работает на хосте или на другой машине.

Настройка Nextcloud через Traefik с автоматическим HTTPS

Добавьте Nextcloud в тот же docker-compose.yml или создайте отдельный. Пример сервиса с метками Traefik:

services:
  nextcloud:
    image: nextcloud:29
    container_name: nextcloud
    restart: unless-stopped
    volumes:
      - nextcloud_data:/var/www/html
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.nextcloud.rule=Host(`nextcloud.example.com`)"
      - "traefik.http.routers.nextcloud.entrypoints=websecure"
      - "traefik.http.routers.nextcloud.tls.certresolver=letsencrypt"
      - "traefik.http.services.nextcloud.loadbalancer.server.port=80"

networks:
  proxy:
    external: true

volumes:
  nextcloud_data:

Что здесь происходит:

  1. traefik.enable=true - явно разрешаем Traefik обнаружить этот контейнер.
  2. Роутер nextcloud принимает запросы на хост nextcloud.example.com только через entrypoint websecure (порт 443).
  3. TLS включается с резолвером letsencrypt - Traefik автоматически запросит сертификат для этого домена.
  4. Сервис балансирует запросы на порт 80 контейнера Nextcloud. Traefik сам найдёт IP контейнера в сети proxy.

После запуска Nextcloud будет доступен по HTTPS. Первый запрос может занять 10-30 секунд: в это время Traefik выполняет HTTP-челлендж и получает сертификат.

Настройка 3x UI через Traefik: пример конфигурации

3x UI - это панель управления Xray-сервером с веб-интерфейсом. Настройка аналогична Nextcloud, меняются только домен и порт:

services:
  3x-ui:
    image: ghcr.io/mhsanaei/3x-ui:latest
    container_name: 3x-ui
    restart: unless-stopped
    volumes:
      - 3xui_db:/etc/x-ui
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.xui.rule=Host(`3x-ui.example.com`)"
      - "traefik.http.routers.xui.entrypoints=websecure"
      - "traefik.http.routers.xui.tls.certresolver=letsencrypt"
      - "traefik.http.services.xui.loadbalancer.server.port=2053"

volumes:
  3xui_db:

Порт 2053 - стандартный порт веб-панели 3x UI. Traefik проксирует HTTPS-запросы с 443 на этот порт внутри контейнера. Сам 3x UI не обязан поддерживать HTTPS: терминация TLS происходит на Traefik, а внутренний трафик идёт по HTTP. Это снижает нагрузку на сервисы и централизует управление сертификатами.

Использование файла динамической конфигурации для сервисов вне Docker

Не все сервисы живут в Docker. У вас может быть отдельный сервер с API, IronFish-нода на соседней машине или веб-интерфейс роутера. Для таких случаев используйте файловый провайдер dynamic.yaml:

http:
  routers:
    router-nas:
      rule: "Host(`nas.example.com`)"
      entryPoints:
        - websecure
      tls:
        certResolver: letsencrypt
      service: service-nas

  services:
    service-nas:
      loadBalancer:
        servers:
          - url: "http://192.168.1.100:5000"

Здесь роутер направляет запросы с nas.example.com на внутренний IP 192.168.1.100 порт 5000. Traefik должен иметь сетевую доступность до этого адреса. Если сервис находится в локальной сети, убедитесь, что хост с Traefik может до него достучаться.

Для более сложных сценариев - цепочек middleware, аутентификации, перезаписи путей - изучите расширенное руководство по маршрутизации в Traefik с готовыми YAML-примерами для Docker и Kubernetes.

Типичные ошибки и их решение: чек-лист для отладки

За годы работы с Traefik я выделил повторяющиеся проблемы, с которыми сталкиваются даже опытные администраторы. Вот список симптомов, причин и решений.

404 Page not found при обращении к сервису. Traefik получил запрос, но не нашёл подходящего роутера. Причины:

  • Неправильное правило Host. Проверьте, совпадает ли домен в запросе с правилом в метках или dynamic.yaml. Traefik чувствителен к точке в конце домена: Host(`nextcloud.example.com`) не совпадёт с Host(`nextcloud.example.com.`).
  • Контейнер не в той сети. Traefik видит только контейнеры в сетях, к которым он сам подключён. Убедитесь, что сервис и Traefik в одной сети proxy.
  • Метка traefik.enable не установлена или установлена в false при exposedByDefault: false.

Ошибка получения сертификата: "acme: error: 400 :: urn:ietf:params:acme:error:connection". Let's Encrypt не может подключиться к вашему серверу для проверки. Причины:

  • Порт 80 закрыт извне. Проверьте telnet-ом с внешней машины.
  • Домен не резолвится в IP сервера. Проверьте nslookup.
  • Указан неверный email в certificatesResolvers.

Сервис не обнаруживается, хотя контейнер запущен. Причины:

  • Провайдер Docker не настроен или не может подключиться к сокету. Проверьте, что volume с docker.sock указан и доступен для чтения.
  • Контейнер запущен до Traefik. Traefik не сканирует уже запущенные контейнеры при старте (если не настроен watch). Перезапустите контейнер сервиса или сам Traefik.

Ошибка "field not found" в логах Traefik. Вы используете синтаксис меток от Traefik v2 в v3 или наоборот. В v3 изменилась структура некоторых параметров. Сверьтесь с официальной документацией вашей мажорной версии.

Проверка логов Traefik и уровни логирования

Логи - основной инструмент диагностики. По умолчанию уровень INFO показывает стартовую информацию и ошибки. Для детальной отладки временно включите DEBUG в traefik.yaml:

log:
  level: DEBUG

После изменения перезапустите Traefik и смотрите логи в реальном времени:

docker logs -f traefik

В DEBUG-режиме видны все запросы, процесс принятия решений по роутингу, детали TLS-хендшейка и обращения к провайдерам. Типичное сообщение об успешной маршрутизации содержит строки "Serving default certificate for request" (если сертификат ещё не готов) или "Using ACME certificate" (если сертификат получен). После решения проблемы верните уровень INFO: DEBUG-логи быстро забивают диск и снижают производительность.

Заключение: дальнейшие шаги и лучшие практики

Вы развернули Traefik, настроили автоматический HTTPS и направили трафик на Nextcloud и 3x UI. Базовая конфигурация готова к работе. Следующий уровень - middleware: добавьте заголовки безопасности (HSTS, X-Frame-Options), настройте rate limiting для защиты от перебора паролей, подключите Basic Auth или OAuth2 для сервисов без встроенной аутентификации. Middleware объединяются в цепочки и применяются к роутерам одной строкой в конфигурации.

Включите дашборд Traefik для визуального мониторинга. В traefik.yaml уже прописан блок api с dashboard: true. Добавьте роутер для него в dynamic.yaml:

http:
  routers:
    dashboard:
      rule: "Host(`traefik.example.com`)"
      entryPoints:
        - websecure
      tls:
        certResolver: letsencrypt
      service: api@internal
      middlewares:
        - auth
  middlewares:
    auth:
      basicAuth:
        users:
          - "admin:$2y$10$..."

Пароль генерируется утилитой htpasswd. Без аутентификации дашборд нельзя публиковать в интернет.

Для production-среды настройте резервное копирование директории letsencrypt. Файл acme.json содержит приватные ключи. Раз в сутки делайте копию на отдельное хранилище. Traefik автоматически продлевает сертификаты за 30 дней до истечения, но потеря acme.json при сбое диска означает полную перевыпуск всех сертификатов с потенциальным простоем.

Если вы разворачиваете Traefik в Kubernetes, обратите внимание на руководство по Ingress-контроллерам с готовыми манифестами для production-среды. Для комплексного управления трафиком в кластере изучите настройку ingress и egress в Kubernetes с примерами NetworkPolicy и Istio.

Регулярно обновляйте Traefik. Разработчики выпускают патчи безопасности и исправления. Подпишитесь на GitHub-релизы проекта и планируйте обновление раз в квартал. Перед обновлением мажорной версии читайте changelog: между v2 и v3 изменился синтаксис некоторых параметров, и слепое обновление может сломать конфигурацию.

Поделиться:
Сохранить гайд? В закладки браузера