סביבת זמן ריצה של Node.js

זמן הריצה של Node.js הוא מחסנית התוכנה שאחראית להתקנה של קוד שירות האינטרנט והתלויות שלו, ולהרצת השירות.

זמן הריצה של Node.js ב-App Engine בסביבה הרגילה מוצהר בקובץ app.yaml:

runtime: nodejsVERSION

‫VERSION הוא מספר הגרסה של Node.js MAJOR. לדוגמה, כדי להשתמש בגרסה האחרונה של Node.js, ‏ Node.js 24, מציינים 24.

לגרסאות נתמכות אחרות של Node.js ולגרסת Ubuntu התואמת לגרסת Node.js שלכם, אפשר לעיין בלוח הזמנים לתמיכה בזמן ריצה.

גרסת Node.js

הגרסה העדכנית ביותר של Node.js שנתמכת היא 24. ה-Node.js runtime משתמש בגרסה היציבה האחרונה של הגרסה שצוינה בקובץ app.yaml. ‫App Engine מתעדכן אוטומטית לגרסאות חדשות של תיקוני אבטחה וגרסאות משניות, אבל הוא לא מתעדכן אוטומטית לגרסה ראשית.

לדוגמה, יכול להיות שהאפליקציה שלכם נפרסה ב-Node.js 10.9.4 ומעלה, והיא תתעדכן אוטומטית לגרסה 10.10.0, אבל היא לא תתעדכן אוטומטית ל-Node.js 12.x.x.

מכיוון שגרסאות משניות וגרסאות תיקון מתעדכנות באופן אוטומטי, אם הן קיימות, המאפיין engines.node בקובץ package.json יכול לציין רק את הגרסה הראשית ולהיות תואם לגרסת Node.js שצוינה בקובץ app.yaml.

לדוגמה, עבור 24:

  • 24.x.x
  • ^24.0.0
  • ~24
  • >=6

אם מציינים גרסת Node.js לא תואמת בקובץ package.json, הפריסה תיכשל ותוצג הודעת שגיאה.

תלויות

במהלך הפריסה, סביבת זמן הריצה מתקינה את התלות באמצעות הפקודה npm install. סביבת זמן הריצה תומכת גם במנהלי החבילות Yarn ‏ (yarn.lock) ו-Pnpm ‏ (pnpm-lock.yaml). מידע נוסף זמין במאמר Specifying Dependencies. מכיוון שסביבת זמן הריצה מבצעת התקנה חדשה, לא צריך להעלות את התיקייה node_modules.

כדי לתמוך בחבילות Node.js שדורשות תוספים מקוריים, סביבת זמן הריצה כוללת חבילות מערכת שמאפשרות לכם להשתמש בכלים כמו ImageMagick,‏ FFmpeg ו-Chrome headless. רשימת החבילות המלאה זמינה במאמר Included System Packages. כדי לבקש חבילה, צריך לפתוח בעיה במעקב הבעיות.

סקריפט build של NPM

כברירת מחדל, כשפורסים את האפליקציה ב-App Engine, סביבת זמן הריצה של Node.js מריצה את npm run build אם מזוהה סקריפט build ב-package.json. אם אתם רוצים שליטה נוספת בשלבי ה-build לפני הפעלת האפליקציה, אתם יכולים לספק שלב build מותאם אישית על ידי הוספת סקריפט gcp-build לקובץ package.json.

כדי למנוע את הרצת הסקריפט npm run build ב-build, צריך:

  • מוסיפים סקריפט gcp-build עם ערך ריק לקובץ package.json: "gcp-build":"". פרטים על הגדרת package.json זמינים במאמר הגדרות של Node.js buildpacks.

  • מוסיפים את משתנה הסביבה של ה-build‏ GOOGLE_NODE_RUN_SCRIPTS עם ערך ריק לקובץ app.yaml.

    build_env_variables:
  GOOGLE_NODE_RUN_SCRIPTS: ''
פרטים נוספים על הגדרת משתני סביבה של build זמינים בקטע build_env_variables בקובץ app.yaml.

הפעלת האפליקציה

כברירת מחדל, סביבת זמן הריצה מפעילה את האפליקציה על ידי הרצת node server.js. אם מציינים סקריפט start בקובץ package.json, סביבת זמן הריצה מפעילה את סקריפט ההתחלה שצוין במקום זאת. לדוגמה:

"scripts": {
  "start": "node app.js"
}

כדי שהאפליקציה תקבל בקשות HTTP, סקריפט start צריך להפעיל שרת אינטרנט שמקשיב למארח 0.0.0.0 ולפורט שצוין על ידי PORT משתנה הסביבה, שאפשר לגשת אליו ב-Node.js בתור process.env.PORT.

כדי להשיג את הביצועים הכי טובים, הסקריפט start צריך להיות קל משקל ולא לכלול שלבי build, כי הוא מופעל בכל פעם שנוצר מופע חדש של האפליקציה.

כדי לשנות את שיטת הפעולה הזאת, אפשר לציין סקריפט בשדה entrypoint ב-app.yaml. במקום להריץ את הפקודה node server.js או סקריפט הפעלה, סביבת זמן הריצה מפעילה את האפליקציה באמצעות הפקודה שציינתם ב-entrypoint.

משתני סביבה

משתני הסביבה הבאים מוגדרים על ידי זמן הריצה:

משתנה הסביבה תיאור
GAE_APPLICATION המזהה של אפליקציית App Engine. המזהה הזה מתחיל בקידומת region code~, למשל e~ לאפליקציות שמוצבות באירופה.
GAE_DEPLOYMENT_ID המזהה של הפריסה הנוכחית.
GAE_ENV סביבת App Engine. ההגדרה היא standard.
GAE_INSTANCE המזהה של המופע שבו השירות שלכם פועל כרגע.
GAE_MEMORY_MB נפח הזיכרון שזמין לתהליך האפליקציה, ב-MB.
GAE_RUNTIME סביבת זמן הריצה שצוינה בקובץ app.yaml.
GAE_SERVICE שם השירות שצוין בקובץ app.yaml. אם לא מציינים שם שירות, ברירת המחדל היא default.
GAE_VERSION תווית הגרסה הנוכחית של השירות.
GOOGLE_CLOUD_PROJECT מזהה הפרויקט ב- Google Cloud שמשויך לאפליקציה.
PORT היציאה שמקבלת בקשות HTTP.
‫NODE_ENV (זמין רק בסביבת זמן ריצה של Node.js) מגדירים את הערך production כשהשירות נפרס.

אפשר להגדיר משתני סביבה נוספים בקובץ app.yaml, אבל אי אפשר לשנות את הערכים שלמעלה, למעט NODE_ENV.

פרוטוקול HTTPS ושרתי proxy להעברה

‫App Engine מסיימת חיבורי HTTPS במאזן העומסים ומעבירה בקשות לאפליקציה. יש אפליקציות שצריכות לקבוע את כתובת ה-IP והפרוטוקול של הבקשה המקורית. כתובת ה-IP של המשתמש זמינה בכותרת הרגילה X-Forwarded-For. אפליקציות שזקוקות למידע הזה צריכות להגדיר את תוכנת ה-framework שלהן כך שתיתן אמון בשרת ה-proxy.

ב-Express.js, משתמשים בהגדרה trust proxy:

app.set('trust proxy', true);

שימו לב: הגדרת trust proxy ל-true עלולה לחשוף את הנכס req.ip לזיוף כתובות IP.

מערכת קבצים

סביבת זמן הריצה כוללת מערכת קבצים מלאה. מערכת הקבצים היא לקריאה בלבד, למעט המיקום /tmp, שהוא דיסק וירטואלי שמאחסן נתונים בזיכרון ה-RAM של מופע App Engine.

שרת מטא-נתונים

כל מופע של האפליקציה יכול להשתמש בשרת המטא-נתונים של App Engine כדי לשלוח שאילתות לגבי המופע והפרויקט.

אפשר לגשת לשרת המטא-נתונים דרך נקודות הקצה הבאות:

  • http://metadata
  • http://metadata.google.internal

בקשות שנשלחות לשרת המטא-נתונים צריכות לכלול את כותרת הבקשה Metadata-Flavor: Google. הכותרת הזו מציינת שהבקשה נשלחה בכוונה מפורשת לאחזר ערכי מטא-נתונים.

בטבלה הבאה מפורטות נקודות הקצה שאליהן אפשר לשלוח בקשות HTTP למטא-נתונים ספציפיים:

נקודת קצה של מטא-נתונים תיאור
/computeMetadata/v1/project/numeric-project-id מספר הפרויקט שהוקצה לפרויקט שלכם.
/computeMetadata/v1/project/project-id מזהה הפרויקט שהוקצה לפרויקט שלכם.
/computeMetadata/v1/instance/region האזור שבו המופע פועל.
/computeMetadata/v1/instance/service-accounts/default/aliases
/computeMetadata/v1/instance/service-accounts/default/email כתובת האימייל בחשבון השירות שמוגדר כברירת מחדל ומוקצה לפרויקט.
/computeMetadata/v1/instance/service-accounts/default/ מציגה את כל חשבונות השירות שמוגדרים כברירת מחדל בפרויקט.
/computeMetadata/v1/instance/service-accounts/default/scopes רשימה של כל ההיקפים הנתמכים בחשבונות שירות שמוגדרים כברירת מחדל.
/computeMetadata/v1/instance/service-accounts/default/token מחזירה את אסימון האימות שאפשר להשתמש בו כדי לאמת את האפליקציה שלכם ב-Google Cloud APIs אחרים.

לדוגמה, כדי לאחזר את מזהה הפרויקט, שולחים בקשה אל http://metadata.google.internal/computeMetadata/v1/project/project-id.