English | 简体中文 | 繁體中文 | Русский
Docker-образ для запуска сервера WireGuard VPN. Основан на Alpine Linux с WireGuard. Разработан как простой, современный и легко поддерживаемый.
Возможности:
- Автоматическая генерация ключей сервера и конфигурации клиента при первом запуске
- Управление клиентами через вспомогательный скрипт (
wg_manage) - QR-код отображается при первом запуске для быстрой настройки мобильных устройств
- Поддержка ядрового WireGuard (5.6+) с автоматическим переключением на
wireguard-go(пользовательское пространство) - Поддержка двойного стека IPv4 и IPv6 для VPN-клиентов
- Автоматически собирается и публикуется через GitHub Actions
- Постоянное хранение данных через Docker volume
- Поддержка нескольких архитектур:
linux/amd64,linux/arm64,linux/arm/v7
Также доступно:
- Без Docker: Скрипт установки WireGuard
- VPN: OpenVPN, IPsec VPN, Headscale
- AI: Стек ИИ на своём сервере для локальных LLM, чата, RAG, голосовых функций и инструментов ИИ
- Книги: Comprehensive VPN server guide · The Self-Hosted AI Builder’s Guide
Шаг 1. Запустите сервер WireGuard:
docker run \
--name wireguard \
--restart=always \
-v wireguard-data:/etc/wireguard \
-p 51820:51820/udp \
-d --cap-add=NET_ADMIN \
--cap-add=SYS_MODULE \
--device=/dev/net/tun \
--sysctl net.ipv4.ip_forward=1 \
--sysctl net.ipv6.conf.all.forwarding=1 \
hwdsl2/wireguard-serverПри первом запуске сервер автоматически генерирует ключи сервера, файл wg0.conf и конфигурацию клиента с именем client.conf. В логи контейнера также выводится QR-код для быстрой настройки мобильных устройств.
Шаг 2. Просмотрите логи контейнера, чтобы получить QR-код клиента:
docker logs wireguardОтсканируйте QR-код приложением WireGuard на телефоне для мгновенного подключения.
Шаг 3. По желанию, скопируйте конфигурацию клиента на локальную машину:
docker cp wireguard:/etc/wireguard/clients/client.conf .Импортируйте client.conf в любой клиент WireGuard для подключения.
В качестве альтернативы вы можете настроить WireGuard VPN без Docker. Чтобы узнать больше о том, как использовать этот образ, прочитайте разделы ниже.
- 📬 Получайте новости проектов и бесплатные руководства по развёртыванию (1–2 письма в месяц; руководства в формате PDF на английском языке)
- 💬 Присоединяйтесь к сообществу r/selfhostedstack для обсуждений и демонстрации проектов
- ⭐ Поставьте звезду репозиторию, если он оказался вам полезен — это поможет другим пользователям его найти.
- Linux-сервер с публичным IP-адресом или DNS-именем
- Установленный Docker
- Открытый в файрволе UDP-порт WireGuard (по умолчанию UDP 51820, или настроенный порт)
- Ядро хоста 5.6+ с поддержкой WireGuard (рекомендуется), или используйте встроенный резервный вариант
wireguard-go(работает на любом ядре)
Получите образ из реестра Docker Hub:
docker pull hwdsl2/wireguard-serverЛибо загрузите из Quay.io:
docker pull quay.io/hwdsl2/wireguard-server
docker image tag quay.io/hwdsl2/wireguard-server hwdsl2/wireguard-serverПоддерживаемые платформы: linux/amd64, linux/arm64 и linux/arm/v7.
Все переменные необязательны. Если не заданы, автоматически используются безопасные значения по умолчанию.
Этот Docker-образ использует следующие переменные, которые можно задать в файле env (см. пример):
| Переменная | Описание | Значение по умолчанию |
|---|---|---|
VPN_DNS_NAME |
Полное доменное имя (FQDN) сервера | Автоопределение публичного IP |
VPN_PUBLIC_IP |
Публичный IPv4-адрес сервера | Автоопределение |
VPN_PUBLIC_IP6 |
Публичный IPv6-адрес сервера | Автоопределение |
VPN_PORT |
UDP-порт WireGuard (1–65535) | 51820 |
VPN_CLIENT_NAME |
Имя первого сгенерированного конфига клиента | client |
VPN_DNS_SRV1 |
Основной DNS-сервер, передаваемый клиентам | 8.8.8.8 |
VPN_DNS_SRV2 |
Резервный DNS-сервер, передаваемый клиентам | 8.8.4.4 |
VPN_DISABLE_USAGE_COUNTS |
Установите 1, чтобы отключить анонимные агрегированные счётчики использования. |
(не задан) |
Примечание: В файле env можно заключать значения в одинарные кавычки, например VAR='значение'. Не добавляйте пробелы вокруг =. Если вы изменили VPN_PORT, соответственно обновите флаг -p в команде docker run.
Пример использования файла env:
docker run \
--name wireguard \
--restart=always \
-v wireguard-data:/etc/wireguard \
-v ./vpn.env:/vpn.env:ro \
-p 51820:51820/udp \
-d --cap-add=NET_ADMIN \
--cap-add=SYS_MODULE \
--device=/dev/net/tun \
--sysctl net.ipv4.ip_forward=1 \
--sysctl net.ipv6.conf.all.forwarding=1 \
hwdsl2/wireguard-serverФайл env монтируется в контейнер через bind mount, поэтому изменения применяются при каждом перезапуске контейнера без его пересоздания.
Используйте docker exec для управления клиентами с помощью вспомогательного скрипта wg_manage.
Добавить нового клиента:
docker exec wireguard wg_manage --addclient alice
docker cp wireguard:/etc/wireguard/clients/alice.conf .Показать QR-код клиента (например, после перезапуска):
docker exec wireguard wg_manage --showclientqr aliceЭкспортировать конфигурацию клиента (выводится в stdout):
docker exec wireguard wg_manage --showclientcfg alice > alice.confСписок клиентов:
docker exec wireguard wg_manage --listclientsУдалить клиента (будет запрошено подтверждение):
docker exec -it wireguard wg_manage --removeclient alice
# Или удалить без запроса подтверждения:
docker exec wireguard wg_manage --removeclient alice -yЭтот образ поддерживает два бэкенда WireGuard, которые выбираются автоматически при запуске:
-
Модуль ядра (предпочтительно) — доступен на ядре Linux 5.6+ (Ubuntu 20.04+, Debian 11+ и большинстве современных дистрибутивов). Обеспечивает наилучшую производительность.
-
wireguard-goв пользовательском пространстве (автоматический резерв) — используется, когда модуль ядра недоступен. Работает на любом ядре хоста. Производительность несколько ниже, но полностью функционален.
При активном wireguard-go в логи контейнера выводится соответствующее сообщение. Дополнительная настройка не требуется — переключение прозрачно.
Чтобы использовать модуль ядра, убедитесь, что он доступен на хосте:
# Проверить, загружен ли модуль на хосте
lsmod | grep wireguard
# Загрузить при необходимости
sudo modprobe wireguardФлаг --cap-add=SYS_MODULE в команде docker run позволяет контейнеру загружать модуль ядра. Если модуль уже загружен на хосте, SYS_MODULE строго не требуется.
Все данные сервера и клиентов хранятся в Docker volume (/etc/wireguard внутри контейнера):
/etc/wireguard/
├── wg0.conf # Конфигурация сервера WireGuard (интерфейс + все клиенты)
└── clients/
├── client.conf # Конфигурация первого клиента
└── alice.conf # Дополнительные клиенты
Сделайте резервную копию Docker volume для сохранения ключей сервера и всех конфигураций клиентов.
Если Docker-хост имеет публичный (глобальный одноадресный) IPv6-адрес и выполнены приведённые ниже требования, поддержка IPv6 автоматически включается при запуске контейнера. Никакой дополнительной настройки не требуется.
Требования:
- Docker-хост должен иметь маршрутизируемый глобальный одноадресный IPv6-адрес (начинающийся с
2или3). Локальные адреса канала (fe80::/10) не подходят. - Для Docker-контейнера должна быть включена поддержка IPv6. См. Enable IPv6 support in Docker.
Чтобы включить IPv6 для Docker-контейнера, сначала включите IPv6 в демоне Docker, добавив следующее в файл /etc/docker/daemon.json на Docker-хосте, затем перезапустите Docker:
{
"ipv6": true,
"fixed-cidr-v6": "fddd:1::/64"
}После этого пересоздайте Docker-контейнер. Чтобы проверить работу IPv6, подключитесь к VPN и проверьте ваш IPv6-адрес, например, с помощью test-ipv6.com.
cp vpn.env.example vpn.env
# При необходимости отредактируйте vpn.env, затем:
docker compose up -d
docker logs wireguardПример docker-compose.yml (уже включён):
services:
wireguard:
image: hwdsl2/wireguard-server
container_name: wireguard
restart: always
ports:
- "51820:51820/udp"
volumes:
- wireguard-data:/etc/wireguard
- ./vpn.env:/vpn.env:ro
cap_add:
- NET_ADMIN
- SYS_MODULE
devices:
- /dev/net/tun:/dev/net/tun
sysctls:
- net.ipv4.ip_forward=1
- net.ipv6.conf.all.forwarding=1
volumes:
wireguard-data:
name: wireguard-dataДля обновления Docker-образа и контейнера сначала загрузите последнюю версию:
docker pull hwdsl2/wireguard-serverЕсли Docker-образ уже актуален, вы увидите:
Status: Image is up to date for hwdsl2/wireguard-server:latest
В противном случае будет загружена последняя версия. Удалите и пересоздайте контейнер, следуя инструкциям из раздела Быстрый старт. Ваши данные сохранены в volume wireguard-data.
Этот образ использует публичные счётчики скачиваний GitHub Release assets для анонимной агрегированной статистики использования. Эти числа приблизительны и не являются количеством уникальных пользователей или активных установок. Образ не отправляет telemetry payload и не использует частный сборщик. Он выполняет только best-effort запрос после запуска сервера с подключённым томом /etc/wireguard, а также при первом запуске другой сборки образа для этой постоянной установки. Чтобы отключить это, задайте VPN_DISABLE_USAGE_COUNTS=1.
- Базовый образ:
alpine:3.23 - WireGuard: последняя версия
wireguard-toolsиз пакетов Alpine - Резервный вариант в пользовательском пространстве:
wireguard-goиз пакетов Alpine - Подсеть VPN:
10.7.0.0/24(сервер:10.7.0.1, клиенты:10.7.0.2+) - Подсеть VPN IPv6:
fddd:2c4:2c4:2c4::/64(при наличии IPv6 на сервере) - Предварительно общие ключи: генерируются для каждого клиента для дополнительной прямой секретности
- Keepalive по умолчанию: 25 секунд (обеспечивает NAT traversal для мобильных клиентов)
- Шифр: ChaCha20-Poly1305 (стандарт WireGuard, не настраивается)
📚 Подробнее о защите вашей конфиденциальности в интернете читайте в книге Privacy Tools in the Age of AI.
Примечание: Программные компоненты внутри предсобранного образа (такие как WireGuard tools и wireguard-go) распространяются под соответствующими лицензиями, выбранными их правообладателями. При использовании любого предсобранного образа пользователь несёт ответственность за соблюдение всех соответствующих лицензий на программное обеспечение, содержащееся в образе.
Copyright (C) 2026 Lin Song
Эта работа распространяется под лицензией MIT.
Этот проект частично основан на работе Nyr и участников проекта, распространяемой под лицензией MIT.