التواصل بين الخدمات: العناوين الداخلية والخدمات الداخلية فقط.
كيف تصل خدمات التطبيق الواحد إلى بعضها عبر العنوان الداخلي، ومتغيرات RIVERVO_<NAME>_URL، والخدمات دون عنوان عام، والنسخ المتعددة، والمهل وإعادة المحاولة مع أمثلة لـ Node.js وLaravel وPython.
تتواصل خدمات التطبيق الواحد مع بعضها مباشرة، دون المرور عبر الإنترنت. يمكن للموقع استدعاء واجهة API الخاصة به، ويمكن للعامل استدعاء خدمة داخلية — وهذه الحركة مجانية: لا تُحتسب ضمن حركة المرور.
تستخدم الأمثلة أدناه خدمتي ويب: web، الموقع الذي يفتحه الزوار، بـ عنوان عام، وapi، التي لا يستدعيها إلا web والخدمات الأخرى، مضبوطة على داخلي فقط.
العنوان الداخلي
لكل خدمة ويب — بعنوان عام أو داخلية فقط — عنوان داخلي بالصيغة http://<service-name>:<port>، مثل http://api:8080. يظهر في صفحة الخدمة وفي نظرة عامة للتطبيق، مع زر نسخ وتلميح «تصل إليها الخدمات الأخرى في هذا التطبيق هنا — دون إنترنت ودون رسوم حركة مرور.»
- المنفذ هو 8080 للخدمة المبنية من مستودع، أو المنفذ الذي حددته للخدمة المبنية من صورة جاهزة.
- لا تصل إلى هذا العنوان إلا خدمات التطبيق نفسه. ولا يُفتح من الإنترنت ولا من تطبيقات أخرى.
- يستخدم العنوان
http://. يبقى الاتصال داخل التطبيق، فلا حاجة إلى إعداد شهادة.
متغيرات بالعناوين
لا تحتاج إلى نسخ العناوين إلى شيفرتك. تحصل كل خدمة شيفرة في التطبيق — خدمات الويب والعمّال الخلفيون والمهام المجدولة — على متغير بالعنوان الداخلي لـ كل خدمة ويب أخرى في التطبيق:
RIVERVO_<NAME>_URL=http://<name>:<port>
NAME هو اسم الخدمة بأحرف كبيرة، مع تحويل الشرطات إلى _:
| الخدمة | المتغير |
|---|---|
api | RIVERVO_API_URL=http://api:8080 |
admin-api | RIVERVO_ADMIN_API_URL=http://admin-api:8080 |
web | RIVERVO_WEB_URL=http://web:8080 |
search (من صورة جاهزة، المنفذ 7700) | RIVERVO_SEARCH_URL=http://search:7700 |
- لا تحصل الخدمة على متغير لنفسها.
- تحتفظ قواعد البيانات وValkey بمتغير
RIVERVO_<NAME>_URLالخاص بها مع عنوان الاتصال. وأسماء الخدمات فريدة داخل التطبيق، فلا تتعارض الأسماء أبدًا. - تُعرض المتغيرات في تبويب المتغيرات ضمن المتغيرات المضبوطة تلقائيًا. وكما هي الحال مع كل متغير تلقائي، يحل محله متغير خاص بك (أو متغير مشترك) يحمل الاسم نفسه — راجع متغيرات البيئة.
- تصل المتغيرات إلى الخدمة مع نشرها التالي. عند إضافة خدمة ويب جديدة أو إعادة تسمية خدمة، تحصل الخدمات الأخرى على المتغير الجديد أو المعدّل في نشرها التالي. أعد نشرها لتلتقطه، مثلًا بالأمر
rivervo deploy <app> --no-build— فهو يشغّل النسخة العاملة مجددًا بالمتغيرات الجديدة، دون بناء جديد.
الخدمات الداخلية فقط
خدمة الويب التي لا تستدعيها إلا خدمات أخرى في التطبيق — واجهة API خلف موقعك، أو واجهة إدارة خلفية، أو محرك بحث — لا تحتاج إلى أن تكون على الإنترنت. اضبطها على داخلي فقط:
| عنوان عام | داخلي فقط | |
|---|---|---|
عنوان على الإنترنت https://<name>.rivervo.app | نعم | لا |
| نطاقاتك الخاصة | نعم | لا |
| معاينات الفروع | نعم | لا |
| عنوان داخلي للخدمات الأخرى | نعم | نعم |
| النسخ المتعددة والتوسع التلقائي والسجلات والمراقبة وفحوص السلامة | نعم | نعم |
تعمل الخدمة الداخلية فقط مثل أي خدمة أخرى؛ والفرق أن خدمات التطبيق نفسه وحدها تصل إليها.
الاختيار عند إنشاء خدمة
عند إنشاء خدمة ويب — بما فيها أول خدمة في تطبيق جديد، من مستودع أو قالب أو صورة جاهزة — اختر عنوان عام أو داخلي فقط. لا يوجد خيار محدد مسبقًا، فالقرار دائمًا لك. والعمّال الخلفيون والمهام المجدولة وقواعد البيانات ليس لها عنوان عام أبدًا، لذا لا خيار لها.
الخدمات التي أُنشئت قبل توفر هذا الخيار تحتفظ بعنوانها العام.
التبديل لاحقًا
الخدمة ← الإعدادات ← العنوان العام: بدّل المفتاح وأكّد. لا يستطيع تغييره إلا مسؤول التطبيق أو مالك الحساب. ولا يُعاد تشغيل أي شيء.
- التبديل إلى داخلي فقط يُرفض ما دامت للخدمة نطاقات مرتبطة — احذفها أولًا من تبويب النطاقات فيها. ويجب إيقاف المعاينات أولًا أيضًا.
- إعادة تفعيل العنوان العام تمنح الخدمة العنوان نفسه
https://<name>.rivervo.app. وقد تستغرق الشهادة نحو دقيقة. - تُرفض إضافة نطاق إلى خدمة داخلية فقط — فعّل عنوانها العام أولًا.
يعمل تبويب الطرفية في الخدمة الداخلية فقط كما في أي خدمة أخرى.
التواصل غير المتزامن
الاستدعاءات أعلاه تنتظر ردًا. عندما ينبغي للخدمة أن تسلّم العمل وتواصل — المهام الخلفية، أو الأحداث التي تتفاعل معها عدة خدمات — أرسل الرسائل بدلًا من ذلك عبر طابور أو وسيط رسائل: Valkey أو NATS أو RabbitMQ. راجع الأحداث والطوابير.
النسخ المتعددة
عندما تعمل الخدمة التي تستدعيها بعدة نسخ، يقود اسمها الداخلي إلى جميع نسخها العاملة، وتتوزع الاتصالات عليها.
العميل الذي يُبقي اتصالاته مفتوحة ويعيد استخدامها (مجموعة اتصالات keep-alive) قد يواصل إرسال طلباته إلى النسخة نفسها؛ أما الاتصالات الجديدة فتتوزع من جديد. هذا أمر طبيعي ولا يحتاج إلى إعداد.
المهل وإعادة المحاولة
أثناء النشر، أو عندما يوقف التوسع التلقائي نسخة، قد يفشل طلب قيد التنفيذ. عادتان تجعلان الاستدعاءات بين الخدمات موثوقة:
- مهلة قصيرة — بضع ثوانٍ، حتى لا يتعلق الاستدعاء أبدًا بينما تتوقف النسخة التي وصل إليها.
- إعادة المحاولة مرة أو مرتين مع توقف قصير، للطلبات الآمنة للتكرار — قراءة البيانات بـ
GET. لا تكرر الطلبات التي تغيّر البيانات (المدفوعات والطلبات) ما لم تكن واجهة API لديك قادرة على التمييز بين الطلب المكرر والطلب الجديد.
مثال: Node.js
const api = process.env.RIVERVO_API_URL
async function getWithRetry(url, attempts = 3) {
for (let i = 1; ; i++) {
try {
const res = await fetch(url, { signal: AbortSignal.timeout(5000) })
if (res.status < 500 || i === attempts) return res
} catch (err) {
if (i === attempts) throw err
}
await new Promise((resolve) => setTimeout(resolve, 200 * i))
}
}
const res = await getWithRetry(`${api}/orders`)
const orders = await res.json()مثال: Laravel
ضع العنوان في config/services.php:
'api' => [
'url' => env('RIVERVO_API_URL'),
],ثم اقرأه بـ config(). ففي بيئة الإنتاج تُخزَّن الإعدادات مؤقتًا، وenv() المستدعاة خارج ملفات الإعدادات لا تُعيد شيئًا:
use Illuminate\Support\Facades\Http;
$orders = Http::timeout(5)
->retry(2, 200)
->get(config('services.api.url').'/orders')
->json();timeout(5) تنتظر 5 ثوانٍ كحد أقصى؛ وretry(2, 200) تُجري حتى محاولتين بفاصل 200 ms بينهما.
مثال: Python
import os
import requests
API = os.environ["RIVERVO_API_URL"]
orders = requests.get(f"{API}/orders", timeout=5).json()مع إعادة المحاولة لطلبات GET:
import os
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
API = os.environ["RIVERVO_API_URL"]
session = requests.Session()
retry = Retry(total=2, backoff_factor=0.2, allowed_methods=["GET"], status_forcelist=[502, 503, 504])
session.mount("http://", HTTPAdapter(max_retries=retry))
orders = session.get(f"{API}/orders", timeout=5).json()يُكرَّر طلب GET الفاشل — بسبب خطأ اتصال أو رد 502 أو 503 أو 504 — حتى مرتين، مع توقف قصير يطول في كل مرة.
من سطر الأوامر وRivervo MCP
- يعرض
rivervo appsوتفاصيل الخدمة العنوان الداخلي لكل خدمة ويب وما إذا كان لها عنوان عام. rivervo services set-public <service> on|offيبدّل العنوان العام. ويتطلب دور المسؤول ورمزًا بمستوى وصول كامل.- في Rivervo MCP يتم التبديل نفسه بالأداة
set_public_address.
راجع أدوات المطوّرين للرموز وسطر الأوامر.