wg-easy: WireGuard yenye UI ya wavuti kwenye Docker

Unachojenga

wg-easy ni WireGuard yenye kiolesura cha wavuti, inayoendesha kama kontena moja la Docker. Inasimamia kiolesura cha WireGuard kwa niaba yako na inaongeza kiolesura cha kivinjari cha kuunda wateja. Kila mteja unayemwunda hupata faili ya usanidi na msimbo wa QR, hivyo simu hujiunga na VPN kwa kuelekeza kamera yake kwenye skrini.

Handaki lenyewe ni WireGuard ya kawaida. Moduli ya kernel huhamisha pakiti, kwa hiyo upitishaji wa data ni sawa na usanidi ulioandikwa kwa mkono. Unachopata ni usimamizi wa mzunguko wa maisha wa wateja: kuongeza, kuzima na kufuta peers bila kuhariri faili ya usanidi kupitia SSH. Unachopoteza ni udhibiti wa moja kwa moja wa faili hiyo ya usanidi, ambao ndio mada ya usanidi wa WireGuard kwa mkono kwenye VPS.

Unahitaji VPS ya KVM yenye anwani ya umma ya IPv4, Docker Engine iliyo na programu-jalizi ya Compose, na ufikiaji wa root. Uboreshaji wa virtual wa kontena unaoshiriki kernel ya mwenyeji, kama OpenVZ au LXC, kwa kawaida hauwezi kupakia moduli ya WireGuard, na kontena itashindwa kuwasha kiolesura.

Toleo la 15 lilihamisha mipangilio kutoka kwenye mazingira

Miongozo mingi utakayopata iliandikwa kwa wg-easy 14, ambapo uliweka WG_HOST kwenye anwani ya seva yako na PASSWORD_HASH kwenye heshi ya bcrypt ya nenosiri la msimamizi, zote zikiwa vigezo vya mazingira. Toleo la 15 ni uandishi upya. Maelezo rasmi ya uhamishaji yanasema wazi kwamba v15 haitumii vigezo vilevile vya mazingira kama v14, na kwamba vingi vilihamishiwa kwenye paneli ya msimamizi katika kiolesura cha wavuti.

Kwa hiyo WG_HOST na PASSWORD_HASH havifanyi tena chochote. Ukikinakili faili ya zamani ya compose, kontena huanza, hupuuza mistari hiyo, kisha hukuomba uunde akaunti ya msimamizi kwenye kivinjari. Hilo si hitilafu. Huo ndio mtiririko mpya wa usanidi.

Kufikia Julai 2026, lebo kuu ya kubandika ni 15. Bandika toleo kuu badala ya kutumia latest, kwa sababu uboreshaji wa toleo kuu hubadilisha umbizo la usanidi lililo kwenye diski na hautarejesha toleo la awali kwa usafi.

Faili ya compose

Unda saraka ya stack na uandike faili rasmi ya compose ndani yake. Hii ni faili kutoka upstream bila mabadiliko.

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

Yaliyomo yanaonekana hivi:

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 ni volume yenye jina inayohifadhi ufunguo wa seva na kila mteja unayemunda. Hifadhi nakala ya volume hiyo, la sivyo ujenzi upya utafuta peers wako wote. Ikiwa ungependa kuona faili hizo kwenye mfumo wa faili wa host, ibadilishe iwe bind mount, kisha usome tofauti kati ya bind mounts na volumes zenye majina kabla ya kufanya hivyo, kwa sababu ruhusa hutenda kazi kwa njia tofauti.

Kwa nini inahitaji NET_ADMIN, SYS_MODULE na sysctl hizi

Kontena hairuhusiwi kugusa stack ya mtandao kwa chaguo-msingi, na kila mstari kati ya hii huondoa kizuizi mahususi.

NET_ADMIN huruhusu kontena kuunda kiolesura cha wg0, kukipangia anwani na kuandika njia za uelekezaji. Bila hiyo, kontena huanza kisha hufa wakati wa kuwasha kiolesura, kwa sababu ip link add wg0 type wireguard hurejesha Operation not permitted.

SYS_MODULE pamoja na mount ya kusoma tu ya /lib/modules huruhusu kontena kupakia moduli ya kernel ya WireGuard ikiwa host bado haijapakia moduli hiyo. Moduli iko kwenye kernel ya host, si ndani ya image, ndiyo maana saraka ya host lazima ionekane. Kwenye kernel ya kisasa, moduli hiyo kwa kawaida imejengwa ndani, na unaweza kuthibitisha hilo kwa sudo modprobe wireguard && echo ok kwenye host.

net.ipv4.ip_forward=1 huifanya kernel ipeleke mbele pakiti ambazo hazijaelekezwa kwenye mashine yenyewe. Bila hiyo, mteja huunganika, handshake hufaulu, kisha kila pakiti inayoelekea intaneti hutupwa, hivyo ping 1.1.1.1 huisha muda huku VPN ikionekana kuwa imeunganishwa.

net.ipv4.conf.all.src_valid_mark=1 ndiyo inayowashangaza watu. WireGuard huweka alama kwenye pakiti zake zinazotoka ili zisielekezwe tena ndani ya tunnel. Uchujaji mkali wa njia ya kurudi huona pakiti ambayo anwani yake ya chanzo hailingani na njia inayotarajiwa na kuitupa. Sysctl hii huiambia kernel ikubali pakiti zilizo na alama, jambo linalozuia full tunnel kujivuruga.

Iwashe na uunde akaunti ya msimamizi

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

Tumia docker compose up na docker compose down, si start na stop. Upstream inaonya kuwa start kwenye kontena lililoundwa kwa mipangilio tofauti huacha mtandao katika hali isiyolingana. Ikiwa unataka stack ianze tena baada ya kuwasha upya, restart: unless-stopped tayari inashughulikia hilo, na tabia ya kuwasha ya huduma za compose inaeleza sera hiyo inaahidi nini na haiahidi nini.

Kiolesura cha wavuti husikiliza TCP 51821. Unapotembelea kwa mara ya kwanza, kinaonyesha ukurasa wa usanidi ambapo unaweka akaunti ya msimamizi na kuthibitisha anwani ya mwenyeji ambayo wateja watatumia kufikia seva. Anwani hiyo ya mwenyeji huwekwa kwenye mstari wa Endpoint wa usanidi wa kila mteja, hivyo lazima iwe IP ya umma au jina la DNS la VPS. Ikiwa si sahihi, msimbo wa QR unaompa simu unaelekeza mahali pasipofikika, na handshake haikamiliki kamwe.

Jambo lingine kuhusu port hiyo: wg-easy 15 hukataa HTTP isiyo na usimbaji fiche isipokuwa uweke INSECURE=true. Kuifikia kupitia HTTPS yenye cheti kisichoaminika, au kumalizia TLS kwenye reverse proxy iliyo mbele yake, yote mawili yanakubalika. Kuifikia kupitia http:// kwa mipangilio chaguomsingi hakukubaliki.

Usichapishe port ya UI kwenye intaneti

Faili ya compose inachapisha port 51821 kwenye kila kiolesura. Hii ni ukurasa wa kuingia wa mfumo unaoweza kuelekeza trafiki yako, kwa hiyo haupaswi kufunguliwa kwa kila mtu. Kuchapisha port katika Docker huandika sheria kwenye chain ya DOCKER, ambayo hutathminiwa kabla ya ufw. Kwa hiyo, sheria ya ufw deny haifungi port hiyo. Ni muhimu kuelewa mtego huu peke yake, na kwa nini port zilizochapishwa na Docker hupuuza ufw inaueleza kikamilifu.

Suluhisho rahisi ni kuunganisha UI kwenye loopback na kuifikia kupitia handaki la SSH:

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

Kisha, kutoka kwenye laptop yako:

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

Fungua http://127.0.0.1:51821 katika kivinjari kwenye laptop yako. Trafiki inasimbwa kwa SSH, port hiyo haiwajibu watumiaji wengine, na INSECURE=true ni salama hapa kwa sababu muunganisho wa HTTP usio na usimbaji hauondoki kwenye kiolesura cha loopback.

Fungua UDP 51820 na ukague ngome zote mbili

WireGuard yenyewe inahitaji UDP 51820 ipatikane kutoka kwenye intaneti. Docker huchapisha mlango huo, lakini watoa huduma wengi huweka ngome tofauti ya mtandao mbele ya VPS, ambayo Docker haiijui. Fungua mlango huo katika sehemu zote mbili. Ikiwa unasimamia ngome ya mwenyeji kwa kutumia ufw, kanuni za msingi za ufw kwa VPS ndiyo njia fupi kuliko kuandika nftables mwenyewe.

Thibitisha kuwa kontena linasikiliza kweli:

sudo ss -ulnp | grep 51820

Unapaswa kuona soketi ya UDP inayosikiliza. Ikiwa hakuna chochote kwenye mstari huo, kontena halikuwasha kiolesura, na sudo docker compose logs wg-easy itaonyesha sababu.

Unda mteja na uchanganue msimbo wake kwenye simu

Katika kiolesura, unda mteja na umpe jina utakalogundua baadaye, kwa mfano jina la kifaa anachohusishwa nacho. wg-easy hutenga anwani inayofuata iliyo huru ya tunnel na hukuundia jozi ya funguo. Kila safu ya mteja ina msimbo wa QR na faili ya .conf inayoweza kupakuliwa.

Sakinisha programu rasmi ya WireGuard kwenye simu. Chagua kuongeza tunnel kutoka kwenye msimbo wa QR. Elekeza kamera kwenye msimbo ulio kwenye skrini yako. Tunnel itaonekana kwa jina uliloandika. Iwashe. Safu ya mteja katika kiolesura itaanza kuonyesha vihesabio vya uhamishaji na muda wa hivi karibuni wa handshake.

Mteja anayeonyesha hakuna handshake baada ya kuuwasha hafikii server kabisa. Hii inaelekeza kwenye UDP 51820, ama kwenye firewall ya mtoa huduma au kwenye anwani ya endpoint iliyoingizwa kwenye usanidi. Mteja anayeonyesha handshake lakini hana intaneti inayofanya kazi ana tatizo la forwarding au DNS.

Kwenye kompyuta ya mezani, pakua faili ya .conf na uiingize kwenye mteja wa WireGuard badala ya kuiandika upya. Private key katika faili hiyo hutengenezwa mara moja na kuonyeshwa mara moja tu. Ishughulikie faili hiyo kwa usalama unaotumia kwa private key ya SSH.

Wakati wa kuzidi uwezo wa UI

wg-easy ni zana inayofaa wakati peers wako ni watu na simu. UI ni ya haraka kuliko kuhariri faili za usanidi, na kubatilisha simu iliyopotea kunahitaji kubofya mara moja.

Utafikia mipaka yake unapotaka kitu ambacho UI haikionyeshi. Uelekezaji wa site-to-site, ambapo AllowedIPs ya peer inahusisha subnet nzima ya mbali badala ya anwani moja, kwa kawaida ndiyo kikwazo cha kwanza. Tunnel zilizogawanywa zenye sheria za uelekezaji kwa kila peer, au usanidi unaozalishwa na zana yako ya provisioning, hufuata. Wakati huo usanidi wa kuandika mwenyewe si mgumu zaidi; ni tofauti tu, na mwongozo wa kawaida wa WireGuard unaonyesha tunnel hiyo hiyo iliyoundwa kutoka wg0.conf. Ikiwa ungependa kuacha kabisa kuendesha control plane, WireGuard ikilinganishwa na Tailscale inaeleza chaguo linalodhibitiwa.

Ikiwa sintaksia ya compose hapo juu ndiyo haikuwa ya kawaida, badala ya sehemu ya WireGuard, misingi ya Docker Compose kwenye VPS inaeleza muundo wa faili na amri za kila siku.

FAQ

Kwa nini wg-easy inapuuza WG_HOST na PASSWORD_HASH zangu?

Vigezo hivyo ni vya wg-easy 14. Toleo la 15 limeandikwa upya, na mradi wa upstream umehamishia karibu usanidi wote kwenye paneli ya usimamizi katika kiolesura cha wavuti. Kontena halisomi kigezo chochote kati ya hivyo viwili. Kwa hiyo huanza kawaida, kisha hukuomba uunde akaunti ya usimamizi unapotembelea mara ya kwanza. Weka anwani ya host inayotumiwa na wateja kwenye ukurasa huo wa usanidi.

Je, ninahitaji SYS_MODULE ikiwa kernel yangu tayari ina WireGuard?

Hapana. SYS_MODULE na mount ya /lib/modules zipo ili kontena liweze kupakia module wakati host haina module hiyo. Kwenye host ambayo sudo modprobe wireguard tayari inafanikiwa, uwezo huo hautumiki. Kuiondoa ni hatua inayofaa ya kuimarisha usalama, na NET_ADMIN bado inahitajika kwa hali zote.

Mteja anaunganika lakini hakuna intaneti. Tatizo ni nini?

Handshake bila traffic karibu kila mara humaanisha tatizo la forwarding. Thibitisha kuwa net.ipv4.ip_forward=1 na net.ipv4.conf.all.src_valid_mark=1 bado zimo kwenye faili la compose, kwa sababu nakala iliyohaririwa kwa mkono mara nyingi hupoteza mipangilio hiyo. Ikiwa forwarding imewashwa, kagua server ya DNS aliyopewa mteja. Tunnel inayotuma traffic yote kupitia VPN lakini inaelekezwa kwenye server ya DNS ambayo haiwezi tena kufikiwa huonekana kama muunganisho uliokufa kwenye browser.

Ninawezaje kuhifadhi nakala za wateja wangu?

Kila kitu kiko kwenye volume yenye jina etc_wireguard, katika faili la wg0.json. Kiolesura cha wavuti pia kina kitufe cha kuhifadhi nakala kinachotoa data hiyo hiyo. Nakili faili hilo mahali palipo nje ya server kabla ya kusasisha chochote. Kurejesha hufanywa kwa kupakia faili wakati wa hatua ya usanidi kwenye kontena jipya.

Je, ninaweza kuendesha wg-easy nyuma ya reverse proxy?

Ndiyo. Weka proxy mbele ya TCP 51821, simamisha TLS hapo, na uweke INSECURE=true kwenye kontena ili likubali hop ya HTTP isiyosimbwa kutoka kwa proxy. Endelea kuchapisha UDP 51820 moja kwa moja, kwa sababu traffic ya VPN ni UDP na haipiti kwenye HTTP proxy.