SSD Nodes Learn Hosting plans →
Посібники Matt ConnorВід Matt Connor · Оновлено 2026-10-23

wg-easy у Docker: WireGuard із вебінтерфейсом

Налаштуйте WireGuard через wg-easy і Docker Compose: порти, NET_ADMIN, sysctls, зміни у версії 15 та QR-коди для підключення телефонів.

Що ви створюєте

wg-easy — це WireGuard із вебінтерфейсом, який працює в одному Docker-контейнері. Він керує інтерфейсом WireGuard і додає браузерний інтерфейс для створення клієнтів. Для кожного створеного клієнта генеруються файл конфігурації та QR-код. Тому телефон можна підключити до VPN, навівши камеру на екран.

Сам тунель є звичайним WireGuard. Пакети передає модуль ядра, тому пропускна здатність така сама, як у конфігурації, створеної вручну. Ви отримуєте керування життєвим циклом клієнтів: можете додавати, вимикати та видаляти peer без редагування конфігураційного файла через SSH. Натомість ви втрачаєте прямий контроль над цим файлом. Цьому присвячено ручне налаштування WireGuard на VPS.

Вам потрібен Linux-хост, яким ви можете керувати, наприклад KVM VPS, із публічною IP-адресою або доменним ім’ям, що вказує на нього, процесором x86_64 або arm64, Docker Engine із Compose plugin і доступом root. Віртуалізація контейнерів зі спільним ядром хоста, наприклад OpenVZ або LXC, зазвичай не може завантажити модуль WireGuard. Через це контейнер не зможе підняти інтерфейс.

У версії 15 налаштування перенесли з environment

Більшість доступних інструкцій написано для wg-easy 14. У цій версії в WG_HOST вказували адресу сервера, а в PASSWORD_HASH — bcrypt-хеш пароля адміністратора. Обидва значення задавалися як environment variables. Версія 15 — це переписана версія. В офіційних примітках до міграції прямо зазначено, що v15 не використовує ті самі environment variables, що й v14, а більшість із них перенесли до панелі адміністратора у вебінтерфейсі.

Тому WG_HOST і PASSWORD_HASH більше нічого не роблять. Якщо скопіювати старий compose-файл, контейнер запуститься, проігнорує ці рядки, а потім запропонує створити обліковий запис адміністратора у браузері. Це не помилка. Це новий процес початкового налаштування.

Станом на October 2026 для фіксації слід використовувати major tag 15. Фіксуйте major version, а не використовуйте latest, оскільки оновлення major version змінює формат конфігурації на диску, і коректно повернутися до попередньої версії не вдасться. Під час переходу на 15 JSON-файл v14 замінили базою даних SQLite.

Файл compose

Створіть каталог для стека та запишіть у нього офіційний compose-файл. Це файл від upstream із вилученими закоментованими необов’язковими рядками.

sudo mkdir -p /etc/docker/containers/wg-easy
sudo curl -o /etc/docker/containers/wg-easy/docker-compose.yml \
  https://raw.githubusercontent.com/wg-easy/wg-easy/master/docker-compose.yml

Вміст має такий вигляд:

volumes:
  etc_wireguard:

services:
  wg-easy:
    image: ghcr.io/wg-easy/wg-easy:15
    container_name: wg-easy
    networks:
      wg:
        ipv4_address: 10.42.42.42
        ipv6_address: fdcc:ad94:bacf:61a3::2a
    volumes:
      - etc_wireguard:/etc/wireguard
      - /lib/modules:/lib/modules:ro
    ports:
      - "51820:51820/udp"
      - "51821:51821/tcp"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv6.conf.all.disable_ipv6=0
      - net.ipv6.conf.all.forwarding=1
      - net.ipv6.conf.default.forwarding=1

networks:
  wg:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 10.42.42.0/24
        - subnet: fdcc:ad94:bacf:61a3::/64

etc_wireguard — це іменований том, у якому зберігаються ключ сервера та всі створені вами клієнти. Дані зберігаються в SQLite-базі даних wg-easy.db. Створюйте резервну копію цього тому, інакше повторна збірка видалить усі ваші peer-підключення. Якщо потрібно бачити ці файли у файловій системі хоста, замініть його на bind mount і перед цим прочитайте про різницю між bind mount та іменованими томами, оскільки права доступу працюють по-різному.

Навіщо потрібні NET_ADMIN, SYS_MODULE і параметри sysctl

Контейнер за замовчуванням не може змінювати мережевий стек, і кожен із цих рядків знімає окреме обмеження.

NET_ADMIN дає контейнеру змогу створити інтерфейс wg0, призначити йому адресу та додати маршрути. Без цього контейнер запускається, а потім завершує роботу під час налаштування інтерфейсу, оскільки ip link add wg0 type wireguard повертає Operation not permitted.

SYS_MODULE разом із монтуванням /lib/modules у режимі лише для читання дає контейнеру змогу завантажити kernel module WireGuard, якщо host ще не завантажив його. Модуль міститься в kernel host, а не всередині image, тому каталог host має бути доступним у контейнері. У сучасному kernel модуль зазвичай уже вбудований. Це можна перевірити командою sudo modprobe wireguard && echo ok на host.

net.ipv4.ip_forward=1 вмикає в kernel пересилання пакетів, адресованих не самому host. Без цього client підключається, handshake проходить успішно, але потім усі пакети до інтернету відкидаються, тому ping 1.1.1.1 завершується за тайм-аутом, хоча VPN виглядає підключеним.

net.ipv4.conf.all.src_valid_mark=1 — параметр, який часто викликає запитання. WireGuard позначає власні вихідні пакети, щоб вони не маршрутизувалися назад у tunnel. Строга reverse path filtering бачить пакет, адреса джерела якого не відповідає очікуваному маршруту, і відкидає його. Цей sysctl повідомляє kernel приймати позначені пакети. Саме це не дає full tunnel зламати власну маршрутизацію.

Запустіть його та створіть обліковий запис адміністратора

cd /etc/docker/containers/wg-easy
sudo docker compose up -d
sudo docker compose logs -f

Використовуйте docker compose up і docker compose down, а не start і stop. start лише перезапускає вже наявні контейнери, тому зміни у compose-файлі, зокрема параметри мережі та sysctl, не застосовуються, тоді як up повторно створює все, що змінилося. Якщо потрібно відновлювати стек після перезавантаження, restart: unless-stopped уже забезпечує це, а в розділі поведінка compose-сервісів під час завантаження пояснено, що саме гарантує ця політика, а що — ні.

Вебінтерфейс прослуховує TCP-порт 51821. Під час першого відкриття він показує сторінку налаштування, де потрібно створити обліковий запис адміністратора та вказати адресу хоста, через яку клієнти підключатимуться до сервера. Ця адреса потрапляє в рядок Endpoint конфігурації кожного клієнта, тому нею має бути публічна IP-адреса або DNS-ім’я VPS. Якщо вказати неправильну адресу, QR-код, який ви передасте на телефон, міститиме недоступну адресу, і рукостискання не завершиться.

Є ще один важливий момент щодо цього порту: wg-easy сам не обслуговує TLS і не відхиляє звичайні HTTP-запити. Через http:// вебінтерфейс усе одно відкривається та показує попередження. Змінюється лише cookie сеансу: він містить прапорець Secure, тому браузер, який відкриває вебінтерфейс через звичайний HTTP за публічною адресою, відкидає цей cookie, і вхід не зберігається. INSECURE=true прибирає цей прапорець і більше нічого не змінює. Якщо розмістити перед wg-easy reverse proxy, який завершує TLS, навіть із самопідписаним сертифікатом, змінювати налаштування wg-easy не потрібно.

Не публікуйте порт UI в інтернеті

Файл compose публікує порт 51821 на всіх інтерфейсах. Це сторінка входу до системи, яка може маршрутизувати ваш трафік, тому вона не повинна бути відкритою для всіх. Публікація порту в Docker додає правила до ланцюжка DOCKER, який обробляється перед ufw, тому правило ufw deny не закриває цей порт. Цю особливість варто зрозуміти окремо; докладне пояснення наведено в матеріалі чому опубліковані Docker порти ігнорують ufw.

Просте рішення — прив’язати UI до loopback і підключатися до нього через SSH-тунель:

    ports:
      - "51820:51820/udp"
      - "127.0.0.1:51821:51821/tcp"
    environment:
      - INSECURE=true

Потім на вашому ноутбуці:

ssh -L 51821:127.0.0.1:51821 youruser@your.server.address

Відкрийте http://127.0.0.1:51821 у браузері на ноутбуці. SSH шифрує трафік, а порт не відповідає іншим підключенням. INSECURE=true лише прибирає прапорець Secure із cookie сесії, щоб браузер зберігав ваш вхід для цієї адреси через звичайний HTTP. У цьому випадку це безпечно, оскільки з’єднання через звичайний HTTP не виходить за межі loopback-інтерфейсу.

Відкрийте UDP-порт 51820 і перевірте обидва firewall

WireGuard потребує доступного з інтернету UDP-порту 51820. Docker публікує цей порт, але багато провайдерів розміщують перед VPS окремий мережевий firewall, про який Docker нічого не знає. Відкрийте порт в обох місцях. Якщо ви керуєте firewall хоста за допомогою ufw, базові правила ufw для VPS налаштувати простіше, ніж вручну писати правила nftables.

Перевірте, чи контейнер справді прослуховує порт:

sudo ss -ulnp | grep 51820

Ви маєте побачити UDP-сокет у стані прослуховування. Якщо в цьому рядку нічого немає, контейнер не зміг підняти інтерфейс, а sudo docker compose logs wg-easy покаже причину.

Створіть клієнта та відскануйте його на телефоні

У UI створіть клієнта та задайте йому ім’я, яке ви зможете розпізнати пізніше, наприклад назву пристрою, якому він належить. wg-easy автоматично призначить наступну вільну адресу тунелю та згенерує для вас пару ключів. У кожному рядку клієнта доступні QR-код і файл .conf для завантаження.

Встановіть на телефоні офіційний застосунок WireGuard, виберіть додавання тунелю з QR-коду та наведіть камеру на код на екрані. Тунель з’явиться під заданим вами ім’ям. Увімкніть його, після чого в рядку клієнта в UI почнуть відображатися лічильники переданих даних і час останнього handshake. Після підключення телефона до тунелю він зможе отримувати доступ до сервісів, які ніколи не публікувалися в інтернеті. Завдяки цьому телефон може завантажувати фотографії на self-hosted фотосервер з будь-якого місця, навіть якщо цей сервер не має жодного відкритого для всього світу порту. Та сама схема підходить для медіа: бібліотека Jellyfin, перетворена на відеопрокат із 90-х, зручно переглядати з готельного номера, поки вона залишається такою ж приватною, як у вашій LAN. Сповіщення працюють у зворотному напрямку через той самий тунель: self-hosted сервер ntfy може надіслати повідомлення на цей телефон одразу після збою завдання резервного копіювання, не приймаючи жодного запиту з публічного інтернету.

Клієнт, у якого після ввімкнення немає handshake, взагалі не досягає сервера. Причина, імовірно, у UDP 51820: його може блокувати firewall провайдера або адреса endpoint, вбудована в конфігурацію. Якщо handshake є, але інтернет не працює, перевірте forwarding або DNS.

На desktop завантажте файл .conf та імпортуйте його в клієнт WireGuard, а не вводьте конфігурацію вручну. Приватний ключ у цьому файлі генерується один раз і показується один раз. Захищайте цей файл так само, як приватний ключ SSH.

Коли UI стає недостатньо

wg-easy — правильний інструмент, поки ваші peers — це люди та телефони. UI швидший за редагування конфігураційних файлів, а відкликання доступу для втраченого телефона виконується одним натисканням.

Обмеження з’являться, коли вам знадобиться те, що UI не підтримує. Site-to-site маршрутизація, у якій AllowedIPs peer охоплює цілу віддалену підмережу, а не одну адресу, зазвичай є першою перешкодою. Далі виникають split tunnel з окремими правилами маршрутизації для кожного peer або конфігурація, згенерована вашим інструментом provisioning. На цьому етапі ручне налаштування не складніше, воно просто інше, а у посібнику зі звичайного WireGuard показано, як побудувати такий самий тунель за допомогою wg0.conf. Якщо ви хочете взагалі відмовитися від control plane, у матеріалі WireGuard порівняно з Tailscale розглянуто керований варіант. Чи буде це виправданим компромісом, залежить від того, до чого насправді має доступ coordination server, тому перед передаванням йому доступу до мережі варто прочитати модель довіри Tailscale. Наступним зазвичай виникає питання вартості. У матеріалі що насправді охоплює безкоштовний план Tailscale зазначено, що він надає до шести користувачів без оплати і лише для некомерційного використання. Тому для домашньої мережі він безкоштовний, а невелика бізнес-команда не відповідає умовам незалежно від кількості її учасників. Після цього тарифікація враховує користувачів, а не пристрої. Це інша модель витрат, ніж VPS, за який ви вже платите, тому перед міграцією команди перевірте скільки коштує Tailscale після перевищення ліміту безкоштовного плану. Для повного тунелю, який ви щойно побудували, там є прямий аналог: оголошення VPS як exit node Tailscale забезпечує такий самий вихід через сервер. Відмінність полягає в тому, що маршрут дозволяється в admin console, а не записується в конфігурацію кожного клієнта. Для обмеження підмережею також є аналог, оскільки оголошення всієї приватної мережі з VPS передає цю мережу кожному пристрою в tailnet без редагування AllowedIPs для кожного peer, через яке UI став недостатнім. Якщо вам потрібні dashboard і автоматична mesh-маршрутизація, але ви не хочете використовувати чужий coordination server, запуск власного сервера NetBird на VPS залишає control plane на обладнанні, яким ви володієте. Водночас доведеться самостійно налаштувати DNS і TLS, чого wg-easy від вас не вимагав.

Якщо незнайомою частиною для вас був синтаксис compose, а не WireGuard, у матеріалі основи Docker Compose на VPS пояснено формат файлу та щоденні команди.

FAQ

Чому wg-easy ігнорує мої WG_HOST і PASSWORD_HASH?

Ці змінні належать до wg-easy 14. Версія 15 є переписаною версією, і розробники перенесли майже всю конфігурацію до панелі адміністратора у вебінтерфейсі. Контейнер не читає жодну з цих змінних. Тому він запускається нормально, а під час першого відвідування просить створити обліковий запис адміністратора. Укажіть адресу хоста, яку бачать клієнти, на цій сторінці налаштування.

Чи потрібен SYS_MODULE, якщо ядро вже має WireGuard?

Ні. SYS_MODULE і монтування /lib/modules потрібні, щоб контейнер міг завантажити модуль, якщо його немає на хості. На хості, де sudo modprobe wireguard вже виконується успішно, ця capability не використовується. Її видалення є обґрунтованим кроком hardening, а NET_ADMIN все одно потрібен.

Клієнт підключається, але інтернету немає. У чому проблема?

Handshake без трафіку майже завжди означає проблему з forwarding. Переконайтеся, що net.ipv4.ip_forward=1 і net.ipv4.conf.all.src_valid_mark=1 досі є у compose-файлі, оскільки копія, відредагована вручну, часто втрачає ці параметри. Якщо forwarding увімкнено, перевірте DNS-сервер, який отримав клієнт. Тунель, що спрямовує весь трафік через VPN, але використовує DNS-сервер, до якого він більше не може дістатися, у браузері виглядає як повністю непрацююче з’єднання.

Як створити резервну копію клієнтів?

Усе зберігається в іменованому volume etc_wireguard. У версії 15 це означає базу даних SQLite за шляхом /etc/wireguard/wg-easy.db усередині контейнера. Документація v15 не описує функції резервного копіювання або експорту, тому створюйте резервну копію самого volume: виконайте docker compose down, скопіюйте вміст volume в інше місце поза сервером, а потім знову запустіть stack за допомогою docker compose up -d. Зробіть це перед будь-яким оновленням. Файл wg0.json, про який згадують старі посібники, належить wg-easy 14. Саме його експортує кнопка резервного копіювання у v14. У v15 він використовується лише як файл, який завантажують у майстрі налаштування під час міграції старої інсталяції.

Чи можна запускати wg-easy за reverse proxy?

Так. Розмістіть proxy перед портом вебінтерфейсу, завершуйте TLS на ньому, а INSECURE залиште невстановленою. Контейнер приймає звичайне HTTP-з’єднання від proxy без додаткових налаштувань, а в офіційних прикладах для Caddy і Traefik змінна INSECURE взагалі не задається. Оскільки браузер підключається до proxy через HTTPS, cookie сесії має зберігати прапорець Secure. Саме його видаляє INSECURE=true. Порт UDP 51820 залиште опублікованим безпосередньо, оскільки VPN-трафік використовує UDP і не проходить через HTTP proxy.

Чи була ця стаття корисною?