الإعدادات

قيد التطوير

يقرأ الخادم متغيرات البيئة 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 الذي تُسجَّل له مفاتيح الأمان الخاصة بـتسجيل الدخول بخطوتين: مضيف خزنة الويب، أو نطاق أب له. تغييره لاحقًا يوقف مفاتيح الأمان الموجودة عن العمل (تستمر تطبيقات المصادقة ورموز الاسترداد في العمل).
`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`. لا تحتوي السجلات أبدًا على أجسام الطلبات أو الرموز أو سلاسل الاستعلام.

المرفقات

مرفقات المستخدمين مشفّرة على أجهزتهم؛ ولا يخزّن الخادم إلا النص المشفَّر. تُحفظ الملفات افتراضيًا في مجلد 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`.

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

تعرض التطبيقات أيقونة موقع كل عنصر بسؤال خادمك (GET /v1/icons/{domain})، الذي يجلبها من الموقع نفسه ويحتفظ بها في مجلد icons ضمن مجلد البيانات لمدة أسبوع. لا تحمل الطلبات حسابًا ولا رمزًا. ولا يتصل الخادم إلا بعناوين الإنترنت العامة، فلا يستطيع موقع توجيهه إلى شبكتك. ويحتاج إلى وصول صادر عبر HTTPS (وHTTP) إلى الإنترنت.

المتغير	الافتراضي	الوصف
`OCTAPASS_SSO_PRIVATE_NETWORK`	`off`	`on` يسمح للخادم بالوصول إلى موفّر هوية على عنوان خاص. وعند إيقافه لا يصل إلا إلى العناوين العامة. وHTTPS مطلوب في الحالتين.
`OCTAPASS_ICONS`	`on`	وكيل أيقونات المواقع. `off` يوقف جلب الخادم للأيقونات: فتعرض التطبيقات الأحرف الأولى وتتوقف عن السؤال. عطّله إذا كان خادمك لا يصل إلى الإنترنت، أو إذا لم تُرد أن يجلب مواقع الويب.

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

تنبيهات تسريب البريد الإلكتروني متوقفة ما لم تضبط مفتاح 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`	يشفّر أملاح تسجيل الدخول الوهمية لعناوين البريد غير المعروفة وتجزئات رموز التحقق.

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

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

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

أداة المسؤول

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

octapass-server admin invite [email protected]          # allow a sign-up when OCTAPASS_SIGNUPS=invite
octapass-server admin delete-account [email protected]  # delete an account and everything in it
octapass-server admin reset-two-step [email protected]  # 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

النسخ الاحتياطية والاستعادة موصوفة في النسخ الاحتياطية.

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

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

الحدود

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

الحد	القيمة
جسم الطلب	1 MiB، و16 MiB لـ `POST /v1/batch`
نظرة العنصر / تفاصيله	64 KiB / 512 KiB من النص المشفَّر
الدفعة	1,000 عملية
صفحة المزامنة	نحو 1,000 عنصر أو 8 MiB
حدود معدّل المصادقة	انظر حدود المعدّل
رموز التسجيل لكل بريد إلكتروني	10 رموز تُرسَل و20 تخمينًا خاطئًا لكل يوم UTC
مهلة الطلب	30 ثانية؛ رفع المرفقات وتنزيلها ساعة واحدة، ويُوقَف الرفع الذي لا يرسل شيئًا لمدة دقيقة
WebSocket	يُرسَل ping كل 30 ثانية؛ ويُغلق عندما تنتهي صلاحية رمز الوصول الخاص به

مخطط له

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