SSD Nodes Learn Hosting plans →
מדריכים Matt Connorמאת Matt Connor · עודכן 2026-11-20

הקמת מקצר קישורים עצמאי עם Shlink ו-Docker Compose

למדו כיצד להריץ שרת קיצור קישורים אישי ב-VPS באמצעות Shlink ו-Docker Compose. המדריך כולל הגדרות DNS, מסד נתונים Postgres, הפקת מפתחות API, הצגת סטטיסטיקות ושימוש ב-QR.

מה אתם בונים

מקצר קישורים בניהול עצמי הוא שרת קטן שהופך קישור ארוך לקישור קצר שבבעלותכם, וסופר כל לחיצה עליו. Shlink הוא הבחירה המומלצת: הוא קוד פתוח, מופץ כ־Docker image, ומבצע את כל העבודה במכולה אחת בתוספת מסד נתונים. מדריך זה יתקין אותו על גבי VPS תחת שם מתחם קצר, עם HTTPS, מפתח API, קודי QR וסטטיסטיקות לחיצות.

שני רכיבים גורמים לו להרגיש כמו שירות קיצור מסחרי. שרת ה־API מבצע את ההפניות ומחזיק את הנתונים. ה־web client הוא יישום סטטי נפרד שמתקשר עם ה־API מתוך הדפדפן שלכם. ניתן להריץ את שניהם, או להריץ רק את ה־API ולנהל אותו משורת הפקודה.

מספרי הגרסאות כאן הם העדכניים נכון ל-19 בנובמבר 2026: Shlink 5.1.8 ו-shlink-web-client 4.9.0.

הפנו תחילה דומיין קצר לשרת

הדומיין הוא המוצר. s.example.com/abc123 הוא הקישור שהמשתמשים רואים, לכן בחרו שם קצר והחליטו עליו לפני שתתקינו דבר מה. Shlink משייכת כל כתובת מקוצרת לדומיין ברירת המחדל או לדומיין שהוקצה במפורש; שינוי שלו בשלב מאוחר יותר מחייב להשאיר את הדומיין הישן מופנה ל-Shlink כדי שהקישורים שכבר הפצתם ימשיכו לעבוד.

צרו רשומת DNS A אחת עבור הדומיין הקצר, המצביעה על כתובת ה-IPv4 הציבורית של ה-VPS שלכם. הוסיפו גם רשומת AAAA אם לשרת יש IPv6. לאחר מכן, ודאו שהשם מתרגם לכתובת (resolves) לפני שתמשיכו.

dig +short s.example.com A

הפלט חייב להיות הכתובת של השרת שלכם. אם הפלט ריק, הרשומה טרם הופצה (propagated), וכל שלב בהמשך ייכשל בצורה לא ברורה, כיוון שלא ניתן להנפיק תעודת TLS (אבטחת שכבת תעבורה) עבור שם שאינו מתרגם לכתובת.

קובץ ה-compose

Shlink זקוק למסד נתונים. SQLite מתאים לבדיקות, אך Postgres הוא הבחירה הנכונה לכל שימוש ארוך טווח, כיוון ששורות הביקורים מצטברות ו-Postgres מנהל אינדקסים וכתיבה במקביל בצורה טובה יותר. יש להציב זאת ב-/opt/shlink/compose.yaml.

services:
  shlink:
    image: shlinkio/shlink:stable
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      DEFAULT_DOMAIN: s.example.com
      IS_HTTPS_ENABLED: "true"
      DB_DRIVER: postgres
      DB_HOST: database
      DB_NAME: shlink
      DB_USER: shlink
      DB_PASSWORD: ${DB_PASSWORD}
    depends_on:
      - database

  database:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: shlink
      POSTGRES_USER: shlink
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - shlink_db:/var/lib/postgresql/data

  web-client:
    image: shlinkio/shlink-web-client:stable
    restart: unless-stopped
    ports:
      - "127.0.0.1:8081:8080"

volumes:
  shlink_db:

שני הפורטים המפורסמים נקשרים ל-127.0.0.1, לכן דבר אינו נגיש מהאינטרנט עד להגדרת ה-reverse proxy בסעיף הבא. Docker כותב חוקי ניתוב משלו לפני ה-firewall של המארח, מה שאומר ששורה מסוג 8080:8080 פשוטה תחשוף את היישום גם בשרת שנראה כאילו ה-firewall שלו סגור. קישור לכתובת ה-loopback מונע זאת. אותה תבנית תקפה לכל יישום שתריצו בדרך זו, והיא מוסברת בפירוט רב יותר ב-מדריך ל-Docker Compose ב-VPS.

סיסמת מסד הנתונים מגיעה מקובץ .env הנמצא לצד קובץ ה-compose, כך שהיא לעולם אינה נשמרת בתוך ה-YAML.

sudo mkdir -p /opt/shlink
printf 'DB_PASSWORD=%s\n' "$(openssl rand -base64 24)" | sudo tee /opt/shlink/.env
sudo chmod 600 /opt/shlink/.env

הפעילו את השירות ועקבו אחר עליית ה-API.

cd /opt/shlink
sudo docker compose up -d
sudo docker compose logs -f shlink

ההרצה הראשונה מבצעת את המיגרציות של מסד הנתונים, לכן היא אורכת זמן רב יותר מהרצות הבאות. כשהתהליך מתייצב, בדקו שהשירות משיב מקומית.

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/rest/health

קבלת 200 משמעותה שה-API פעיל וחיבור מסד הנתונים תקין. קבלת 503 משמעותה ש-Shlink רץ אך בדיקת מסד הנתונים שלו נכשלה. ה-endpoint של ה-health משיב 503 בכל שגיאת מסד נתונים, ולעולם לא 500. אם curl מדפיס 000 במקום זאת, הוא לא קיבל קוד תגובת HTTP; בדקו את הקישוריות ואת הלוגים לעיל לפני שתסיקו שהמכולה נעצרה או מבצעת הפעלה מחדש. אם הלוגים מציגים שגיאת אימות מול מסד הנתונים, ודאו שה-DB_PASSWORD ב-.env תואם למה שהוגדר בעת יצירת Postgres, כיוון שתמונת ה-Postgres קוראת את POSTGRES_PASSWORD רק בעת אתחול ספריית נתונים ריקה. עריכת .env בשלב מאוחר יותר אינה משנה את סיסמת מסד הנתונים הקיימת; עליכם לשנות גם את סיסמת ה-role של מסד הנתונים, או להחזיר את הסיסמה הקיימת ל-.env.

סיום HTTPS לפני השירות

Shlink מגיש HTTP רגיל בפורט 8080. תפקידו של ה-TLS הוא ב-reverse proxy, וההגדרה החשובה ביותר היא העברת שם ה-host המקורי. Shlink משתמש ב-header מסוג Host כדי לחפש קודים מקוצרים, עם מנגנון fallback להתאמת קישורים בדומיין ברירת המחדל. לכן, host שעבר כתיבה מחדש עלול לגרום לבחירת הקישור השגוי או להחזרת שגיאת 404 עבור קוד שקיים רק בדומיין אחר.

server {
    server_name s.example.com;
    listen 80;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

לאחר מכן, הנפיקו את התעודה. המדריך המלא, כולל טיימר החידוש, נמצא ב-מדריך Certbot עבור nginx ב-Ubuntu 24.04.

sudo certbot --nginx -d s.example.com

ההגדרה IS_HTTPS_ENABLED: "true" בקובץ ה-compose היא זו שגורמת ל-Shlink להדפיס https:// בכתובות ה-URL המקוצרות שהוא מחזיר. היא אינה מפעילה TLS בעצמה. השאירו אותה כ-false מאחורי proxy מסוג HTTPS, כך שכל קישור שה-API מחזיר יהיה קישור http://, מה שחוסך round trip מיותר ומונע תצוגה שגויה ב-web client.

יצירת מפתח API

ממשק הניהול (management API) דורש מפתח; נקודת הקצה לבדיקת תקינות (health endpoint) פתוחה לציבור. צרו מפתח באמצעות ה-CLI בתוך המכולה.

sudo docker compose exec shlink shlink api-key:generate --name "web client"

הפקודה מציגה את המפתח פעם אחת בלבד. העתיקו אותו כעת, כיוון שהוא נשמר בצורה מוצפנת (hashed) ולא ניתן להציגו שוב. הפקודה shlink api-key:list מציגה את שמות המפתחות ואת הסטטוס שלהם (פעיל או לא), אך לעולם לא את המפתח עצמו. ניתן לבטל מפתח באמצעות shlink api-key:disable ושם המפתח.

שלחו את המפתח בתוך כותרת (header) מסוג X-Api-Key עבור קריאות ניהול ב-REST.

curl -H "X-Api-Key: YOUR_KEY" https://s.example.com/rest/v3/short-urls

אובייקט JSON עם מפתח shortUrls מעיד על כך שהמפתח תקין. קוד שגיאה 401 שבו ה-type הוא https://shlink.io/api/error/invalid-api-key, עם הכותרת Invalid API key, מעיד על כך שהמפתח שגוי, מושבת או שפג תוקפו.

יצירת קישורים מקוצרים משורת הפקודה

ממשק שורת הפקודה (CLI) הוא הדרך המהירה ביותר ליצירת קישורים, והוא מתאים במיוחד לשימוש בתוך סקריפטים.

sudo docker compose exec shlink shlink short-url:create https://example.com/a/very/long/path
sudo docker compose exec shlink shlink short-url:create https://example.com/docs --custom-slug docs --tag reference

--custom-slug מאפשר לכם ליצור קישור קריא במקום קוד שנוצר באופן אקראי. ה־slugs הם ייחודיים לכל דומיין, לכן ניסיון ליצור קישור עם slug שכבר קיים ייכשל, במקום לדרוס את הקישור הקיים ללא התראה. ניתן להשתמש ב---tag שוב ושוב, ותגיות (tags) הן הדרך שבה מקבצים קישורים שעבורם תרצו להפיק נתונים סטטיסטיים משותפים בעתיד.

הציגו את רשימת הקישורים הקיימים, ולאחר מכן בדקו את התעבורה של קישור ספציפי.

sudo docker compose exec shlink shlink short-url:list
sudo docker compose exec shlink shlink short-url:visits docs

short-url:visits מדפיס שורה אחת עבור כל הקלקה, הכוללת את התאריך, ה־referrer וסוכן המשתמש (user agent). העמודות של המדינה והעיר יישארו ריקות אלא אם תגדירו את משתנה הסביבה GEOLITE_LICENSE_KEY, שהוא מפתח MaxMind חינמי שבו Shlink משתמש כדי להוריד את מסד הנתונים GeoLite2. ללא הגדרה זו, הביקורים עדיין יתועדו, אך ללא ציון מיקום גיאוגרפי.

הלקוח מבוסס הדפדפן וקודי QR

הלקוח מבוסס הדפדפן זמין כעת ב-127.0.0.1:8081 ודורש הגדרת proxy משלו, או מנהרת SSH אם אינכם מעוניינים לחשוף אותו לציבור. בטעינה הראשונה, הוא יבקש כתובת URL של השרת ומפתח API. הזינו את https://s.example.com ואת המפתח שיצרתם. הלקוח שומר את שניהם באחסון הדפדפן ופונה ל-API שלכם ישירות, כך ששום מידע לא עובר דרך צד שלישי. הפרדת הממשק מה-API היא תבנית שראוי לשים לב אליה, שכן זו אותה תבנית המאפשרת ל-Halcyon להציג ספריית Jellyfin כחנות השכרת סרטים משנות ה-90 מבלי לשנות את שרת המדיה שמאחוריה.

קודי QR מיוצרים על ידי הלקוח מבוסס הדפדפן, ולא על ידי ה-API. גרסה 5 של Shlink הסירה את הטריק הישן של הוספת /qr-code לכתובת מקוצרת, ולכן כתובת זו אינה מחזירה עוד תמונה. במקום זאת, הלקוח משרטט את הקוד בדפדפן שלכם, ללא פנייה ל-Shlink. פתחו את אפשרות ה-QR code עבור כל קישור ברשימת הכתובות המקוצרות, הגדירו את הגודל, הפורמט והשוליים, והורידו את התוצאה. העלו את רמת תיקון השגיאות (error correction level) עבור קוד שצריך להיסרק גם כשהוא מודפס בקטן או מכוסה חלקית. אותו חלון הגדרות מאפשר גם בחירת צבעים והוספת לוגו.

שמירה על פעילות תקינה

שירות קיצור קישורים עלול להפסיק לעבוד ללא התרעה. הקישורים מפסיקים להפנות ליעדם, והמשתמשים מניחים פשוט שהקישור שבור. הגדירו בדיקת זמינות (uptime check) שמפנה לכתובת מקוצרת פעילה, ולא רק לדף הבית, והגדירו התראה על כל תוצאה שאינה הפניה (redirect). מופע Uptime Kuma בהתקנה עצמית מבצע זאת היטב, ויכול לנטר קוד סטטוס ספציפי.

בצעו גיבוי למסד הנתונים, לא למכולה. פקודה אחת מבצעת dump לנתונים.

sudo docker compose exec -T database pg_dump -U shlink shlink | gzip > shlink-$(date +%F).sql.gz

קובץ זה, יחד עם קובץ ה-compose שלכם ו-.env, מאפשרים לשחזר את כל השירות בשרת חדש. כל יישום על השרת זקוק לגרסת גיבוי משלו. ספריית תמונות היא מקרה מורכב, כיוון ש-PhotoPrism ו-Immich שומרים את הקבצים המקוריים על הדיסק לצד רשומות במסד הנתונים. לכן, ביצוע dump בלבד ישחזר את רשומות מסד הנתונים, אך לא את התמונות עצמן או את הגדרות הקבצים של PhotoPrism. גבו גם את הגדרות PhotoPrism, כולל קובץ ה-settings.yml שמכיל את העדפות ממשק המשתמש, ההורדות והאינדוקס. שדרוגים מתבצעים באמצעות sudo docker compose pull ולאחריו sudo docker compose up -d, ו-Shlink מריץ כל migration חדש בעת העלייה. בצעו את ה-dump לפני ה-pull, כיוון שלא ניתן לבצע rollback ל-migration.

FAQ

מדוע הקישורים הקצרים שלי מחזירים שגיאת 404 לאחר הוספת reverse proxy?

Shlink משווה את הקוד הקצר מול שם המתחם ב־header מסוג Host. אם ה־proxy שולח host שונה, Shlink בודק את שם המתחם הזה ומנסה למצוא התאמה לקישור ב־default-domain; אם לא נמצא קוד באף אחד מהם, המערכת מחזירה 404. הגדירו את proxy_set_header Host $host; בתוך בלוק ה-location של nginx וטענו מחדש את ה-proxy. הקישורים יתחילו לעבוד מיד, ללא צורך באתחול המכולה.

האם אני חייב להשתמש ב-Postgres, או ש-SQLite מספיק?

SQLite מתאים לבדיקה ראשונית של Shlink ואינו דורש מכולה נוספת. עברו ל-Postgres לפני פרסום קישורים חשובים, כיוון ששורות הביקורים גדלות עם כל הקלקה ו-SQLite מבצע סריאליזציה לכתיבה. מעבר מאוחר יותר ידרוש ייצוא וייבוא מחדש של הקישורים שלכם, לכן בחירה ב-Postgres מלכתחילה תחסוך לכם את תהליך ההגירה.

האם ניתן לשחזר מפתח API ששכחתי להעתיק?

לא. Shlink שומר hash של המפתח, לכן api-key:list מציג שמות וסטטוסים אך לעולם לא את ערך המפתח עצמו. צרו מפתח חלופי באמצעות shlink api-key:generate, הדביקו אותו בלקוח ה-web, ולאחר מכן השביתו את המפתח הישן בעזרת shlink api-key:disable כדי להפסיק את פעולתו.

מדוע עמודות המדינה בסטטיסטיקת הביקורים ריקות?

מיקום גיאוגרפי דורש את מסד הנתונים GeoLite2, ש-Shlink מוריד רק כאשר מספקים לו GEOLITE_LICENSE_KEY. המפתח ניתן בחינם מ-MaxMind. הוסיפו אותו לסעיף ה-environment, צרו מחדש את המכולה, וביקורים חדשים ימוקמו גיאוגרפית. ביקורים שנרשמו לפני כן יישארו ריקים עד להרצת shlink visit:locate.

שמרו על שם המתחם והעבירו את הנתונים. בצעו dump למסד הנתונים בעזרת pg_dump, העתיקו את ה-dump, את קובץ ה-compose ואת .env לשרת החדש, הפעילו רק את מסד הנתונים, שחזרו את ה-dump למסד הנתונים הריק, ולאחר מכן הפעילו את Shlink ואת לקוח ה-web לפני הגעת תעבורה אמיתית. שנו את רשומת ה-DNS בסוף התהליך. הקודים הקצרים והיסטוריית הביקורים שלהם יישמרו, כיוון שהכול נמצא בתוך מסד הנתונים.

האם המאמר הזה היה מועיל?

#shlink#url-shortener#self-hosting#docker#postgres