wg-easy 15 ile web arayüzlü WireGuard VPN nasıl çalıştırılır

wg-easy, bir WireGuard VPN sunucusunu ve bir web arayüzünü tek bir Docker konteynerinde bir araya getirir. Yapılandırma dosyalarını düzenlemek yerine VPN istemcilerini tarayıcıda oluşturur, devre dışı bırakır ve silersiniz; onları QR kod veya indirilebilir dosya olarak dağıtırsınız. 15. sürüm güncel ana sürümdür: eski ortam değişkeni tabanlı kurulumun yerini ilk çalıştırmada açılan bir kurulum sihirbazı ve bir Admin Panel aldı, iki faktörlü doğrulama eklendi ve web arayüzünün HTTPS üzerinden sunulması beklenir hale geldi.

Bu rehber projenin resmi Docker Compose dosyasını kullanır, web arayüzünü 127.0.0.1 üzerinde tutar ve TLS sertifikasıyla Caddy üzerinden yayınlar; ardından kurulum sihirbazını, 2FA'yı, istemci oluşturmayı, yedeklemeyi, güncellemeyi ve sık görülen hataları anlatır. WireGuard'ı web arayüzü olmadan elle yönetmeyi tercih ediyorsanız bunun yerine WireGuard VPN sunucusu nasıl kurulur rehberini izleyin; ikisini aynı portta çalıştırmayın.

Adım 1 — Resmi Compose dosyasını indirin

Temel kurulum rehberi docker-compose.yml dosyasını depodan indirir; herhangi bir klasör kullanılabilir, bu rehber /opt/wg-easy kullanır:

sudo mkdir -p /opt/wg-easy
sudo chown $USER:$USER /opt/wg-easy
cd /opt/wg-easy
curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/wg-easy/wg-easy/master/docker-compose.yml
cat docker-compose.yml

Başlatmadan önce dosyayı okuyun. Dosya ghcr.io/wg-easy/wg-easy:15 imajını çalıştırır, her şeyi etc_wireguard adlı volume'da saklar, /lib/modules klasörünü salt okunur bağlar, WireGuard'ın ihtiyaç duyduğu NET_ADMIN ve SYS_MODULE yetkilerini ekler, IP yönlendirmeyi sysctls ile açar ve konteyner için sabit IPv4 ve IPv6 adresli bir Docker ağı oluşturur.

Adım 2 — Web arayüzünü localhost'ta tutun

Dosya varsayılan olarak web arayüzünü sunucunun tüm adreslerinde 51821 numaralı portta yayınlar. Docker'ın yayınladığı portlar ufw'yi atladığı için yalnızca bu satırı loopback adresine bağlanacak şekilde değiştirin. Dosyayı nano docker-compose.yml ile açın; sonuç şöyle görünür (özgün dosyadaki yorumlar korunmuştur):

volumes:
  etc_wireguard:

services:
  wg-easy:
    #environment:
    #  Optional:
    #  - PORT=51821
    #  - HOST=0.0.0.0
    #  - INSECURE=false

    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"
      - "127.0.0.1:51821:51821/tcp"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
      # - NET_RAW # Podman kullanıyorsanız yorumu kaldırın
    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

51820/udp portu herkese açık kalır, çünkü VPN istemcileri oraya bağlanır. INSECURE değerini varsayılan false olarak bırakın: arayüz girişleri yalnızca HTTPS üzerinden kabul eder; HTTPS'yi bir sonraki adımda Caddy sağlar.

Adım 3 — Güvenlik duvarını açın ve Caddy sitesini ekleyin

SSH'ye, web trafiğine ve WireGuard portuna izin verin. Docker 51820/udp portunu ufw'den bağımsız olarak yayınlar; ancak kural amacı belgeler ve kurulumu ileride değiştirirseniz de çalışmaya devam eder:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 51820/udp
sudo ufw enable

/etc/caddy/Caddyfile dosyasına loopback portuna yönlendiren bir site bloğu ekleyin. Caddy alan adı için sertifikayı kendiliğinden alır:

vpn.example.com {
    reverse_proxy 127.0.0.1:51821
}

sudo systemctl reload caddy

Projenin kendi Caddy örneği Caddy'yi ortak bir Docker ağında konteyner olarak çalıştırır; buradaki gibi sunucuda çalışan bir Caddy ve loopback portu aynı sonucu verir. Nginx ve Certbot veya Traefik de kullanılabilir.

Adım 4 — wg-easy'yi başlatın

docker compose up -d
docker compose ps
docker compose logs --tail 30
curl -I https://vpn.example.com

docker compose ps, wg-easy konteynerini çalışıyor olarak gösterir; loglarda WireGuard veya iptables hatası görünmez ve curl geçerli bir sertifika üzerinden arayüzden yanıt alır.

Adım 5 — Kurulum sihirbazını tamamlayın

https://vpn.example.com adresini açın. Sihirbaz şunları sorar:

1. User setup: bir yönetici kullanıcı adı ve parola yöneticinizden alınmış uzun bir parola.
2. Existing setup: yeni kurulum için No seçin. (Yes seçeneğini yalnızca wg-easy 14'ten bir wg0.json yedeğini içe aktarmak için kullanın.)
3. Host setup: istemcilerin bağlanacağı host ve port. vpn.example.com (veya sunucunun genel IP adresi) ile 51820 girin. Bu değer her istemci yapılandırmasına yazılır; bu yüzden sunucunun genel adresi olmalıdır. IPv6 adresleri [2001:db8::1] gibi köşeli parantez içinde yazılır.

Sihirbazdan sonra istemci listesine giriş yaparsınız. Otomatik kurulumlar için belgeler, ilk başlatmada sihirbazı atlayan INIT_* ortam değişkenlerini de (INIT_USERNAME, INIT_PASSWORD, INIT_HOST ve INIT_PORT gibi) anlatır; parolanın Compose dosyasında kalmaması için bunları sonradan kaldırın.

Adım 6 — İki faktörlü doğrulamayı açın

Sağ üst köşedeki menüyü açın, Account sayfasına gidin ve Enable Two Factor Authentication seçeneğini seçin. QR kodunu bir doğrulayıcı uygulamayla tarayın ve geçerli kodla onaylayın. Bundan sonra giriş ekranı kodu da ister. Doğrulayıcınızı yedekli tutun; 2FA'yı Account sayfasından kapatmak için giriş yapmış olmanız gerekir.

Adım 7 — İstemcileri oluşturun ve sunucu ayarlarını düzenleyin

New Client düğmesine tıklayın, her cihaz için bir ad verin (örneğin laptop veya phone), isteğe bağlı olarak bir bitiş tarihi belirleyin ve oluşturun. Her istemci için daha sonra şunları yapabilirsiniz:

• telefondaki WireGuard uygulamasıyla taramak için bir QR kod göstermek,
• masaüstü uygulamaları için .conf dosyasını indirmek,
• yapılandırmayı bir kullanıcıya göndermek için tek kullanımlık bağlantı oluşturmak,
• sonradan devre dışı bırakmak, düzenlemek veya silmek.

Yapılandırmayı WireGuard uygulamasına aktarın ve bağlanın. İstemci listesi bundan sonra o istemcinin son el sıkışmasını ve trafiğini gösterir.

Admin Panel sunucu genelindeki ayarları tutar: yeni istemci yapılandırmalarına yazılan varsayılan DNS sunucuları ve izin verilen IP'ler (0.0.0.0/0, ::/0 tüm trafiği VPN'den geçirir; özel bir aralık bölünmüş tünel sağlar), istemci adres aralığı gibi arayüz seçenekleri ve Interface altındaki deneysel Per-Client Firewall; bu özellik her istemcinin nelere erişebileceğini sınırlar ve sunucuda iptables ile uygulanır. VPN istemcileriniz için AdGuard Home çalıştırıyorsanız wg-easy belgelerindeki AdGuard Home örneğini izleyin.

Yedekleme ve geri yükleme

Tüm durum Docker volume'undadır: kullanıcıları, istemcileri ve anahtarları içeren wg-easy veritabanı ile oluşturulan WireGuard yapılandırması. Compose volume adının başına proje klasörünün adını ekler; bu yüzden önce adı kontrol edin:

docker volume ls
sudo mkdir -p /opt/backups
cd /opt/wg-easy
docker compose stop
docker run --rm -v wg-easy_etc_wireguard:/data -v /opt/backups:/backup ubuntu tar czf /backup/wg-easy-$(date +%F).tar.gz -C /data .
docker compose start
sudo chmod 600 /opt/backups/wg-easy-*.tar.gz

Konteyner durduğu birkaç saniye boyunca istemcilerin bağlantısı kesilir. Arşiv tüm özel anahtarları içerir; gizli tutun ve docker-compose.yml dosyasıyla birlikte sunucunun dışına kopyalayın.

Geri yüklemek için, örneğin 1–3. adımlardan sonra yeni bir sunucuda, Compose'un konteyneri ve volume'u başlatmadan oluşturmasını sağlayın, volume içeriğini arşivle değiştirin ve wg-easy'yi başlatın. rm adımı önce volume'u boşaltır; bu yüzden içindeki mevcut yapılandırma değiştirilir:

cd /opt/wg-easy
docker compose down
docker compose create
docker run --rm -v wg-easy_etc_wireguard:/data -v /opt/backups:/backup ubuntu sh -c "rm -rf /data/* && tar xzf /backup/wg-easy-2026-10-09.tar.gz -C /data"
docker compose up -d

Anahtarlar değişmediği için mevcut istemciler, kurulumdaki host adı hâlâ sunucuyu gösterdiği sürece yeni yapılandırmaya gerek kalmadan yeniden bağlanır.

wg-easy güncelleme

Önce sürüm notlarını okuyun ve yedek alın. 15 etiketiyle güncellemeler 15. sürümün içinde kalır. Projenin güncelleme rehberi imajı çekmeyi ve konteyneri yeniden oluşturmayı tek komutta yapar:

cd /opt/wg-easy
docker compose up -d --pull always
docker compose logs --tail 30
docker image prune

Gelecekteki bir ana sürümden önce onun taşıma rehberini okuyun, imaj etiketini kendiniz değiştirin ve yeni sürüm çalışana kadar yedeği saklayın. Belgeler Watchtower ile otomatik güncellemeyi de gösterir; güvendiğiniz bir VPN'de elle güncelleme, zamanı sizin seçmenizi sağlar.

Sorun giderme

Error: WireGuard exited with the error: Cannot find device wg0

WireGuard çekirdek modülü yüklü değil. Modülü şimdi ve her açılışta yükleyin, ardından konteyneri yeniden başlatın:

sudo modprobe wireguard
echo wireguard | sudo tee /etc/modules-load.d/wireguard.conf
docker compose restart

Can't initialize iptables table nat: Table does not exist

Sunucu çekirdeği iptables nat tablosunun modülünü yüklememiş. wg-easy SSS sayfası çözümü verir: iptable_nat modülünü (IPv6 mesajı için ip6table_nat modülünü) sudo modprobe ile yükleyin ve modül adlarını yukarıdaki gibi /etc/modules-load.d/ içindeki dosyalara ekleyin.

Giriş başarısız oluyor veya sayfa giriş yapmadan yenileniyor

Arayüzü düz HTTP üzerinden açıyorsunuz; örneğin Caddy'yi kullanmak yerine 51821 numaralı portu doğrudan yayınladıktan sonra. 15. sürüm girişleri yalnızca güvenli bir bağlantı üzerinden kabul eder. https://vpn.example.com adresini kullanın; INSECURE=true değerini yalnızca yerel ağınızın dışından hiçbir zaman erişilemeyen bir arayüz için ayarlayın.

Yönetici parolasını unuttunuz

Parolayı yerleşik komut satırı aracıyla sıfırlayın. Araç yeni parolayı sorar:

docker compose exec -it wg-easy cli db:admin:reset

İstemciler bağlanıyor ama hiç el sıkışması olmuyor

UDP 51820 sunucuya ulaşmıyor veya istemciler yanlış adresi kullanıyor. Sağlayıcınızın güvenlik duvarını kontrol edin, vpn.example.com kaydının sunucuya çözümlenen yalnızca DNS bir kayıt olduğundan emin olun (bir CDN proxy'si WireGuard trafiğini taşıyamaz) ve Admin Panel'deki host ile portu kontrol edin; bunları değiştirdikten sonra istemci yapılandırmalarını yeniden indirin veya tarayın.

Sonraki adımlar

• wg-easy'nin neyi otomatikleştirdiğini WireGuard VPN sunucusu nasıl kurulur rehberini okuyarak anlayın.
• Tüm VPN istemcileri için reklamları ve izleyicileri AdGuard Home ile engelleyin.
• Compose dosyalarını Docker Compose temelleri rehberinde daha ayrıntılı öğrenin.
• Kendi VPN'iniz için sunucuları VPN sunucusu sayfasında karşılaştırın.
• API, metrikler ve gelişmiş yapılandırma için wg-easy belgelerini okuyun.