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

كيفية استضافة OneCLI ذاتيًا: Agent لكل شخص

امنح كل شخص Agent معزولًا واحفظ المفاتيح في Gateway واحدة. شغّل OneCLI على VPS باستخدام Docker Compose وPostgreSQL، مع 2 GiB لكل Sandbox.

ما تحصل عليه عند الاستضافة الذاتية لـOneCLI

استضف OneCLI ذاتياً، وسيحصل كل فرد في فريقك على agent خاص به. يعمل كل agent داخل sandbox مستقل، بينما تُحفظ مفاتيح API في gateway لا يقرأها agents مطلقاً. يتكوّن التثبيت من حزمة Docker Compose مع PostgreSQL خلفها، ويمكن الوصول إليها عبر http://localhost:10254. خطط لاستخدام خادم فعلي. الحد الافتراضي الموثق هو 2 GiB من الذاكرة لكل sandbox خاص بـagent، لذلك خصص ذاكرة منفصلة للحزمة الأساسية وللاستهلاك الفعلي للذاكرة من جانب agents.

تتضمن هذه الحزمة ثمانية مكونات. ومعرفة وظيفة كل مكون تجعل قراءة بقية هذا الدليل أسهل.

  • لوحة الويب (Next.js)، على المنفذ 10254. إنشاء agents، والدردشة، وتحرير الذاكرة والمهارات، والاتصالات والأسرار.
  • خادم API، على المنفذ 10256. طبقة التحكم: قاعدة البيانات، ومعالجة المحادثات، وقوائم العمل.
  • بوابة Rust، على المنفذ 10255. تعترض الطلبات الصادرة من agents وتحقن بيانات الاعتماد.
  • Runner. يصفه README بأنه المكون الذي «يبدأ sandboxes الخاصة بـagents ويوقفها ويزيلها. ولا يسمح إلا بالاتصالات الصادرة، ولا يلمس قاعدة البيانات مطلقاً».
  • Sandbox Supervisor. يصفه README بأنه يعمل «داخل كل sandbox، ويتحدث عبر واجهة harness محايدة تجاه المورّد، بحيث يمكن تبديل runtime الخاص بـagent».
  • منهي SSH، على المنفذ 10257. يسميه README «بوابة SSH الأمامية»: ينهي اتصالات SSH باستخدام شهادات قصيرة العمر يصدرها API، ويربط كل جلسة بـsandbox الخاص بـagent. يعمل تحت ملف التعريف runner نفسه المستخدم مع runner.
  • محوّل القنوات. خدمة daemon تتصل بتطبيق Slack، بحيث يجيب agent في القنوات والرسائل المباشرة باسمه.
  • PostgreSQL. يشغّل ملف compose المرفق postgres:18-alpine مع وحدة تخزين pgdata.

الاسم يوحي بأداة CLI، لكن المنتج خادم

OneCLI منصة خوادم. يوحي الاسم بأداة سطر أوامر تثبّتها على حاسوب محمول، لكن هذا التصور لا ينطبق على ما يشرحه هذا الدليل. يوجد عميل منفصل لسطر الأوامر في المستودع onecli/onecli-cli، وهو يمرّر حركة مرور وكيل برمجي محلي عبر بوابة. أما ما تنشره هنا فهو تطبيق ويب متعدد المستخدمين: نظام حسابات يضم المؤسسات والدعوات، وقاعدة بيانات للمحادثات والأسرار، ومشغّل يبدأ الحاويات.

نموذج المستخدم المنفصل هو أساس التصميم كله. يذكر README: «تنشئ وكيلاً لكل شخص، وتمنح كل وكيل صلاحيات الوصول التي يحتاج إليها، ويعمل الوكيل في بيئة معزولة ويمرّر حركة المرور عبر بوابة تحقن بيانات الاعتماد وتفرض سياستك». لكل وكيل نظام ملفات وshell خاصان به، وصفحة محادثة خاصة به، وذاكرة تحتفظ بها المنصة، ومهارات تكتبها مرة واحدة. تعمل بيانات الاعتماد هنا بعكس الإعداد المعتاد. بدلاً من نسخ مفتاح API إلى بيئة كل شخص، تخزّن المفتاح مرة واحدة وتمنحه للوكلاء المسموح لهم باستخدامه.

ما يحتاجه الخادم قبل البدء

  • Docker، مع إضافة Compose بإصدار 2.24.0 أو أحدث. يستخدم ملف Compose المرفق تعيينات env_file اختيارية مع required: false، ويدعمها Docker بدءاً من الإصدار 2.24.0. توضّح تعليقات الترحيل فيه أن الحد الأدنى المذكور، وهو 2.19، يوفّر دعماً للاعتماديات التي تُنفّذ مرة واحدة ضمن up --wait، لكنه لا يشمل ملفات البيئة الاختيارية التي يستخدمها الملف.
  • الذاكرة، فهي القيد الفعلي. اقرأ قسم تحديد الحجم أدناه قبل اختيار الخطة.
  • منافذ loopback متاحة: 10254 و10255 و10256 و10257 و5432. المنفذ 10257 هو مدخل SSH، ويبدأ باستخدام ملف التعريف runner الذي يفعّله هذا الدليل.

لا تحتاج إلى تثبيت PostgreSQL بنفسك، لأن ملف Compose يشغّله كخدمة. يحتاج معالج الإعداد أدناه إلى Node.js وpnpm على الخادم المضيف. ويتطلب العمل على الشيفرة نفسها أيضاً استخدام mise لتثبيت سلسلة الأدوات، بما في ذلك Rust الخاص بالبوابة.

كم عدد بيئات العزل للوكلاء التي يمكن أن يستضيفها VPS لديك؟

تعرض وثائق المشغّل أرقاماً فعلية بدلاً من التخمينات. تُحدَّد ذاكرة كل بيئة عزل بحد أقصى قدره 2048 MB (RUNNER_SANDBOX_MEMORY_MB)، وتستخدم CPU واحداً (RUNNER_SANDBOX_CPUS)، وتسمح بـ512 عملية (RUNNER_SANDBOX_PIDS). حدّ التزامن هو 4 (RUNNER_MAX_SANDBOXES)، وتوصي الوثائق بتوفير نحو 10 GiB من الذاكرة الحرة، إضافةً إلى الذاكرة التي تستخدمها المكوّنات الأساسية، لتحقيق هذا الحد.

رسم بيانيAgent memory budgets per box, using the documented 2 GiB cap
البيانات وراء هذا الرسم البياني
[
  {
    "plan": "2 GB box",
    "ram_gb": 2,
    "sandbox_slots": 0
  },
  {
    "plan": "4 GB box",
    "ram_gb": 4,
    "sandbox_slots": 1
  },
  {
    "plan": "8 GB box",
    "ram_gb": 8,
    "sandbox_slots": 3
  },
  {
    "plan": "16 GB box",
    "ram_gb": 16,
    "sandbox_slots": 7
  },
  {
    "plan": "32 GB box",
    "ram_gb": 32,
    "sandbox_slots": 15
  }
]

هذه الأعداد حسابية وليست نتيجة اختبار أداء: إجمالي الذاكرة، مطروحاً منه نحو 2 GB المفترضة لـPostgreSQL والخدمات الأخرى طويلة التشغيل، مقسوماً على حد الذاكرة البالغ 2 GiB لكل بيئة عزل. وبناءً على ذلك، تتيح ميزانية 2 GB box تشغيل 0 بيئات عزل عند بلوغ كل منها حد الذاكرة الكامل؛ ويعني الصفر عدم وجود ميزانية لتشغيل بيئة عند الحد الكامل وفق هذه الافتراضات، ولا يعني أن Docker يرفض بدء تشغيل وكيل. توفّر 16 GB box مساحة لـ7، وهي أعلى بفارق مريح من حد التزامن الافتراضي البالغ 4، كما تتجاوز نحو 10 GiB من الذاكرة الحرة التي تطلبها وثائق المشغّل. تنقلك 32 GB box إلى 15. يتطلب تشغيل أكثر من أربع بيئات في الوقت نفسه أيضاً رفع RUNNER_MAX_SANDBOXES.

يؤثر عاملان في هذا الحساب. لا تدخل بيئة العزل في وضع الخمول ما دام فيها process يعمل في الخلفية، ولذلك تحتفظ بموضعها باستمرار. هذا يعني أن عليك تحديد حجم RUNNER_MAX_SANDBOXES وفق الحمل المستمر، لا وفق أكثر دقيقة ازدحاماً. تضع المنصة حداً لذلك: يحتفظ كل مشغّل افتراضياً بحد أقصى قدره RUNNER_MAX_SANDBOXES ناقص واحد من بيئات العزل التي تبقى نشطة (ولا يقل العدد أبداً عن واحد). ويمكن تجاوز ذلك باستخدام MAX_HELD_AWAKE_SANDBOXES عبر API. بعد تجاوز الحد، يزيل المشغّل بيئة العزل الأطول خمولاً، ويبلّغ عن process الذي كان يراقبه باعتباره مفقوداً. يعتمد استهلاك الذاكرة وCPU على نوع العمل. تُحدَّد كل بيئة عزل بحد أقصى قدره CPU واحد، لذلك يمكن لأربعة وكلاء مشغولين استخدام أربع أنوية. لكن إعداد الذاكرة البالغ 2 GiB هو حد أقصى، وليس حجزاً مسبقاً: لا تستهلك أربعة وكلاء خاملين لكنهم نشطون تلقائياً 8 GiB.

إعدادات المشغّل التي قد ترغب في تغييرها
  • RUNNER_MAX_SANDBOXES (الافتراضي 4): عدد بيئات العزل التي تعمل في الوقت نفسه.
  • RUNNER_SANDBOX_MEMORY_MB (الافتراضي 2048): حد الذاكرة لكل بيئة عزل.
  • RUNNER_SANDBOX_CPUS (الافتراضي 1): حد CPU لكل بيئة عزل.
  • RUNNER_SANDBOX_PIDS (الافتراضي 512): حد العمليات لكل بيئة عزل.
  • RUNNER_NETWORK_INTERNAL (الافتراضي true): يُبقي شبكة بيئة العزل بلا مسار إلى الخارج. اتركه مفعّلاً.
  • RUNNER_SANDBOX_NETWORK (الافتراضي onecli-sandboxes): الشبكة التي تنضم إليها بيئات العزل.
  • RUNNER_RECONCILE_SECONDS (الافتراضي 60): عدد المرات التي يصالح فيها المشغّل الحالة.
  • RUNNER_ORPHAN_GRACE_SECONDS (الافتراضي 3600): المدة التي بعدها تُدمَّر الحاويات وvolumes اليتيمة.
  • RUNNER_AGENT_IMAGE: يتجاوز صورة بيئة العزل، التي تتبع ONECLI_VERSION في الحالة العادية.

تثبيت OneCLI باستخدام Docker Compose

يكتب التسلسل الخام في وثيقة الاستضافة الذاتية من upstream ثلاثة أسرار في docker/.env بجانب ملف Compose. لكنه لا يتضمن رمز runner، ومجموعة Docker socket، وبيانات اعتماد SSH التي تتطلبها الخدمات التي يفعّلها. لذلك شغّل معالج الإعداد قبل بدء المكدس.

git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --wait

اقرأ ذلك المقطع قبل تشغيله. علامة heredoc غير مقتبسة، لذلك تنفّذ shell كل head -c 32 /dev/urandom | base64 وتكتب الناتج بدلاً من النص الحرفي. SECRET_ENCRYPTION_KEY هو مفتاح AES-256-GCM لكل سر في قاعدة البيانات. GATEWAY_INTERNAL_SECRET يصادق gateway لدى API. BETTER_AUTH_SECRET يوقّع ملفات تعريف ارتباط الجلسات. COMPOSE_PROFILES=runner هو السطر الأهم، لأن خدمة runner تعمل خلف profile في Compose. إذا حذفته، يبدأ المكدس بحالة سليمة، لكن لا تبدأ أي بيئة sandbox للوكيل.

ينتظر --wait تشغيل الخدمات أو وصولها إلى الحالة السليمة، وانتقال تبعية migrations بنجاح. لذلك تكون قيمة الخروج غير الصفرية أول إشارة إلى وجود مشكلة. بعد ذلك، افحص ما بدأ فعلياً.

docker compose ps
docker compose logs migrations

ثبّت الإصدار. يضبط ONECLI_VERSION الوسم لجميع الخدمات دفعة واحدة، وتتبع صورة agent sandbox هذا الوسم ما لم يوجّه RUNNER_AGENT_IMAGE إلى مكان آخر. استخدم رقم الإصدار وحده. لا تتضمن وسوم الصور المنشورة بادئة v. في 1 November 2026، كان الإصدار الحالي هو v2.17.0، وقد نُشر في 31 October 2026. أضفه إلى الملف نفسه، ثم استخدم مسار الترقية الموثّق لكي تنتقل بيئات sandbox قيد التشغيل إلى تلك الصورة أيضاً.

echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd docker

يتوفر أيضاً برنامج تثبيت هو curl -fsSL https://onecli.sh/install | sh، ويكتب إعداداته في ~/.onecli/.env وينفّذ العمل نفسه. يضبط ONECLI_VERSION=latest أثناء تشغيله، وهذا يتجاوز التثبيت المحدد في ملف .env وحده. يتيح مسار Compose قراءة كل ملف قبل تشغيل أي شيء، ولذلك استخدمه على خادم يشغّل مكدسات Compose أخرى مسبقاً. تُجري إعدادات checkout المذكورة أعلاه الترقية باستخدام pnpm run setup --upgrade. يتطلب هذا المسار وجود Node.js وpnpm على المضيف. كما يتطلب العمل على الشيفرة نفسها mise وRust من أجل gateway، ولذلك يناسب من يعتزمون تعديل OneCLI. بالنسبة إلى Kubernetes، أُضيفت Helm chart في الإصدار v2.11.0 (8 October 2026). وتشغّل chart الحالية بيئات agent sandbox كـJobs مع وحدات تخزين دائمة، من دون Docker daemon، وتوثّق الأسرار المطلوبة وإعدادات قاعدة البيانات والتوجيه.

الوصول إلى لوحة التحكم من حاسوبك المحمول

يربط كل منفذ منشور في ملف Compose المرفق بالعنوان ${ONECLI_BIND_HOST:-127.0.0.1}. على VPS، يعني ذلك أن لوحة التحكم تعمل، ولا يمكن لأي شيء خارج الخادم الوصول إليها. هذا الإعداد الافتراضي صحيح. اتركه كما هو، وأنشئ نفقاً:

ssh -N -L 10254:127.0.0.1:10254 you@your-server

افتح الآن http://localhost:10254 على حاسوبك المحمول. تمر حركة الشبكة عبر اتصال SSH، لذلك لا توجد لوحة تحكم غير مشفّرة على الإنترنت العام، ولا حاجة إلى فتح منفذ إضافي في جدار الحماية.

يؤدي ضبط ONECLI_BIND_HOST=0.0.0.0 إلى نشر لوحة التحكم عبر HTTP عادي، كما ينشر PostgreSQL معها باستخدام كلمة المرور الافتراضية في ملف Compose، وهي onecli، ما لم تضبط POSTGRES_PASSWORD. وينشر أيضاً واجهة SSH الأمامية على المنفذ 10257، وهي خدمة تَركب Docker socket. إذا احتاج عدة أشخاص إلى لوحة التحكم، ضع Reverse Proxy مع TLS (أمان طبقة النقل) أمامها، واترك عنوان الربط كما هو. اضبط ONECLI_EXTERNAL_URL على عنوان HTTPS الخاص بها، واستخدم إعداد Reverse Proxy الخاص بالمشروع upstream، الذي يوجّه مسارات لوحة التحكم وAPI وgateway إلى الخدمات المعنية. لا يمنع Reverse Proxy وحده الغرباء من الوصول. توضح وثيقة الاستضافة الذاتية أن التسجيل مفتوح عمداً، ولا يوجد مفتاح لتعطيله: يمكن لأي شخص يصل إلى لوحة التحكم إنشاء حساب، ويحصل الحساب على organization خاصة به، بينما يتطلب الانضمام إلى organization الخاصة بك دعوة فقط. وتوصي الوثيقة بإبقاء لوحة التحكم خلف حدود شبكتك. إذا كان Reverse Proxy يواجه بالفعل تطبيقاتك الأخرى المستضافة ذاتياً، فإن تمرير المصادقة عبر طبقة تسجيل دخول موحّد مستضافة ذاتياً يضع لوحة التحكم خلف تسجيل الدخول الذي يستخدمه فريقك بالفعل، ولذلك يؤدي حذف شخص من مكان واحد إلى إغلاق هذا الباب أيضاً.

إنشاء الحساب الأول، ثم منحه مفتاح نموذج

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

بعد ذلك، خزّن مفتاح نموذج قبل إنشاء وكيل. يحتاج الوكيل المستضاف إلى مفتاح نموذج ممنوح، وترتيب الخطوات مهم: خزّن المفتاح في لوحة التحكم، وامنحه للوكيل، ثم ابدأ محادثة فقط بعد ذلك. إذا تخطيت عملية المنح، فلن تُشغَّل البيئة المعزولة؛ وسيرد الوكيل في سلسلة المحادثة موضحاً أنه يحتاج إلى مفتاح نموذج.

امنح الصلاحيات بأضيق نطاق. يحصل كل وكيل على الصلاحيات التي منحتها له فقط، وتفرض البوابة ذلك في كل طلب. لذلك لا يستطيع وكيل يقرأ مستودعاً واحداً الوصول إلى مفتاح موفر الدفع لديك. كما أن قائمة المنح نفسها تتيح لك التحكم في الإنفاق. فالوكيل المخصص لكل شخص، إذا كان يستطيع استدعاء أي نموذج تملكه، يؤدي إلى فاتورة مستقلة لكل شخص. لذلك من المفيد قراءة كيفية تحديد ما يمكن للوكيل إنفاقه على استدعاءات النماذج قبل منح هذه الصلاحية لعشرة وكلاء.

كيف يحافظ البوابة على إبعاد المفاتيح عن الوكلاء

البوابة هي وكيل HTTPS مكتوب بلغة Rust ويستمع على المنفذ 10255. يُضبط عميل HTTP لدى الوكيل لاستخدامها، ويحمل الوكيل بيانات اعتماد بديلة بدلاً من بيانات اعتماد حقيقية. تطابق البوابة الطلب الصادر مع الصلاحيات الممنوحة لذلك الوكيل، ثم تفك تشفير السر الحقيقي وتستبدله في الطلب، وتعيد توجيهه. تُخزَّن الأسرار في PostgreSQL مشفَّرة باستخدام AES-256-GCM (معيار التشفير المتقدم، 256 بت، ونمط غالويس/العداد)، ولا تُفك إلا وقت الطلب. تُسجَّل كل مكالمة مع هوية الوكيل والوجهة، ما يوفّر مسار تدقيق لا يمكنك الحصول عليه عندما تكون المفاتيح موجودة في ملفات shell الشخصية لعشرة أشخاص.

تحدد آليتان طريقة نشرها.

  • اعتراض HTTPS هو هجوم رجل في الوسط. تنشئ البوابة مرجعاً محلياً لإصدار الشهادات، ويثق به الوكيل، ثم تنهي البوابة اتصال TLS الخاص بالوكيل وتفتح اتصالاً جديداً مع الخدمة المصدر. لذلك يفشل الوكيل الذي لا يثق عميل HTTP لديه بمرجع إصدار شهادات البوابة بخطأ في التحقق من الشهادة، لا بخطأ في المصادقة.
  • يعرّف الوكيل نفسه باستخدام ترويسة Proxy-Authorization. على جهاز واحد، حيث يشترك الوكلاء والبوابة في شبكة Docker داخلية، لا تعبر هذه الترويسة شبكة لا تملكها. إذا وجّهت وكيلاً خارج الجهاز إلى البوابة، فاحمِ الاتصال باستخدام VPN أو نقل TLS، لأن هذه الترويسة رمز حامل؛ وتوصي الجهة الموفرة باستخدام VPN لمنفذ وكيل CONNECT الخام.

المقابل الذي يجب أخذه بجدية: تقرأ البوابة كل طلبات وكلائك بنص واضح، وهذا مقصود في تصميمها. وهي أكثر عملية حساسية على الجهاز. تعامل مع مضيفها وفقاً لذلك، وقلّل عدد الأشخاص الذين يمكنهم تسجيل الدخول باستخدام مستخدمي Linux ذوي أقل الصلاحيات.

لماذا لا يحتاج الـrunner إلى منفذ وارد

يعمل الـrunner باتصالات صادرة فقط. وفقاً لوثائقه: «لا يحتفظ بأي منافذ يمكن للعالم الخارجي الوصول إليها، لذلك يعمل حاسوب محمول أو بيئة منزلية أو VPC خلف NAT من دون وصول وارد، أو نفق، أو الحاجة إلى إنهاء TLS». يشير NAT إلى ترجمة عناوين الشبكة، وهي الوظيفة التي ينفذها موجّه الشبكة المنزلية. يتصل الـrunner بسطح التحكم ويجلب منه المهام، لذلك لا يوجد شيء لإعادة توجيهه ولا منفذ لفتحه.

يظهر أثر هذا التصميم في شبكة sandbox. يعرّف ملف compose شبكة ثانية تحمل الوسم internal: true، ما يعني في Docker عدم وجود اتصال خارجي بالشبكة. تنضم إليها بيئات sandbox. ويتصل الـgateway بالشبكتين، لذلك فهو المسار الوحيد إلى الخارج. توضّح وثائق الـrunner ذلك مباشرة: «إن وجود شبكة internal متصل بها الـgateway عبر واجهتين هو ما يجعل الخروج المسموح به عبر الـgateway حدّاً فعلياً، لا مجرد توصية». لا يستطيع agent تجاوز الـgateway بفتح اتصال مباشر بعنوان خارجي؛ إذ تظل سياسة الـgateway هي التي تقرر الطلبات المسموح بها.

تحقق من ذلك على جهازك بدلاً من الوثوق بالفقرة السابقة.

docker network ls
docker network inspect onecli-sandboxes | grep -i internal

يجب أن ترى "Internal": true. إذا كانت النتيجة false، فهذا يعني أن التحكم في الاتصالات الصادرة معطّل، وأن الـgateway عاد مجرد توصية. استخدم اسم شبكة sandbox الذي تطبعه docker network ls، لأن onecli-sandboxes ليس سوى الاسم الافتراضي.

ما مدى قوة بيئة OneCLI المعزولة؟

اقرأ هذا القسم ببطء، لأن وصف المشروع نفسه يمنح كلمة «معزولة» دلالة كبيرة، بينما توثّق وثائق runner والشفرة الخلفية الآلية الفعلية.

يذكر README أن كل agent يحصل على «بيئة معزولة خاصة به، مع نظام ملفات وshell»، ويسمي Sandbox Supervisor المكوّن الذي «يعمل داخل كل بيئة معزولة، ويتحدث عبر واجهة harness محايدة تجاه المورّد، بحيث يمكن تبديل runtime الخاص بـagent». لا تذكر أي من الجملتين مكوّنات العزل. توضح وثائق runner ذلك: الواجهة الخلفية الافتراضية هي Docker (RUNNER_BACKEND=docker)، والبيئة المعزولة عبارة عن حاوية Docker لها حد للذاكرة، وحد لوحدة المعالجة المركزية، وحد لعدد العمليات، وموصولة بالشبكة الداخلية. وتتضمن الشفرة نقطة فصل تتيح استخدام واجهات خلفية أخرى. كما تطبق شفرة runner الحالية واجهة خلفية لـKubernetes، ويستخدمها مخطط Helm لإنشاء Jobs للبيئات المعزولة ووحدات التخزين الدائمة. أما في تثبيت Compose الوارد في هذا الدليل، فالبيئة المعزولة عبارة عن حاوية Docker.

تصف وثائق runner الآن حدود Docker: يعمل agent بصفته node، مع no-new-privileges، بعد إسقاط جميع إمكانات Linux واستخدام ملف seccomp الافتراضي في Docker. ولا يركّب الـbackend داخل بيئته المعزولة إلا home الدائم الخاص بـagent. لذلك اعتمد القراءة الأضيق. الحدود المفروضة هي حدود للموارد. والشبكة الداخلية تفرض تحكماً فعلياً في الاتصالات الصادرة. ويعتمد العزل بين agent والمضيف على ضوابط الحاوية هذه، مع ملاحظة أن الحاوية تشارك نواة المضيف.

هناك حقيقة ثانية يجب أخذها في الحسبان. يركّب runner service الملف /var/run/docker.sock، لأنه يحتاج إليه لإنشاء البيئات المعزولة. ويعادل الوصول إلى socket الخاص بـDocker daemon يعمل بصلاحيات root امتلاك صلاحيات root على المضيف، لأن من يستطيع استدعاء واجهة API هذه يستطيع تشغيل حاوية مع تركيب نظام ملفات المضيف داخلها. ويستخدم runner المدعوم بـDocker والمورّد مع هذا الدليل ذلك socket. والنتيجة أن عملية runner حساسة بقدر gateway. كما يركّب SSH terminator الـsocket نفسه لكي ينفذ أوامر داخل حاويات البيئات المعزولة، وتوضح التعليقات الموجودة في ملف Compose نفسه أن هذا التركيب يعادل امتلاك صلاحيات root على المضيف. لذلك أبقِ المنفذ 10257 على loopback، ما لم يكن لديك سبب لفتحه.

تعامل مع حدود النواة المشتركة بحذر. ويعني ذلك عملياً اتباع ثلاث ممارسات.

  1. شغّل OneCLI على جهاز لا يؤدي أي مهام أخرى. لا تشغّل عليه خدمة إنتاج غير مرتبطة، أو قاعدة بيانات مشتركة، أو بيانات فريق آخر.
  2. افترض أن agent الذي يحصل على تنفيذ تعليمات برمجية عشوائية داخل بيئته المعزولة قد يصل إلى المضيف، واجعل التعامل مع هذه النتيجة ممكناً عبر الاحتفاظ بنسخ احتياطية خارج الجهاز.
  3. اقرأ apps/runner/src أو اسأل المشروع upstream قبل أن تخبر زميلاً بأن agent معزول.

للاطلاع على شكل الحدود الموثّقة، ومعرفة الأسئلة التي يجدر طرحها على المشروع upstream، قارن ذلك بـشكل حدود بيئة agent المعزولة الحقيقية. والسؤال هو ما إذا كانت الآلية الموثّقة تغطي التهديدات التي تحتاج إلى إيقافها.

انقسام التراخيص، ولماذا يجب التحقق قبل البناء

يخضع المكوّن الأساسي في OneCLI لترخيص Apache-2.0، ويُسمح باستضافته ذاتياً في بيئة الإنتاج. أما المجلدات التي تحمل الاسم ee/ فتخضع لترخيص OneCLI Enterprise License منفصل: وهي مجانية للتطوير والاختبار والتقييم، لكن استخدام الإنتاج يتطلب اشتراكاً. تشير ملاحظات الإصدار v2.0.1 الصادرة في 18 August 2026 إلى استعادة ملف ترخيص Apache-2.0 الذي يمكن لـGitHub اكتشافه، ولذلك تغيّرت الشارة في صفحة المستودع مؤخراً. تحقّق من الوسم الذي ستنشره فعلياً، ولا تعتمد على ملخص كُتب في تاريخ آخر.

cd onecli && find . -type d -name ee -not -path '*/node_modules/*'

كل ما يقع ضمن هذه المسارات هو الجزء التجاري. إذا كانت هناك ميزة تخطط للاعتماد عليها ضمنها، فتحقق من سعرها قبل أن تبني إجراءً يعتمد عليها.

الترقيات وعمليات الترحيل والملف الوحيد الذي لا يمكنك فقدانه

يجب أن تحدّث الترقيات صور الخدمة وصورة الوكيل المنفصلة، ثم تعيد تشغيل صناديق الاختبار قيد التشغيل. تعمل خدمة ترحيل لمرة واحدة قبل واجهة API في كل up، وإذا فشلت عملية ترحيل، ترفض المجموعة بدء التشغيل بدلاً من تقديم الخدمة باستخدام مخطط قاعدة بيانات مرحّل جزئياً. هذا هو السلوك المطلوب، لأن فشل الترقية سيظهر عندئذٍ كتعطل، لا كتلف صامت، ويوضح docker compose logs migrations السبب.

من السهل تفويت خطوة واحدة. تحذّر وثيقة الاستضافة الذاتية من الترقية باستخدام docker compose pull && docker compose up -d مجرد، لأن صورة صندوق اختبار الوكيل ليست خدمة Compose. بل هي قيمة RUNNER_AGENT_IMAGE على عامل التشغيل، ولذلك لا يرى docker compose pull هذه القيمة، وقد تبقى الوكلاء المستضافون على صورة صندوق اختبار قديمة من دون تحذير. حدّث نسخة المستودع، وغيّر قيمة التثبيت، ثم شغّل أداة الترقية الموثقة؛ فهي تسحب صورة صندوق الاختبار وتعيد تشغيل صناديق الاختبار قيد التشغيل.

cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrations

استبدل 2.17.0 بالإصدار الذي تنتقل إليه. تؤدي إعادة تشغيل صناديق الاختبار إلى مقاطعة العمل الجاري، لكن مساحة العمل الدائمة لكل وكيل تبقى محفوظة.

إذا ثبّت البرنامج باستخدام سكربت التثبيت بدلاً من ذلك، فأعد تشغيل ذلك السكربت بدلاً من السحب يدوياً، حتى يبقى ملف Compose متوافقاً مع الصور التي يشير إليها. صدّر ONECLI_VERSION أولاً إذا أردت إصداراً محدداً، لأن السكربت يستبدل قيمة التثبيت المحفوظة في ملف .env فقط.

أنشئ نسخة احتياطية من قاعدة البيانات والإعدادات ووحدات تخزين مساحات عمل الوكلاء. يحتفظ PostgreSQL بالوكلاء والمحادثات والذاكرة والأسرار المشفّرة. يحتوي ملف docker/.env على SECRET_ENCRYPTION_KEY، ومن دون ذلك المفتاح لا يمكن قراءة الأسرار المشفّرة، حتى إذا استُعيد باقي محتوى قاعدة البيانات. توجد قيمة /workspace الخاصة بكل وكيل على وحدة تخزين دائمة منفصلة، وتحتاج إلى نسختها الاحتياطية الخاصة.

cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backup

احتفظ بهذه النسخ ونسخ مساحات العمل الاحتياطية خارج الخادم. هذا هو الإجراء نفسه الذي تحتاج إليه أي مجموعة Compose تحفظ حالة، لذلك إذا كنت تنفّذ بالفعل نسخاً احتياطية وترقية لمجموعة Docker Compose وفق جدول زمني، فأضف وحدات تخزين قاعدة البيانات والإعدادات ومساحات العمل إليها، ولا تشغل بالك بالأمر بعد ذلك.

عندما لا يعمل

  • لا تصبح الحزمة سليمة أبداً، ويخرج docker compose up -d --wait بحالة غير صفرية. اقرأ docker compose logs migrations أولاً، لأن واجهة API تنتظر هذه الخدمة عمداً.
  • يبقى أحد الوكلاء خاملاً ولا تظهر أي بيئة معزولة. تحقق من أن COMPOSE_PROFILES=runner موجود في docker/.env، وأن docker compose ps يعرض مشغّلاً. ثم تحقق من أن الوكيل يملك مفتاح نموذج ممنوحاً، لأن البيئات المعزولة لا تبدأ من دونه.
  • لا توجد خانات متاحة. القيمة الافتراضية لـRUNNER_MAX_SANDBOXES هي 4، وتشغل البيئة المعزولة التي تعمل فيها عملية خلفية خانتها حتى يطردها الحد الأقصى لفترة إبقائها مستيقظة. يعرض docker ps ما يعمل فعلياً.
  • لا تبدأ الحزمة، ويبلغ Docker بأن منفذاً قيد الاستخدام. عند تفعيل ملف التعريف runner، تحتاج بوابة SSH الأمامية إلى 10257 بالإضافة إلى المنافذ الأربعة الأخرى.
  • تختفي الحاويات، أو يصبح المضيف بطيئاً جداً. تحقق من نفاد الذاكرة باستخدام dmesg -T | grep -i oom؛ إذ يسمح حد الذاكرة الافتراضي لبيئة معزولة واحدة باستخدام ما يصل إلى 2048 MB.
  • تفشل طلبات HTTPS التي يرسلها أحد الوكلاء بسبب أخطاء التحقق من الشهادة، لا بسبب أخطاء المصادقة. لا يثق عميل HTTP لديه بسلطة الشهادات الخاصة بالبوابة.
  • تبقى حاويات أو وحدات تخزين قديمة بعد حذف وكيل. يجري المشغّل المطابقة كل 60 ثانية ويدمر العناصر اليتيمة الأقدم من RUNNER_ORPHAN_GRACE_SECONDS، وقيمته الافتراضية 3600، لذا انتظر ساعة قبل اعتبار ذلك تسرّباً.

هل هذا هو الخيار المناسب لتشغيله؟

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

بالنسبة إلى شخص واحد، هذه بنية كبيرة من دون فائدة حقيقية. ستشغّل PostgreSQL وcontrol plane وgateway وrunner لتوفير agent واحد لنفسك، بينما تكاد مشكلة بيانات الاعتماد التي يحلّها gateway غير موجودة عندما تكون أنت وحدك من يملك المفتاح. شغّل harness واحداً على جهاز أصغر بدلاً من ذلك: harness واحد لـagent على VPS ينفّذ المهمة نفسها باستخدام جزء من الذاكرة. إذا لم تكن قد اخترت اتجاهاً بعد، فسيكون الاستطلاع في مقارنة بين agents ذاتية الاستضافة خطوة أولى أقل تكلفة. وإذا كان الجزء غير المألوف هو agents نفسها لا الخوادم التي تشغّلها، فابدأ بـمسار تدريجي لتعلّم كيفية عمل agents فعلياً، لأن فهمك لما يفعله استدعاء الأداة ومخزن الذاكرة فعلياً هو ما يحدد الصلاحيات التي ينبغي أن يحصل عليها agent كل شخص.

FAQ

ما الحد الأدنى لمتطلبات الخادم للاستضافة الذاتية لـ OneCLI؟

تحتاج إلى Docker مع Compose plugin بإصدار 2.24.0 أو أحدث، وإلى Node.js وpnpm لمعالج الإعداد المستخدم هنا، وإلى ذاكرة كافية. يأتي PostgreSQL مع ملف compose، لذلك لا تحتاج إلى تثبيته بشكل منفصل. تحدد الذاكرة الخطة: يضع runner حداً أقصى قدره 2048 MB لكل agent sandbox افتراضياً، وتطلب وثائقه نحو 10 GiB من الذاكرة الحرة فوق المكدس الأساسي لتشغيل الحد الافتراضي البالغ أربعة sandboxes. وفق ميزانية المكدس الأساسي البال 2 GB المفترضة في المخطط، يخصص خادم بسعة 4 GB مساحة لـsandbox واحد عند حده الأقصى، بينما يغطي خادم بسعة 16 GB حد التزامن الافتراضي. هذه أرقام للتخطيط، وليست متطلبات دنيا مقاسة أو تخصيصات ثابتة للذاكرة.

هل يحتاج OneCLI إلى PostgreSQL، أم يمكنه استخدام SQLite؟

يحتاج إلى PostgreSQL. توثّق DATABASE_URL على أنها سلسلة اتصال PostgreSQL، ويشغّل ملف compose المرفق postgres:18-alpine مع وحدة تخزين pgdata، كما تطبّق خدمة migrations منفصلة المخطط قبل بدء API. لا يوجد خيار موثّق لاستخدام SQLite. عند استخدام خادم PostgreSQL خارجي، اضبط خدمتي API وmigrations لاستخدامه؛ إذ يضبط ملف compose المرفق سلاسل اتصالهما على خدمة PostgreSQL المضمّنة فيه.

هل يُعد agent sandbox في OneCLI حداً أمنياً حقيقياً؟

تتمثل آلية Compose الموثّقة في حاوية Docker مع حدود للذاكرة ووحدة المعالجة المركزية والعمليات، ومتصلة بشبكة تحمل العلامة internal: true، بحيث تمر الاتصالات الخارجية عبر gateway. التحكم في الاتصالات الصادرة فعلي، ويمكنك التحقق منه باستخدام docker network inspect. يعمل agent بصفة node، مع no-new-privileges، ومع إسقاط جميع إمكانات Linux واستخدام ملف seccomp الافتراضي في Docker، مع استمرار مشاركة نواة النظام المضيف. يركّب كل من runner وSSH terminator الملف /var/run/docker.sock، وهذا يعادل صلاحيات root على مضيف يستخدم Docker daemon بصلاحيات root. شغّل OneCLI على خادم مخصص، واحتفظ بالنسخ الاحتياطية خارج ذلك الخادم.

هل أحتاج إلى فتح أي منافذ واردة لـOneCLI؟

لا. يعمل runner باتصالات صادرة فقط ولا يحتفظ بأي منافذ يمكن للعالم الخارجي الوصول إليها، لذلك يعمل خلف NAT من دون نفق. يربط ملف compose لوحة المعلومات وgateway وAPI وPostgreSQL، وكذلك بوابة SSH الأمامية على المنفذ 10257 ضمن profile runner، بالعنوان 127.0.0.1 افتراضياً. يمكنك الوصول إلى لوحة المعلومات عبر نفق SSH، أو استخدام إعداد reverse proxy من upstream مع TLS والمسارات المطلوبة للوحة المعلومات وAPI وgateway إذا احتاج عدة أشخاص إلى الوصول إليها، مع تذكّر أن التسجيل يظل مفتوحاً لأي شخص يستطيع الوصول إليه. يُستخدم gateway على المنفذ 10255 مع agents، وعلى خادم واحد تصل هذه agents إليه عبر شبكة Docker الداخلية.

هل استخدام OneCLI داخل الشركة مجاني؟

النواة مرخّصة بموجب Apache-2.0، ويُسمح باستخدامها ذاتياً في بيئة الإنتاج من دون ترخيص تجاري. تخضع الأدلة التي تحمل أسماء ee/ لترخيص OneCLI Enterprise License، وهو مجاني للتطوير والاختبار والتقييم، لكنه يتطلب اشتراكاً في بيئة الإنتاج. يتغير هذا الفصل بين الإصدارات، وتذكر ملاحظات الإصدار v2.0.1 بتاريخ 18 August 2026 استعادة ملف ترخيص Apache-2.0 الذي يمكن لـGitHub اكتشافه، لذلك تحقّق من LICENSE والأدلة ee/ في الوسم exact tag الذي ستنشره قبل بناء سير عمل يعتمد على أي ميزة منفردة.

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