סביבת זמן ריצה של 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. אפשר לעיין ברשימה המלאה של החבילות במאמר חבילות מערכת כלולות. כדי לבקש חבילה, צריך לדווח על בעיה בכלי למעקב אחר בעיות.

סקריפט build של NPM

כברירת מחדל, כשפורסים את האפליקציה ב-App Engine, סביבת זמן הריצה של Node.js מפעילה את npm run build אם מזוהה סקריפט build ב-package.json. אם אתם צריכים שליטה נוספת בשלבי הבנייה לפני הפעלת האפליקציה, אתם יכולים לספק שלב בנייה בהתאמה אישית על ידי הוספת סקריפט 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. באפליקציות שנדרש בהן המידע הזה, צריך להגדיר את מסגרת האינטרנט כך שתיתן אמון ב-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.