Cara Pasang wg-easy WireGuard dalam Docker

Perkara yang anda bina

wg-easy ialah WireGuard dengan antara muka web yang dijalankan sebagai satu bekas Docker. Ia mengurus 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 ialah WireGuard biasa. Modul kernel mengalihkan paket, jadi daya pemprosesan adalah sama seperti persediaan yang ditulis secara manual. Kelebihannya ialah kitar hayat klien: menambah, melumpuhkan dan memadam peer tanpa menyunting fail konfigurasi melalui SSH. Kekurangannya ialah anda tidak lagi mempunyai kawalan terus terhadap fail konfigurasi itu, yang dibincangkan dalam persediaan WireGuard manual pada VPS.

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

Versi 15 memindahkan tetapan daripada persekitaran

Kebanyakan panduan yang anda temui ditulis untuk wg-easy 14. Dalam versi itu, anda menetapkan WG_HOST kepada alamat pelayan anda dan PASSWORD_HASH kepada cincangan bcrypt kata laluan pentadbir, kedua-duanya sebagai pemboleh ubah persekitaran. Versi 15 ialah penulisan semula. Nota migrasi rasmi menyatakan dengan jelas bahawa v15 tidak menggunakan pemboleh ubah persekitaran yang sama seperti v14, dan kebanyakannya 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, kemudian meminta anda mencipta akaun pentadbir dalam pelayar. Itu bukan pepijat. Itulah aliran persediaan baharu.

Setakat July 2026, tag utama yang perlu dipin ialah 15. Pin versi utama dan bukannya menggunakan latest, kerana peningkatan versi utama mengubah format konfigurasi pada cakera dan tidak dapat dipulihkan kepada versi sebelumnya dengan sempurna.

Fail compose

Cipta direktori untuk stack tersebut dan tulis fail compose rasmi ke dalamnya. Ini ialah fail upstream tanpa sebarang perubahan.

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 ini:

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 volume bernama yang menyimpan kunci pelayan dan setiap klien yang anda cipta. Sandarkan volume tersebut, atau proses binaan semula akan memadamkan semua peer anda. Jika anda mahu melihat fail tersebut pada sistem fail hos, gantikan volume itu dengan bind mount dan baca perbezaan antara bind mount dengan volume bernama terlebih dahulu kerana kebenaran aksesnya berbeza.

Mengapa ia memerlukan NET_ADMIN, SYS_MODULE dan sysctl

Bekas tidak dibenarkan mengakses tindanan rangkaian secara lalai, dan setiap baris ini menghapuskan satu sekatan khusus.

NET_ADMIN membolehkan bekas mencipta antara muka wg0, menetapkan alamat padanya dan menulis laluan. Tanpanya, bekas bermula kemudian berhenti semasa mengaktifkan antara muka kerana ip link add wg0 type wireguard mengembalikan Operation not permitted.

SYS_MODULE bersama pelekap /lib/modules baca sahaja membolehkan bekas memuatkan modul kernel WireGuard jika hos belum memuatkannya. Modul itu berada pada kernel hos, bukan di dalam imej. Oleh itu, direktori hos perlu kelihatan dari dalam bekas. Pada kernel moden, modul itu biasanya terbina dalam. Anda boleh mengesahkannya dengan sudo modprobe wireguard && echo ok pada hos.

net.ipv4.ip_forward=1 menyebabkan kernel memajukan paket yang tidak ditujukan kepada hos itu sendiri. Tanpanya, klien bersambung, jabat tangan berjaya, kemudian setiap paket ke internet digugurkan. Akibatnya, ping 1.1.1.1 mengalami tamat masa walaupun VPN kelihatan bersambung.

net.ipv4.conf.all.src_valid_mark=1 ialah tetapan yang sering mengejutkan pengguna. WireGuard menandakan paket keluarannya sendiri supaya paket itu tidak dihalakan semula ke dalam terowong. Penapisan laluan terbalik yang ketat melihat paket dengan alamat sumber yang tidak sepadan dengan laluan yang dijangka, lalu menggugurkannya. sysctl ini memberitahu kernel supaya menerima paket yang ditandakan. Tetapan ini menghalang terowong penuh daripada memutuskan sambungannya sendiri.

Mulakannya 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. Upstream memberi amaran bahawa start pada bekas yang dicipta dengan tetapan berbeza akan menyebabkan rangkaian berada dalam keadaan tidak konsisten. Jika anda mahu tindanan dimulakan semula selepas but semula, restart: unless-stopped sudah mengendalikannya, dan tingkah laku but bagi perkhidmatan compose menerangkan perkara yang dijanjikan dan tidak dijanjikan oleh dasar tersebut.

Antara muka web mendengar pada TCP 51821. Pada lawatan pertama, antara muka ini memaparkan halaman persediaan untuk mencipta akaun pentadbir dan mengesahkan alamat hos yang akan digunakan oleh klien untuk mencapai pelayan. Alamat hos itu dimasukkan ke dalam baris Endpoint bagi setiap konfigurasi klien. Oleh itu, alamat tersebut mestilah alamat IP awam atau nama DNS VPS. Jika alamat itu salah, kod QR yang anda berikan kepada telefon akan menunjuk ke lokasi yang tidak dapat dicapai, dan jabat tangan tidak akan selesai.

Satu lagi perkara tentang port itu: wg-easy 15 menolak HTTP biasa melainkan anda menetapkan INSECURE=true. Mengaksesnya melalui HTTPS dengan sijil yang tidak dipercayai, atau menamatkan TLS pada proksi songsang di hadapannya, kedua-duanya boleh digunakan. Mengaksesnya melalui http:// dengan tetapan lalai tidak dibenarkan.

Jangan terbitkan port UI ke Internet

Fail compose menerbitkan port 51821 pada setiap antara muka. Port itu ialah halaman log masuk untuk pelayan yang boleh menghalakan trafik anda, jadi port tersebut tidak sepatutnya terbuka kepada umum. Penerbitan port dalam Docker menulis peraturan ke dalam rantaian DOCKER, yang dinilai sebelum ufw. Oleh itu, peraturan ufw deny tidak menutupnya. Perangkap ini wajar difahami secara berasingan, dan sebab port yang diterbitkan Docker mengabaikan ufw menerangkannya dengan lengkap.

Penyelesaian mudah ialah mengikat UI kepada loopback dan mengaksesnya 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, port tersebut tidak memberi respons kepada pihak lain, dan INSECURE=true selamat digunakan di sini kerana sambungan HTTP biasa tidak pernah meninggalkan antara muka loopback.

Buka UDP 51820 dan semak kedua-dua tembok api

WireGuard memerlukan UDP 51820 boleh dicapai dari internet. Docker menerbitkan port ini, tetapi banyak penyedia meletakkan tembok api rangkaian berasingan di hadapan VPS yang tidak diketahui oleh Docker. Buka port tersebut di kedua-dua tempat. Jika anda mengurus tembok api hos dengan ufw, peraturan asas ufw untuk VPS ialah cara yang lebih ringkas berbanding menulis nftables secara manual.

Semak bahawa bekas tersebut benar-benar sedang mendengar:

sudo ss -ulnp | grep 51820

Anda sepatutnya melihat soket UDP yang sedang mendengar. Jika tiada apa-apa pada baris itu, bekas tersebut tidak pernah mengaktifkan antara muka, dan sudo docker compose logs wg-easy akan menyatakan sebabnya.

Cipta klien dan imbasnya pada telefon

Dalam UI, cipta klien dan berikan nama yang boleh anda kenal pasti kemudian, seperti nama peranti yang menggunakannya. wg-easy memperuntukkan alamat terowong kosong seterusnya dan menjana pasangan kunci untuk anda. Setiap baris klien menyediakan kod QR dan fail .conf yang boleh dimuat turun.

Pasang aplikasi WireGuard rasmi pada telefon. Pilih untuk menambah terowong daripada kod QR, kemudian halakan kamera pada kod tersebut pada skrin anda. Terowong itu akan muncul dengan nama yang anda masukkan. Hidupkannya. Baris klien dalam UI akan mula memaparkan pembilang pemindahan dan masa jabat tangan terkini.

Klien yang tidak menunjukkan jabat tangan selepas diaktifkan langsung tidak mencapai pelayan. Ini menunjukkan masalah pada UDP 51820, sama ada pada tembok api penyedia atau alamat titik akhir yang dimasukkan dalam konfigurasi. Klien yang menunjukkan jabat tangan tetapi tidak mempunyai internet yang berfungsi menunjukkan masalah pada pemajuan atau DNS.

Pada komputer desktop, muat turun fail .conf dan import fail itu ke dalam klien WireGuard. Jangan masukkan semula kandungannya secara manual. Kunci peribadi dalam fail itu dijana sekali dan dipaparkan sekali sahaja. Kendalikan fail tersebut seperti anda mengendalikan kunci peribadi SSH.

Bila perlu beralih daripada UI

wg-easy ialah alat yang sesuai selagi rakan setara anda ialah orang dan telefon. UI lebih pantas daripada mengedit fail konfigurasi, dan pembatalan akses telefon yang hilang hanya memerlukan satu klik.

Anda akan mencapai hadnya apabila anda memerlukan sesuatu yang tidak dimodelkan oleh UI. Penghalaan antara tapak, apabila AllowedIPs rakan setara meliputi keseluruhan subnet jauh dan bukannya satu alamat, biasanya ialah had pertama. Terowong berpecah dengan peraturan penghalaan bagi setiap rakan setara, atau konfigurasi yang dijana oleh alat penyediaan anda, ialah keperluan seterusnya. Pada ketika itu, persediaan yang ditulis secara manual tidak lebih sukar; kaedahnya sahaja berbeza. Panduan WireGuard biasa menunjukkan terowong yang sama dibina daripada wg0.conf. Jika anda lebih suka menghentikan operasi satah kawalan sepenuhnya, Perbandingan WireGuard dengan Tailscale menerangkan pilihan terurus.

Jika sintaks compose di atas yang tidak biasa bagi anda, bukannya bahagian WireGuard, Asas Docker Compose pada VPS menerangkan 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 telah ditulis semula, dan pihak upstream memindahkan hampir semua konfigurasi ke panel pentadbir dalam UI web. Kontena tidak membaca mana-mana pemboleh ubah tersebut. Oleh itu, kontena bermula seperti biasa dan kemudian meminta anda mencipta akaun pentadbir pada lawatan pertama. Tetapkan alamat hos untuk klien pada halaman persediaan tersebut.

Adakah saya memerlukan SYS_MODULE jika kernel saya sudah mempunyai WireGuard?

Tidak. Pelekap SYS_MODULE dan /lib/modules membolehkan kontena memuatkan modul apabila hos belum memilikinya. Pada hos yang sudo modprobe wireguard sudah berjaya, keupayaan tersebut tidak digunakan. Mengalih keluarnya ialah langkah pengukuhan yang munasabah, dan NET_ADMIN masih diperlukan dalam kedua-dua keadaan.

Klien bersambung tetapi tiada internet. Apakah masalahnya?

Jabat tangan tanpa trafik hampir selalu menunjukkan masalah pemajuan. Pastikan net.ipv4.ip_forward=1 dan net.ipv4.conf.all.src_valid_mark=1 masih terdapat dalam fail compose, kerana salinan yang disunting secara manual sering kehilangan kedua-duanya. Jika pemajuan diaktifkan, semak pelayan DNS yang diterima oleh klien. Terowong yang menghantar semua trafik melalui VPN tetapi menunjuk kepada pelayan DNS yang tidak lagi dapat dicapainya akan kelihatan seperti sambungan yang tidak berfungsi dalam pelayar.

Bagaimanakah saya membuat sandaran klien saya?

Semua data berada dalam volume bernama etc_wireguard, 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 semasa langkah persediaan pada kontena baharu.

Bolehkah saya menjalankan wg-easy di sebalik proksi songsang?

Ya. Letakkan proksi di hadapan TCP 51821, tamatkan TLS di situ, dan tetapkan INSECURE=true pada kontena supaya kontena menerima sambungan HTTP biasa daripada proksi. Terbitkan UDP 51820 secara terus kerana trafik VPN menggunakan UDP dan tidak melalui proksi HTTP.