SSD Nodes Learn Hosting plans →
الأدلة Matt Connorبقلم Matt Connor

استضافة Rakazo ذاتياً على VPS خطوة بخطوة

شغّل Rakazo على VPS مع Node 22 وpnpm وPostgres وGraphile Worker عبر Docker Compose، وتعرّف إلى اختيار sandbox وإدارة المفاتيح ومتطلبات العتاد الواقعية.

ما الذي يشغّله Rakazo فعلياً عند الاستضافة الذاتية

تعني الاستضافة الذاتية لـRakazo تشغيل خمسة مكونات على خادم Linux واحد: PostgreSQL، وعملية Graphile Worker، وواجهة API، وتطبيق الويب، وحاوية sandbox تعمل كحاسوب للروبوتات. Rakazo بديل مفتوح المصدر عن Grok Bot، نشره elie222 بموجب ترخيص Apache 2.0. يحصل كل روبوت على محادثاته وذاكرته وروتيناته وسجلّه الخاص، ويشارك Team Computer واحداً مع الروبوتات الأخرى في مساحة العمل ما لم تخصّص له Private Computer، ويمكنه إنشاء نظراء أو subagents قصيرة العمر. إذا كانت كلمات مثل الذاكرة وsubagent واستدعاء الأداة تؤدي وظيفة غير مألوفة في هذه الجملة، فمن المفيد تخصيص فترة بعد الظهر أولاً لقراءة مسار تدريجي يشرح كيفية عمل الوكلاء فعلياً، لأن معظم الإعدادات أدناه لا تصبح مفهومة إلا عندما تتصور ما يفعله الروبوت عند استيقاظه.

ولهذا السبب تحديداً يجب تشغيله على VPS (خادم خاص افتراضي)، لا على جهاز مكتبي. فالروبوت الذي يحتفظ بالذاكرة وينفذ المهام المجدولة يجب أن يكون قابلاً للوصول أثناء نومك. وعندما يدخل الحاسوب المحمول في وضع السكون، تتوقف قائمة الانتظار.

لا يزال Rakazo يصف نفسه بأنه إصدار تجريبي حتى October 2026، رغم أنه ينشر الآن إصدارات بأرقام مستقرة. لذلك تعامل معه باعتباره إعداداً عملياً، لا جهازاً مكتمل التجهيز. المكدس مكتوب بالكامل بلغة TypeScript: React 19 وVite لتطبيق الويب، وHono لواجهة API، وPostgres مع Prisma، وBetter Auth للحسابات، وGraphile Worker للمهام الخلفية. يخزّن Graphile Worker قائمة الانتظار داخل Postgres، لذلك لا تحتاج إلى تشغيل Redis أو مخزن بيانات ثانٍ. يضبط .env.example قيمة WAKEUP_DRIVER=graphile، ما يعني أن استيقاظ الروبوت هو مهمة مدعومة بواسطة Postgres. أوقف Postgres، فتتوقف معه كل إجراءات الروبوت المجدولة. إذا كنت تفضّل تجميع وكيل من مكونات منفصلة بدلاً من تشغيل منتج طوّره طرف آخر، فالمسار الآخر هو بناء وكيلك الخاص من المكونات.

لماذا لن تكفي خطة بسعة 1 GB

احسب عدد العمليات. Postgres عملية واحدة. وواجهة API هي عملية Node. والعامل عملية ثانية. وتطبيق الويب عملية ثالثة. ومشرف sandbox عملية رابعة. ثم يأتي حاسوب bots: افتراضياً، توجد حاوية Team Computer مشتركة واحدة تحتوي على سطح مكتب Linux رسومي، مع شاشة X وعملية Chrome منفصلتين لكل bot نشط.

لم تعد وثيقة الاستضافة الذاتية للمشروع تحدد حجم المضيف. فالوثيقة الموجودة في v0.3.5، والتي تم التحقق منها في 27 أكتوبر 2026، تسرد متطلبات البرامج فقط. لكنها تحدد حداً أقصى لكل computer: مع Docker sandboxes، تكون RAKAZO_COMPUTER_MEMORY افتراضياً 2g وتكون RAKAZO_COMPUTER_CPUS هي 2. ينطبق هذا الحد على كل computer، وليس على كل bot. تحصل كل مساحة عمل على Team Computer واحد افتراضياً، ويشغّل كل Team bot نشط سطح المكتب والمتصفح الخاصين به داخله، لذلك تتشارك جميعها 2 GB ونواتين. لا يحصل على حاوية وحد أقصى خاص به إلا bot الذي تنقله إلى Private Computer. اضبط SANDBOX_PROVIDER=docker، وستنتقل أسطح المكتب هذه إلى VPS الخاص بك فوق control plane، ولذلك تكون 4 GB حداً أدنى لا هدفاً. ابدأ بسعة 8 GB إذا كنت تخطط لإبقاء أكثر من bot واحد قيد التشغيل، وارفع RAKAZO_COMPUTER_MEMORY حتى يتمكن computer المشترك فعلياً من استخدام تلك الذاكرة، وقِس العدد الفعلي باستخدام docker stats أثناء عمل bots. المتصفح داخل sandbox هو ما يرفع استهلاك الذاكرة، لذلك لن تخبرك ورقة المواصفات بالحجم المطلوب. ولمنع جهاز صغير من تشغيل عدد كبير من المتصفحات في الوقت نفسه، اضبط SANDBOX_TEAM_SCREEN_LIMIT على قيمة موجبة تحدد عدد أسطح المكتب النشطة على Docker Team Computer. وتترك 0 المضمّنة هذا العدد غير محدود. وإذا كانت الذاكرة محدودة إجمالاً، فإن RAKAZO_COMPUTER_MEMORY تقبل أيضاً قيمة أصغر مثل 1536m. أما الطريقة العامة لتحديد حجم جهاز لأعمال agents، فتشرح مقدار RAM وCPU الذي يحتاج إليه VPS فعلياً لتشغيل agent القياس بالتفصيل.

يوجد إعداد واحد يمنع تفاقم الوضع. تأتي .env.example مع SANDBOX_IDLE_MS=600000، ويذكر التعليق فيها أن computers يتم إيقافها مؤقتاً أو إيقافها بعد عدد محدد من milliseconds من الخمول. بعد عشر دقائق من الخمول، يختفي computer. الحد الأدنى للقيمة المقبولة هو 30000، وتعطّل القيمة 0 وضع السكون عند الخمول. ويقترح التعليق نفسه استخدام 0 في Docker self-hosts، حيث لا تكلّف computer الخاملة شيئاً، حتى تبقى التطبيقات والجلسات طويلة التشغيل متاحة. ينطبق ذلك على التكلفة، لا على الذاكرة. على VPS صغير، أبقِ المؤقت مفعّلاً، لأن كل computer شغّلته وكل متصفح داخله سيستمران في العمل بدونه.

تُحتسب مساحة القرص أيضاً. تشترك صورة sandbox ووحدات Node ووحدة تخزين Postgres في قرص واحد، لذلك تُعد سعة 40 GB نقطة بداية مناسبة.

ثبّت الإصدار قبل الاستنساخ

يتطور Rakazo بسرعة، وmain ليس إصداراً. اعتباراً من 9 November 2026، فإن v0.8.0، المنشور في 4 November 2026، هو الإصدار المعلَّم Latest. يظل هذا الدليل مثبتاً على v0.3.5، المنشور في 25 October 2026.

git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout f31e3c0699f086d663637c4107858c238a086fb3
git log -1 --format='%H %ci'

يشير ذلك الالتزام إلى ما تحدده v0.3.5. ثبّت الالتزام بدلاً من الفرع أو الوسم. يتغير الفرع عند git pull التالي، والوسم تسمية قابلة للتحريك يمكن للمشرف إعادة توجيهها، لذلك لا يحدد أيٌّ منهما شجرة يمكنك العودة إليها. لا يمكن تغيير معرّف الالتزام. دوّن معرّفك بجانب معلومات الخادم الأخرى، لأن الحل السريع والرخيص عند تسبب الترقية في عطل هو git checkout <old commit> وإعادة البناء، وهذا لا ينجح إلا إذا عرفت أي التزام كان يعمل. يصف README المثبّت Rakazo بأنه إصدار تجريبي، لذلك يستحق هذا التثبيت الدقيق الجهد البسيط. يمكن تثبيت مشروع ذي سجل طويل من الإصدارات المقصودة على وسم منشور بدلاً من ذلك، وهذا ما يفعله مكدس أصغر للاستضافة الذاتية مثل openGym.

المتطلبات: Node 22 وpnpm 9 وDocker

node -v
pnpm -v
docker --version

يعرّف package.json كلاً من "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" } و"packageManager": "pnpm@9.15.0". لذلك يجب أن يطبع node -v الإصدار v22.22.2 أو إصداراً أحدث من السلسلة 22.x، أو أي v24، أو الإصدار v26 أو أحدث. الإصدار v22 الأقدم من 22.22.2 خارج هذا النطاق، ويذكر README صراحةً أن Node.js 23.x و25.x غير مدعومين. ثبّت إصدار Node مدعوماً من NodeSource أو nvm. يأتي Corepack مع Node 22 و24. أما في Node 26 وما بعده، فثبّته أولاً باستخدام npm install -g corepack. ثم فعّل pnpm:

corepack enable
corepack prepare pnpm@9.15.0 --activate

يغطي Docker Engine مع إضافة compose بقية المتطلبات. تتطلب وثائق الاستضافة الذاتية Docker Engine بإصدار 26 أو أحدث، وواجهة API بإصدار 1.45 أو أحدث، لاستخدام المسارات الفرعية لوحدة تخزين الدليل الرئيسي للروبوت، إضافةً إلى curl وOpenSSL. يجب أن يتمكن مستخدمك أيضاً من الوصول إلى البرنامج الخفي. إذا أجاب docker ps بـpermission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock، فأضف مستخدمك إلى المجموعة docker وافتح shell جديداً لتسجيل الدخول. اعرف أولاً ما تمنحه هذه الصلاحية: تعادل العضوية في docker امتلاك صلاحيات root على الجهاز، لأن أي مستخدم في هذه المجموعة يستطيع تشغيل حاوية تربط نظام ملفات المضيف.

اضبط .env، ثم شغّل Postgres

cp .env.example .env
chmod 600 .env

يجب تغيير عدة قيم قبل بدء أي شيء. يوزّع .env.example القيم BETTER_AUTH_SECRET=replace-with-32-plus-character-secret وENCRYPTION_KEY=replace-with-64-random-hex-characters وSCREEN_PROXY_SECRET=replace-with-32-plus-character-screen-proxy-secret وSANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token، ويترك POSTGRES_PASSWORD وPOSTGRES_APP_PASSWORD فارغتين. كل عنصر نائب من هذه العناصر منشور في المستودع، لذلك فإن النشر الذي يُبقي أحدها يعمل باستخدام سر يمكن لأي شخص قراءته. عيّن قيمة عشوائية مستقلة لكل عنصر. يجب أن يتكوّن ENCRYPTION_KEY من 64 محرفاً سداسياً عشوائياً، وهذا بالضبط ما يطبعه openssl rand -hex 32. تتطلب الأسرار الأخرى 32 محرفاً أو أكثر، لذلك شغّل سطر base64 مرة لكل سر. وبالنسبة إلى كلمتي مرور Postgres، تطلب وثيقة الاستضافة الذاتية قيماً آمنة للاستخدام في URL، ويوفّرها لك السطر الأخير، لذلك شغّله مرة لكل كلمة مرور أيضاً. تحتوي قاعدة البيانات على حسابي تسجيل دخول. يأتي DATABASE_MIGRATION_URL مضبوطاً على postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo، وهو الحساب المالك الذي يشغّل عمليات الترحيل، ويأتي DATABASE_URL مضبوطاً على postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo، وهو حساب التطبيق نفسه، ولا يملك صلاحيات superuser ويخضع لأمان على مستوى الصفوف. ضع كل كلمة مرور في URL مستقلة. ينشئ pnpm db:migrate حساب rakazo_app باستخدام كلمة المرور التي عيّنتها.

openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24

بعد ذلك شغّل قاعدة البيانات وحدها، ثم نفّذ عمليات الترحيل.

docker compose --env-file .env -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.postgres-host.yml up postgres -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:build

ينشئ pnpm sandbox:build صورة حاسوب الروبوت، المعرّفة في package.json على أنها docker build -t rakazo/computer:local infra/sandboxes/computer. إنها صورة رسومية، لذلك يجلب البناء الأول كمية كبيرة من البيانات ويستغرق وقتاً. تأكد من اكتمالها باستخدام docker image ls rakazo/computer، الذي يجب أن يطبع صفاً واحداً.

لا ينشر ملف Compose الأساسي أي منفذ لـPostgres. تنشر طبقة docker-compose.postgres-host.yml في ذلك الأمر المنفذ على 127.0.0.1:5433، وهو مقيّد بواجهة loopback فقط، لذلك تستطيع أدوات المضيف مثل pnpm db:migrate وpnpm dev الوصول إليه. اتركه بهذه الطريقة. يرفض Compose تشغيل Postgres من دون POSTGRES_PASSWORD في .env، لكن إتاحة منفذ Postgres عبر الإنترنت تعرّضه لهجمات تخمين كلمات المرور. يقرأ ملف Compose الخاص بالإنتاج المتغير نفسه، ولا ينشر أي منفذ لقاعدة البيانات.

التشغيل الأول

pnpm dev

يشغّل ذلك أربعة مكونات: API على المنفذ 3100، وGraphile Worker، وتطبيق الويب Vite على 5173، ومشرف sandbox على 7091 افتراضياً. إذا كانت هذه المنافذ مشغولة، يحدد pnpm dev كتلة حرة أخرى ويطبع عناوين URL. عند استخدام المنافذ الافتراضية، يتوفر التطبيق على http://127.0.0.1:5173، وينبغي أن تظهر لك صفحة تسجيل الدخول.

على VPS، لا تكون جالساً أمام ذلك الجهاز، ولا ينبغي أن تنشر المنفذ 5173 للوصول إليه. بدلاً من ذلك، أعد توجيه المنافذ عبر SSH (secure shell) من جهازك.

ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-server

انتبه إلى الفرق بين طرق تشغيل هذا النظام. يشغّل pnpm dev Vite على المضيف مع ربطه محلياً. تنشر خدمة web في ملف compose الخاص بالتطوير 127.0.0.1:5173:5173، وتنفّذ خدمتها api 127.0.0.1:3100:3100، وكلتاهما متاحتان عبر loopback فقط، لذلك يعمل النفق نفسه معها. في ملف الإنتاج، لا ينشر تطبيق الويب أي منفذ على المضيف، ولا يعرّض المنفذ 5173 إلا للحاويات على شبكاته الخاصة، بينما ينشر Caddy وحده المنفذين 80 و443. لذلك استخدم ملف الإنتاج وReverse Proxy الخاص به لأي شيء تتركه قيد التشغيل.

أي موفّر sandbox آمن على خادم؟

هذا هو الإعداد الأهم الذي يجب ضبطه بشكل صحيح. SANDBOX_PROVIDER في .env هو docker افتراضياً، كما يدعم checkout المثبّت Railway إلى جانب الموفّرات المدرجة في مستند الاستضافة الذاتية.

  • docker هو الإعداد الافتراضي. تعمل حواسيب البوتات كـcontainers على جهازك، وتُبنى من الصورة التي ينتجها الأمر pnpm sandbox:build، ثم تعمل تحت إشراف supervisor. تشترك بوتات مساحة العمل افتراضياً في Team Computer واحد، ولا يحصل البوت على container خاص به إلا عند استخدام Private Computer. لا تحتاج إلى حساب E2B.
  • e2b يشغّل حواسيب البوتات على E2B ويتطلب E2B_API_KEY. عند v0.3.5 يقبله المصنع في الإنتاج عند توفير المفتاح، من دون قيد NODE_ENV. ويذكر مستند الاستضافة الذاتية أنه مناسب لبيئات الإنتاج العامة أو متعددة المستخدمين، لأنه يُبقي حواسيب البوتات بعيدة عن المضيف الذي يشغّل API وقاعدة بياناتك.
  • daytona وcreateos وboat موفّرات بعيدة إضافية، ويتطلب كل منها مفتاحه الخاص: DAYTONA_API_KEY أو CREATEOS_SANDBOX_API_KEY أو BOAT_API_KEY.
  • railway يشغّل الحواسيب على Railway ويتطلب RAILWAY_API_TOKEN وRAILWAY_ENVIRONMENT_ID محدداً بشكل صريح على API وworker. استخدم مشروع Railway أو بيئة مخصصة لـsandboxes.
  • desktop يشغّل أوامر البوت مباشرة على مضيف API وworker، وفقاً لما يذكره المستند. عند v0.3.5 يرفضه API وworker ما لم يكن NODE_ENV هو development أو test، لكن .env.example يضمّن NODE_ENV=development، ولذلك يظل الخادم الذي يشغّل pnpm dev يقبله. لا تفعّله على خدمة عامة أو مشتركة.
  • fake محاكي مخصص للتحقق فقط. وليس بيئة تشغيل.
  • none يشغّل المنتج من دون أي مضيف للحاسوب.

تعامل مع ذلك حرفياً. لا يوجد في وضع سطح المكتب أي حد عزل على الإطلاق، ولذلك ينفّذ البوت أوامر shell بصفة المستخدم الذي يشغّل عملية API، مع الدليل الرئيسي لذلك المستخدم، ومفاتيح SSH الخاصة به، وبيانات اعتماد السحابة الخاصة به، و.env الخاص به. يتحول النص الموجود في صفحة ويب يقرأها البوت إلى أمر على خادمك. استخدام وضع سطح المكتب على خادم هو ما يجعل البوت ينتهي إلى امتلاك بيانات اعتمادك. استخدمه على جهاز تجلس أمامه، أو لا تستخدمه مطلقاً. يؤدي تبديل الموفّرات إلى وضع container حول مسار صفحة الويب بدلاً من إغلاقه، كما أن منح البوت واجهة بحث SearXNG خاصة به يغطي سطح الحقن نفسه من جهة البحث.

يشكّل docker حداً حقيقياً بين البوتات ومضيفك، لكنه يشكّل حداً ضعيفاً بين البوتات نفسها. فهي تشترك افتراضياً في Team Computer واحد، ويذكر مستند بيئة تشغيل الحاسوب أن بوتات Team تشترك في مستخدم نظام التشغيل ومساحة العمل وملفات تعريف المتصفح ووصول shell وX11، وأن مجلدات كل بوت تنظّم العمل لكنها ليست حدوداً أمنية. لذلك يمكن لأي بوت في Team قراءة ملفات بوت آخر في Team. يجب وضع البوت الذي يحتاج إلى عزل خاص به على Private Computer، حيث يشغّله موفّر docker كـcontainer شقيق منفصل على شبكته الخاصة. لكن supervisor الذي ينشئ تلك الـcontainers يربط /var/run/docker.sock، ويذكر مستند الاستضافة الذاتية ذلك بوضوح: الوصول إلى تلك socket يعادل التحكم في مضيف Docker. لذلك أبقِ supervisor خاصاً. يتعامل .env.example مع SANDBOX_SUPERVISOR_TOKEN بصفته بيانات اعتماد مخصصة، منفصلة عن BETTER_AUTH_SECRET، وتتطلبها Docker sandboxes خارج التطوير المحلي، ويأتي معها placeholder يمكن لأي شخص قراءته على GitHub. امنحه قيمة عشوائية خاصة به. ولأقوى فصل متاح هنا، استخدم e2b، أو امنح Rakazo جهازاً لا يحتوي على أي شيء آخر. وهذا هو المنطق نفسه وراء تشغيل وكلاء البرمجة في VM مؤقتة: أرخص طريقة للنجاة من ارتكاب وكيل لخطأ هي أن تكون قيمة جهازه معدومة.

أين تُحفظ مفاتيح واجهة برمجة تطبيقات النماذج؟

تظل فوترة أرصدة النماذج الاختيارية في Rakazo متوقفة ما لم تُضبط سريتا Stripe كلتاهما. أنت توفّر المفتاح. يضبط .env.example قيمة PI_DEFAULT_PROVIDER=openrouter، لذلك يكون OPENROUTER_API_KEY هو المكان المعتاد، وتعمل مفاتيح المزوّدين عبر الإعداد نفسه.

احتفظ بالمفتاح في .env، ولا تضعه في أي ملف تلتزم به في المستودع. يمرّر أمرا compose في المستودع --env-file .env، لذلك تصل القيم إلى الحاويات من دون كتابتها في ملفات YAML التي يتتبعها git. يمكنك أيضاً ترك OPENROUTER_API_KEY فارغاً وربط نموذج من داخل التطبيق بعد التسجيل، وهذا سبب إضافي يجعل ENCRYPTION_KEY يحتاج إلى قيمة عشوائية حقيقية بدلاً من القيمة النائبة المضمّنة مع البرنامج.

اضبط حدّاً للإنفاق على المفتاح لدى المزوّد قبل أن يستخدمه أي روبوت. فالروبوت الذي يدخل في حلقة يواصل الإنفاق. يوفّر Rakazo أيضاً MAX_TOOL_CALLS_PER_TURN: اضبطه على عدد صحيح موجب لإيقاف الجولة مؤقتاً عند تجاوز ميزانية استدعاءات الأدوات، مع الاستمرار في إنشاء رسالة نهائية من المساعد. إذا كانت القيمة غير مضبوطة أو فارغة أو تساوي 0، فلن يكون هناك حد. يحسب هذا الإعداد استدعاءات الأدوات، وليس المال، لذلك لا يحل محل حدّ الإنفاق الذي يفرضه المزوّد. امنح هذا المفتاح اسماً خاصاً به حتى تتمكن من إبطاله وحده. إذا كنت تجهّز هذا لفريق بدلاً من إعداد شخصي، فإن بوابة OneCLI واحدة أمام وكيل الجميع تقدم حلاً مختلفاً للمشكلة نفسها، لأنها تحتفظ بمفاتيح المزوّدين في مكان واحد بدلاً من مفتاح لكل شخص.

الانتقال من وضع التطوير إلى إعداد يمكنك تركه قيد التشغيل

يتضمن المستودع ملف Compose للإنتاج يشغّل Postgres وواجهة API والعامل وتطبيق الويب وCaddy لشهادات TLS (أمان طبقة النقل) التي يحصل عليها تلقائياً. Caddy هو الخدمة الوحيدة التي تنشر المنافذ في هذا الملف. ويستخدم E2B افتراضياً لأجهزة الروبوت. أما التراكب الاختياري، infra/compose/docker-compose.prod.docker.yml، فيشغّل أجهزة Docker محلية ضمن الحزمة نفسها، ويحذّر المستند من أن المشرف الذي يضيفه يملك صلاحيات مكافئة لـroot على المضيف.

sudo --preserve-env=SSH_CONNECTION DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  build --build-arg GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  up -d --wait --pull never
curl --fail https://app.example.com/health

أنشئ حساب deploy لا يسمح إلا بالمفاتيح، وتأكد من قدرتك على تسجيل الدخول إليه قبل تشغيل البرنامج النصي. يعطّل harden-host.sh تسجيل الدخول عبر كلمة مرور SSH وتسجيل الدخول إلى root، ويحدّ من معدل اتصالات SSH، ويضيف السماح بـSSH وHTTP وHTTPS عبر UFW (جدار الحماية غير المعقد)، مع الحفاظ على قواعد الشبكة الخاصة الحالية، ويفعّل fail2ban وتحديثات الأمان غير التفاعلية وAppArmor وقواعد التدقيق. يرفض التشغيل من دون SSH_CONNECTION، ولذلك يمرر الأمر هذه القيمة عبر sudo، كما يتراجع عن تغيير جدار الحماية ما لم تؤكده من جلسة SSH جديدة خلال ثلاث دقائق. اقرأه قبل تشغيله، لأنه يغيّر طريقة تسجيل الدخول إليك ويعيد تحميل SSH. أبقِ وحدة تحكم مزود الخدمة مفتوحة حتى ينجح تسجيل دخول SSH جديد.

يتطلب ملف .env للإنتاج إعداداً يتجاوز إعداد التطوير. ويسرد مستند التشغيل الذاتي هذا الحد الأدنى، بالإضافة إلى الأسرار.

NODE_ENV=production
RAKAZO_HOST=app.example.com
BETTER_AUTH_URL=https://app.example.com
WEB_ORIGIN=https://app.example.com
API_URL=https://app.example.com
SIGNUPS_ENABLED=true
SIGNUP_ALLOWLIST=you@example.com
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
WAKEUP_DRIVER=graphile
DATA_DIR=/data
RAKAZO_DEPLOY_DIR=/srv/rakazo
RAKAZO_IMAGE_TAG=local
POSTGRES_PASSWORD=<random, URL-safe>
POSTGRES_APP_PASSWORD=<random, URL-safe>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<64 random hex characters>
SCREEN_PROXY_SECRET=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>

وجّه سجلاً من نوع A إلى الخادم قبل أول up. يطلب Caddy شهادة للاسم الموجود في RAKAZO_HOST؛ ويجب أن يُحل هذا الاسم إلى هذا الخادم، وأن يكون المنفذ 80 للتحقق عبر HTTP أو المنفذ 443 للتحقق عبر TLS-ALPN متاحاً من خارج الشبكة. ويكون كلا التحديين مفعّلاً افتراضياً، لذلك لا يمنع إغلاق المنفذ 80 وحده إصدار الشهادة عبر المنفذ 443.

أبقِ SIGNUP_ALLOWLIST مضبوطاً على عنوانك أنت منذ البداية. يتضمن .env.example الإعداد SIGNUPS_ENABLED=true، وتُقرأ القيمتان من البيئة عند كل بدء لواجهة API، لذلك فإن مثيلاً متاحاً على اسم عام مع تفعيل التسجيلات ومن دون قائمة سماح سيقبل تسجيلات أي شخص يعثر عليه. وتُطبَّق قائمة السماح غير الفارغة عند كل بدء، وتستبدل القائمة المخزنة. ويتطلب التسجيل المسموح به التحقق من صندوق البريد، بما في ذلك الحساب الأول، لذلك أعدد تسليم البريد الإلكتروني قبل التسجيل. ومن دون البريد الإلكتروني، يوصي المستند بالبدء باستخدام SIGNUPS_ENABLED=false وإنشاء حسابك عبر أمر التمهيد من جهة الخادم الذي يورده، ما ينشئ حساباً عادياً تم التحقق منه من دون صلاحيات على الخادم. ابدأ بقائمة السماح. ويمكنك تخفيفها لاحقاً إذا أردت. وإذا كنت تشغّل عدة خدمات على الخادم نفسه وتفضّل الاحتفاظ بقائمة واحدة للأشخاص بدلاً من قائمة سماح لكل تطبيق، فإن وضع مثيل Authentik أمامها ينقل هذا القرار إلى الـproxy، لكنه يعمل أمام حسابات Better Auth الخاصة بـRakazo بدلاً من استبدالها.

اعتبر docs/self-host.md في المستودع المرجع المعتمد لإعدادات الإنتاج، لأنه يتغير مع تغيّر الشيفرة بينما لا يتغير هذا الدليل. وبما أن Compose يتولى التنفيذ، تنطبق القواعد المعتادة، وتوضح أساسيات Docker Compose لخادم VPS سبب ازدياد أهمية --env-file والأحجام المسماة عندما تصبح الحزمة شيئاً تتركه دون تدخل لأشهر.

النسخ الاحتياطية

تحتوي Postgres ومجلد data/ على بيانات المثيل في هذا الإعداد. وتتطلب الاستعادة أيضاً ENCRYPTION_KEY وأي مفاتيح رئيسية لمحتوى مشفّر جرى إعدادها. لذلك احتفظ بنسخ خارج الخادم.

./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMP

يفرّغ backup.sh قاعدة بيانات Postgres ويؤرشف data/. يعمل restore.sh على مكدس Compose الخاص بالتطوير، داخل قاعدة بيانات فارغة ومع إيقاف خدمات التطبيق، ولا يقرأ ملفات النسخ الاحتياطية الخاصة بالإنتاج. على جهاز تعتمد عليه، ثبّت infra/compose/backup-prod.sh بوصفه /usr/local/sbin/rakazo-backup مع المؤقت الذي يوفّره المستودع. يكتب تفريغاً تم التحقق منه وأرشيفاً لبيانات التطبيق إلى /var/backups/rakazo. ويحتفظ افتراضياً بما يصل إلى ثلاث لقطات تم التحقق منها، ويُحدَّد ذلك بواسطة RAKAZO_BACKUP_KEEP، ضمن حد أقصى قدره 50 GiB يحدده RAKAZO_BACKUP_MAX_GB. كما يحذف اللقطات غير المكتملة والسجل الزائد قبل كل تشغيل، لذلك تتم عملية التدوير تلقائياً. ويمكنه أيضاً تشفير كل نسخة احتياطية باستخدام age إلى جهات الاستلام العامة التي تدرجها في /etc/rakazo/backup.env، بحيث يكتب الخادم نسخاً احتياطية لا يستطيع قراءتها. أنشئ زوج المفاتيح على جهاز تتحكم فيه، واحتفظ بالمفتاح الخاص خارج الخادم. عند عدم تحديد جهات استلام، تبقى النسخة الاحتياطية بنص واضح ويُسجّل تحذير. لكن بعد إنشاء أول نسخة احتياطية مشفّرة، يفشل أي تشغيل من دون جهات استلام ما لم تسمح صراحةً بالنص الواضح باستخدام RAKAZO_BACKUP_ALLOW_PLAINTEXT=1. النسخة الاحتياطية الموجودة على القرص نفسه الذي يحتوي على قاعدة البيانات ليست نسخة احتياطية. لذلك انسخها إلى خارج الجهاز. ثم استعدها مرة واحدة على خادم احتياطي قبل أن تحتاج إليها.

سبب فشلها وما ستراه

لا يستطيع pnpm db:migrate الوصول إلى قاعدة البيانات. تفيد عملية الترحيل بأنها لا تستطيع الوصول إلى خادم قاعدة البيانات على 127.0.0.1:5433. إما أن حاوية Postgres لا تعمل، أو أنها تعمل لكنها لم تصبح جاهزة بعد، أو أنها شُغِّلت من دون تراكب docker-compose.postgres-host.yml، وهو الذي ينشر المنفذ 5433 على المضيف. شغّل docker compose --env-file .env -f infra/compose/docker-compose.yml ps وابحث عن خدمة postgres وهي تفيد بأنها سليمة، لأن ملف compose يزوّدها بفحص صحة يعمل كل ثلاث ثوانٍ. إذا أعيد تشغيل الحاوية في حلقة، فاقرأ سجلاتها: ترفض حزمة Compose المثبتة بدء التشغيل باستخدام وحدة تخزين قديمة لـPostgres 16 إلى أن تُرحَّل إلى Postgres 18. يمسح docker compose ... down -v ذلك، ويحذف البيانات معه.

المنفذ مستخدم مسبقاً. يفشل تشغيل Postgres مع bind: address already in use عندما يحتفظ شيء آخر بالمنفذ 5433، وغالباً ما تكون حزمة Rakazo أقدم نسيت إيقافها. يحدّد sudo ss -lntp | grep 5433 العملية. يقرأ التراكب منفذ المضيف من POSTGRES_HOST_PORT، لذلك يمكنك تغييره، ما دام DATABASE_URL وDATABASE_MIGRATION_URL يتغيران معه.

لا يحصل أحد الروبوتات على حاسوب. عند استخدام SANDBOX_PROVIDER=docker ومن دون صورة rakazo/computer:local، لا يوجد شيء يمكن تشغيله. يوضح docker image ls rakazo/computer ذلك في سطر واحد، ويعالجه pnpm sandbox:build. إذا تعذّر على المشرف الوصول إلى مقبس Docker، فلن يتمكن من إنشاء الحاويات أيضاً، وتذكر الرسالة المسار: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.

يتوقف أمر طويل في منتصف التنفيذ. يضبط .env.example القيمة SANDBOX_COMMAND_TIMEOUT_MS=300000، لذلك يُوقَف أمر واحد داخل حاسوب الروبوت بعد خمس دقائق. ارفع هذه القيمة عند تنفيذ عمليات بناء بطيئة، بدلاً من افتراض أن البيئة المعزولة تعطّلت.

يتعطّل pnpm install بطرق مربكة. افحص node -v قبل أي شيء آخر. يعلن workspace عن ^22.22.2 || ^24.0.0 || >=26.0.0، لذلك تكون الإصدارات 23.x و25.x وأي إصدار 22.x أقدم من 22.22.2 خارج النطاق. يحدد .npmrc القيمة engine-strict=true، لذلك يرفض pnpm install إصدار Node غير المدعوم بخطأ في المحرك أو الإصدار قبل تشغيل تعليمة تبعيات التطبيق.

ينجح تسجيل الدخول محلياً، لكنه لا ينجح عبر النطاق. يجب أن تتطابق BETTER_AUTH_URL وWEB_ORIGIN وAPI_URL جميعاً مع الأصل العام نفسه الظاهر في شريط العنوان، بما في ذلك المخطط. يكون وجود قيمة قديمة في http://127.0.0.1:5173 في أحدها هو السبب المعتاد لعدم استمرار الجلسة.

تحديث نسخة مسحوبة ومثبتة

مسار الترقية في وثيقة الاستضافة الذاتية لمكدس Compose إنتاجي مبني من نسخة مسحوبة من مستودعك قصير: اسحب المصدر الجديد، ثم أعد بناء API وworker وتطبيق الويب وأعد تشغيلها. تُجرى عمليات الترحيل عند بدء API، لأن أمر بدء التشغيل يطبّقها قبل أن يبدأ في خدمة الطلبات.

sudo /usr/local/sbin/rakazo-backup
git fetch --all --tags
git checkout NEW_COMMIT_SHA
export GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  up -d --wait --pull never --build api worker web

أنشئ نسخة احتياطية أولاً. تتقدم عمليات الترحيل إلى الأمام، ولا يوفّر الإصدار التجريبي مسار تراجع يمكن الاعتماد عليه. إذا كانت نسخة المستودع المسحوبة أقدم من 30 August 2026، ويشمل ذلك الالتزام v0.1.0-beta، فاقرأ ملاحظة الوثيقة حول عملية الترحيل 20260830200000_space_scope_names_and_user_credentials قبل الترقية. هذه عملية انتقال منسقة، لذلك أوقف API وworker القديمين أولاً، وشغّل فحص حدّ الخصوصية في Space الذي توضحه الوثيقة. عند الترقية من نسخة مسحوبة تسبق تسجيل الدخول المنفصل للتطبيق، عيّن POSTGRES_APP_PASSWORD في .env قبل إعادة البناء؛ إذ يرفض ملف Compose الإنتاجي البدء من دونه. تستخدم أيضاً ملفات Compose الخاصة بنسخة المصدر المسحوبة وبالإنتاج Postgres 18: ويحتاج تثبيت Postgres 16 الموجود إلى إجراء infra/compose/upgrade-postgres.sh الوارد في الوثيقة قبل أن يبدأ بالتخطيط الجديد. اقرأ الالتزامات الواقعة بين SHA المثبت لديك وSHA الجديد قبل تطبيقها، لأن مشروعاً حديثاً إلى هذا الحد قد يعيد تسمية متغيرات البيئة من دون إعلان، ويظهر المتغير المفقود على هيئة خدمة تبدأ ثم تخرج. إذا كنت لا تزال تقرر ما إذا كان Rakazo هو الخيار المناسب للتشغيل أصلاً، فإن ملخص وكلاء الذكاء الاصطناعي المستضافين ذاتياً يوضح ما الخيارات الأخرى الموجودة ضمن هذه الفئة وما تكلفة إبقاء كل منها قيد التشغيل.

FAQ

هل يمكنني تشغيل Rakazo على VPS بسعة 1 GB؟

لا. تعمل Postgres وAPI والعامل ومشرف sandbox وتطبيق الويب في الوقت نفسه. ومع SANDBOX_PROVIDER=docker، يضيف حاسوب الروبوت حاوية تحتوي على سطح مكتب رسومي، مع شاشة X وعملية Chrome منفصلتين لكل روبوت نشط، وكل ذلك ضمن حد افتراضي واحد يبلغ 2 GB من الذاكرة ووحدتي CPU. لا تحدد وثيقة الاستضافة الذاتية في v0.3.5 حجم المضيف. اعتبر 4 GB الحد الأدنى لطائرة التحكم، واستخدم سعة أكبر عندما تعمل أسطح المكتب على جهازك.

هل موفّر سطح المكتب المعزول آمن على الخادم؟

لا. توضح وثيقة الاستضافة الذاتية أن desktop ينفّذ الأوامر مباشرة على مضيف API والعامل، لذلك يعمل الروبوت بهوية المستخدم الذي يشغّل تلك العملية، وتكون ملفات ذلك المستخدم وبيانات اعتماده متاحة له. عند v0.3.5، يرفض API والعامل استخدامه خارج وضع التطوير والاختبار، لكن الخادم الذي يعمل على pnpm dev يكون في وضع التطوير ويقبله. أبقه بعيداً عن أي خادم عام أو مشترك. استخدم docker لمنح الروبوت Private Computer عندما يجب ألا يشارك الملفات مع روبوتات مساحة العمل الأخرى، أو e2b عندما يسجّل أكثر من شخص الدخول.

ما إصدار Rakazo الذي ينبغي أن أثبّته؟

اعتباراً من 9 November 2026، أحدث إصدار هو v0.8.0، المنشور في 4 November 2026 والمعلَّم Latest. لمتابعة هذا الدليل، تحقّق من الالتزام v0.3.5 المثبّت، وهو f31e3c0699f086d663637c4107858c238a086fb3، بدلاً من تتبّع main أو الإصدار التمهيدي لشهر August v0.1.0-beta. يتحرك الفرع، ويمكن إعادة توجيه الوسم، لذلك لا يحدد أيٌّ منهما شجرة يمكنك العودة إليها. سجّل الالتزام، لأن التراجع لا يكون ممكناً إلا عندما تعرف أيّاً منها كان يعمل.

أين أضع مفتاح OpenRouter API؟

ضعه في .env بالقيمة OPENROUTER_API_KEY، ولا تضعه مطلقاً في ملف compose تلتزم به في المستودع. يمرّر أمرا compose في المستودع --env-file .env، لذلك تصل القيمة إلى الحاويات من دون كتابتها في YAML المتتبَّع. يمكنك أيضاً تركه فارغاً وربط نموذج في التطبيق بعد التسجيل. حدّد سقفاً للإنفاق على المفتاح لدى الموفّر، لأن الروبوت العالق في حلقة سيواصل استدعاء النموذج إلى أن يوقفه شيء ما.

هل أحتاج إلى اسم نطاق وTLS؟

نعم، لأي استخدام يتجاوز الاختبار الأول. يشغّل ملف compose الخاص بالإنتاج Caddy ويحصل على الشهادات تلقائياً. اضبط RAKAZO_HOST على اسم المضيف العام، واضبط BETTER_AUTH_URL وWEB_ORIGIN وAPI_URL على مصدر HTTPS العام نفسه. لإلقاء نظرة أولى، يمكنك تجاوز النطاق: شغّل pnpm dev وأعد توجيه المنفذ 5173 عبر SSH بدلاً من نشره.

هل كان هذا المقال مفيدًا؟