Cara Pasang wg-easy WireGuard UI dengan Docker

Apa yang anda bina

wg-easy ialah WireGuard dengan antara muka web yang berjalan sebagai satu bekas Docker. Ia menguruskan antara muka WireGuard untuk anda dan menambah UI pelayar bagi mencipta klien. Setiap klien yang anda cipta mendapat fail konfigurasi dan kod QR, jadi telefon boleh menyertai VPN dengan menghalakan kameranya ke skrin.

Terowong itu sendiri adalah WireGuard biasa. Modul kernel memindahkan paket, jadi daya pemprosesan adalah sama seperti persediaan manual. Apa yang anda peroleh ialah kitaran hayat klien: menambah, melumpuhkan dan memadamkan peer tanpa perlu menyunting fail konfigurasi melalui SSH. Apa yang anda korbankan ialah kawalan terus ke atas konfigurasi tersebut, yang merupakan topik bagi persediaan manual WireGuard pada VPS.

Anda memerlukan VPS KVM dengan alamat IPv4 awam, Docker Engine dengan pemalam Compose, dan akses root. Virtualisasi bekas yang berkongsi kernel hos, seperti OpenVZ atau LXC, biasanya tidak dapat memuatkan modul WireGuard, dan bekas tersebut akan gagal untuk mengaktifkan antara muka.

Versi 15 memindahkan tetapan keluar daripada persekitaran

Kebanyakan panduan yang anda temui ditulis untuk wg-easy 14, di mana anda menetapkan WG_HOST kepada alamat pelayan anda dan PASSWORD_HASH kepada hash bcrypt bagi kata laluan admin, kedua-duanya sebagai pemboleh ubah persekitaran (environment variables). Versi 15 ialah penulisan semula. Nota migrasi rasmi menyatakan dengan jelas bahawa v15 tidak menggunakan pemboleh ubah persekitaran yang sama seperti v14, dan kebanyakan daripadanya telah dipindahkan ke panel admin dalam UI web.

Oleh itu, WG_HOST dan PASSWORD_HASH tidak lagi berfungsi. Jika anda menyalin fail compose lama, kontena akan bermula, mengabaikan baris tersebut, dan kemudian meminta anda membuat akaun admin dalam pelayar. Itu bukan pepijat. Ia adalah aliran persediaan yang baharu.

Sehingga Julai 2026, tag utama untuk disematkan ialah 15. Sematkan versi utama daripada menggunakan latest, kerana naik taraf versi utama akan mengubah format konfigurasi pada cakera dan tidak akan dapat diputar balik dengan lancar.

Fail compose

Cipta direktori untuk stack tersebut dan tulis fail compose rasmi ke dalamnya. Ini merupakan fail hulu (upstream) yang tidak diubah.

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

Kandungan fail tersebut adalah seperti berikut:

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 ialah volum bernama yang menyimpan kunci pelayan dan setiap klien yang anda cipta. Buat sandaran untuk volum tersebut, atau binaan semula akan melupuskan semua peer anda. Jika anda lebih suka melihat fail-fail tersebut pada sistem fail hos, tukarkannya kepada bind mount, dan baca perbezaan antara bind mount dan volum bernama sebelum anda melakukannya, kerana keizinan (permissions) berfungsi secara berbeza.

Mengapa ia memerlukan NET_ADMIN, SYS_MODULE dan sysctl

Bekas (container) tidak dibenarkan menyentuh tindanan rangkaian (network stack) secara lalai, dan setiap baris ini membuang satu sekatan khusus.

NET_ADMIN membolehkan bekas mencipta antara muka wg0, menetapkan alamat kepadanya dan menulis laluan (routes). Tanpanya, bekas akan bermula dan kemudian mati semasa cuba menaikkan antara muka tersebut, kerana ip link add wg0 type wireguard mengembalikan Operation not permitted.

SYS_MODULE berserta lekap (mount) baca-sahaja /lib/modules membolehkan bekas memuatkan modul kernel WireGuard jika hos belum memuatkannya. Modul tersebut berada pada kernel hos, bukan di dalam imej, itulah sebabnya direktori hos perlu dapat dilihat. Pada kernel moden, modul ini biasanya sudah terbina di dalam, dan anda boleh mengesahkannya dengan sudo modprobe wireguard && echo ok pada hos.

net.ipv4.ip_forward=1 menyebabkan kernel memajukan paket yang tidak ditujukan kepada kotak itu sendiri. Tanpanya, klien akan bersambung, jabat tangan (handshake) berjaya, dan kemudian setiap paket ke internet akan digugurkan, menyebabkan ping 1.1.1.1 tamat tempoh (timeout) sementara VPN kelihatan bersambung.

net.ipv4.conf.all.src_valid_mark=1 adalah perkara yang mengejutkan orang ramai. WireGuard menandakan paket keluar miliknya sendiri supaya ia tidak dihalakan semula ke dalam terowong. Penapisan laluan balik (reverse path filtering) yang ketat melihat paket yang alamat sumbernya tidak sepadan dengan laluan yang dijangkakan lalu menggugurkannya. Sysctl ini memberitahu kernel untuk menerima paket yang ditandakan, yang merupakan perkara yang menghalang terowong penuh daripada merosakkan dirinya sendiri.

Mulakan ia dan cipta akaun pentadbir

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

Gunakan docker compose up dan docker compose down, bukan start dan stop. Pihak hulu memberi amaran bahawa start pada kontena yang dicipta di bawah tetapan berbeza akan menyebabkan rangkaian berada dalam keadaan tidak konsisten. Jika anda mahukan tindanan (stack) kembali selepas but semula, restart: unless-stopped sudah pun melindunginya, dan tingkah laku but bagi servis compose menjelaskan perkara yang dijanjikan dan tidak dijanjikan oleh polisi tersebut.

UI web mendengar pada TCP 51821. Pada lawatan pertama, ia memaparkan halaman persediaan di mana anda mencipta akaun pentadbir dan mengesahkan alamat hos yang akan digunakan oleh klien untuk mencapai pelayan. Alamat hos tersebut akan berakhir pada baris Endpoint bagi setiap konfigurasi klien, jadi ia mestilah IP awam atau nama DNS bagi VPS tersebut. Jika ia salah, kod QR yang anda berikan kepada telefon akan menghala ke tempat yang tidak boleh dicapai dan jabat tangan (handshake) tidak akan lengkap.

Satu lagi perkara tentang port tersebut: wg-easy 15 menolak HTTP biasa melainkan anda menetapkan INSECURE=true. Mencapainya melalui HTTPS dengan sijil yang tidak dipercayai, atau menamatkan TLS pada reverse proxy di hadapannya, kedua-duanya adalah boleh diterima. Mencapainya melalui http:// dengan tetapan lalai adalah tidak dibenarkan.

Jangan dedahkan port UI ke internet

Fail compose mendedahkan port 51821 pada setiap antara muka. Ini merupakan halaman log masuk untuk kotak yang boleh menghalakan trafik anda, dan ia tidak sepatutnya dibuka kepada umum. Mendedahkan port dalam Docker akan menulis peraturan ke dalam chain DOCKER, yang dinilai sebelum ufw, jadi peraturan deny ufw tidak akan menutupnya. Perangkap ini perlu difahami secara khusus, dan mengapa port yang didedahkan Docker mengabaikan ufw membincangkannya dengan lengkap.

Penyelesaian mudahnya adalah dengan mengikat UI ke loopback dan mencapainya melalui SSH tunnel:

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

Kemudian dari komputer riba anda:

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

Buka http://127.0.0.1:51821 dalam pelayar pada komputer riba anda. Trafik disulitkan oleh SSH, port tersebut tidak menjawab sesiapa pun, dan INSECURE=true adalah selamat di sini kerana lompatan HTTP biasa tidak pernah meninggalkan antara muka loopback.

Buka UDP 51820, dan semak kedua-dua firewall

WireGuard sendiri memerlukan port UDP 51820 boleh dicapai dari internet. Docker menerbitkan port tersebut, namun banyak penyedia meletakkan firewall rangkaian berasingan di hadapan VPS yang tidak diketahui oleh Docker. Buka port tersebut pada kedua-dua tempat. Jika anda mengurus firewall hos dengan ufw, peraturan asas ufw untuk VPS adalah langkah yang lebih pantas berbanding menulis nftables secara manual.

Semak sama ada container tersebut benar-benar sedang mendengar:

sudo ss -ulnp | grep 51820

Anda sepatutnya melihat soket UDP yang sedang mendengar. Jika tiada apa-apa pada baris tersebut, bermakna container tidak berjaya menaikkan antara muka (interface), dan sudo docker compose logs wg-easy akan menyatakan puncanya.

Cipta klien dan imbas pada telefon

Dalam UI, cipta klien dan berikan nama yang mudah dikenali, seperti nama peranti yang menggunakannya. wg-easy akan memperuntukkan alamat tunnel bebas yang seterusnya dan menjana pasangan kunci untuk anda. Setiap baris klien menawarkan kod QR dan fail .conf yang boleh dimuat turun.

Pasang aplikasi rasmi WireGuard pada telefon, pilih untuk menambah tunnel daripada kod QR, dan halakan kamera ke kod pada skrin anda. Tunnel tersebut akan muncul dengan nama yang anda taip. Hidupkannya, dan baris klien dalam UI akan mula memaparkan pembilang pemindahan serta masa jabat tangan (handshake) terkini. Sebaik sahaja telefon berada dalam tunnel, ia boleh mencapai servis yang tidak pernah anda terbitkan ke internet. Inilah cara telefon terus memuat naik ke pelayan foto yang dihoskan sendiri dari mana-mana sahaja tanpa perlu membuka satu pun port pelayan tersebut kepada dunia luar. Trik yang sama meliputi media, dan pustaka Jellyfin yang dibina semula seperti kedai video 90-an adalah sesuatu yang menyeronokkan untuk dilayari dari bilik hotel sementara ia kekal peribadi seperti berada di LAN anda. Makluman berfungsi sebaliknya pada tunnel yang sama, kerana pelayan ntfy yang dihoskan sendiri boleh menolak mesej ke telefon tersebut sebaik sahaja tugasan sandaran gagal tanpa perlu menjawab sebarang permintaan daripada internet awam.

Klien yang tidak menunjukkan jabat tangan selepas anda mendayakannya bermakna ia tidak mencapai pelayan langsung. Ini menunjukkan masalah pada UDP 51820, sama ada pada firewall penyedia atau alamat endpoint yang ditetapkan dalam konfigurasi. Klien yang menunjukkan jabat tangan tetapi tiada akses internet pula menunjukkan masalah pada penghalaan (forwarding) atau DNS.

Pada desktop, muat turun fail .conf dan import ke dalam klien WireGuard daripada menaipnya semula. Kunci peribadi dalam fail tersebut dijana sekali dan dipaparkan sekali sahaja. Kendalikan fail tersebut seperti anda mengendalikan kunci peribadi SSH.

Bilakah anda perlu beralih daripada UI

wg-easy ialah alat yang tepat selagi rakan setara anda terdiri daripada manusia dan telefon. UI adalah lebih pantas berbanding menyunting fail konfigurasi, dan membatalkan akses telefon yang hilang hanya memerlukan satu klik.

Anda akan mencapai hadnya apabila anda mahukan sesuatu yang tidak dimodelkan oleh UI. Penghalaan site-to-site, di mana AllowedIPs rakan setara meliputi keseluruhan subnet jauh dan bukannya satu alamat tunggal, biasanya merupakan halangan pertama yang ditemui. Split tunnel dengan peraturan penghalaan bagi setiap rakan setara, atau konfigurasi yang dijana oleh alat penyediaan anda, adalah langkah seterusnya. Pada tahap itu, penyediaan secara manual tidaklah lebih sukar, ia hanya berbeza, dan panduan WireGuard biasa menunjukkan tunnel yang sama dibina daripada wg0.conf. Jika anda lebih suka untuk tidak menjalankan control plane sama sekali, WireGuard berbanding Tailscale merangkumi pilihan terurus. Sama ada ia merupakan pertukaran yang adil bergantung pada perkara yang boleh dicapai oleh pelayan koordinasi, dan model kepercayaan Tailscale wajar dibaca sebelum anda menyerahkan rangkaian anda kepadanya. Kos biasanya menjadi persoalan seterusnya, dan apa yang diliputi oleh pelan percuma Tailscale adalah mencukupi untuk isi rumah atau pasukan kecil tidak membayar apa-apa. Melepasi tahap itu, pengebilan mengira pengguna dan bukannya peranti, yang merupakan bentuk bil berbeza daripada VPS yang anda sudah bayar, jadi kos Tailscale setelah anda melepasi pelan percuma ialah angka yang perlu disemak sebelum anda memindahkan pasukan. Tunnel penuh yang baru anda bina mempunyai setara langsung di sana, kerana mengiklankan VPS sebagai exit node Tailscale memberikan anda laluan keluar yang sama melalui pelayan, diluluskan dalam konsol pentadbir dan bukannya ditulis ke dalam setiap konfigurasi klien. Halangan subnet juga mempunyai setara, kerana mengiklankan keseluruhan rangkaian peribadi daripada VPS menyerahkan rangkaian tersebut kepada setiap peranti dalam tailnet tanpa penyuntingan AllowedIPs bagi setiap rakan setara yang menyebabkan anda meninggalkan UI. Jika anda mahukan papan pemuka tersebut dan penghalaan mesh automatik tetapi bukan pelayan koordinasi orang lain, menjalankan pelayan NetBird anda sendiri pada VPS mengekalkan control plane pada perkakasan milik anda, dengan kos penyediaan DNS dan TLS yang tidak pernah diminta oleh wg-easy.

Jika sintaks compose di atas adalah bahagian yang tidak biasa dan bukannya bahagian WireGuard, asas Docker Compose pada VPS menjelaskan format fail dan arahan harian.

FAQ

Mengapakah wg-easy mengabaikan WG_HOST dan PASSWORD_HASH saya?

Pemboleh ubah tersebut adalah untuk wg-easy 14. Versi 15 merupakan penulisan semula, dan pihak pembangun telah memindahkan hampir semua konfigurasi ke dalam panel pentadbir di web UI. Kontena tersebut tidak membaca kedua-dua pemboleh ubah itu, jadi ia bermula seperti biasa dan kemudian meminta anda untuk mencipta akaun pentadbir pada lawatan pertama. Tetapkan alamat hos yang menghadap klien pada halaman persediaan tersebut.

Adakah saya memerlukan SYS_MODULE jika kernel saya sudah mempunyai WireGuard?

Tidak. SYS_MODULE dan mount /lib/modules wujud supaya kontena boleh memuatkan modul apabila hos tidak mempunyainya. Pada hos di mana sudo modprobe wireguard sudah berjaya, keupayaan tersebut tidak digunakan. Membuangnya adalah langkah pengukuhan yang munasabah, dan NET_ADMIN masih diperlukan walau apa pun keadaannya.

Klien bersambung tetapi tiada internet. Apakah masalahnya?

Handshake yang berlaku tanpa trafik hampir selalu bermaksud masalah forwarding. Sahkan net.ipv4.ip_forward=1 dan net.ipv4.conf.all.src_valid_mark=1 masih ada dalam fail compose, kerana salinan yang disunting secara manual sering kali kehilangannya. Jika forwarding dihidupkan, periksa pelayan DNS yang diterima oleh klien. Terowong yang menghantar semua trafik melalui VPN tetapi menghala ke pelayan DNS yang tidak lagi boleh dicapai akan kelihatan seperti sambungan yang terputus dalam pelayar.

Bagaimanakah cara saya membuat sandaran klien saya?

Segala-galanya disimpan dalam volume bernama etc_wireguard, di dalam fail wg0.json. UI juga mempunyai butang sandaran yang mengeksport data yang sama. Salin fail tersebut ke lokasi di luar pelayan sebelum sebarang naik taraf. Pemulihan dilakukan dengan memuat naik fail tersebut semasa langkah persediaan pada kontena yang baharu.

Bolehkah saya menjalankan wg-easy di sebalik reverse proxy?

Boleh. Letakkan proksi di hadapan TCP 51821, tamatkan TLS di situ, dan tetapkan INSECURE=true pada kontena supaya ia menerima hop HTTP biasa daripada proksi. Pastikan UDP 51820 diterbitkan secara terus, kerana trafik VPN adalah UDP dan tidak melalui proksi HTTP.