📘 תיעוד 75

פריסה ותפעול של Claude apps gateway

רשום את השער (gateway) מול ספק הזהויות שלך (IdP), בנה את הקונטיינר, פרוס על גבי Kubernetes או Cloud Run, ותפעל אותו: בדיקות תקינות (health checks), סבב סודות (secret rotation), שדרוגים ואבטחה.

דף זה מכסה את הצד התפעולי של הפעלת Claude apps gateway: רישום לקוח OAuth בספק הזהויות שלך (IdP), פריסת השער כקונטיינר, והפעלתו השוטפת יום-יום. לכל אפשרות בקובץ gateway.yaml שהשער קורא בעת האתחול, ראה את מדריך התצורה.

פריסה בסביבת ייצור (production) מתבצעת לפי ארבעה שלבים לפי הסדר, והסעיפים שלהלן תואמים להם. בשני השלבים הראשונים מתקבלות ההחלטות; שני השלבים הבאים הם חומרי עיון לעיון לאחר שהשער כבר פועל.

1. הגדרת ספק הזהויות שלך: רשום את לקוח ה-OAuth ובדוק את ההערות עבור Okta, Entra ו-Google
2. פריסת השער: בנה תמונת קונטיינר מקובעת גרסה (pinned) והרץ אותה על גבי Kubernetes, Cloud Run, או הפלטפורמה שלך. סעיף זה מכסה גם החלטות לגבי עלויות, מעקף (bypass), ריבוי שערים ו-serverless
3. הגדרת תפעול: יומנים (logs), בדיקות תקינות (health probes), התנהגות בעת השבתה, סבב סודות ושדרוגים. חומר עיון בעת הגדרת ניטור ונוהלי תפעול (runbooks)
4. סקירת מערך האבטחה: אילו נתונים זורמים ולאן, מודל האיומים, ותשובות לתאימות (compliance). חומר עיון עבור סקירת אבטחה

אם כניסה (sign-in) או אתחול (boot) נכשלים לאורך הדרך, עבור ישירות אל פתרון בעיות, המסודר לפי השגיאה שמופיעה.

הערה: פרוס ברשת הפרטית שלך. Claude Code מתחבר אך ורק לשער שכתובתו פרטית. זהו מנגנון הגנה של אבטחה, מכיוון ששער מהימן (trusted) יכול להפיץ הגדרות שמריצות פקודות במחשבי מפתחים. הצב את השער שאתה פורס מאחורי נתב עומסים פנימי (internal load balancer) או VPN, והענק לו שם מארח (hostname) שנפתר לכתובות IP פרטיות בלבד.

#הגדרת ספק הזהויות (Identity provider setup)

רשום יישום אינטרנט חסוי (confidential web application) מסוג OAuth/OpenID Connect (OIDC) עם redirect URI יחיד, https://<gateway>/oauth/callback, והקצה אותו למשתמשים או לקבוצות שאמורה להיות להם גישה לשער.

כל IdP התואם ל-OIDC יעבוד: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate, ואחרים. ספק הזהויות חייב לעמוד בשלוש דרישות:

• מגיש את /.well-known/openid-configuration, מעל HTTPS בסביבת ייצור; השער מקבל מנפיק ב-http://, ומנפיק ב-loopback דורש בנוסף את CLAUDE_GATEWAY_ALLOW_LOOPBACK=1
• תומך ב-authorization-code flow. מנגנון PKCE (Proof Key for Code Exchange) מופעל כברירת מחדל; השבת אותו באמצעות oidc.use_pkce: false עבור ספקי זהויות שאינם תומכים בו
• מחזיר email ולפי בחירה groups בתוך ה-id_token, או מגיש אותם מנקודת הקצה userinfo כאשר מוגדר oidc.userinfo_fallback: true

עבור PKI פרטי, הגדר את oidc.ca_cert_pem.

מספר ספקים מטפלים בטענות (claims) של דוא"ל וקבוצות באופן שונה:

• Okta: שרת ההרשאות הארגוני (org authorization server) בכתובת https://example.okta.com מחזיר id_token רזה שאינו כולל את email ואת groups, לכן הגדר oidc.userinfo_fallback: true בכל פעם שאתה משתמש בו בתור issuer. שרת הרשאות מותאם אישית (custom authorization server) כגון https://example.okta.com/oauth2/default שכולל את email ואת groups (באופן אופציונלי) בתוך ה-id_token, פולט אותם ישירות ואינו זקוק לנתיב גיבוי (fallback). חברת Okta פולטת את groups רק כאשר תחום ההרשאה (scope) של groups מבוקש ב-oidc.scopes ומסנן טענות הקבוצות של האפליקציה מאפשר זאת; userinfo_fallback אינו יכול למלא טענה שלא התבקשה מספק הזהויות.
• Microsoft Entra ID: מנפיק issuer = https://login.microsoftonline.com/<tenant-id>/v2.0. חברת Entra פולטת מזהי אובייקט (Object IDs) של קבוצות ולא שמות, לכן השתמש בערכי ה-GUID בתוך managed.policies.match.groups, או השתמש ב-App Roles עבור שמות קריאים לאדם. אם ה-tenant שלך פולט תפקידים תחת roles במקום groups, הגדר oidc.groups_claim: roles.
• Google Workspace: מנפיק issuer = https://accounts.google.com. ה-id_token של Google אינו מכיל קבוצות. כדי להשתמש ב-allowed_groups או ב-managed.policies מבוססי קבוצות כאשר Google משמש כ-IdP, הגדר את oidc.google_groups, אשר בודק את הקבוצות של כל משתמש דרך ה-Admin SDK Directory API באמצעות חשבון שירות (service account) עם האצלת סמכויות לכלל הדומיין (domain-wide delegation). ללא זאת, השתמש ב-oidc.allowed_email_domains להגבלת חברות וב-managed.policies.match.email_domain להקצאת מדיניות. כמו כן, Google מתעלמת מטווח ההרשאה הסטנדרטי offline_access. לקבלת אסימוני רענון (refresh tokens), הגדר oidc.scopes: [openid, profile, email] וכן oidc.extra_auth_params: { access_type: offline, prompt: consent }.

אזהרה: אסימוני רענון (refresh tokens) מאפשרים לשער לחדש את ההפעלה (session) של המפתח באופן שקט, מבלי לשלוח את המפתח שוב לדפדפן. הם גם מניעים ביטול הרשאות (deprovisioning), מכיוון שכאשר ספק הזהויות משבית משתמש, הריענון הבא נכשל וההפעלה מסתיימת בתוך ttl_hours. השער מבקש offline_access כברירת מחדל כדי לקבל אסימון רענון. אם ספק הזהויות שלך דורש הסכמה מפורשת עבור גישה לא מקוונת, הגדר את לקוח ה-OAuth לאפשר זאת.

אם ספק הזהויות שלך אינו יכול להנפיק אסימוני רענון כלל, השער עדיין פועל, אך אין חידוש שקט, ולכן מפתחים מבצעים מחדש את ההתחברות בדפדפן כאשר תוקף ההפעלה שלהם פג. כדי למנוע מזה לקרות בכל שעה, העלה את session.ttl_hours ל-8 או ל-12. הפשרה היא השהיה בביטול ההרשאות (deprovisioning latency), מכיוון שללא אסימוני רענון, משתמש שהושבת שומר על גישה עד שחולף ה-TTL הארוך יותר.

#פריסה (Deployment)

השער הוא קובץ בינארי יחיד וחסר מצב (stateless) של Linux המתאם פעולות דרך Postgres, לכן פרוס אותו כפי שאתה פורס כל שירות חסר מצב אחר בסביבה שלך. שמור אותו בתוך הרשת שלך, במקום שבו המפתחים וספק הזהויות (IdP) שלך יכולים לגשת אליו דרך HTTPS, והתייחס אליו כמו אל כל שירות המחזיק באישורי גישה (credentials) של סביבת ייצור.

מספר החלטות מעצבות את הפריסה מעבר למקום שבו היא פועלת:

• עלות: אין רישיון נפרד או עמלה לפי מושב (per-seat). השער הוא חלק מהקובץ הבינארי claude, כך שאתה משלם על הסקת מודלים (inference) דרך ההתחייבות הקיימת שלך, בתוספת משאבי המחשוב שעליהם הוא רץ.
• מעקף (Bypass): השער אינו אוכף שהנתיב היחיד למודל יעבור דרכו. מפתח שיש לו אישורי גישה משלו עדיין יכול לקרוא ישירות לספק, ולכן סגירת הנתיב הזה היא החלטת מדיניות רשת, למשל חסימת יציאה (egress) אל api.anthropic.com למעט מהשער. חסימת תעבורת יציאה זו שוברת גם את בדיקת בטיחות הדומיין של WebFetch, אשר קוראת ל-api.anthropic.com ממחשבו של כל מפתח. הגדר skipWebFetchPreflight: true במדיניות המנוהלת (managed policy) כדי להשבית אותה.
• מספר שערים: כל שער הוא פריסה נפרדת עם תצורה משלו, וה-CLI שומר אמון ואישורי גישה עבור כל שם מארח של שער בנפרד, כך שצוותים יכולים להשתמש בשערים שונים ללא התנגשות. כדי לשרת מספר מנפיקי OIDC, הרץ מופעים נפרדים.
• Serverless: שירות Cloud Run עובד אם מגדירים min-instances: 1 כדי למנוע גילוי OIDC קר. Lambda ו-Cloud Functions אינם עובדים, מכיוון שהשער הוא שרת HTTP הפועל ברציפות לאורך זמן.

כל טופולוגיית ייצור כאן מציבה פרוקסי בשכבה 7 (L7 proxy), כגון Ingress, חזית השירות של Cloud Run, או ALB, לפני עותקים משוכפלים (replicas) הפועלים ב-HTTP פשוט. הגדר את listen.trusted_proxies לטווחי המקור של הפרוקסי כדי שהשער יקרא כתובות IP של לקוחות מתוך X-Forwarded-For. השער מכבד את הכותרת רק כאשר עמית ה-TCP מהימן. הדוגמאות המעשיות של Google Cloud ושל AWS כוללות ערכים קונקרטיים לכל טופולוגיה. ללא שרתי פרוקסי מהימנים, כל בקשה נראית כאילו הגיעה מכתובת ה-IP של הפרוקסי, מה שממזג מגבלות קצב (rate limits) של כל כתובת IP למאגר משותף יחיד ומתעד את כתובת ה-IP של הפרוקסי באירועי ביקורת (audit events).

הגדר לפרוקסי כל פסק זמן של חוסר פעילות (idle timeout) הארוך יותר ממרווח שמירת הקשר (keepalive interval) של השער, אשר תלוי בספק ה-upstream:

• בכל upstream למעט provider: anthropic, השער כותב ping של SSE ברגע שהזרם (stream) שקט במשך כ-15 שניות.
• ב-provider: anthropic, השער מעביר את התגובה ללא שינוי, כולל אותות ה-ping העצמאיים של ה-API של Anthropic.

ערך ברירת מחדל כמו 60 שניות של ה-ALB מספיק כדי לשמור על זרם שקט פתוח. הדוגמה המעשית של AWS מעלה אותו לשעה בכל מקרה, ושורת פתרון הבעיות שלה מכסה שערים ישנים יותר מגרסה v2.1.229, אשר לא שלחו דבר בזמנים שקטים בספקי ה-upstream שכעת מקבלים אותות ping.

#תמונת קונטיינר (Container image)

בנה תמונה משלך סביב הקובץ הבינארי המקורי של claude מתוך מהדורת Claude Code הסטנדרטית:

1. הורד את מהדורת ה-Linux עבור ארכיטקטורת התמונה שלך מתוך מהדורה מקובעת (pinned release); ראה התקנת גרסה ספציפית עבור כתובת ה-URL להורדה.
2. אמת אותה מול קובץ ה-manifest.json של המהדורה החתום ב-GPG כמתואר ב-שלמות קבצים בינאריים וחתימת קוד.
3. העתק אותה לתוך הקשר הבנייה (build context).

צור מראה (mirror) של המהדורה ברגיסטרי הפנימי שלך אם תהליכי הבנייה שלך אינם יכולים להגיע לשרת המארח של המהדורה, וקבע את הגרסה שצי המחשבים (fleet) שלך מריץ.

מעבר לקובץ הבינארי, התמונה זקוקה ל:

• תמונה מבוססת glibc: התלויות הדינמיות היחידות של גרסת ה-glibc הן ספריות glibc. תמונות מבוססות musl זקוקות לגרסת linux-x64-musl או linux-arm64-musl בתוספת חבילות נוספות; ראה הגדרת Alpine Linux.
• ספריית מצב הניתנת לכתיבה: השער רץ ככל משתמש, אך לתמונות מינימליות אין ספריית בית (home) הניתנת לכתיבה. הגדר את CLAUDE_CONFIG_DIR לנתיב הניתן לכתיבה כגון /tmp/.claude.
• פקודת הקונטיינר: claude gateway --config /etc/claude/gateway.yaml, כאשר קובץ התצורה מותקן (mounted) לקריאה בלבד וסודות מסופקים כמשתני סביבה; השער מאזין ב-listen.port, ברירת המחדל היא 8080.

#Kubernetes

הרץ את השער בתור Deployment, כמו כל שירות חסר מצב:

• התקן (mount) את התצורה מתוך ConfigMap וסודות מתוך Secret; התייחס לסודות ב-YAML דרך ${file:/path/to/secret} או כמשתני סביבה
• סיים את הצפנת ה-TLS ב-Ingress והגדר את listen.public_url לשם המארח של ה-Ingress
• כוון את בדיקת המוכנות (readiness probe) אל GET /readyz ואת בדיקת החיות (liveness probe) אל GET /healthz

לדוגמה מעשית מלאה ב-AWS, המכסה את ECS Fargate או EKS, את Amazon RDS ואת AWS Secrets Manager, ראה פריסה ב-AWS.

העדף שימוש בזהות עומסי עבודה (workload identity) של הפלטפורמה על פני מפתחות סטטיים; מדריך ההפניה של upstreams מכיל פרטי הגדרה לכל פלטפורמה. עבור שילוב בין עננים שונים, כגון Amazon Bedrock בתור upstream על גבי GKE, הגדר במקום זאת אישורי גישה מפורשים בבלוק ה-auth של ה-upstream.

#Cloud Run

הגדר את השירות באופן הבא:

• השאר את listen.port בערך ברירת המחדל שלו, 8080, התואם ל-PORT ברירת המחדל של Cloud Run, או הגדר port: ${PORT}
• הגדר את public_url למקור הנגיש חיצונית. עבור סביבת ייצור זהו בדרך כלל שם מארח של נתב עומסים פנימי, מכיוון ש-/login דוחה כתובות ציבוריות וכתובת ה-URL של *.run.app נפתרת לכתובת כזו, כך שכתובת ה-URL של Cloud Run לבדה פועלת רק עבור בדיקת עשן (smoke test) בדפדפן או באמצעות curl. היוצא מן הכלל הוא רשת שבה *.run.app נפתר באופן פרטי דרך Private Service Connect ואזור פרטי של Cloud DNS; בטופולוגיה זו כתובת ה-URL של Cloud Run היא public_url תקין. הדוגמה המעשית של Google Cloud מכסה את שני המקרים.
• התקן את התצורה בתור secret volume
• הגדר min-instances: 1 כדי למנוע גילוי OIDC קר בבקשה הראשונה

לדוגמה מעשית מלאה ב-Google Cloud, המכסה את Cloud Run או GKE, את Cloud SQL ואת Secret Manager, ראה פריסה ב-Google Cloud.

#הפצת כתובת ה-URL של השער למחשבי מפתחים (Push the gateway URL to developer machines)

לאחר שהשער מתחיל לשרת בקשות, הפץ את forceLoginMethod, forceLoginGatewayUrl ואת parentSettingsBehavior: "merge" למחשב של כל מפתח דרך הגדרות מנוהלות, באמצעות MDM או על ידי כתיבה ישירה של managed-settings.json המתאים למערכת ההפעלה. ללא זאת, הפקודה /login מציגה את בורר החשבונות הרגיל ללא אפשרות לשער. ראה הגדרות מנוהלות בצד הלקוח עבור נתיבי הקבצים ועבור הערך המקביל של bootstrapUrl ב-Claude Desktop.

#תפעול (Operations)

לאחר שהשער משרת תעבורה, התפעול השוטף יום-יום כולל קריאת יומנים, בדיקת תקינות וביצוע סבב סודות לפי לוח הזמנים שלך. סעיפי המשנה מכסים כל אחד מהנושאים הללו, בנוסף למה ש-Postgres מכיל וכיצד שדרוגים וחזרות לאחור (rollbacks) מתנהגים.

#יומנים (Logs)

השער כותב שני זרמים (streams) אל stderr, שניהם מותאמים ל-JSON:

• אירועי ביקורת (Audit events): שורת JSON בודדת עבור כל אירוע רלוונטי לאבטחה. נתב את stderr אל מרכז היומנים (log aggregator) שלך. האירועים הנפלטים כוללים את config.load, session.mint, session.refresh, device.authorize, device.verify, device.callback, auth.denied, access.denied, inference, managed.serve, desktop_bootstrap.serve, desktop_bootstrap.denied, spend.blocked, admin.denied, admin.limit.upsert ו-admin.limit.delete. השדות משתנים לפי האירוע:
  • אירועי יצירה (mint) ורענון (refresh) מוצלחים נושאים את sub, email, client_ip ואת התוצאה
  • auth.denied ו-access.denied נושאים את הסיבה ואת כתובת ה-client_ip, בתוספת נתיב הבקשה עבור auth.denied, מכיוון שלא קיימת זהות משתמש בעת דחיות אלו
  • inference מתעד איזה upstream שירת את הבקשה ואת סטטוס התגובה
  • desktop_bootstrap.denied מתעד שליפה שנדחתה של אתחול (bootstrap) עבור Claude Desktop עם הסיבה (not_configured, policy_not_opted_in או no_policy_matched) ואת זהות המשתמש
  • admin.denied מתעד ניסיון אימות שנדחה עבור ה-admin-API עם כתובת ה-client_ip, המתודה, הנתיב והסיבה, ללא חומר המפתחות שהוצג: invalid_key כאשר הוצג x-api-key אך הוא לא תאם אף מפתח מוגדר, bearer_rejected כאשר הוצגה רק כותרת Authorization והיא לא אומתה כהפעלת שער בקבוצות admin.admin_groups, או no_credentials כאשר אף כותרת לא הוצגה
• יומנים תפעוליים (Operational logs): שורות קריאות לאדם בעלות הקידומת [gateway] עבור אתחול, אזהרות ושגיאות upstream. משתנה הסביבה CLAUDE_GATEWAY_LOG_LEVEL שולט ברמת הפירוט ומקבל debug, info, warn או error, כאשר info הוא ברירת המחדל. ברמת debug, כל התחברות ורענון מתעדים גם את השמות, ולא את הערכים, של הטענות בתוך ה-id_token, בתוספת השמות של טענות ה-userinfo כאשר userinfo_fallback סיפק כאלה, כך שתוכל לאבחן הגדרות של email_claim ו-groups_claim מבלי לתעד מידע מזהה אישי (PII). הדבר אינו משפיע על אירועי ביקורת, הנפלטים תמיד.

#בדיקות תקינות (Health)

השער מגיש את GET /healthz בתור בדיקת חיות (liveness probe) ואת GET /readyz בתור בדיקת מוכנות (readiness probe); הבדיקה /readyz מאמתת שמאגר הנתונים נגיש. שתיהן פטורות מ-access_control.allow_cidrs, כך שבדיקות התקינות ממשיכות לעבוד על מאזין (listener) נעול.

מסמך גילוי ה-OAuth בנתיב /.well-known/oauth-authorization-server מחזיר גם הוא 200 רק לאחר שטעינת התצורה, גילוי ה-OIDC, בניית לקוח ה-upstream והגירת Postgres מצליחים כולם, ולכן הוא משמש גם כבדיקת אתחול מקצה לקצה.

#התנהגות בעת השבתה (Outage behavior)

אם Postgres קורס, השער עצמו ממשיך לשרת מפתחים מחוברים, וכניסות חדשות נכשלות. השאלה האם מפתחים ימשיכו לעבוד בפועל תלויה באופן שבו מערכת התזמור (orchestrator) שלך מטפלת במוכנות:

• הפעלות קיימות (Existing sessions): אסימוני bearer מאומתים מקומית באמצעות סוד ה-JWT, רענוני הפעלה אינם נוגעים במאגר הנתונים, ותהליך השער עדיין יכול לשרת הסקת מודלים
• כניסות חדשות (New sign-ins): נכשלות עד ש-Postgres מתאושש, מכיוון שתהליך ה-device flow ומוני הגבלת הקצב שלו שמורים ב-Postgres
• אכיפת מגבלת הוצאות: כושלת למצב פתוח (fails open) כברירת מחדל במהלך ההשבתה, כך שהסקת מודלים עדיין זורמת; הפוך אותה לכישלון במצב סגור (fail closed) אם אתה מעדיף לחסום במקום לפעול ללא מדידה
• מוכנות (Readiness): הבדיקה /readyz מדווחת על חוסר מוכנות במהלך ההשבתה, ולכן מערכות תזמור שמתנות תעבורה במוכנות מסירות את כל העותקים המשוכפלים מסבב השירות בבת אחת. בטופולוגיה זו כל התעבורה, כולל הסקת מודלים שהשער עדיין יכול לשרת, נכשלת בנתב העומסים עד ש-Postgres מתאושש. בדיקת החיות ב-/healthz ממשיכה לעבור בהצלחה, כך שהעותקים המשוכפלים אינם מופעלים מחדש. כוון את בדיקת המוכנות אל /healthz במקום זאת אם אתה מעדיף שמפתחים מחוברים ימשיכו לעבוד לאורך השבתת מאגר נתונים; המחיר הוא שכניסות חדשות ייכשלו מול עותק שעדיין מדווח על מוכנות.

אם ספק הזהויות (IdP) שלך קורס, הפעלות קיימות פועלות עד תום ttl_hours, וכניסות ורענונים חדשים נכשלים. הגדר ttl_hours ארוך יותר אם לספק הזהויות שלך יש חלונות תחזוקה תכופים.

#סבב סודות JWT (JWT secret rotation)

בצע סבב של סוד החתימה בשלושה שלבים כדי שהפעלות קיימות יישארו תקפות:

1. צור סוד חדש. הוסף אותו לתחילת המערך session.jwt_secret.
2. בצע פריסה מדורגת (roll) של השירות. אסימונים חדשים ייחתמו באמצעות הסוד החדש; אסימונים ישנים עדיין יאומתו.
3. לאחר ttl_hours בתוספת מרווח ביטחון, הסר את הסוד הישן ובצע פריסה מדורגת מחדש.

סבב סודות הוא גם הדרך היחידה לסיים הפעלות בכפייה לפני שתוקפן פג: אסימוני bearer מאומתים מקומית מול סוד ה-JWT, ולכן אין אפשרות לביטול פר הפעלה בודדת. החלפת הסוד באופן מוחלט, מבלי לשמור את הישן במערך, פוסלת בבת אחת את כל ההפעלות הפעילות. עבור גריעת עובד בודד (individual offboarding), בטל את הרשאות המשתמש בספק הזהויות (IdP); ההפעלה שלו תסתיים בתוך ttl_hours.

#Postgres

השער מחזיק חמש טבלאות נתונים בנוסף לטבלת _migrations, כולן נוצרות על ידי הגירות המבנה בעת האתחול:

לולאה של 30 שניות פוסלת שורות kv שעברו את ה-TTL שלהן, וסריקה שעתית אוכפת את חלונות השימור בטבלאות ההוצאה, כך ששום דבר אינו גדל ללא הגבלה. ללא הגדרת מגבלות הוצאה, רק טבלת kv נכתבת. השער מחיל את הגירות הסכמה שלו בעצמו בעת האתחול ובכל שדרוג, כך שתפקיד מסד הנתונים שלו (database role) זקוק להרשאות ליצור ולשנות טבלאות. כוון אותו למסד נתונים או לסכמה המוקדשים לשער כדי לשמור על הרשאה צרה זו.

כאשר משתמשים במגבלות הוצאה, אובדן של מסד הנתונים פירושו אובדן מעקב ותקרות הוצאה, ולא רק התחברות מחדש של מפתחים, לכן בצע גיבויים שוטפים. כדי למחוק באופן מיידי מפתח שעזב במקום להמתין לתקופת השימור, הרץ ישירות DELETE FROM principal_emails WHERE principal = '<sub>'; פעולה זו מוחקת את הטבלה היחידה שמחזיקה את הדוא"ל, השם והקבוצות שלו. שורות ב-spend וב-admin_audit מתייחסות אך ורק למזהה ה-sub הפסאודונימי של OIDC.

#שדרוגים (Upgrades)

העותקים המשוכפלים הם חסרי מצב, ולכן הפעלה מחדש מדורגת (rolling restart) בטוחה בכל עת. השער מריץ הגירות סכמה בעת האתחול, מה שאומר שפריסת הקובץ הבינארי החדש מבצעת הגירה עצמית של מסד הנתונים. עותקים משוכפלים מקבילים מסתנכרנים באופן טורי באמצעות נעילה מייעצת ב-Postgres (Postgres advisory lock), כך שרק עותק אחד מחיל כל הגירה.

ההגירות הן במתכונת הוספה בלבד (append-only), ולכן חזרה לאחור (rollback) לקובץ בינארי קודם המכיר פחות הגירות היא בטוחה; הוא מתעלם מהשורות הנוספות. חזרה לאחור גם מאמתת מחדש את ה-YAML מול הסכמה של הקובץ הבינארי הישן יותר, ולכן תצורה שאימצה מפתח שהוצג במהדורה החדשה יותר תיכשל באתחול על הקובץ הישן. הסר את המפתח החדש לפני החזרה לאחור.

מכיוון שאתה מקבע את גרסת השער בתמונה שלך, תיקונים במהדורות חדשות של Claude Code, כולל תיקוני אבטחה, מגיעים לפריסה שלך רק כאשר אתה מעדכן את הקיבוע ופורס מחדש. כלול את השער באותו קצב עדכוני אבטחה (patching cadence) שבו אתה משתמש עבור שירותים אחרים המחזיקים באישורי גישה של סביבת ייצור.

#אבטחה (Security)

סעיף זה עונה על השאלות שסקירת אבטחה מעלה: אילו נתונים זורמים דרך השער ולאן הם מגיעים, מפני אילו התקפות התכנון מגן, ואילו תשובות שייכות לשאלון תאימות (compliance questionnaire).

#זרימת נתונים (Data flow)

#סיכום מודל האיומים (Threat model summary)

השער יושב בתוך היקף הרשת שלך (network perimeter), אך מחשבים ניידים של מפתחים בודדים אינם נחשבים מהימנים. התכנון מתחשב בכך בשלוש דרכים:

• מפתחים מחזיקים ב-JWT קצרי מועד במקום במפתחות upstream גולמיים. הקטע שבין ה-CLI לשער משתמש ב-device grant של RFC 8628, והחלפת ה-authorization-code של השער מול ספק הזהויות מריצה PKCE בתצורת ברירת המחדל, כך שקוד הרשאה של ספק הזהויות שיורט הוא חסר תועלת.
• דף אימות המכשיר (device-verification) אוכף same-origin POST והגבלת קצב לכל כתובת IP לפי RFC 8628 §5.1. ראה עמידות בפני מתקפת כוח גס על קוד המשתמש.
• בקשות יוצאות עוברות דרך מנגנון הגנה מפני זיוף בקשות בצד השרת (SSRF), אשר פותר כתובות DNS, חוסם כברירת מחדל כתובות link-local, נתוני מטא-דאטה של ענן ו-loopback, ומקבע את החיבור לכתובת ה-IP שנפתרה, כך שכתובות URL המושפעות על ידי המפעיל, כגון יעדי ה-IdP ו-OTLP, אינן יכולות להיות מנותבות מחדש לנקודות קצה של נתוני מטא-דאטה של ענן. טווחי רשת פרטיים לפי RFC 1918 מותרים במכוון, מכיוון שספקי זהויות ורכיבי איסוף OTLP יושבים בדרך כלל בכתובות IP פרטיות. הגדר CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 בסביבת השער רק כאשר רכיב שהשער חייב להגיע אליו באופן לגיטימי יושב על loopback, כגון IdP לפיתוח מקומי או רכיב איסוף OTLP בתצורת sidecar על גבי localhost. המשתנה מרפה את חסימת ה-loopback עבור כל כתובת URL שהוגדרה על ידי המפעיל וגם מדלג על אזהרת זמן האתחול הבודקת האם ה-pod יכול להגיע לנקודת הקצה של מטא-דאטה של הענן, ולכן עדיף להעניק לרכיב האיסוף כתובת פנימית משלו.

אם אתה מוסיף בקרות יציאה משלך, השער חייב להגיע לשרת המטא-דאטה בכל פעם שהוא משתמש באישורי גישה של מטא-דאטה של המופע, כגון workload identity.

שני איומים נמצאים מחוץ לתחום מכיוון שהם חלק מהתשתית שלך שבאחריותך לאבטח:

• מארח שער שנפרץ (compromised gateway host): המארח מחזיק הן באישורי הגישה של ה-upstream והן מפיץ הגדרות מנוהלות לכל מפתח מחובר, ולכן שליטה בתצורת השער שקולה לשליטה ב-MDM שלך. תיבת הדו-שיח לאישור של ה-CLI עבור הגדרות בעלות יכולת הרצה ב-shell מגבילה שינויים שקטים, אך אינה מהווה תחליף לאבטחת המארח.
• ספק OIDC זדוני: הספק חותם על ה-id_tokens שהשער נותן בהם אמון, ולכן הוא יכול לטעון לכל זהות. בדיקת נאותות ואבטחת ספק הזהויות שלך הן באחריותך.

#עמידות בפני מתקפת כוח גס על קוד המשתמש (User-code brute-force resistance)

ה-user_code שמפתח מקליד בדף האימות /device מורכב מ-8 תווים מתוך אלפבית של 20 תווים, מה שמניב 20⁸ או כ-2.56×10¹⁰ צירופים, ותוקפו פג לאחר 10 דקות.

השער מחיל מגבלות קצב לכל כתובת IP בנקודות הקצה של device-grant, הניתנות להגדרה באמצעות rate_limits. העלה את המגבלות אם מפתחים רבים מתחברים מכתובת NAT ארגונית משותפת יחידה. המגבלות חלות אך ורק על תהליך ההתחברות, ולא על הסקת מודלים.

#מערך תאימות (Compliance posture)

• מיקום שמירת הנתונים (Data residency): מישור הנתונים (data plane) של השער עצמו אינו שולח דבר ל-Anthropic, אלא אם כן ה-API של Anthropic מוגדר כ-upstream; כאשר הוא מוגדר כך, הסכם הטיפול בנתונים הקיים שלך חל על נתיב הסקת המודלים. טלמטריה, ביקורת, זהות והגדרות מועברות אך ורק ליעדים שאתה מגדיר.
• תעבורת תהליך המארח (Host-process traffic): תהליך המארח הוא ה-CLI של Claude Code. הפקודה claude gateway פועלת תחת אותם כללי צד-שלישי כמו פריסות של Amazon Bedrock ושל Google Cloud Agent Platform ואינה שולחת דבר ל-Anthropic. לפני גרסה v2.1.227, תהליך המארח שלח טלמטריית הפעלה כגון גרסת המוצר והפלטפורמה, והגדרה של CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 בסביבת הקונטיינר השביתה זאת. מהדורות אלו שלחו גם בקשת HEAD אחת בעת האתחול, ללא גוף בקשה וללא אישורי גישה, אל /api/hello בכתובת https://api.anthropic.com, או בכתובת ANTHROPIC_BASE_URL כאשר הסביבה הגדירה זאת, אלא אם כן הסביבה הגדירה גם משתנה פרוקסי כגון HTTPS_PROXY או תעודת לקוח של mTLS. הן התעלמו מהתגובה, כך שחסימת הבקשה הזו בחומת האש של תעבורת היציאה לא השפיעה על השער.
• ניתוח נתוני לקוח (Client analytics): ה-CLI משבית את ניתוח השימוש ודיווחי השגיאות שלו בעת חיבור לשער. לפני ההתחברות הראשונה, ה-CLI עדיין שולח אירועי הפעלה ל-Anthropic, כולל במחשבים שההגדרות המנוהלות שלהם כופות התחברות דרך שער. כדי להשבית גם אותם, העבר את DISABLE_TELEMETRY באותן הגדרות מנוהלות בצד הלקוח הכופות התחברות דרך השער.
• דיווחי שגיאות (Error reporting): ה-CLI מכבה דיווחי שגיאות בכל פעם שבקשות המודל שלו נשלחות לנקודת קצה כלשהי שאינה ה-API הישיר של Anthropic, כגון Amazon Bedrock או כתובת ANTHROPIC_BASE_URL מותאמת אישית.
• מחשבי לקוח (Client machines): ה-CLI של המפתחים עדיין שולח בדיקות שמות מארח של WebFetch ובדיקות גרסה ל-Anthropic, אלא אם כן מוגדרים CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ו-skipWebFetchPreflight: true. ראה שימוש בנתונים.
• דירוגי סקרים (Survey ratings): בעת חיבור לשער, ה-CLI משבית את העלאת הדירוגים המיועדים ל-Anthropic יחד עם זרמי הניתוח, כך שהוא אינו שולח דירוגים ל-Anthropic.
• שיתוף תמלילים (Transcript sharing): בחירה ב-Yes בהנחיית שיתוף התמליל בסקר כותבת קובץ מקומי תחת ~/.claude/feedback-bundles/ במקום להעלות אותו ל-Anthropic.
• עדכוני לקוח (Client updates): בדיקות עדכון נפרדות מתעבורת השער. קבע גרסאות דרך מנגנון ההפצה שלך והגדר את DISABLE_UPDATES אם על מחשבים ניידים נאסר להוריד מהדורות. DISABLE_AUTOUPDATER עוצר רק עדכוני רקע, בעוד שהפקודה claude update ממשיכה לפעול.
• TLS: הגש את public_url מעל HTTPS בסביבת ייצור, מתוך המאזין של השער עצמו דרך listen.tls או מ-ingress המסיים TLS לפני עותקים משוכפלים ב-HTTP פשוט, כאשר listen.public_url מוגדר בשני המקרים. השער אינו דוחה HTTP פשוט. ספק הזהויות חייב להגיש HTTPS בסביבת ייצור, ו-Postgres תומך ב-?sslmode=require. הגדר Strict-Transport-Security ב-ingress שלך.
• חשיפת פגיעויות (Vulnerability disclosure): פעל לפי דיווח על בעיות אבטחה

#פתרון בעיות (Troubleshooting)

לשאלות ומשוב, השתמש ב-תמיכת Claude Code, או פתח פנייה ב-מאגר GitHub של Claude Code. בעת דיווח על בעיה, כלול:

• בעיית שער (Gateway issue): פלט ה-stderr של השער עבור חלון הזמן הרלוונטי, קובץ ה-gateway.yaml שלך כשהסודות מושחרים (redacted), גרסת השער, המוצגת בדף הנחיתה ב-/ ובכותרת התגובה x-cc-gateway-version ב-/managed/settings, ומה השתנה לאחרונה
• בעיית התחברות (Login issue): המפתח מריץ claude --debug-file ./claude-debug.txt, משחזר את הבעיה, ושולח קובץ זה בתוספת יומן הביקורת של השער עבור אותו חלון זמן
• בעיית הסקת מודל (Inference issue): המודל שהתבקש, ה-upstreams המוגדרים, ויומן הביקורת של השער עבור הבקשה, המתעד איזה upstream שירת אותה ואת סטטוס התגובה

ה-stderr של השער כולל את זרם אירועי הביקורת, יומן הביקורת מתעד זהויות מפתחים, וקובץ הדיבאג מתעד פלטי hook ושרת MCP ממחשב המפתח. בדוק והשחר נתונים אלה לפני פרסומם בפנייה ציבורית.

הודעת אי ההתאמה כוללת את שם המארח של השער ואת 16 התווים הראשונים של כל אחת מטביעות האצבע, זו שקובעה וזו שהוצגה.

אם Claude Code מדווח על couldn't load your organization's managed settings לאחר התחברות לשער, Claude Code מציין את הסיבה, מופעל מחדש במקומו וממשיך את השיחה. אם Claude Code אינו יכול להפעיל את עצמו מחדש, למשל בהפעלה ברקע, Claude Code מסיים את ההפעלה ושומר את מצב ההתחברות.

#נושאים קשורים (Related)

• סקירת Claude apps gateway: התחלה מהירה וחיבור מפתחים
• מדריך תצורה: כל אפשרות בקובץ gateway.yaml