SSD Nodes Learn Hosting plans →
Руководства Matt ConnorАвтор: Matt Connor

Запуск Tailscale в Docker Compose через sidecar

Узнайте, как изолировать контейнеры в Docker Compose с помощью Tailscale sidecar. Вы исключите публикацию портов на хосте и сделаете сервис доступным только внутри tailnet.

Запуск Tailscale в стеке Docker Compose

Для запуска Tailscale в Docker Compose требуется два сервиса. Первый — это контейнер tailscale/tailscale, который подключается к вашей tailnet. Второй — это контейнер вашего приложения, который использует сетевое пространство имен (network namespace) первого контейнера вместо публикации порта на хосте. В результате сервис становится доступен с вашего ноутбука по имени, при этом оставаясь полностью недоступным из публичного интернета.

Tailnet — это частная сеть, которую Tailscale создает между устройствами, в которые вы вошли. Если этот термин вам незнаком, сначала прочитайте что такое Tailscale и как он соединяет две машины. В этом руководстве предполагается, что Docker Engine и плагин Compose v2 уже работают, как описано в первом стеке Docker Compose на VPS.

Пример от вендора и открытый порт

Собственное руководство Tailscale по Compose содержит стек, близкий к этому.

services:
  tailscale:
    image: tailscale/tailscale:latest
    container_name: tailscale
    hostname: tailscale-nginx
    environment:
      - TS_AUTHKEY=tskey-auth-REPLACE-ME
      - TS_STATE_DIR=/var/lib/tailscale
    volumes:
      - ./tailscale-state:/var/lib/tailscale
    cap_add:
      - net_admin
      - net_raw
    restart: unless-stopped

  nginx:
    image: nginx:latest
    container_name: nginx_server
    ports:
      - "8080:80"
    depends_on:
      - tailscale
    restart: unless-stopped

Каждая строка сервиса tailscale верна. TS_AUTHKEY выполняет аутентификацию узла. TS_STATE_DIR указывает tailscaled, где сохранять состояние, а bind mount сохраняет это состояние на диске. Проблема заключается во втором сервисе.

Эти два контейнера находятся в стандартной мостовой сети Compose, каждый со своим адресом. Это обычное поведение, описанное в как сети Compose соединяют контейнеры по имени сервиса. Контейнер tailscale присоединился к tailnet только для себя и не перенаправляет трафик в контейнер nginx. Таким образом, в tailnet нет маршрута к nginx, и единственный способ доступа снаружи VPS — это порт 8080 на хосте.

Опубликованный порт привязывается к 0.0.0.0, если вы не укажете адрес перед ним или не зададите другой адрес привязки по умолчанию в сети, поэтому на VPS этот порт отвечает на публичном IP. Фактически приложение находится в вашем tailnet по имени, но доступно из интернета. Хостовый файрвол вас также не спасет, так как Docker вставляет свои правила перенаправления перед цепочкой ufw. Это ловушка, описанная в почему правило deny в ufw не закрывает опубликованный порт Docker.

Еще одна деталь, которую стоит упомянуть. Пример предоставляет net_admin и net_raw, но не выполняет маппинг /dev/net/tun. TS_USERSPACE по умолчанию имеет значение true, поэтому контейнер запускает сетевой стек в пространстве пользователя, и эти две возможности остаются неиспользованными.

Sidecar: одно пространство имен, без публикации портов

Поместите приложение в сетевое пространство имен контейнера tailscale с помощью network_mode: service:tailscale. Оба процесса будут видеть один и тот же loopback-интерфейс и один и тот же адрес в tailnet, даже если они запущены в разных контейнерах.

services:
  tailscale:
    image: tailscale/tailscale:v1.102.5
    container_name: ts-nginx
    hostname: nginx-demo
    environment:
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_HOSTNAME=nginx-demo
      - TS_STATE_DIR=/var/lib/tailscale
    volumes:
      - ./ts-state:/var/lib/tailscale
    restart: unless-stopped

  nginx:
    image: nginx:1.30.4-alpine
    network_mode: service:tailscale
    depends_on:
      - tailscale
    restart: unless-stopped

Ключ размещается в файле .env рядом с файлом compose, а не в YAML, поэтому файл, который вы отправляете в репозиторий, не содержит секретов. Одна строка: TS_AUTHKEY=tskey-auth-.... В сохранении секретов вне коммитов compose-файла описаны остальные аспекты этого подхода.

Запустите конфигурацию и проверьте обе части.

docker compose up -d
docker compose exec tailscale tailscale status
docker compose logs --tail 20 tailscale

tailscale status должен вывести строку для этого узла с адресом 100.x, за которой последуют другие машины в вашей tailnet. С ноутбука, который также авторизован в сети, curl http://nginx-demo/ возвращает приветственную страницу nginx. На самом VPS sudo ss -lntp | grep 8080 не возвращает ничего, так как порт не был опубликован.

Почему порт 80, а не 8080: в режиме userspace tailscaled направляет входящее туннельное соединение на тот же порт на localhost. nginx слушает 80-й порт внутри общего пространства имен, поэтому tailnet достигает его через 80-й порт. Измените порт, на котором слушает приложение, и порт в tailnet изменится вместе с ним. Этот трюк с совместным использованием пространства имен не является специфичным для Tailscale, и те же вопросы о доступе к хосту и остальному стеку возникают в контейнере Gluetun, который управляет сетью соседних контейнеров.

Какой ключ аутентификации нужен контейнеру?

Тип ключа определяет поведение при повторном запуске, поэтому выберите его до развертывания. Сгенерируйте ключ на странице Keys в консоли администратора. Диалоговое окно отобразит его только один раз.

  • Одноразовые ключи (One-off keys) аутентифицируют только одно устройство. Стек, пересозданный без директории состояния, не сможет подключиться снова.
  • Многоразовые ключи (Reusable keys) аутентифицируют любое количество устройств. Это стандартный выбор для стека Compose.
  • Эфемерные ключи (Ephemeral keys) помечают узел для автоматического удаления. Tailscale удаляет эфемерное устройство через 30–60 минут после его последней активности.
  • Предварительно одобренные ключи (Pre-approved keys) позволяют пропустить ручное подтверждение устройства; это важно, только если в вашей tailnet включено подтверждение устройств.
  • Тегированные ключи (Tagged keys) применяют тег ACL, например tag:container, в момент аутентификации. Устройство перестает принадлежать конкретному пользователю, а срок действия его ключа по умолчанию отключается.

Последний пункт — самый важный для эксплуатации. Срок действия ключа узла по умолчанию составляет 180 дней, и после его истечения узел отключается от tailnet, пока пользователь не выполнит вход повторно или администратор не отключит истечение срока действия ключа. Тегированный ключ убирает это ограничение, поэтому теги используются для серверов и контейнеров.

Истечение срока действия ключа аутентификации — это отдельное событие, и их часто путают. Ключи аутентификации действуют от 1 до 90 дней, по умолчанию — 90 дней. Истечение срока действия ключа не отключает устройства, которые уже прошли аутентификацию. Оно лишь блокирует добавление новых устройств. Для долгоживущего сервиса используйте многоразовый тегированный ключ, который не является эфемерным. Для стека, который вы постоянно удаляете, например, для среды предварительного просмотра, эфемерный ключ поможет поддерживать чистоту в консоли администратора без ручного удаления.

Почему контейнер каждый раз определяется как новая машина?

Потому что tailscaled сохранил свое состояние там, где оно не сохранилось. Если TS_STATE_DIR не задан, образ хранит состояние только в оперативной памяти. Если он задан, но не смонтирован, состояние попадает в записываемый слой контейнера, а docker compose down удаляет контейнер.

Идентификатор узла находится в этом каталоге состояния. Обеспечьте его постоянное хранение, и контейнер сохранит свое имя и 100.x адрес после перезагрузок, вместе со всей конфигурацией сервиса. Потеряете его — и следующий запуск станет первым: контейнер снова пройдет аутентификацию с тем же ключом, а в консоли администратора появится вторая машина. Обе претендуют на имя хоста nginx-demo, поэтому MagicDNS присваивает новой машине пронумерованный суффикс, а все сохраненные вами ссылки будут указывать на нерабочий узел.

Должны выполняться два условия. TS_STATE_DIR=/var/lib/tailscale должен быть задан, так как вне Kubernetes у него нет значения по умолчанию. И этот путь должен быть смонтирован — либо через bind mount, как показано выше, либо через именованный том; выбор между ними описан в bind mounts versus named volumes. Настройка одного без другого — распространенная ошибка. Монтирование без TS_STATE_DIR приводит к потере идентификатора при каждой перезагрузке, а TS_STATE_DIR без монтирования работает незаметно: стек ведет себя корректно до первого down.

Проверяйте это, а не полагайтесь на предположения.

docker compose down
ls -l ./ts-state
docker compose up -d
docker compose exec tailscale tailscale status

./ts-state должен содержать tailscaled.state еще до второго up, и узел должен вернуться с тем же адресом, который у него был ранее. Другой адрес означает, что монтирование не работает.

Закрепите образ и укажите использованный тег

tailscale/tailscale:latest следует за новейшей стабильной сборкой. docker compose pull через шесть месяцев загрузит другой tailscaled, а следующий docker compose up -d пересоздаст контейнер на основе кода, который вы не выбирали. Обычный перезапуск сохраняет старый образ, поэтому изменения вступят в силу при следующей пересоздании контейнера, а не в момент загрузки. Приведенный выше стек закрепляет v1.102.5 — образ, на который указывали теги stable и latest в Docker Hub 10 октября 2026 года. В журнале изменений Tailscale уже указан клиент 1.104.1, выпущенный 7 октября 2026 года, поэтому перед изменением закрепления проверьте Docker Hub на наличие соответствующего тега образа. Docker Hub также публикует v1.102 для ветки исправлений и тег unstable, которые не следует использовать на сервере.

Обновляйтесь осознанно.

docker compose pull tailscale
docker compose up -d
docker compose exec tailscale tailscale version

Редактирование тега и выполнение up -d пересоздает контейнер, что не равносильно его перезапуску. Статью Разница между restart, up и rebuild стоит прочитать до того, как вы начнете отладку изменений версии, которые не вступили в силу.

Сетевое взаимодействие в пространстве пользователя и его стоимость

TS_USERSPACE по умолчанию имеет значение true. В этом режиме контейнер запускает стек TCP/IP в пространстве пользователя и не обращается к /dev/net/tun, что позволяет работать на хостах, которые не предоставляют контейнеру устройство TUN. Входящие соединения по-прежнему работают, так как входящие туннельные подключения перенаправляются на тот же порт на localhost. Именно поэтому sidecar-контейнеру выше не требуются специальные устройства или права доступа.

Исходящий трафик — это то, за что приходится платить. В режиме пространства пользователя приложение не может просто открыть сокет к другому узлу tailnet. Вместо этого tailscaled предоставляет SOCKS5-прокси и HTTP-прокси. Вам нужно настроить TS_SOCKS5_SERVER=localhost:1055 в сервисе tailscale и ALL_PROXY=socks5://localhost:1055 в приложении, при этом приложение должно учитывать эти настройки. Любое приложение, игнорирующее переменные окружения прокси, не сможет связаться с tailnet.

Сам стек имеет ограничения, о которых стоит знать. Передаются только протоколы TCP и UDP, поэтому любые другие IP-протоколы, такие как SCTP, не проходят. Поддержка ICMP ограничена только эхо-запросами (ping), которые восстанавливает демон, что добавляет небольшую заметную задержку. Соединения завершаются на узле и устанавливаются заново до целевого адреса, поэтому они не являются сквозными (end-to-end). Начиная с версии 1.20, узел в пространстве пользователя может достичь выходного узла (exit node) или маршрута подсети, который анонсирует кто-то другой, но только через эти прокси; также он может сам анонсировать такие маршруты.

Если вам нужен прозрачный исходящий трафик, переключитесь на сетевой стек ядра, добавив три параметра в сервис tailscale.

    environment:
      - TS_USERSPACE=false
    devices:
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - net_admin

Сначала убедитесь, что хост может предоставить такую возможность с помощью test -c /dev/net/tun && echo ok. В KVM это устройство присутствует. В контейнерной виртуализации, использующей общее ядро хоста, оно может отсутствовать, и тогда пространство пользователя останется единственным вариантом. Предоставьте контейнеру устройство TUN, если он должен выполнять роль маршрутизатора подсети, анонсирующего частный диапазон или выходного узла для других ваших устройств, так как именно эти роли больше всего ограничены при работе в пространстве пользователя.

Доступ к сервису: serve или обычное имя MagicDNS

Самый простой путь — использование имени MagicDNS. С любого устройства в tailnet работает http://nginx-demo/, а также полное имя http://nginx-demo.your-tailnet.ts.net/. Обычный HTTP в данном случае не является открытым текстом в сети, так как WireGuard шифрует трафик между двумя узлами, а информация о том, что сервер координации может и не может видеть определяет границы этой гарантии. Сертификат отсутствует, поэтому браузер помечает источник как небезопасный, и любые веб-функции, требующие безопасного контекста, отказываются работать.

Другой путь — использование Tailscale Serve, запущенного внутри контейнера.

docker compose exec tailscale tailscale serve --bg localhost:80
docker compose exec tailscale tailscale serve status

Эта команда публикует приложение по адресу https://nginx-demo.your-tailnet.ts.net с сертификатом, который предоставляет Tailscale. И MagicDNS, и HTTPS-сертификаты должны быть включены на странице DNS в панели администратора, иначе не будет имени, которое можно указать в сертификате. --bg записывает конфигурацию в состояние tailscaled, которое вы сохранили, поэтому она восстанавливается вместе с контейнером, а tailscale serve reset удаляет её. TS_SERVE_CONFIG указывает на JSON-файл, если вы предпочитаете хранить конфигурацию в репозитории, а не в командной строке. Serve работает только внутри tailnet. Funnel — это отдельная команда, которая выставляет тот же сервис в публичный интернет, поэтому ознакомьтесь с разницей между Serve и Funnel перед выполнением любой из них.

Типичные сбои и сообщения об ошибках

Error response from daemon: conflicting options: port publishing and the container type network mode. Вы оставили блок ports: в описании sidecar-сервиса. Публиковать порты может только контейнер, владеющий пространством имен, а приложение, работающее только внутри tailnet, не должно публиковать ничего. Удалите этот блок.

Контейнер приложения запущен, но запросы до него не доходят. Вы пересоздали сервис tailscale отдельно. Пространство имен, которым он владел, было уничтожено вместе с ним, и приложение теперь привязано к несуществующему объекту. Пересоздайте пару целиком с помощью docker compose up -d --force-recreate.

Узел не появляется в консоли администратора. Прочитайте docker compose logs tailscale. Там отображаются отклоненные ключи. Использование одноразового ключа, который уже был применен, или ключа с истекшим сроком действия останавливает узел до того, как он подключится к tailnet.

Узел запущен, tailscale status выглядит корректно, а curl http://nginx-demo/ зависает. Приложение слушает не тот интерфейс, который вы ожидаете. Проверьте его изнутри общего пространства имен с помощью docker compose exec nginx wget -qO- http://localhost/. Если проверка не проходит, проблема в приложении, а не в Tailscale. Если проходит, значит, приложение привязано к конкретному интерфейсу, а не ко всем доступным.

Машина исчезла из консоли через час после остановки стека. Ключ был эфемерным. Удаление происходит через 30–60 минут после последней активности, это штатная работа функции.

Начиная с версии 1.78 образ может открывать неаутентифицированный endpoint /healthz: установите TS_ENABLE_HEALTH_CHECK=true, который слушает TS_LOCAL_ADDR_PORT, по умолчанию [::]:9002. Настройте healthcheck в Compose на этот адрес, чтобы узел, не прошедший аутентификацию, помечался как неработоспособный, а не отображался как активный. Если вы не хотите зависеть от серверов координации Tailscale, тот же файл compose может взаимодействовать с вашим собственным сервером управления через TS_EXTRA_ARGS=--login-server=https://headscale.example.com, что является отправной точкой для запуска Headscale в качестве собственного сервера управления.

FAQ

Почему другие устройства в моей tailnet не могут получить доступ к моему контейнеру с приложением?

Потому что контейнер Tailscale присоединился к tailnet только для самого себя. Если приложение работает в стандартной сети Compose bridge со своим собственным адресом, узел Tailscale не пересылает на него трафик, и единственный способ попасть внутрь с хоста — это опубликованный порт. Назначьте приложению network_mode: service:tailscale, чтобы оно использовало сетевое пространство имен контейнера Tailscale, а затем удалите блок ports:. После этого приложение станет доступно в tailnet на порту, который оно прослушивает.

Нужен ли /dev/net/tun для запуска Tailscale в Docker Compose?

Для входящих соединений — нет. TS_USERSPACE по умолчанию имеет значение true, и в этом режиме tailscaled использует собственный сетевой стек, перенаправляя входящие соединения туннеля на тот же порт на localhost. Таким образом, sidecar-контейнер работает без устройства и дополнительных прав доступа. /dev/net/tun, TS_USERSPACE=false и net_admin требуются, когда контейнеру необходимо прозрачно открывать исходящие соединения в tailnet или выступать в роли subnet router или exit node.

Что использовать для стека Compose: эфемерный или многоразовый ключ аутентификации?

Для любых долгоживущих сервисов используйте многоразовый ключ с тегами, который не является эфемерным. У устройства, прошедшего аутентификацию с тегом, по умолчанию отключено истечение срока действия ключа узла, поэтому контейнер не будет удален из tailnet через 180 дней в ожидании повторной авторизации. Добавление тега к уже авторизованному узлу не меняет срок действия до тех пор, пока он не пройдет аутентификацию снова. Выбирайте эфемерный ключ только для стеков, которые часто удаляются (например, среды предварительного просмотра), так как Tailscale удаляет эфемерное устройство через 30–60 минут после последней активности, что позволяет поддерживать чистоту в консоли администратора.

Почему мой контейнер отображается как новая машина при каждом перезапуске?

Директория состояния не сохраняется, поэтому tailscaled запускается без идентификатора и проходит аутентификацию как совершенно новый узел. Укажите TS_STATE_DIR=/var/lib/tailscale, у которого нет значения по умолчанию вне Kubernetes, и примонтируйте этот путь к bind mount или именованному тому. Без TS_STATE_DIR состояние хранится в оперативной памяти и исчезает при каждом перезапуске. Если задать параметр без монтирования, всё будет выглядеть нормально до первого docker compose down. Убедитесь, что tailscaled.state существует в примонтированной директории, пока стек остановлен.

Была ли эта статья полезной?