תיעוד Nodaroארכיטקטורה
איך Nodaro בנוי, למנהלי שרתים ולתורמים לקוד: העורך, ה-API ב-Fastify, ה-workers של BullMQ, Redis, האחסון, שלוש שיטות האימות והמהדורות.
Nodaro הוא מנוע תהליכי AI שבנוי סביב REST API. בעורך בדפדפן, המשתמשים מחברים רכיבי AI — יצירת תמונות ווידאו, הרכבת וידאו, מודלי טקסט ואודיו — לגרף. הגרף נשמר ב-Postgres של Supabase. כשהוא רץ, API ב-Fastify ממיין אותו ומעביר את העבודה של כל רכיב ל-workers דרך תורים ב-Redis. ספקי המודלים מבצעים את היצירה, והתוצאות נשמרות באחסון תואם S3.
אותו קוד משרת שלוש מהדורות — Community, Business ו-Cloud — ומקבל שלושה סוגים של אסימוני גישה. הדף הזה מיועד למנהלי השרתים שמריצים את Nodaro ולמי שתורם לקוד שלו.
המערכת במבט אחד
מאגר הקוד
מאגר הקוד הציבורי, github.com/nodaroai/app.nodaro.ai, הוא monorepo אחד של npm workspaces:
| תיקייה | מה יש בה |
|---|---|
backend/ | ה-API ב-Fastify, ה-workers של BullMQ וה-orchestrator. Node.js 22, TypeScript. |
frontend/ | אפליקציית הדפדפן: העורך, מריץ האפליקציות וממשק הניהול. React 19, React Router 7, React Flow. |
packages/ | קוד משותף וחבילות ה-npm שמתפרסמות — @nodaro/shared, @nodaro/sdk ו-@nodaro/cli — וגם קומפוזיציות הווידאו של Remotion. |
supabase/ | סכמת מסד הנתונים, כמיגרציות SQL שמתקדמות רק קדימה. |
docs/ | התיעוד של המוצר, כולל הערות תכנון. |
tools/ | סקריפטים למנהלי השרת: מחולל המפתחות, בדיקת החוזה, גיבוי ושחזור. |
examples/ | דוגמאות, כמו workflow של GitHub Actions שמעדכן שרת דרך SSH. |
פרונטאנד
הפרונטאנד הוא אפליקציית עמוד יחיד שבנויה ב-Vite. באימג׳ של Docker, שרת הווב, Caddy, מגיש אותה כקבצים סטטיים. היא כוללת ארבעה מוצרים באותו bundle:
- העורך — הקנבס של React Flow, חלונית הגדרות לכל משפחת רכיבים ומנוע הרצה לגרף, שמריץ תהליכים בדפדפן בזמן העריכה.
- מריץ האפליקציות — מציג תהליך שפורסם כטופס פשוט של קלטים ותוצאות.
- מסך ההסכמה של OAuth — המסך שבו משתמשים מאשרים אפליקציות צד שלישי ולקוחות MCP, בנתיב
/oauth/authorize. - ממשק הניהול — רק במהדורות Business ו-Cloud.
המצב שמגיע מהשרת מנוהל ב-React Query, מצב הממשק ב-Zustand, ומצב הקנבס במאגר המצב של React Flow עצמו.
API
ה-API הוא שרת Fastify על Node.js 22, שכתוב ב-TypeScript. הנתיבים הם תוספים של Fastify, וכל נקודת קצה מצהירה על סכמה לבקשה ולתגובה שלה. אותן סכמות בודקות את התקינות של כל בקשה ומפיקות את מסמך OpenAPI 3.1 בנתיב /v1/openapi.json. הנתיב GET /v1/nodes מחזיר את סוגי הרכיבים שההתקנה יכולה להריץ.
לפני כל נתיב רץ hook אימות אחד: ראו את הסעיף אימות.
פרוססים ותורים
הבקאנד מגיע כחמישה פרוססים של Node.js באימג׳ אחד:
| פרוסס | תפקיד |
|---|---|
| שרת ה-API | ה-HTTP API. |
| ה-worker של המדיה | לוקח מהתור משימות של רכיבים בודדים, קורא לספקי המודלים ומעלה את התוצאות לאחסון. יותר מ-40 סוגי משימות, כמו יצירת תמונות ווידאו, עיבוד ב-ffmpeg ואודיו. מקביליות ברירת מחדל: 50, כי רוב הזמן הוא ממתין לרשת. |
| ה-worker של הרינדור | מנוע הרינדור של Remotion, לקומפוזיציות, לגרפיקת תנועה, לשכבות Lottie, לכותרות תלת־ממד ולשילובי שכבות. הוא מריץ Chrome ללא ממשק, וה-CPU הוא שמגביל אותו. מקביליות ברירת מחדל: 2. |
| ה-orchestrator | מריץ תהליכים שלמים: קורא הרצה, ממיין את הגרף שלה ומריץ אותו רמה אחר רמה. מקביליות ברירת מחדל: 20. |
| ה-pipeline worker | הפייפליין סיפור ← וידאו. ה-worker הזה כלול בכל מהדורה, אבל רץ רק ב-Nodaro Cloud, ובכל מקום אחר הוא נסגר מיד. |
ב-Docker, סקריפט הפעלה אחד מעלה את כולם, ו-Caddy מוצב לפני ה-API. כשמרחיבים את ההתקנה, כל אחד מהם יכול לרוץ בקונטיינר משלו. התיאום ביניהם נעשה רק דרך תורי BullMQ ב-Redis ורשומות ההרצה ב-Postgres. ראו את הדף הרחבת קיבולת.
איך תהליך רץ
כשמשתמש לוחץ על הרצה בעורך, יש שני מסלולים:
- בדפדפן. בזמן העריכה, העורך מריץ את הגרף בעצמו וקורא לנקודת קצה אחת של ה-API לכל רכיב. כל תוצאה מופיעה ברגע שהרכיב שלה מסתיים.
- בשרת. הרצות שמתחילות מטריגר — מ-Webhook, מתזמון או מה-API — הרצות של אפליקציות והרצות שמבקשים במפורש להריץ בשרת עוברות ל-orchestrator. ה-orchestrator שומר את ההתקדמות ברשומת ההרצה, כך שכל לקוח יכול לבדוק את מצב ההרצה.
ה-orchestrator:
- טוען את הרכיבים והחיבורים של התהליך.
- ממיין את הגרף לרמות. כל רמה כוללת את הרכיבים שכל הקלטים שלהם מוכנים.
- מריץ במקביל את הרכיבים של כל רמה, עד רמת המקביליות של המשתמש ועד התקרה של השרת,
MAX_CONCURRENT_NODES_PER_EXECUTION. - מריץ כל רכיב באחת משלוש דרכים:
| דרך | איפה | דוגמאות | למה |
|---|---|---|---|
| בתור | משימה ל-worker של המדיה או ל-worker של הרינדור | יצירת תמונה, יצירת וידאו, טקסט לדיבור, שילוב סרטונים, רינדור וידאו | עבודה ארוכה או קריאות חיצוניות, מנותקות מה-orchestrator כדי לאפשר back-pressure |
| HTTP ישיר | קריאה פנימית לנתיב של ה-API | יצירת טקסט - כל LLM, גרפיקת תנועה, עוזר הפרומפטים, רכיבי הפרסום ברשתות החברתיות | קריאות מהירות למודלי טקסט, בלי התקורה של תור |
| מוטבע | בתוך ה-orchestrator | שילוב טקסט, פיצול טקסט, שילוב שכבות | לוגיקה טהורה בלי קריאות חיצוניות |
- אחרי כל רכיב, מעביר את הפלט שלו לרכיבים שתלויים בו, ושומר את התקדמות ההרצה בכתיבה אחת למסד הנתונים לכל רכיב.
הרצה יכולה להיעצר בשתי דרכים. הרצה בסטטוס בוטל נעצרת מיד: רכיבים שכבר רצים ננטשים, וקרדיטים שכבר נגבו לא מוחזרים. הרצה בסטטוס עוצר משלימה את הרמה הנוכחית ונעצרת לפני הרמה הבאה.
מגבלות. כל רכיב יכול לרוץ עד 90 דקות, והרצה שלמה עד 120 דקות. רכיב שמצהיר על תקציב זמן משלו — כיום רכיב החלת רשימת עריכה, שהתקציב שלו נקבע לפי העריכה שהוא מרנדר — מקבל את התקציב הזה במקום, ומגבלת ההרצה גדלה באותה מידה. אם ה-orchestrator עולה מחדש באמצע הרצה, רכיב עם תקציב שה-worker שלו עדיין פעיל ממשיך מאותה נקודה במקום לרוץ פעמיים. רכיבי תת־תהליך רצים באופן רקורסיבי, עד עומק של 5 רמות, עם זיהוי מעגלים.
אחסון ומסד נתונים
- מדיה — כל קובץ תמונה, וידאו ואודיו שנוצר נשמר באחסון תואם S3, ומפנים אליו לפי המפתח שלו. Nodaro אף פעם לא מוחק מעצמו מדיה שמורה.
- מסד נתונים — ב-Postgres של Supabase נשמרים פרופילים, פרויקטים, תהליכים, הרצות וההתקדמות שלהן, משימות, רשומות מדיה, תנועות קרדיטים, אפליקציות OAuth והאסימונים שלהן, אסימוני API אישיים וחיבורים מוצפנים לרשתות חברתיות. בכל טבלה נאכפת אבטחה ברמת השורה, כך שמסד הנתונים עצמו מגביל כל משתמש לשורות שלו.
- מיגרציות — הסכמה נמצאת ב-
supabase/migrations/, והמיגרציות מוחלות לפי סדר שמות הקבצים, ורק קדימה. - Redis — שומר את התורים ומטמונים משותפים קטנים. מצב המשימות ששמור בו הוא זמני: ראו את הדף גיבוי ושחזור.
אימות
ה-API מקבל שלושה סוגים של אסימוני Bearer ומבחין ביניהם לפי המבנה שלהם:
| אסימון | מקור | פועל בתור |
|---|---|---|
eyJ…, כלומר JWT | סשן התחברות של Supabase בעורך | המשתמש המחובר |
ndr_app_<64 hex> | אפליקציית OAuth שמשתמש אישר | המשתמש שאישר את האפליקציה, בגבולות ההרשאות שניתנו |
ndr_<64 hex> | אסימון API אישי | הבעלים של האסימון |
הפרוססים של התקנה אחת גם מאמתים זה את זה עם INTERNAL_ORCHESTRATOR_SECRET, שמושווה בזמן קבוע. שרת הווב מסיר את הכותרת הזו מבקשות שמגיעות מבחוץ.
בכל בקשה, ה-API בודק לפי הסדר הזה:
- נתיבים ציבוריים, כמו
/v1/openapi.jsonו-Webhooks נכנסים, מדלגים על האימות. - הסוד הפנימי, לקריאות בין הפרוססים.
- אסימון של אפליקציית OAuth, בתנאי שהוא לא בוטל ולא פג תוקפו.
- אסימון סשן של Supabase. התפקיד של המשתמש נקרא מהפרופיל שלו ונשמר במטמון ל-5 דקות.
- כל דבר אחר נדחה עם
401.
את אסימוני ה-API האישיים בודקים הנתיבים שמקבלים אותם, ואותם נתיבים גם אוכפים מגבלות קצב ומגבילים כל אסימון לתהליכים שלו. ראו את דף ה-API אימות ואת הדף אפליקציות OAuth.
המהדורות בקוד
בסיס קוד אחד משרת את שלוש המהדורות:
- מהדורת Community (
EDITION=community, ברירת המחדל) — באירוח עצמי, בלי ממשק ניהול, בלי ניהול קרדיטים ובלי חיוב. כל מי שנרשם הוא משתמש רגיל. - מהדורת Business (
EDITION=business) — מוסיפה את ממשק הניהול וניהול משתמשים, ועדיין באירוח עצמי ובלי חיוב. - מהדורת Cloud (
EDITION=cloud) — מוסיפה קרדיטים, חיוב ומחירי קרדיטים שהמנהלים קובעים. על המהדורה הזו רץ app.nodaro.ai, והיא לא מיועדת לאירוח עצמי.
הנתיבים בודקים את היכולות של המהדורה, לא את השם שלה: נתיב ניהול רץ רק במהדורה שיש בה ממשק ניהול, וקוד של קרדיטים רץ רק במהדורה שיש בה קרדיטים. הבדיקה באה ראשונה בנתיב, לפני כל לוגיקה אחרת. אפליקציית הדפדפן קוראת את המהדורה שלה בזמן הבנייה, מ-VITE_EDITION. ראו את הדף מהדורות ופרופילי ממשק.
סטטוס והזרמה
את הסטטוס של משימות ושל הרצות בודקים בתשאול, כל 2–5 שניות: הוא משתנה בקצב של שניות, ותשאול לא מסבך את הפריסה. פלט בהזרמה — טקסט ממודלי הטקסט, הרצות של תהליכים ופייפליינים — משתמש באירועי שרת (SSE). לכן אסור לפרוקסי הפוך שמוצב לפני Nodaro לאגור את התגובות.
למה הבחירות האלה
- Fastify — תמיכה מלאה בטיפוסים של TypeScript, בדיקת תקינות מבוססת סכמות, ותוספים שמבודדים כל נתיב בהקשר משלו.
- BullMQ — תור בשל על Redis, עם ניסיונות חוזרים, המתנה שמתארכת בין ניסיונות ובקרת מקביליות, באותו סטאק של Node.js.
- REST — הגדרה קלה של הרשאות OAuth לכל נתיב, מסמך OpenAPI שנוצר אוטומטית, ומודל פשוט ללקוחות צד שלישי.
- Supabase — Postgres, התחברות, עדכונים בזמן אמת ואבטחה ברמת השורה בשירות אחד. האבטחה ברמת השורה מחליפה הרבה קוד הרשאות ייעודי.
- React Flow — קנבס מוכח לגרפים של רכיבים, ש-Nodaro מרחיב במידה רבה.
- Remotion — קומפוזיציות React דקלרטיביות, שהרינדור שלהן בשרת זהה לתצוגה המקדימה בעורך.
- שכבת ספקים אחת — כל קריאה למודל עוברת דרך הפשטה אחת, כך שאפשר להעביר מודל לספק אחר בלי לשנות את הקוד של הפיצ׳רים.
שאלות נפוצות
באילו טכנולוגיות Nodaro בנוי?
Nodaro בנוי מאפליקציית עמוד יחיד ב-Vite וב-React 19 עם קנבס של React Flow, מ-API ב-Fastify על Node.js 22 ב-TypeScript, מתורי BullMQ על Redis, מ-Supabase ל-Postgres ולהתחברות, מאחסון תואם S3 למדיה ומ-Remotion להרכבת וידאו.
איך תהליך רץ בשרת?
ה-orchestrator טוען את התהליך, ממיין את הגרף שלו לרמות ומריץ במקביל את הרכיבים של כל רמה, עד מגבלות המקביליות. עבודה ארוכה או חיצונית עוברת דרך Redis ל-worker של המדיה ול-worker של הרינדור; קריאות טקסט מהירות ולוגיקה טהורה רצות ישירות.
אילו אסימונים ה-API של Nodaro מקבל?
ה-API של Nodaro מקבל אסימון סשן של Supabase מהעורך, אסימון גישה של OAuth מיישום מפתחים, שמתחיל ב-ndr_app_, ואסימון API אישי, שמתחיל ב-ndr_. כל אסימון ממופה למשתמש, ולאסימוני OAuth יש גם הרשאות.
כמה זמן הרצה יכולה להימשך?
כל רכיב יכול לרוץ עד 90 דקות, והרצה שלמה עד 120 דקות. רכיב שמצהיר על תקציב זמן משלו, כמו רכיב החלת רשימת עריכה, מקבל את התקציב הזה במקום, ומגבלת ההרצה גדלה באותה מידה.
איפה נמצא מסמך ה-OpenAPI של התקנה?
מסמך ה-OpenAPI נמצא בנתיב /v1/openapi.json בהתקנה שלכם. כל נקודת קצה בודקת את תקינות הקלט שלה מול סכמה, ואותן סכמות מפיקות את מסמך OpenAPI 3.1. הנתיב GET /v1/nodes מחזיר את סוגי הרכיבים שההתקנה יכולה להריץ.
דפים קשורים
הרחבת קיבולת
תרומה לפרויקט
אימות
SDK ל-TypeScript
מהדורות ופרופילי ממשק
עודכן לאחרונה