Docker-контейнери через VPN: чому зникають порти
Gluetun і network_mode: service змінюють мережевий простір контейнера. Дізнайтеся, чому порти зникають і як налаштувати робочий compose-файл.
Чому порти зникають, коли Docker-контейнери працюють через VPN
Щоб спрямувати Docker-контейнери через VPN, підключіть тунель до одного контейнера, а потім приєднайте інші контейнери до його мережевого простору імен за допомогою network_mode: "service:gluetun". Саме це приєднання часто спричиняє несподівані наслідки. Приєднаний контейнер більше не має власної мережі, тому разом із нею втрачає опубліковані порти та ім’я Docker-сервісу. Публікуйте порти на VPN-контейнері, а з інших контейнерів звертайтеся до застосунку за іменем VPN-контейнера.
Якщо залишити блок ports: у приєднаному контейнері, Docker взагалі відмовиться його створювати:
Error response from daemon: conflicting options: port publishing and the container type network modeУ цьому прикладі використовується Gluetun — контейнер, який підключається до комерційного провайдера VPN (віртуальної приватної мережі) через WireGuard або OpenVPN і має власний firewall. Станом на October 2026 актуальною є версія v3.41.3. У прикладах використовується Mullvad із WireGuard, тому вам потрібні обліковий запис і ключ від провайдера. Якщо ви хочете завершувати тунель на власному обладнанні, розгортання власного WireGuard-сервера на VPS створює інший кінець тунелю, а wg-easy у Docker додає до нього вебінтерфейс.
Що насправді робить network_mode: "service:gluetun"
Кожен контейнер Docker зазвичай отримує власний мережевий простір імен: власні інтерфейси, таблицю маршрутизації, правила firewall і сокети, що прослуховують порти. Режим service: пропускає цей крок і запускає контейнер у просторі імен gluetun. Один простір імен означає одну IP-адресу, і це змінює шість речей.
- Застосунок не має власної адреси. Його адреса — адреса gluetun.
- Застосунок не підключений до жодної Docker network, тому його ім’я сервісу не реєструється і не розпізнається. Інші контейнери мають використовувати
gluetun. - Контейнери в одному просторі імен взаємодіють через
localhost. - Два контейнери в одному просторі імен не можуть прослуховувати один і той самий порт. У документації Gluetun це зазначено прямо: обхідного рішення немає.
- Capabilities належать контейнеру, а не простору імен. Gluetun має
NET_ADMINі/dev/net/tun, оскільки створює тунельний інтерфейс. Підключений контейнер не успадковує їх. - Compose відхиляє будь-який файл, у якому один сервіс задає одночасно
network_modeіnetworks. Підключіть gluetun до своїх мереж, і застосунок використовуватиме їх через цей контейнер.
Перезапуск gluetun від’єднує всі підключені до нього компоненти. Це задокументована поведінка, і саме тому gluetun перезапускає процес VPN усередині контейнера, а не завершує роботу, коли з’єднання розривається. Після ручного перезапуску або повторного створення gluetun перезапустіть контейнери, підключені до нього.
Файл compose, який працює
services:
gluetun:
image: qmcgaw/gluetun:v3
container_name: gluetun
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
environment:
- VPN_SERVICE_PROVIDER=mullvad
- VPN_TYPE=wireguard
- SERVER_CITIES=Amsterdam
- TZ=Europe/Amsterdam
env_file:
- ./gluetun.env
volumes:
- ./gluetun:/gluetun
ports:
- 127.0.0.1:8080:8080/tcp
restart: unless-stopped
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:latest
container_name: qbittorrent
network_mode: "service:gluetun"
environment:
- PUID=1000
- PGID=1000
- TZ=Europe/Amsterdam
- WEBUI_PORT=8080
volumes:
- ./qbittorrent:/config
- ./downloads:/downloads
depends_on:
gluetun:
condition: service_healthy
restart: unless-stoppedТег :v3 — це останній стабільний реліз у серії v3. Тег :latest вказує на останній коміт гілки master, тобто на нестабільну версію для розробки, тому зафіксуйте :v3 на машині, яку не плануєте налагоджувати посеред робочого дня.
WEBUI_PORT=8080 має відповідати опублікованому порту, оскільки qBittorrent прив’язується всередині namespace gluetun, а правило публікації передає трафік із хоста на порт 8080 у цьому namespace. Якщо змінити лише одне з цих чисел, порт не відповідатиме. 127.0.0.1:8080:8080 залишає вебінтерфейс доступним лише через loopback-адресу хоста. Окремий 8080:8080 публікує порт на всіх інтерфейсах і додає власне правило firewall. Саме так опубліковані порти Docker обходять ufw.
Запустіть стек, а потім перевірте його в такому порядку:
docker compose up -d
docker compose ps
docker compose logs gluetun | tail -30docker compose ps має показати gluetun зі статусом healthy, а qbittorrent — зі статусом running. Потім перевірте адресу виходу зсередини namespace. Саме ця перевірка визначає результат усіх наступних:
docker run --rm --network=container:gluetun alpine:3.22 sh -c "apk add wget && wget -qO- https://ipinfo.io"Поле ip у цьому JSON має містити адресу вашого VPN-провайдера. Якщо там указано адресу самого сервера, застосунок не працює через тунель, і все описане нижче працюватиме неправильно.
Не зберігайте ключі у файлі compose
gluetun.env містить облікові дані, і цей файл не додають до git:
WIREGUARD_PRIVATE_KEY=wOEI9rqqbDwnN8/Bpp22sVz48T71vJ4fYmFWujulwUU=
WIREGUARD_ADDRESSES=10.64.222.21/32Обидва значення беруться з файла конфігурації WireGuard, який ви створюєте в обліковому записі у провайдера. Встановіть для файла режим 600. Важливо правильно оцінювати переваги: ключ не потрапляє до вашого репозиторію, але docker inspect gluetun усе одно виводить усі змінні середовища для будь-кого, хто має доступ до Docker socket. У матеріалі Файли середовища та секрети в Docker Compose описано надійніші варіанти.
Як контейнер поза тунелем взаємодіє з контейнером усередині нього
Обидва напрямки працюють, і для кожного використовується інше ім’я. Контейнерам потрібна спільна Docker network — у цьому випадку network gluetun, оскільки підключений контейнер не має власної network. У розділі Як підключені мережі Docker Compose описано стандартну конфігурацію.
Для підключення ззовні до контейнера всередині використовуйте ім’я gluetun і порт, на якому прослуховується застосунок. Контейнер reverse proxy звертається до web-інтерфейсу qBittorrent за адресою gluetun:8080. Запис ports: для цього не потрібен, оскільки трафік між контейнерами залишається в Docker network і не проходить через порт хоста.
Для підключення зсередини назовні використовуйте service name іншого контейнера, наприклад postgres:5432. Починаючи з v3.41, Gluetun визначає імена інших контейнерів зі свого namespace. Якщо ім’я не визначається, зафіксуйте цю або новішу версію.
Firewall Gluetun визначає, хто може відкривати до нього з’єднання. Трафік із власної Docker network gluetun дозволений. Для клієнта з іншої subnet, ноутбука у вашій LAN або контейнера в окремій bridge network потрібні дозволений firewall Gluetun і маршрут для зворотного трафіку:
FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24Документоване значення точне: subnet, розділені комами, до яких Gluetun і контейнери зі спільним network stack мають доступ.
Вхідні з’єднання з інтернету — окрема проблема. Піри torrent-клієнта підключаються через VPN, тому публікація порту 6881 на хості їм не допоможе. Потрібен port forwarding від вашого провайдера, а цей порт має бути вказаний у FIREWALL_VPN_INPUT_PORTS. Це дозволяє використовувати порти на стороні VPN-сервера. Mullvad, який використовується в цьому прикладі, не підтримує port forwarding, тому потрібен провайдер із такою підтримкою. Саме ця частина найчастіше залишається несправною у media stack, створених за допомогою Docker Compose.
Kill switch: що відбувається, коли тунель розривається
Ця схема виправдовує свою складність у разі збою. Підключений контейнер використовує інтерфейси та таблицю маршрутизації Gluetun. Firewall Gluetun блокує звичайний інтернет-трафік поза тунелем, але дозволяє підключення до endpoint VPN-сервера, локальний Docker-трафік і налаштовані винятки. Саме цей firewall не дає трафіку перейти на звичайний інтерфейс після розриву тунелю. Немає проміжку, протягом якого пакети можуть витікати через звичайний інтерфейс, поки клієнт повторно підключається.
Gluetun контролює власне підключення. Щохвилини він надсилає ICMP echo (ping) на адреси з HEALTH_ICMP_TARGET_IPS, значення яких за замовчуванням — 1.1.1.1,8.8.8.8. Якщо ICMP заборонений, ця коротка перевірка натомість використовує незашифрований UDP-запит DNS. Кожні 5 хвилин він встановлює повне TCP- і TLS-підключення (transport layer security) до HEALTH_TARGET_ADDRESSES, значення якого за замовчуванням — cloudflare.com:443,github.com:443. Якщо ці перевірки не проходять, Gluetun перезапускає VPN усередині контейнера та записує подію в журнал:
WARN [vpn] restarting VPN because it failed to pass the healthcheck: periodic check: dialing: dial tcp4: lookup cloudflare.com: i/o timeoutПереглядайте журнали підключеного контейнера з урахуванням цього порядку. Рядки на кшталт connection refused, operation not permitted і i/o timeout усередині застосунку є наслідками непрацюючого тунелю, а не його причинами. У документації Gluetun це прямо зазначено, оскільки користувачі повідомляють про наслідок і годинами шукають причину не там.
HEALTH_RESTART_VPN=on увімкнено за замовчуванням і його слід залишати увімкненим. Вимикайте його лише під час діагностики конкретної проблеми, оскільки після вимкнення непрацюючий тунель залишатиметься непрацюючим.
Порядок запуску: не запускайте стек, доки тунель не встановлено
У цьому образі вже налаштовано Docker healthcheck:
HEALTHCHECK --interval=5s --timeout=5s --start-period=10s --retries=3 CMD /gluetun-entrypoint healthcheckЦя команда запускає ще один короткоживучий екземпляр gluetun, який опитує health server запущеного екземпляра за адресою http://127.0.0.1:9999/. Працюючий тунель повертає 200 OK. Непрацюючий тунель повертає 500 Internal server error із рядком помилки, після чого Docker позначає контейнер як несправний після трьох послідовних невдалих перевірок.
Саме condition: service_healthy очікує на цей результат. Звичайний depends_on: [gluetun] очікує лише запуску контейнера. Це відбувається за кілька секунд до завершення handshake, тому застосунок запускається без робочої мережі й часто завершує роботу після першої невдалої спроби підключення. У розділі Healthchecks у Docker Compose описано синтаксис і поля, що визначають час очікування.
Є обмеження, про яке часто забувають. Compose перевіряє цю умову під час запуску стека. Пізніше він не зупиняє і не перезапускає застосунок, якщо gluetun переходить у стан несправності. У такому випадку працює внутрішній механізм auto-healing gluetun. Саме тому він перезапускає VPN-процес, а не контейнер.
Перевірте витік DNS, перш ніж довіряти налаштуванню
DNS (domain name system) — це витік, який зберігається навіть за правильно налаштованого тунелю. Gluetun запускає власний resolver у namespace і за замовчуванням пересилає запити через DoT (DNS over TLS) до Cloudflare: DNS_UPSTREAM_RESOLVER_TYPE=dot і DNS_UPSTREAM_RESOLVERS=cloudflare. Не змінюйте ці параметри, і DNS-запити буде зашифровано та передано через тунель.
Параметр, який порушує цю схему, якщо вказати локальний resolver, — DNS_UPSTREAM_PLAIN_ADDRESSES. До нього звертаються, коли ім’я не вдається розв’язати і потрібно, щоб відповідь надав router або resolver провайдера. Документація Gluetun попереджає, що запити до resolver у Docker bridge або LAN виходять за межі VPN-тунелю. Публічний resolver без шифрування все одно отримує запити через тунель, але VPN-провайдер може їх читати та змінювати. Аналогічну помилку для WireGuard описано в розділі DNS, який перестає розв’язувати імена через тунель WireGuard.
Щоб виконати перевірку, задайте SHADOWSOCKS=on і SHADOWSOCKS_PASSWORD для gluetun, опублікуйте 8388:8388/tcp і 8388:8388/udp, потім підключіться за допомогою клієнта Shadowsocks, налаштованого для передавання UDP DNS через тунель, і відкрийте тест на витік DNS. У результаті має бути вказано вашого провайдера або Cloudflare, але не ваш домашній router. Власна документація Gluetun попереджає, що деякі тести на витік можуть показувати нетипові результати, оскільки resolver усередині namespace є локальним кешувальним посередником, а не сервером, який остаточно надає відповідь. Справжньою ознакою витоку вважайте неправильну країну або resolver вашого ISP.
Додавання Tailscale поруч із VPN sidecar і визначення пріоритетного маршруту
Tailscale — це overlay network на основі WireGuard для доступу до власних машин. Його запускають поруч із VPN провайдера, щоб зберегти адміністративний доступ до стеку. Спільний namespace також означає спільні правила firewall, тому налаштування firewall і маршрутизації мають бути сумісними. У документації Tailscale зазначено поведінку за замовчуванням: він працює як overlay network, маршрутизує трафік лише між пристроями, на яких запущено Tailscale, і не змінює ваш публічний інтернет-трафік.
Відповідь залежить від одного параметра.
- Tailscale у власному контейнері з конфігурацією за замовчуванням: він ніколи не бачить вихідний трафік застосунку. Увесь цей трафік передає Gluetun. Процес у контейнері Tailscale досягає застосунку за адресою
gluetun:8080через спільну Docker network; щоб зробити це з’єднання доступним клієнтам tailnet, потрібні forwarding або proxy. - Tailscale, під’єднаний до namespace gluetun за допомогою
network_mode: "service:gluetun": у режимі userspace networking за замовчуваннямTS_USERSPACEувімкнено, tailscaled не створює жодного інтерфейсу та працює як SOCKS5 або HTTP proxy, тому не може змінювати маршрутизацію. Gluetun і далі передає звичайний вихідний трафік, якщо застосунок явно не використовує цей proxy. - Те саме з
TS_USERSPACE=false: Tailscale потребує власного пристрою/dev/net/tunі capabilities, оскільки namespace їх не надає. Tailscaled створює tunnel device і в Linux зазвичай встановлює окремі IPv4-маршрути peer /32, а не один маршрут для100.64.0.0/10. Саме налаштуванняTS_USERSPACE=falseне вмикає агрегований маршрут. Маршрути підмереж інших вузлів він встановлює лише якщо передати--accept-routesчерезTS_EXTRA_ARGS.TS_ROUTESпрацює у зворотному напрямку: він оголошує решті вашого tailnet підмережі, до яких може дістатися цей контейнер, тобто еквівалентtailscale set --advertise-routes=, і не додає тут жодних маршрутів. Публічний трафік і далі виходить через gluetun. - Kernel networking у namespace gluetun із вибраним exit node,
sudo tailscale set --exit-node=<exit-node-ip>: Tailscale встановлює default routes у цьому namespace, але firewall Gluetun може блокувати цей шлях. Вибір exit node в окремому контейнері не змінює маршрути застосунку, а userspace mode передає лише трафік, який явно спрямовано через його proxy. Не поєднуйте конкуруючі default routes у namespace gluetun. Один default route — один власник.
Якщо ці оголошені маршрути є метою і потрібно забезпечити доступ до всієї приватної мережі за цим хостом, а не лише до самого хоста, запуск Tailscale subnet router на VPS охоплює схвалення маршруту, IP forwarding і прапорець на стороні клієнта, які TS_ROUTES самостійно не налаштовує.
Якщо Tailscale потрібен для надання admin URL, а не маршруту, tailscale serve і tailscale funnel розміщують HTTPS перед локальним HTTP-сервісом, причому лише funnel відкриває його для публічного інтернету. Документація Tailscale Serve підтримує лише http://127.0.0.1 як ціль HTTP proxy. Спільна Docker network не робить http://gluetun:8080 підтримуваною ціллю. Використайте спільний network namespace gluetun із network_mode: "service:gluetun" і вкажіть http://127.0.0.1:8080 як ціль.
Один побічний ефект помітний, коли Tailscale працює всередині тунелю. Його peers бачать адресу VPN-провайдера, тому він частіше переходить на relays. tailscale status показує relay "..." поруч із peer замість direct, коли це сталося. З’єднання працює, але воно повільніше. Якщо вам фактично потрібна лише overlay network, різниця між звичайним WireGuard і Tailscale — краща відправна точка.
Що може зламатися і яке повідомлення ви побачите
Docker відмовляється створювати контейнер застосунку. Error response from daemon: conflicting options: port publishing and the container type network mode означає, що блок ports: досі належить підключеному сервісу. Перенесіть його до gluetun.
Compose відмовляється обробляти весь файл. Сервіс не може одночасно задавати network_mode і networks. Додайте мережі до gluetun.
Інший контейнер не може визначити адресу застосунку. curl: (6) Could not resolve host: qbittorrent є правильною поведінкою, оскільки підключений контейнер не приєднався до жодної мережі й не зареєстрував жодного імені. Використовуйте gluetun і порт.
Другий підключений контейнер не запускається. Два процеси в одному namespace не можуть прив’язати один і той самий порт, тому процес, який програв, повідомляє, що адреса вже використовується. Змініть внутрішній порт застосунку або запустіть другий gluetun.
Після змін у gluetun застосунок не має мережі. Перезапуск або повторне створення gluetun розриває підключення для всіх приєднаних до нього контейнерів. Перезапустіть ці контейнери.
Малі сторінки завантажуються, а великі зависають. Це проблема MTU (максимального розміру передаваного блока). Тунель додає службові дані, і певний вузол на маршруті відкидає завеликі пакети, не повертаючи повідомлення про помилку. Перевірте WIREGUARD_MTU. Значення за замовчуванням у v3.41.3 — 1320. Зменште його, якщо маршрут потребує менших пакетів. У development image використовується path MTU discovery, якщо це значення не задано.
Gluetun не переходить у стан healthy. Перевірка під час запуску називає перші об’єкти для перевірки: WARN [vpn] restarting VPN because it failed to pass the healthcheck: startup check: dialing: dial tcp4: lookup cloudflare.com: i/o timeout. Переконайтеся, що ключ не прострочений, потім перевірте актуальність списку серверів і чи не блокує firewall хоста вихідний UDP-трафік.
FAQ
Чому опубліковані порти мого контейнера перестали працювати за Gluetun?
Тому що network_mode: "service:gluetun" розміщує контейнер у мережевому просторі імен gluetun, а один простір імен має одну IP-адресу та один набір портів, на яких прослуховуються з’єднання. Застосунок продовжує прослуховувати порт, але правило публікації має бути вказане для контейнера, який володіє цим простором імен. Перенесіть список ports: до сервісу gluetun. Якщо залишити його у підключеному сервісі, Docker взагалі не створить контейнер: Error response from daemon: conflicting options: port publishing and the container type network mode.
Як підключитися з контейнера поза VPN-тунелем до контейнера всередині нього?
Використовуйте ім’я сервісу gluetun і порт, на якому прослуховує з’єднання застосунок, наприклад gluetun:8080. Підключений контейнер не має власної Docker network, тому його власне ім’я не визначається. Для трафіку між контейнерами не потрібно публікувати порти. У зворотному напрямку контейнер усередині простору імен може підключитися до зовнішнього контейнера за його іменем сервісу, наприклад postgres:5432, у Gluetun v3.41 і новіших версіях. Клієнту в іншій підмережі, наприклад ноутбуку у вашій LAN, потрібен зворотний маршрут, дозволений firewall і маршрутизацією gluetun; додайте цю підмережу до FIREWALL_OUTBOUND_SUBNETS.
Чи працює Gluetun як kill switch у разі розриву VPN-з’єднання?
Так, якщо firewall увімкнено. Підключений контейнер використовує інтерфейси та маршрути Gluetun, а firewall блокує звичайний інтернет-трафік поза тунелем, дозволяючи підключення до endpoint VPN-сервера, локальний Docker-трафік і налаштовані винятки. Після цього Gluetun перезапускає VPN внутрішньо та записує в журнал WARN [vpn] restarting VPN because it failed to pass the healthcheck, а не завершує роботу, оскільки під час перезапуску самого gluetun кожен підключений контейнер втрачає мережу.
Tailscale і Gluetun в одному stack: який із них передає вихідний трафік?
Звичайний вихідний трафік передає Gluetun, якщо ви явно не спрямували його через Tailscale. За замовчуванням Tailscale маршрутизує лише трафік між пристроями у вашому tailnet і не змінює публічний трафік. У стандартному userspace mode образу контейнера він взагалі не створює інтерфейс, тому не може впливати на маршрутизацію. За використання TS_USERSPACE=false Linux зазвичай отримує окремі маршрути IPv4 peer /32, а не агрегований маршрут 100.64.0.0/10, а також маршрути підмереж інших вузлів, лише якщо додати --accept-routes через TS_EXTRA_ARGS. TS_ROUTES оголошує підмережі цього контейнера у вашому tailnet і не додає локальних маршрутів. Вибір exit node за допомогою sudo tailscale set --exit-node=<exit-node-ip> встановлює маршрути за замовчуванням лише у просторі імен, який використовує kernel networking Tailscale; окремий контейнер не змінює маршрути застосунку, а userspace mode передає лише трафік, спрямований через його proxy. Виберіть один продукт, який відповідатиме за маршрут за замовчуванням, замість одночасного використання обох.