התקנת wg-easy עם Docker: מדריך הגדרה מלא
למדו להריץ WireGuard עם ממשק ניהול ב-Docker Compose. המדריך מסביר את הגדרות NET_ADMIN ו-sysctls הנדרשות, ואיך לעבור לגרסה 15 ללא שגיאות במשתני הסביבה.
מה אתם בונים
wg-easy הוא WireGuard עם ממשק אינטרנטי, הפועל כמכולת Docker אחת. הוא מנהל עבורכם את ממשק ה-WireGuard ומוסיף ממשק משתמש בדפדפן ליצירת לקוחות. כל לקוח שאתם יוצרים מקבל קובץ הגדרות וקוד QR, כך שטלפון מצטרף ל-VPN על ידי הפניית המצלמה אל המסך.
המנהרה עצמה היא WireGuard רגיל. מודול ה-kernel מעביר את החבילות, לכן קצב העברת הנתונים זהה להגדרה ידנית. מה שאתם מרוויחים הוא ניהול מחזור החיים של הלקוח: הוספה, השבתה ומחיקה של עמיתים (peers) ללא עריכת קובץ הגדרות דרך SSH. מה שאתם מוותרים עליו הוא שליטה ישירה באותו קובץ הגדרות, נושא שנדון ב-הגדרה ידנית של WireGuard על גבי VPS.
אתם זקוקים למארח Linux שניתן לנהל, כגון KVM VPS, עם כתובת IP ציבורית או שם מתחם המצביע אליו, מעבד x86_64 או arm64, מנוע Docker עם תוסף Compose, והרשאות root. וירטואליזציה של מכולות המשתפת את ה-kernel של המארח, כגון OpenVZ או LXC, בדרך כלל אינה יכולה לטעון את מודול ה-WireGuard, והמכולה תיכשל בהעלאת הממשק.
גרסה 15 העבירה את ההגדרות מחוץ לסביבה
רוב המדריכים שתמצאו נכתבו עבור wg-easy 14, שבה הגדרתם את WG_HOST לכתובת השרת שלכם ואת PASSWORD_HASH ל-hash מסוג bcrypt של סיסמת הניהול, שניהם כמשתני סביבה. גרסה 15 היא שכתוב מלא. הערות השדרוג הרשמיות מציינות במפורש שגרסה 15 אינה משתמשת באותם משתני סביבה כמו גרסה 14, וכי רובם הועברו ללוח הבקרה בממשק ה-web.
לפיכך, WG_HOST ו-PASSWORD_HASH אינם עושים דבר עוד. אם תעתיקו קובץ compose ישן, המכולה תעלה, תתעלם מהשורות הללו, ולאחר מכן תבקש מכם ליצור חשבון מנהל בדפדפן. זו אינה תקלה. זהו תהליך ההגדרה החדש.
נכון לאוקטובר 2026, ה-tag העיקרי שיש לקבע הוא 15. קבעו את הגרסה הראשית במקום להשתמש ב-latest, כיוון ששדרוג גרסה ראשית משנה את פורמט התצורה על הדיסק ולא יאפשר חזרה לאחור בצורה נקייה. המעבר לגרסה 15 החליף את קובץ ה-JSON של גרסה 14 בבסיס נתונים מסוג SQLite.
קובץ ה-compose
צרו ספרייה עבור ה-stack וכתבו לתוכה את קובץ ה-compose הרשמי. זהו הקובץ המקורי (upstream), ללא השורות האופציונליות המושארות כהערות.
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תוכן הקובץ נראה כך:
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::/64etc_wireguard הוא volume בעל שם המכיל את מפתח השרת ואת כל הלקוחות שתיצרו, המאוחסנים בתוך מסד הנתונים SQLite בשם wg-easy.db. בצעו גיבוי ל-volume הזה, אחרת בנייה מחדש תגרום לאובדן כל ה-peers שלכם. אם אתם מעדיפים לראות את הקבצים הללו במערכת הקבצים של ה-host, החליפו אותו ב-bind mount, אך קראו תחילה על ההבדלים בין bind mounts לבין volumes בעלי שם לפני שתעשו זאת, כיוון שההרשאות מתנהגות בצורה שונה.
מדוע נדרשים NET_ADMIN, SYS_MODULE והגדרות sysctl
כברירת מחדל, מכולה אינה מורשית לגעת ב-stack של הרשת, וכל אחת מהשורות הללו מסירה חסימה ספציפית.
NET_ADMIN מאפשר למכולה ליצור את הממשק wg0, להקצות לו כתובת ולכתוב נתיבי ניתוב (routes). ללא הרשאה זו, המכולה עולה ואז קורסת בעת ניסיון העלאת הממשק, כיוון ש-ip link add wg0 type wireguard מחזיר Operation not permitted.
SYS_MODULE יחד עם ה-mount לקריאה בלבד של /lib/modules מאפשרים למכולה לטעון את מודול ה-kernel של WireGuard אם המארח (host) טרם טען אותו. המודול נמצא ב-kernel של המארח ולא בתוך ה-image, וזו הסיבה שתיקיית המארח חייבת להיות גלויה. ב-kernel מודרני המודול לרוב מובנה, וניתן לוודא זאת באמצעות sudo modprobe wireguard && echo ok על המארח.
net.ipv4.ip_forward=1 גורם ל-kernel להעביר (forward) חבילות מידע שאינן ממוענות למכונה עצמה. ללא הגדרה זו, לקוח מתחבר, ה-handshake מצליח, אך לאחר מכן כל חבילה המיועדת לאינטרנט נזרקת, ולכן ping 1.1.1.1 מגיע ל-timeout בעוד ה-VPN נראה מחובר.
net.ipv4.conf.all.src_valid_mark=1 הוא ההגדרה שמפתיעה משתמשים רבים. WireGuard מסמן את חבילות המידע היוצאות שלו כדי שלא ינותבו חזרה לתוך ה-tunnel. מנגנון סינון נתיב חוזר (reverse path filtering) קפדני מזהה חבילה שכתובת המקור שלה אינה תואמת לנתיב הצפוי וזורק אותה. הגדרת sysctl זו מורה ל-kernel לקבל חבילות מסומנות, וזה מה שמונע מ-tunnel מלא לשבש את עצמו.
הפעלת השירות ויצירת חשבון מנהל
cd /etc/docker/containers/wg-easy
sudo docker compose up -d
sudo docker compose logs -fהשתמשו ב-docker compose up וב-docker compose down, ולא ב-start וב-stop. הפקודה start מאתחלת רק מכולות קיימות, לכן כל שינוי שביצעתם בקובץ ה-compose, כולל הגדרות רשת ו-sysctl, לא ייושם; לעומת זאת, up יוצרת מחדש כל רכיב שהשתנה. אם ברצונכם שה-stack יעלה לאחר אתחול המערכת, restart: unless-stopped כבר מטפלת בכך, והקישור להתנהגות שירותי compose בעת עליית המערכת מסביר מה מדיניות זו מבטיחה ומה לא.
ממשק ה-web מאזין בפורט TCP 51821. בביקור הראשון יוצג דף הגדרה שבו תיצרו את חשבון המנהל ותאשרו את כתובת ה-host שבה ישתמשו הלקוחות כדי להגיע לשרת. כתובת ה-host הזו מופיעה בשורת ה-Endpoint בכל קובץ הגדרות של לקוח, לכן עליה להיות ה-IP הציבורי או שם ה-DNS של ה-VPS. אם הכתובת שגויה, קוד ה-QR שתעבירו לטלפון יפנה ליעד לא נגיש, ותהליך ה-handshake לא יושלם לעולם.
נקודה נוספת בנוגע לפורט זה: wg-easy לא מספק TLS בעצמו, והוא אינו מסרב לחיבורי HTTP רגילים. בחיבור דרך http:// הממשק עדיין ייטען ויוצג באנר אזהרה. השינוי שברירת המחדל מבצעת הוא ב-session cookie, הנושא את הדגל Secure; לכן, דפדפן שמגיע לממשק דרך HTTP רגיל בכתובת ציבורית יפסול את ה-cookie וההתחברות לא תישמר. INSECURE=true מסיר את הדגל הזה ולא מבצע שום פעולה אחרת. הצבת reverse proxy לפני השירות שיבצע TLS termination, גם אם באמצעות תעודה בחתימה עצמית, אינה דורשת שום שינוי ב-wg-easy.
אל תפרסמו את פורט ה-UI לאינטרנט
קובץ ה-compose מפרסם את פורט 51821 בכל ממשקי הרשת. מדובר בדף התחברות למערכת שמסוגלת לנתב את התעבורה שלכם, ולכן אין לחשוף אותו לעולם. פרסום פורט ב-Docker כותב חוקים לשרשרת ה-DOCKER, אשר מוערכת לפני ה-ufw, ולכן חוק deny ב-ufw לא יחסום אותו. כדאי להבין את המלכודת הזו לעומק, והמאמר מדוע פורטים שמפורסמים על ידי Docker מתעלמים מ-ufw מסביר זאת במלואו.
הפתרון הפשוט הוא לקשור (bind) את ה-UI לממשק ה-loopback ולגשת אליו דרך מנהרת SSH:
ports:
- "51820:51820/udp"
- "127.0.0.1:51821:51821/tcp"
environment:
- INSECURE=trueלאחר מכן, מהמחשב הנייד שלכם:
ssh -L 51821:127.0.0.1:51821 youruser@your.server.addressפתחו את http://127.0.0.1:51821 בדפדפן במחשב הנייד. התעבורה מוצפנת באמצעות SSH והפורט אינו מגיב לאף גורם אחר. ה-INSECURE=true רק מסיר את דגל ה-Secure מעוגיית ההתחברות כדי שהדפדפן ישמור על ההתחברות שלכם בכתובת ה-HTTP הפשוטה הזו; זה בטוח במקרה זה, כיוון שהקפיצה ב-HTTP הפשוט לעולם לא יוצאת מממשק ה-loopback.
פתיחת פורט UDP 51820 ובדיקת שני ה־firewalls
הפרוטוקול WireGuard דורש שפורט UDP 51820 יהיה נגיש מהאינטרנט. Docker מפרסם את הפורט, אך ספקי שירות רבים מציבים firewall רשתי נפרד לפני ה־VPS, ש־Docker אינו מודע לקיומו. יש לפתוח את הפורט בשני המקומות. אם אתם מנהלים את ה־firewall של המארח באמצעות ufw, המדריך כללי ufw בסיסיים ל־VPS הוא דרך קצרה יותר מאשר כתיבת חוקי nftables ידנית.
וודאו שהמכולה אכן מאזינה:
sudo ss -ulnp | grep 51820עליכם לראות socket מסוג UDP במצב האזנה. אם השורה ריקה, המשמעות היא שהמכולה לא הצליחה להעלות את הממשק, ו־sudo docker compose logs wg-easy יציג את הסיבה לכך.
יצירת לקוח וסריקה שלו בטלפון
בממשק המשתמש, צרו לקוח ותנו לו שם שתוכלו לזהות מאוחר יותר, למשל שם המכשיר שאליו הוא שייך. wg-easy מקצה את כתובת ה-tunnel הפנויה הבאה ומייצר עבורכם את זוג המפתחות. כל שורת לקוח מציגה קוד QR וקובץ .conf להורדה.
התקינו את אפליקציית WireGuard הרשמית בטלפון, בחרו באפשרות להוסיף tunnel מקוד QR, וסרקו את הקוד שמופיע על המסך שלכם. ה-tunnel יופיע תחת השם שהקלדתם. הפעילו אותו, ושורת הלקוח בממשק תתחיל להציג מוני תעבורה וזמן handshake אחרון. ברגע שהטלפון מחובר ל-tunnel, הוא יכול להגיע לשירותים שלא פרסמתם לאינטרנט; כך טלפון יכול להמשיך להעלות קבצים ל-שרת תמונות בניהול עצמי מכל מקום, מבלי שלשרת יהיה פורט אחד פתוח לעולם. אותו טריק עובד גם עבור מדיה, ו-ספריית Jellyfin שעוצבה כספריית וידאו משנות ה-90 היא דבר נעים לגלישה מחדר מלון, בעוד היא נשארת פרטית בדיוק כפי שהייתה ב-LAN הביתי שלכם. התראות עובדות בכיוון ההפוך על גבי אותו tunnel, שכן שרת ntfy בניהול עצמי יכול לדחוף הודעה לטלפון ברגע שמשימת גיבוי נכשלת, מבלי לענות מעולם לבקשה מהאינטרנט הציבורי.
לקוח שלא מציג handshake לאחר הפעלתו אינו מגיע לשרת כלל. זה מצביע על בעיה בפורט UDP 51820, ב-firewall של ספק השירות או בכתובת ה-endpoint שמוטמעת בתוך ה-config. לקוח שמציג handshake אך ללא גישה לאינטרנט מצביע על בעיית forwarding או DNS.
במחשב שולחני, הורידו את קובץ ה-.conf וייבאו אותו לתוך לקוח ה-WireGuard במקום להקליד אותו מחדש. המפתח הפרטי בקובץ זה נוצר פעם אחת ומוצג פעם אחת. התייחסו לקובץ זה כפי שאתם מתייחסים למפתח פרטי של SSH.
מתי כדאי לעבור משימוש בממשק גרפי
wg-easy הוא הכלי המתאים כל עוד המשתמשים שלכם הם אנשים ומכשירים ניידים. הממשק הגרפי מהיר יותר מעריכת קובצי תצורה, וביטול גישה למכשיר שאבד מתבצע בלחיצה אחת.
אתם תיתקלו במגבלות הכלי כאשר תזדקקו להגדרה שהממשק אינו תומך בה. ניתוב Site-to-site, שבו ה-AllowedIPs של עמית (peer) מכסה תת-רשת מרוחקת שלמה במקום כתובת בודדת, הוא בדרך כלל המחסום הראשון. מנהרות מפוצלות (split tunnels) עם חוקי ניתוב פר-עמית, או תצורה שנוצרת על ידי כלי ה-provisioning שלכם, הם השלב הבא. בנקודה זו, הגדרה ידנית אינה קשה יותר, היא פשוט שונה, ו-המדריך הבסיסי ל-WireGuard מציג את אותה מנהרה שנבנית מ-wg0.conf. אם אתם מעדיפים להפסיק להריץ את ה-control plane בעצמכם, השוואה בין WireGuard ל-Tailscale מכסה את האפשרות המנוהלת. האם מדובר בעסקה משתלמת תלוי במה ששרת התיאום יכול להגיע אליו בפועל, ומומלץ לקרוא את מודל האמון של Tailscale לפני שאתם מוסרים לו את הרשת שלכם. עלות היא בדרך כלל השאלה הבאה, ו-מה כוללת התוכנית החינמית של Tailscale מוגבלת לעד שישה משתמשים ללא עלות, לשימוש לא-מסחרי בלבד, כך שמשק בית אינו משלם דבר בעוד שצוות עסק קטן אינו זכאי לכך ללא קשר למספר המשתמשים. מעבר לנקודה זו, החיוב מבוסס על מספר משתמשים ולא על מכשירים, מה שיוצר מבנה עלות שונה מזה של VPS שעבורו אתם כבר משלמים, לכן עלויות Tailscale לאחר חריגה מהתוכנית החינמית הוא הנתון שיש לבדוק לפני העברת צוות. למנהרה המלאה שבניתם יש שקול ישיר שם, שכן הגדרת ה-VPS כ-exit node ב-Tailscale מעניקה לכם את אותו ניתוב החוצה דרך השרת, באישור מתוך ה-admin console במקום בכתיבה ידנית לכל קובץ תצורה של לקוח. גם למחסום תת-הרשת יש פתרון שקול, כיוון ש-פרסום רשת פרטית שלמה מה-VPS מעביר את הרשת הזו לכל מכשיר ב-tailnet ללא צורך בעריכת ה-AllowedIPs לכל עמית, מה שהוציא אתכם מהשימוש בממשק הגרפי מלכתחילה. אם אתם מעוניינים בלוח הבקרה ובניתוב ה-mesh האוטומטי אך לא בשרת תיאום של גורם חיצוני, הרצת שרת NetBird עצמאי על VPS שומרת את ה-control plane על חומרה שבבעלותכם, במחיר של הגדרות DNS ו-TLS ש-wg-easy מעולם לא דרש מכם.
אם תחביר ה-compose לעיל היה החלק הלא מוכר ולא ה-WireGuard עצמו, יסודות Docker Compose על גבי VPS מסביר את מבנה הקובץ ואת הפקודות היומיומיות.
FAQ
מדוע wg-easy מתעלם מהמשתנים WG_HOST ו-PASSWORD_HASH שלי?
משתנים אלו שייכים לגרסה 14 של wg-easy. גרסה 15 היא כתיבה מחדש של התוכנה, והמפתחים העבירו כמעט את כל התצורה ללוח הניהול בממשק האינטרנט. המכולה אינה קוראת את המשתנים הללו, לכן היא עולה כרגיל ומבקשת ממך ליצור חשבון מנהל בביקור הראשון. הגדר את כתובת המארח (host) עבור הלקוחות בדף ההגדרה הראשונית במקום זאת.
האם אני זקוק ל-SYS_MODULE אם ה-kernel שלי כבר כולל את WireGuard?
לא. ה-SYS_MODULE וה-mount של /lib/modules קיימים כדי שהמכולה תוכל לטעון את המודול כאשר המארח לא עשה זאת. במארח שבו sudo modprobe wireguard מצליח כבר כעת, היכולת הזו אינה בשימוש. הסרתה היא צעד מומלץ להקשחת אבטחה, אך NET_ADMIN עדיין נדרש בכל מקרה.
הלקוח מתחבר אך אין אינטרנט. מה הבעיה?
לחיצת יד (handshake) ללא תעבורה מעידה כמעט תמיד על בעיית ניתוב (forwarding). ודא ש-net.ipv4.ip_forward=1 ו-net.ipv4.conf.all.src_valid_mark=1 עדיין קיימים בקובץ ה-compose, שכן עותק שנערך ידנית נוטה לאבד אותם. אם הניתוב מופעל, בדוק את שרת ה-DNS שקיבל הלקוח. מנהרה ששולחת את כל התעבורה דרך ה-VPN אך מצביעה על שרת DNS שהיא כבר לא יכולה להגיע אליו, תיראה בדפדפן בדיוק כמו חיבור תקול.
כיצד אוכל לגבות את הלקוחות שלי?
הכל נמצא בתוך ה-volume בעל השם etc_wireguard. בגרסה 15 המשמעות היא מסד נתונים מסוג SQLite בנתיב /etc/wireguard/wg-easy.db בתוך המכולה. התיעוד של גרסה 15 אינו מתאר תכונת גיבוי או ייצוא, לכן יש לגבות את ה-volume עצמו: הרץ את docker compose down, העתק את תוכן ה-volume למקום מחוץ לשרת, ולאחר מכן החזר את ה-stack לפעולה עם docker compose up -d. בצע זאת לפני כל שדרוג. הקובץ wg0.json שמדריכים ישנים מציינים שייך ל-wg-easy 14. זהו הקובץ שיוצא על ידי כפתור הגיבוי בגרסה 14, ובגרסה 15 השימוש היחיד שלו הוא כקובץ שמעלים באשף ההגדרה בעת הגירה מהתקנה ישנה.
האם ניתן להריץ את wg-easy מאחורי reverse proxy?
כן. הצב את ה-proxy לפני פורט ממשק האינטרנט, בצע שם TLS termination, והשאר את INSECURE ללא הגדרה. המכולה מקבלת את ה-HTTP הפשוט מה-proxy כפי שהוא, והדוגמאות הרשמיות עבור Caddy ו-Traefik אינן מגדירות את המשתנה INSECURE כלל. מכיוון שהדפדפן מדבר HTTPS מול ה-proxy, תרצה ש-cookie של הסשן ישמור על דגל ה-Secure שלו, שכן זהו הדבר היחיד ש-INSECURE=true מסיר. השאר את פורט UDP 51820 חשוף ישירות, מכיוון שתעבורת ה-VPN היא מסוג UDP ואינה עוברת דרך proxy של HTTP.