Что получится
/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; порты сервисов не публикуются
Настройка
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Порты 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.
Общая сеть
docker network create proxyСеть создаём отдельно от стеков, поэтому в compose-файлах она
external: true. Пересоздали стек Traefik — сеть осталась, и сервисы от неё не отцепились.Каталоги и файл для сертификатов
mkdir -p /opt/traefik/data/dynamic /opt/traefik/data/logs touch /opt/traefik/data/acme.json chmod 600 /opt/traefik/data/acme.jsontouchобязателен: если файла нет, Docker при монтировании создаст на его месте пустой каталог («Несуществующий путь в томе»), и Traefik не сможет сохранить сертификаты. Права 600 Traefik проверяет сам.Статический конфиг
/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 по блокам».
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— разбираем до следующего шага.Проверочный сервис
traefik/whoamiотвечает текстом: какие заголовки и с какого адреса пришли. На нём проверяем маршрут, сертификат иX-Forwarded-For, пока настоящий сервис не подключён./opt/whoami/docker-compose.yaml services: whoami: image: traefik/whoami container_name: whoami restart: unless-stoppedlabels: - "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: trueports:нет: снаружи 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.Первый настоящий сервис
/opt/memos/docker-compose.yaml services: memos: image: neosmemo/memos:stable container_name: memos restart: unless-stoppedvolumes: - ./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 на несуществующем роутере»).Общий 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 "закрыт"
# закрыт