# مرحّل الدفع

> كيف يوقظ Octa Pass الهواتف لتزامن. ما مرحّل الدفع، وما يحمله إشعار الدفع، وما يستطيع المرحّل وApple وGoogle رؤيته، وكيف تشغّل مرحّلًا خاصًا بك.

Source: https://octap.app/ar/docs/self-hosting/push-relay/
Status: beta
Project: Octa Pass

:::caution[مبني، ولم يُشغَّل مع Apple أو Google بعد]
مزامنة الدفع والمرحّل مكتملان ومختبَران من البداية إلى النهاية على جهاز واحد، مقابل بدائل تحاكي خدمات الدفع لدى Apple وGoogle. لم يُرسَل شيء عبر الخدمات الحقيقية بعد، ومرحّل Octa Pass لا يعمل. وإلى أن يعمل، يحتاج الدفع إلى مرحّل تشغّله أنت ببيانات اعتماد Apple وGoogle الخاصة بك، وإلى تطبيقات تبنيها بها.
:::

لا يوقظ تطبيقَ الهاتف إلا ناشرُه: تسلّم Apple وGoogle إشعارات الدفع المرسلة ببيانات اعتماد من ينشر التطبيق. وخادم Octa Pass المستضاف ذاتيًا لا يملكها، فيطلب من **مرحّل الدفع** (push relay)، وهو خدمة صغيرة تحتفظ بها، أن يمرّر إشارة الإيقاظ. ثم يزامن الهاتف مع خادمك كما يفعل دائمًا.

الدفع متوقف ما لم تشغّله بـ [`OCTAPASS_PUSH_RELAY=true`](https://octap.app/ar/docs/self-hosting/configuration/#مزامنة-الدفع). ومن دونه تزامن الهواتف عندما تفتح التطبيق وما دام مفتوحًا.

## ما يحمله إشعار الدفع

كلمة واحدة، ولا شيء غيرها:

| الكلمة | متى | ما يفعله الهاتف |
|---|---|---|
| `sync` | تغيّر شيء في خزنة يستطيع الحساب رؤيتها، أو تغيّر من يستطيع رؤيتها | يزامن بصمت |
| `alert` | شوركت معك خزنة، أو دعتك عائلة، أو أضافك أحدهم جهة اتصال للطوارئ، أو طلب الوصول في الطوارئ، أو رُفض طلبه أو مُنحه | يعرض تنبيهًا («تغيّر شيء في المشاركة أو الوصول في الطوارئ. افتح التطبيق لتراه.») ويزامن |

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

والهاتف المقفل يزامن أيضًا: ينزّل ما تغيّر، مشفَّرًا كما هو، فيجده الملء التلقائي وفتح القفل التالي. لا يُفك تشفير شيء حتى تفتح القفل.

## من يرى ماذا

| من | ما يراه |
|---|---|
| خادمك | رمز الدفع (push token) لكل هاتف، والجهاز والحساب اللذين ينتمي إليهما، ومتى أرسل إليه إشعار دفع |
| المرحّل | أي خادم يطلب، ولكل إشعار: رمزًا، وApple أو Google، والكلمة. لا حساب ولا بريد إلكتروني ولا خزنة ولا عنصر أبدًا. لا يخزّن أي رموز ولا يسجّل إلا الأعداد |
| Apple أو Google | الرمز والكلمة والوقت، كما في إشعارات أي تطبيق |

لذا يستطيع المرحّل وApple وGoogle معرفة عدد مرات إيقاظ هواتفك، وأن رمزًا ما تلقّى `alert` لا `sync`. ولا يستطيعون معرفة صاحبه ولا ما تغيّر. انظر [نموذج الأمان](https://octap.app/ar/docs/security/overview/) لبقية ما يستطيع الخادم رؤيته.

## كيف يستخدمه الخادم

1. مع `OCTAPASS_PUSH_RELAY=true` يسجّل الخادم نفسه لدى المرحّل (`OCTAPASS_PUSH_RELAY_URL`) ويحتفظ بمعرّف التثبيت ومفتاحه في قاعدة بياناته.
2. الهواتف التي ترى `pushRelay: true` في `GET /v1/server-info` ترسل رمز الدفع الخاص بها إلى `PUT /v1/devices/current/push` (انظر [واجهة API للمزامنة](https://octap.app/ar/docs/developers/sync-api/#إشعارات-الدفع)).
3. عند حدوث تغيير، يرسل الخادم إلى المرحّل رموز الأجهزة المسجَّل دخولها في الحسابات المتأثرة مع الكلمة، 100 على الأكثر في كل طلب.
4. عندما يقول المرحّل إن رمزًا ما لم يعد صالحًا (أُزيل التطبيق)، يحذفه الخادم. وتسجيل خروج جهاز يحذف رمزه أيضًا.

إشعارات الدفع بأفضل جهد (best effort). إذا كان المرحّل متوقفًا أو يحدّ من معدّل خادمك، تسقط تلك الجولة وتلحق الهواتف بالتغييرات في المرة التالية التي تُفتح فيها.

## شغّل مرحّلًا

المرحّل هو `octapass-push-relay` في `apps/push-relay`: ملف تنفيذي واحد وقاعدة بيانات صغيرة (SQLite أو PostgreSQL) للتثبيتات. لا تصل إشعارات الدفع إلا إلى التطبيقات الموقّعة بفريق Apple ومشروع Firebase نفسيهما اللذين تعود إليهما بيانات اعتماد المرحّل، لذا لا يفيد مرحّل خاص بك إلا مع تطبيقات تبنيها بنفسك.

```bash
cargo build --release -p octapass-push-relay
OCTAPASS_PUSH_RELAY_DATABASE_URL=sqlite:///var/lib/octapass-push-relay/relay.db \
OCTAPASS_PUSH_RELAY_APNS_KEY_FILE=/etc/octapass-push-relay/AuthKey.p8 \
OCTAPASS_PUSH_RELAY_APNS_KEY_ID=ABC123DEFG \
OCTAPASS_PUSH_RELAY_APNS_TEAM_ID=TEAM123456 \
OCTAPASS_PUSH_RELAY_FCM_CREDENTIALS_FILE=/etc/octapass-push-relay/firebase-service-account.json \
./target/release/octapass-push-relay
```

ضعه خلف وكيل عكسي مع HTTPS، ووجّه خادمك إليه بـ `OCTAPASS_PUSH_RELAY_URL`.

| المتغير | الافتراضي | الوصف |
|---|---|---|
| `OCTAPASS_PUSH_RELAY_DATABASE_URL` | مطلوب | `sqlite://…` أو `postgres://…`. لا تحوي إلا التثبيتات. |
| `OCTAPASS_PUSH_RELAY_BIND` | `127.0.0.1:8092` | العنوان والمنفذ المستمع عليهما. |
| `OCTAPASS_PUSH_RELAY_TRUST_PROXY` | `false` | `true` خلف وكيل عكسي، كي يستخدم حد التسجيل آخر عنوان في `X-Forwarded-For`. |
| `OCTAPASS_PUSH_RELAY_APNS_KEY_FILE` | غير مضبوط | مفتاح الدفع `.p8` من Apple. اضبطه، أو ملف FCM، أو كليهما. |
| `OCTAPASS_PUSH_RELAY_APNS_KEY_ID`, `OCTAPASS_PUSH_RELAY_APNS_TEAM_ID` | مطلوبان مع المفتاح | معرّف المفتاح ومعرّف فريقك في Apple. |
| `OCTAPASS_PUSH_RELAY_APNS_TOPIC` | `app.octap.ios` | معرّف الحزمة (bundle ID) لتطبيق iPhone. |
| `OCTAPASS_PUSH_RELAY_FCM_CREDENTIALS_FILE` | غير مضبوط | مفتاح حساب خدمة Firebase (JSON) مسموح له بالإرسال عبر Cloud Messaging. |
| `OCTAPASS_PUSH_RELAY_PUSHES_PER_MINUTE` | `600` | عدد إشعارات الدفع التي يجوز لخادم واحد إرسالها في الدقيقة. |
| `OCTAPASS_PUSH_RELAY_REGISTRATIONS_PER_HOUR` | `5` | عدد الخوادم الجديدة التي يجوز لها التسجيل من عنوان واحد في الساعة. |

تُقرأ بيانات الاعتماد من ملفات، ولا تُقرأ من البيئة أبدًا. أبقِها، وقاعدة البيانات، خاصة.

### إدارة الخوادم

```bash
octapass-push-relay admin list                 # every installation, active or revoked, and when it was last used
octapass-push-relay admin revoke <installation id>
```

يُرفض الخادم الملغى من حينها (`403`)، فيتوقف خادم Octa Pass عن الإرسال ولا يعيد التسجيل من تلقاء نفسه؛ بل يحاول مجددًا بعد إعادة تشغيله. يستطيع خادم معدَّل أن يسجّل من جديد، ضمن حد التسجيل، لذا احجب عنوانه عند الوكيل أيضًا عند إساءة الاستخدام.

## بناء التطبيقات لمرحّلك

- **iPhone:** فريق Apple يملك قدرة Push Notifications، ومفتاح `.p8` من ذلك الفريق للمرحّل. تستخدم بناءات التطوير بيئة sandbox لدى Apple، ويختارها المرحّل مما يخبر به الهاتف خادمك.
- **Android:** مشروع Firebase. ابنِ بإعداداته (`-PoctapassFcmProjectId` و`-PoctapassFcmAppId` و`-PoctapassFcmApiKey` و`-PoctapassFcmSenderId`) وأعطِ المرحّل مفتاح حساب خدمة من المشروع نفسه. ومن دون هذه الإعدادات لا يكون في التطبيق دفع. لا يُستخدم إلا Firebase Cloud Messaging: لا Analytics، وتبقى مقاييس التسليم معطّلة.

## ذات صلة

- [الإعدادات](https://octap.app/ar/docs/self-hosting/configuration/#مزامنة-الدفع)
- [ربط التطبيقات بخادمك](https://octap.app/ar/docs/self-hosting/connect-apps/#مزامنة-الدفع-على-iphone-وandroid)
- [واجهة API للمزامنة: إشعارات الدفع](https://octap.app/ar/docs/developers/sync-api/#إشعارات-الدفع)