# الإعدادات

> اضبط خادم Octa Pass المستضاف ذاتيًا بمتغيرات البيئة OCTAPASS_*، وتشمل العناوين ومجلد البيانات وقاعدة البيانات والبريد الإلكتروني والتسجيل وCORS ومفاتيح الأمان وأداة المسؤول.

Source: https://octap.app/ar/docs/self-hosting/configuration/
Status: in-progress
Project: Octa Pass

:::note[قيد التطوير]
الإعدادات في الجداول الأربعة الأولى تعمل اليوم، مع SQLite أو PostgreSQL. وقد تتغير أسماء الخيارات قبل الإصدار الأول.
:::

يقرأ الخادم متغيرات البيئة `OCTAPASS_*`.

## الإعدادات الأساسية

| المتغير | الافتراضي | الوصف |
|---|---|---|
| `OCTAPASS_PUBLIC_URL` | `http://<bind address>` | العنوان العام لخادمك. يُستخدم في رسائل البريد؛ وعندما يبدأ بـ `https://` يرسل الخادم HSTS أيضًا. |
| `OCTAPASS_BIND` | `127.0.0.1:8080` | العنوان والمنفذ المستمع عليهما. تضبط صورة Docker القيمة `0.0.0.0:8080`. |
| `OCTAPASS_DATA_DIR` | `./data` | يحوي قاعدة البيانات وأسرار الخادم، والمرفقات ما لم تستخدم S3. تستخدم صورة Docker المسار `/data`. |
| `OCTAPASS_DATABASE_URL` | `sqlite://<data dir>/octapass.db` | SQLite، أو PostgreSQL 16+ بالصيغة `postgres://user:password@host:5432/database`. يُنشأ المخطط ويُرقّى عند البدء. |
| `OCTAPASS_MAX_ITEMS` | `50000` | عدد العناصر التي يجوز لكل حساب تخزينها في الخزنات التي يملكها، بما فيها سلة المهملات. |
| `OCTAPASS_MAX_ITEM_BYTES` | `1073741824` (1 GiB) | حجم النص المشفَّر للعناصر الذي يجوز لكل حساب تخزينه، كما أُرسل (base64url). |
| `OCTAPASS_FAMILY_MAX_MEMBERS` | `6` | عدد الأعضاء مع الدعوات المعلقة الذي يجوز للعائلة امتلاكه، بمن فيهم المنظّم (من 2 إلى 100). |
| `OCTAPASS_WEB_ORIGINS` | `http://localhost:5173` | المصادر المسموح لها باستدعاء الـ API من متصفح (خزنة الويب)، مفصولة بفواصل. |
| `OCTAPASS_WEBAUTHN_RP_ID` | مضيف أول مصدر ويب | معرّف الطرف المعتمِد (relying party) في WebAuthn الذي تُسجَّل له مفاتيح الأمان الخاصة بـ[تسجيل الدخول بخطوتين](https://octap.app/ar/docs/features/two-step-sign-in/): مضيف خزنة الويب، أو نطاق أب له. تغييره لاحقًا يوقف مفاتيح الأمان الموجودة عن العمل (تستمر تطبيقات المصادقة ورموز الاسترداد في العمل). |
| `OCTAPASS_TRUST_PROXY` | `false` | اضبطه على `true` خلف وكيل عكسي، كي تستخدم حدود المعدّل آخر عنوان في `X-Forwarded-For`. اتركه معطّلًا في غير ذلك، وإلا استطاع العملاء تزييف عناوينهم. |
| `OCTAPASS_WEB_DIR` | غير مضبوط؛ `/web` في صورة Docker | يقدّم خزنة الويب المبنية من هذا المجلد على مصدر الخادم نفسه. المسارات خارج `/v1` التي لا تطابق أي ملف تحصل على `index.html`. تحصل صفحاتها على CSP لا تسمح إلا بهذا المصدر مع `wasm-unsafe-eval`. |
| `OCTAPASS_LOG` | `info` | مرشّح السجل، مثل `debug` أو `octapass_server=debug`. لا تحتوي السجلات أبدًا على أجسام الطلبات أو الرموز أو سلاسل الاستعلام. |

## المرفقات

[مرفقات](https://octap.app/ar/docs/features/attachments/) المستخدمين مشفّرة على أجهزتهم؛ ولا يخزّن الخادم إلا النص المشفَّر. تُحفظ الملفات افتراضيًا في مجلد `attachments` ضمن مجلد البيانات. اضبط `OCTAPASS_S3_BUCKET` لحفظها في تخزين كائنات متوافق مع S3 بدلًا من ذلك (AWS S3 وMinIO وGarage وBackblaze B2 وWasabi وHetzner وغيرها).

| المتغير | الافتراضي | الوصف |
|---|---|---|
| `OCTAPASS_MAX_ATTACHMENT_BYTES` | `1073741824` (1 GiB) | مساحة المرفقات لكل حساب، محسوبة على الخزنات التي يملكها (بما فيها سلة المهملات)، كما هي مخزَّنة. |
| `OCTAPASS_MAX_FILE_BYTES` | `104857600` (100 MiB) | أكبر ملف منفرد، كما هو مخزَّن. يضيف التشفير 52 بايت، إضافة إلى 16 لكل 64 KiB. |
| `OCTAPASS_S3_BUCKET` | غير مضبوط | يفعّل تخزين الكائنات. |
| `OCTAPASS_S3_ENDPOINT` | `https://s3.<region>.amazonaws.com` | نقطة نهاية مزوّدك، مثل `https://minio.example.com:9000`. |
| `OCTAPASS_S3_REGION` | `us-east-1` | منطقة الحاوية، كما يسميها مزوّدك. |
| `OCTAPASS_S3_ACCESS_KEY_ID`, `OCTAPASS_S3_SECRET_ACCESS_KEY` | مطلوبان مع الحاوية | بيانات اعتماد تسمح بوضع الكائنات في الحاوية وجلبها وحذفها، والتحقق من وجودها. |
| `OCTAPASS_S3_PATH_STYLE` | `true` عند ضبط `OCTAPASS_S3_ENDPOINT`، وإلا `false` | `https://endpoint/bucket/key` بدل `https://bucket.endpoint/key`. تحتاج معظم الخوادم المستضافة ذاتيًا إلى نمط المسار. |

تُوقَّع الطلبات بـ AWS Signature Version 4. أسماء الكائنات عشوائية ولا تدل على حسابات أو عناصر. تمر الرفوع عبر ملف مؤقت في `<data dir>/uploads`، فيجب أن تتوفر هناك مساحة لأكبر ملف يُرفع. وعند حذف الملفات (من المستخدمين، أو مع عناصرهم بعد 30 يومًا في سلة المهملات، أو مع حساب) يحذفها الخادم من التخزين فورًا، ويعيد المحاولة بتباعد متزايد، حتى مرة في اليوم، ما دام التخزين غير متاح. ويفشل `/readyz` ما دام التخزين لا يمكن الوصول إليه.

## البريد الإلكتروني والتسجيل

| المتغير | الافتراضي | الوصف |
|---|---|---|
| `OCTAPASS_SMTP_URL` | غير مضبوط | `smtp://` أو `smtps://user:pass@host:port` للبريد الصادر. بدونه (ودون `OCTAPASS_EMAIL_TO_LOG` أو وضع التطوير) لا يستطيع أحد التسجيل، لأن التسجيل يحتاج إلى بريد إلكتروني موثَّق. |
| `OCTAPASS_SMTP_FROM` | `Octa Pass <noreply@<public host>>` | عنوان المرسِل. |
| `OCTAPASS_SIGNUPS` | `open` | `open`، أو `invite` (فقط عناوين البريد المضافة بـ `admin invite` أو `OCTAPASS_INVITES`)، أو `closed`. |
| `OCTAPASS_INVITES` | غير مضبوط | عناوين بريد إلكتروني مفصولة بفواصل تُدعى في كل تشغيل، ما دام ليس لها حساب. |
| `OCTAPASS_EMAIL_TO_LOG` | `false` | يكتب مستلم كل رسالة وموضوعها في السجل، حيث يوجد رمز التسجيل. للخوادم بلا SMTP. وعلى خلاف وضع التطوير، لا تُعاد الرموز إلى العملاء أبدًا. |
| `OCTAPASS_DEV_MODE` | `false` | يسجّل الرسائل في السجل ويعيد رموز التحقق في استجابة الـ API. **لا تفعّله أبدًا على خادم يستخدمه آخرون.** |
| `OCTAPASS_RATE_LIMITS` | `on` | `off` يوقف حدود المعدّل (تسجيل الدخول وعمليات البحث وروابط المشاركة وجهات اتصال الطوارئ والأيقونات)، لمجموعات الاختبار المحلية التي تسجّل الدخول مرات كثيرة من عنوان واحد. لا يُقبل إلا مع `OCTAPASS_DEV_MODE=true`. |

## أيقونات المواقع

تعرض التطبيقات [أيقونة موقع](https://octap.app/ar/docs/features/website-icons/) كل عنصر بسؤال خادمك (`GET /v1/icons/{domain}`)، الذي يجلبها من الموقع نفسه ويحتفظ بها في مجلد `icons` ضمن مجلد البيانات لمدة أسبوع. لا تحمل الطلبات حسابًا ولا رمزًا. ولا يتصل الخادم إلا بعناوين الإنترنت العامة، فلا يستطيع موقع توجيهه إلى شبكتك. ويحتاج إلى وصول صادر عبر HTTPS (وHTTP) إلى الإنترنت.

| المتغير | الافتراضي | الوصف |
|---|---|---|
| `OCTAPASS_SSO_PRIVATE_NETWORK` | `off` | `on` يسمح للخادم بالوصول إلى [موفّر هوية](https://octap.app/ar/docs/features/single-sign-on/) على عنوان خاص. وعند إيقافه لا يصل إلا إلى العناوين العامة. وHTTPS مطلوب في الحالتين. |
| `OCTAPASS_ICONS` | `on` | وكيل [أيقونات المواقع](https://octap.app/ar/docs/features/website-icons/). `off` يوقف جلب الخادم للأيقونات: فتعرض التطبيقات الأحرف الأولى وتتوقف عن السؤال. عطّله إذا كان خادمك لا يصل إلى الإنترنت، أو إذا لم تُرد أن يجلب مواقع الويب. |

## تنبيهات تسريب البريد الإلكتروني

[تنبيهات تسريب البريد الإلكتروني](https://octap.app/ar/docs/security/breach-checks/#تنبيهات-تسريب-البريد-الإلكتروني-اختيارية) متوقفة ما لم تضبط مفتاح API من Have I Been Pwned، تحصل عليه من HIBP. ومن دونه لا يرى المستخدمون مفتاح التشغيل، وتجيب نقطة النهاية بـ 404. ومعه، يظل على كل مستخدم أن يشغّل التنبيهات بنفسه، وعندها تمر عناوينه عبر خادمك في طريقها إلى HIBP.

| المتغير | الافتراضي | الوصف |
|---|---|---|
| `OCTAPASS_HIBP_API_KEY` | غير مضبوط | مفتاح HIBP API الخاص بك. ضبطه يتيح الميزة لمستخدميك. وهو سر: مرّره كما تمرّر كلمة مرور قاعدة البيانات. |
| `OCTAPASS_HIBP_REQUESTS_PER_MINUTE` | `10` | ما تسمح به خطتك في HIBP، للخادم كله. الطلبات التي تتجاوزه تنتظر حتى 15 ثانية، ثم تحصل على `429`. |

## مجلد البيانات

عند أول تشغيل ينشئ الخادم ملفي سر في مجلد البيانات، لا يقرؤهما إلا مستخدم الخادم:

| الملف | الغرض |
|---|---|
| `opaque-server-setup.bin` | مفتاح خادم OPAQUE. إذا فُقد، **لا يستطيع أحد تسجيل الدخول مرة أخرى**. |
| `server-secret.bin` | يشفّر أملاح تسجيل الدخول الوهمية لعناوين البريد غير المعروفة وتجزئات رموز التحقق. |

انسخ مجلد البيانات كله احتياطيًا، لا قاعدة البيانات وحدها. كل ما فيه عدا هذين الملفين نص مشفَّر أو بيانات وصفية. انظر [النسخ الاحتياطية](https://octap.app/ar/docs/self-hosting/backups/).

مجلد `icons` يخزّن مؤقتًا أيقونات المواقع العامة فقط. أسماء ملفاته مفتاحية بسر الخادم، فهو ليس قائمة مقروءة بالمواقع، لكن الأيقونات نفسها تدل على المواقع الموجودة في خزنات مستخدميك؛ فأبقِه خاصًا مثل بقية المجلد. ويمكنك حذفه في أي وقت، ولا حاجة إلى نسخه احتياطيًا.

مع SQLite تُكتب فوق الصفوف المحذوفة في ملف قاعدة البيانات (`secure_delete`) ويُفرَّغ سجل الكتابة المسبقة (write-ahead log) بعد كل حذف حساب، فلا يمكن استرداد حساب محذوف من مجلد البيانات. أما PostgreSQL فيعيد استخدام مساحة الصفوف المحذوفة عبر autovacuum، لكن نسخ الصفوف القديمة قد تبقى على القرص وفي أرشيفات WAL إلى حين ذلك؛ فأبقِ مجلد بياناته وأرشيفاته خاصة مثل النسخ الاحتياطية. تختفي الحسابات المحذوفة من النسخ الاحتياطية بقدر تدويرك لها فقط. وتحتفظ الخدمة المستضافة بالنسخ الاحتياطية 30 يومًا على الأكثر؛ افعل الشيء نفسه إذا قطعت هذا الوعد لمستخدميك.

## أداة المسؤول

شغّلها بالبيئة نفسها التي يعمل بها الخادم (في Docker: `docker exec octapass octapass-server admin …`).

```bash
octapass-server admin invite alice@example.com          # allow a sign-up when OCTAPASS_SIGNUPS=invite
octapass-server admin delete-account alice@example.com  # delete an account and everything in it
octapass-server admin reset-two-step alice@example.com  # turn off two-step sign-in for someone who lost every method
octapass-server admin backup /backups                   # a backup of the database, secrets and attachments (SQLite)
octapass-server admin restore /backups/octapass-…       # put a backup in place (stop the server first)
octapass-server healthcheck                             # exit 0 when the server answers /healthz
octapass-server openapi                                 # print the API as OpenAPI 3.1
```

النسخ الاحتياطية والاستعادة موصوفة في [النسخ الاحتياطية](https://octap.app/ar/docs/self-hosting/backups/).

يفعل `admin delete-account` ما يفعله حذف الحساب داخل التطبيق تمامًا، دون أن يطلب كلمة المرور، ويرسل إلى المستخدم رسالة التأكيد بالبريد الإلكتروني. ولا يمكن التراجع عنه.

يزيل `admin reset-two-step` تطبيق المصادقة ومفاتيح الأمان ورموز الاسترداد من الحساب، ويسجّل ذلك في سجل الأمان للمستخدم ويراسله. لا تستخدمه إلا بعد أن تتأكد ممن يطلب: فهو يترك كلمة المرور الرئيسية والمفتاح السري الحماية الوحيدة لعمليات تسجيل الدخول الجديدة.

## الحدود

هذه ثابتة حاليًا:

| الحد | القيمة |
|---|---|
| جسم الطلب | 1 MiB، و16 MiB لـ `POST /v1/batch` |
| نظرة العنصر / تفاصيله | 64 KiB / 512 KiB من النص المشفَّر |
| الدفعة | 1,000 عملية |
| صفحة المزامنة | نحو 1,000 عنصر أو 8 MiB |
| حدود معدّل المصادقة | انظر [حدود المعدّل](https://octap.app/ar/docs/developers/sync-api/#حدود-المعدّل) |
| رموز التسجيل لكل بريد إلكتروني | 10 رموز تُرسَل و20 تخمينًا خاطئًا لكل يوم UTC |
| مهلة الطلب | 30 ثانية؛ رفع المرفقات وتنزيلها ساعة واحدة، ويُوقَف الرفع الذي لا يرسل شيئًا لمدة دقيقة |
| WebSocket | يُرسَل ping كل 30 ثانية؛ ويُغلق عندما تنتهي صلاحية رمز الوصول الخاص به |

## مخطط له

| الإعداد | الغرض |
|---|---|
| `octapass.toml` | الإعدادات نفسها في ملف |
| قائمة سماح لنطاقات البريد الإلكتروني | السماح بالتسجيل من نطاقات محددة فقط |
| وضع Pwned Passwords | التمرير عبر خادمك (الافتراضي) أو السماح للعملاء باستدعاء HIBP مباشرة |
| عنوان Redis/Valkey | حدود معدّل مشتركة بين عدة نسخ |
| المقاييس | Prometheus `/metrics` على منفذ منفصل، مجمَّعة فقط |
| أوامر مسؤول إضافية | `disable-signups` و`quota` |