תיעוד 165

קובץ תצורה

הערה

Quick Tunnels לא זקוקים לקובץ תצורה.

מנהרות שמנוהלות מקומית רצות כמופע של cloudflared במחשב שלך. אפשר להגדיר מאפיינים של cloudflared על ידי שינוי פרמטרים של שורת הפקודה או על ידי עריכת קובץ התצורה של המנהרה.

ה-CLI מספק דרך מהירה לטפל בתצורות אם מחברים שירות יחיד דרך cloudflared. קובץ התצורה של המנהרה שימושי אם מחברים כמה שירותים וצריך להגדיר מאפיינים או חריגות למקורות מסוימים. בקובץ התצורה אפשר להגדיר מאפיינים ברמה העליונה עבור מופע cloudflared, וגם מאפיינים ספציפיים למקור. לרשימה מלאה של אפשרויות התצורה, הקלד cloudflared tunnel help בטרמינל.

בהיעדר קובץ תצורה, cloudflared יתווך תעבורה יוצאת דרך פורט 8080.

#מבנה הקובץ עבור יישומים שפורסמו

אם חושפים שירותים מקומיים לאינטרנט, אפשר לשייך שם מארח ציבורי לכל שירות:

tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551ef
credentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.json

ingress:
  - hostname: gitlab.widgetcorp.tech
    service: http://localhost:80
  - hostname: gitlab-ssh.widgetcorp.tech
    service: ssh://localhost:22
  - service: http_status:404

קבצי תצורה שמכילים כללי ingress חייבים תמיד לכלול כלל catch-all שמסיים את הקובץ. בדוגמה זו, cloudflared יגיב עם קוד מצב 404 כאשר הבקשה לא תואמת לאף אחד משמות המארח הקודמים.

#איך תעבורה מותאמת

בגרסה 2026.10.0 של cloudflared ואילך, אפשר לנרמל כתובות URL לפני התאמה לכללי ingress. זה משפר את האבטחה עבור כללים שדורשים אימות JWT של Cloudflare Access.

הנרמול מסיר מקטעי נקודה (. ו-..) לפי RFC 3986. הוא גם ממיר לוכסנים הפוכים ללוכסנים וממזג לוכסנים חוזרים.

הנרמול כבוי כברירת מחדל בגרסה 2026.10.0. כדי להפעיל אותו, הגדר --disable-path-normalization=false לפני run.

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

הדוגמאות האלה חלות כאשר הנרמול פועל ולמנהרה יש כללים שדורשים אימות Access. הנתיבים הנכנסים מוצגים כפי ש-cloudflared קיבל אותם:

נתיב נכנס	נתיב שמשמש להתאמת ingress	נתיב שנשלח למקור
`/hello/../path`	`/path`	`/hello/../path`
`/hello//path`	`/hello/path`	`/hello//path`
`/hello\path`	`/hello/path`	`/hello\path`

הנה דוגמה לקובץ תצורה שמגדיר כמה כללים:

tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551ef
credentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.json

ingress:
  # Rules map traffic from a hostname to a local service:
  - hostname: example.com
    service: https://localhost:8000
  # Rules can match the request's path to a regular expression:
  - hostname: static.example.com
    path: \.(jpg|png|css|js)$
    service: https://localhost:8001
  # Rules can match the request's hostname to a wildcard character:
  - hostname: "*.example.com"
    service: https://localhost:8002
  # An example of a catch-all rule:
  - service: https://localhost:8003

#תווים כלליים

אפשר להשתמש בתווים כלליים כדי להתאים תעבורה לכמה תת-דומיינים. לדוגמה, אם מגדירים את המפתח hostname ל-*.example.com, גם alpha.example.com וגם beta.example.com ינתבו תעבורה למקור. cloudflared לא תומך בתווים כלליים באמצע שם המארח, כמו test.*.example.com.

אפשר גם להזין ביטויים רגולריים עבור המפתח path. לדוגמה, אם hostname הוא static.example.com ו-path הוא \.(jpg|png|css|js)$, כתובות URL תואמות יכולות לכלול את https://static.example.com/data.js, את http://static.example.com/images/photo.jpg, וכן הלאה. Cloudflare מנתח את הביטוי הרגולרי של הנתיב באמצעות חבילת syntax של Go.

העברת נתיב

cloudflared מתאים נתיבי בקשה כדי להעריך כללים, אבל הוא מעביר את נתיב הבקשה המלא לשירות בלי לשנות אותו או להסיר ממנו חלקים. נרמול URL להתאמת ingress לא משנה את ההתנהגות הזו.

לדוגמה, אם כלל ingress תואם ל-path: /api, בקשה אל https://example.com/api/users נשלחת לשירות כ-http://localhost:8000/api/users.

אם היישום דורש הסרת נתיב או שכתוב URL, אפשר לשכתב את ה-URL בקצה של Cloudflare באמצעות URL Rewrite Rules, או להעביר תעבורה מ-cloudflared אל פרוקסי הפוך מקומי (כמו Nginx או Traefik) שמוגדר להסיר קידומות נתיב לפני שהתעבורה מגיעה ליישום.

#שירותים

בנוסף ל-HTTP, cloudflared תומך בפרוטוקולים כמו SSH, RDP, שירותי TCP שרירותיים, ושקעי Unix. אפשר גם לנתב תעבורה אל שרת הבדיקה המובנה hello_world או להגיב לתעבורה עם מצב HTTP. לרשימה מלאה של סוגי שירות נתמכים, ראה פרוטוקולים ליישומים שפורסמו.

tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551ef
credentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.json

ingress:
  # Example of a request over TCP:
  - hostname: example.com
    service: tcp://localhost:8000
  # Example of an HTTP request over a Unix socket:
  - hostname: staging.example.com
    service: unix:/home/production/echo.sock
  # Example of a request mapping to the Hello World test server:
  - hostname: test.example.com
    service: hello_world
  # Example of a rule responding to traffic with an HTTP status:
  - service: http_status:404

#תצורת מקור

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

בדוגמה הבאה, התצורה ברמה העליונה connectTimeout: 30s קובעת זמן קצוב לחיבור של 30 שניות עבור כל השירותים בתוך אותו מופע של cloudflared. כלל ה-ingress עבור service: localhost:8002 מגדיר אז חריגה לתצורה ברמה העליונה על ידי הגדרת connectTimeout עבור השירות הזה ל-10s. זמן הקצוב לחיבור של 30 שניות עדיין חל על כל שאר השירותים.

tunnel: 6ff42ae2-765d-4adf-8112-31c55c1551ef
credentials-file: /root/.cloudflared/6ff42ae2-765d-4adf-8112-31c55c1551ef.json
originRequest: # Top-level configuration
  connectTimeout: 30s

ingress:
  # The localhost:8000 service inherits all root-level configuration.
  # In other words, it will use a connectTimeout of 30 seconds.
  - hostname: example.com
    service: localhost:8000
  - hostname: example2.com
    service: localhost:8001
  # The localhost:8002 service overrides some root-level config.
  - service: localhost:8002
    originRequest:
      connectTimeout: 10s
      disableChunkedEncoding: true
  # Some built-in services such as `http_status` do not use any configuration.
  # The service below will simply respond with HTTP 404.
  - service: http_status:404

#אימות כללי ingress

כדי לאמת את כללי ה-ingress בקובץ התצורה, הרץ:

cloudflared tunnel ingress validate

זה יוודא שקבוצת כללי ה-ingress שצוינה בקובץ התצורה תקינה.

#בדיקת כללי ingress

כדי לוודא ש-cloudflared יתווך את התעבורה הנכונה לשירות המקומי הנכון, השתמש ב-cloudflared tunnel ingress rule. הפקודה בודקת כתובת URL מול כל כלל, מהראשון עד האחרון, ומציגה את הכלל הראשון שתואם. לדוגמה:

cloudflared tunnel ingress rule https://foo.example.com

Using rules from /usr/local/etc/cloudflared/config.yml
Matched rule #3
	hostname: *.example.com
	service: https://localhost:8000

#עדכון קובץ תצורה

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

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

ה-cloudflared שלך ירוץ עכשיו עם הגרסה המעודכנת של קובץ התצורה.

טיפול בתעבורה

כאשר המופע הראשון של cloudflared נעצר, בקשות HTTP ממושכות (לדוגמה, Websocket) וחיבורי TCP (לדוגמה, SSH) יושמטו. גם זרימות UDP יושמטו, כי הן ממודלות על בסיס זמני קצוב. כאשר העותק החדש מתחבר, הוא יטפל בכל התעבורה החדשה, כולל בקשות HTTP חדשות, חיבורי TCP וזרימות UDP.