Cara Pasang wg-easy WireGuard UI dengan Docker

Apa yang anda sedang bina

wg-easy ialah WireGuard dengan antara muka web, yang berjalan sebagai satu kontena Docker. Ia menguruskan antara muka WireGuard untuk anda dan menambah UI pelayar untuk 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 kadar pemindahan 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 subjek persediaan manual WireGuard pada VPS.

Anda memerlukan hos Linux yang boleh anda uruskan, seperti KVM VPS, dengan alamat IP awam atau nama domain yang menghala kepadanya, CPU x86_64 atau arm64, Docker Engine dengan pemalam Compose, dan akses root. Virtualisasi kontena yang berkongsi kernel hos, seperti OpenVZ atau LXC, biasanya tidak dapat memuatkan modul WireGuard, dan kontena akan gagal untuk menghidupkan antara muka tersebut.

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 pentadbir, kedua-duanya sebagai pemboleh ubah persekitaran (environment variables). Versi 15 merupakan 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 pentadbir 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 untuk mencipta akaun pentadbir dalam pelayar. Itu bukan pepijat. Ia adalah aliran persediaan yang baharu.

Sehingga Oktober 2026, tag utama untuk disematkan ialah 15. Sematkan versi utama dan bukannya menggunakan latest, kerana naik taraf versi utama akan mengubah format konfigurasi pada cakera dan tidak akan dapat diputar balik (roll back) dengan lancar. Peralihan ke versi 15 menggantikan fail JSON v14 dengan pangkalan data SQLite.

Fail compose

Cipta direktori untuk stack tersebut dan tulis fail compose rasmi ke dalamnya. Ini merupakan fail upstream, dengan baris pilihan yang dikomen telah dibuang.

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

Kandungannya kelihatan 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 named volume yang menyimpan kunci pelayan dan setiap klien yang anda cipta, disimpan di dalam pangkalan data SQLite wg-easy.db. Lakukan sandaran (backup) pada volume tersebut, atau binaan semula akan memadamkan 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 named volume sebelum anda melakukannya, kerana keizinan (permissions) berfungsi secara berbeza.

Mengapa NET_ADMIN, SYS_MODULE dan sysctl diperlukan

Secara lalai, kontena tidak dibenarkan untuk mengubah suai tindanan rangkaian (network stack), dan setiap baris ini membuang satu sekatan khusus.

NET_ADMIN membolehkan kontena mencipta antara muka wg0, menetapkan alamat kepadanya serta menulis laluan (routes). Tanpanya, kontena akan bermula dan kemudian terhenti semasa proses menghidupkan antara muka, kerana ip link add wg0 type wireguard mengembalikan Operation not permitted.

SYS_MODULE berserta lekap (mount) baca-sahaja /lib/modules membolehkan kontena 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 mesin itu sendiri. Tanpanya, klien akan bersambung, jabat tangan (handshake) berjaya, namun setiap paket ke internet akan digugurkan, menyebabkan ping 1.1.1.1 tamat masa (timeout) walaupun VPN kelihatan bersambung.

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

Mulakan 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. start hanya memulakan semula kontena yang sedia ada, jadi sebarang perubahan yang anda buat pada fail compose, termasuk tetapan rangkaian dan sysctl, tidak akan diaplikasikan, manakala up mencipta semula apa sahaja yang berubah. Jika anda mahukan stack kembali selepas but semula, restart: unless-stopped sudah pun melindunginya, dan gelagat but perkhidmatan compose menjelaskan perkara yang dilakukan 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 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 tidak pernah menyediakan TLS sendiri, dan ia tidak menolak HTTP biasa. Melalui http://, UI masih dimuatkan dan memaparkan sepanduk amaran. Perkara yang diubah oleh lalai ialah kuki sesi, yang membawa flag Secure, jadi pelayar yang mencapai UI melalui HTTP biasa pada alamat awam akan membuangnya dan log masuk tidak akan kekal. INSECURE=true membuang flag tersebut dan tidak melakukan apa-apa lagi. Meletakkan reverse proxy di hadapan yang menamatkan TLS, walaupun dengan sijil yang ditandatangani sendiri, tidak memerlukan sebarang perubahan pada wg-easy sama sekali.

Jangan terbitkan port UI ke internet

Fail compose menerbitkan 51821 pada setiap antara muka. Itu adalah halaman log masuk untuk kotak yang boleh menghalakan trafik anda, dan ia tidak sepatutnya terbuka kepada dunia. Menerbitkan port dalam Docker menulis peraturan ke dalam rantaian DOCKER, yang dinilai sebelum ufw, jadi peraturan deny ufw tidak akan menutupnya. Perangkap ini perlu difahami sendiri, dan mengapa port yang diterbitkan Docker mengabaikan ufw meliputinya sepenuhnya.

Penyelesaian mudahnya ialah dengan mengikat UI ke loopback dan mencapainya melalui terowong SSH:

    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 dan port tersebut tidak menjawab sesiapa pun. INSECURE=true hanya membuang flag Secure daripada kuki sesi supaya pelayar mengekalkan log masuk anda pada alamat HTTP biasa ini, dan itu selamat di sini kerana hop HTTP biasa tidak pernah meninggalkan antara muka loopback.

Buka UDP 51820, dan periksa kedua-dua firewall

WireGuard sendiri memerlukan port UDP 51820 boleh dicapai dari internet. Docker menerbitkan port ini, 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 ufw asas untuk VPS adalah cara yang lebih pantas berbanding menulis nftables secara manual.

Pastikan kontena 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 kontena tidak berjaya menaikkan antaramuka, dan sudo docker compose logs wg-easy akan menyatakan puncanya.

Cipta klien dan imbasnya pada telefon

Dalam UI, cipta klien dan berikan nama yang mudah anda kenali kemudian, 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 arah kod pada skrin anda. Tunnel tersebut akan muncul dengan nama yang anda taip. Hidupkannya, dan baris klien dalam UI akan mula memaparkan pembilang pemindahan data 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 pelayan tersebut membuka satu pun port 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 secara terbalik 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 sama sekali. Ini menunjukkan masalah pada UDP 51820, sama ada pada firewall penyedia atau pada alamat titik akhir (endpoint) yang ditetapkan dalam konfigurasi. Klien yang menunjukkan jabat tangan tetapi internet tidak berfungsi 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. Layani fail tersebut seperti anda melayani kunci peribadi SSH.

Bilakah masanya untuk beralih daripada UI

wg-easy ialah alat yang tepat selagi peer anda terdiri daripada orang dan telefon. UI adalah lebih pantas daripada 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 tapak ke tapak (site to site), di mana AllowedIPs peer meliputi keseluruhan subnet jauh dan bukannya satu alamat tunggal, biasanya merupakan halangan pertama. Terowong terpisah (split tunnels) dengan peraturan penghalaan bagi setiap peer, atau konfigurasi yang dijana oleh alat penyediaan anda, adalah halangan seterusnya. Pada tahap itu, persediaan manual tidaklah lebih sukar, ia hanya berbeza, dan panduan WireGuard biasa menunjukkan terowong yang sama dibina daripada wg0.conf. Jika anda lebih suka untuk berhenti menjalankan satah kawalan (control plane) sama sekali, WireGuard berbanding Tailscale merangkumi pilihan terurus. Sama ada ia pertukaran yang adil bergantung pada apa yang pelayan penyelarasan boleh capai, dan model kepercayaan Tailscale wajar dibaca sebelum anda menyerahkan rangkaian anda kepadanya. Kos biasanya menjadi soalan seterusnya, dan apa yang sebenarnya dilindungi oleh pelan percuma Tailscale adalah sehingga enam pengguna tanpa kos, untuk kegunaan bukan komersial sahaja, jadi isi rumah tidak membayar apa-apa manakala pasukan perniagaan kecil tidak layak tidak kira betapa sedikit ahlinya. Melepasi tahap itu, pengebilan mengira pengguna dan bukannya peranti, yang merupakan bentuk bil yang berbeza daripada VPS yang anda sudah bayar, jadi kos Tailscale selepas anda melebihi pelan percuma adalah angka yang perlu disemak sebelum anda memindahkan pasukan. Terowong penuh yang baru anda bina mempunyai setara terus 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 itu kepada setiap peranti dalam tailnet tanpa penyuntingan AllowedIPs bagi setiap peer yang menyebabkan anda meninggalkan UI. Jika anda mahukan papan pemuka itu dan penghalaan mesh automatik tetapi bukan pelayan penyelarasan orang lain, menjalankan pelayan NetBird anda sendiri pada VPS mengekalkan satah kawalan pada perkakasan milik anda, dengan kos persediaan DNS dan TLS yang tidak pernah diminta oleh wg-easy daripada anda.

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

Mengapa wg-easy mengabaikan WG_HOST dan PASSWORD_HASH saya?

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

Adakah saya perlukan SYS_MODULE jika kernel saya sudah mempunyai WireGuard?

Tidak. SYS_MODULE dan lekap /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.

Klien bersambung tetapi tiada internet. Apa yang salah?

Jabat tangan tanpa trafik hampir selalu bermaksud penghalaan (forwarding). Sahkan net.ipv4.ip_forward=1 dan net.ipv4.conf.all.src_valid_mark=1 masih berada dalam fail compose, kerana salinan yang disunting secara manual sering kehilangannya. Jika penghalaan 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 kelihatan sama seperti sambungan yang mati dalam pelayar.

Bagaimanakah cara saya membuat sandaran klien saya?

Segala-galanya berada dalam volum bernama etc_wireguard. Dalam versi 15, itu bermaksud pangkalan data SQLite di /etc/wireguard/wg-easy.db di dalam kontena. Dokumentasi v15 tidak menerangkan sebarang ciri sandaran atau eksport, jadi buat sandaran volum itu sendiri: jalankan docker compose down, salin kandungan volum ke suatu tempat di luar pelayan, kemudian bawa semula stack dengan docker compose up -d. Lakukan ini sebelum sebarang naik taraf. Fail wg0.json yang disebut oleh panduan lama adalah milik wg-easy 14. Ia adalah apa yang dieksport oleh butang sandaran v14, dan dalam v15 kegunaan satu-satunya adalah sebagai fail yang anda muat naik dalam wizard persediaan apabila anda memigrasikan pemasangan lama.

Bolehkah saya menjalankan wg-easy di sebalik reverse proxy?

Ya. Letakkan proksi di hadapan port UI web, tamatkan TLS di sana, dan biarkan INSECURE tidak ditetapkan. Kontena menerima hop HTTP biasa daripada proksi seperti sedia ada, dan contoh rasmi Caddy dan Traefik tidak menetapkan sebarang pemboleh ubah INSECURE sama sekali. Memandangkan pelayar bercakap HTTPS dengan proksi, anda mahu kuki sesi mengekalkan flag Secure-nya, yang merupakan satu-satunya perkara yang dibuang oleh INSECURE=true. Pastikan UDP 51820 diterbitkan secara terus, kerana trafik VPN adalah UDP dan tidak melalui proksi HTTP.