متغيرات البيئة
تسرد هذه الصفحة متغيرات البيئة المدعومة والموجهة للمشغلين التي تقرأها حاليًا الواجهة والخادم الخلفي وبرامج الصيانة في Libre WebUI. وقد حُذفت عمدًا المتغيرات الداخلية المخصصة للاختبارات.
الخادم الخلفي
| المتغير | الافتراضي | الغرض |
|---|---|---|
NODE_ENV | development | وضع التشغيل |
PORT | 3001 في التطوير، 8080 في الإنتاج | منفذ HTTP للخادم الخلفي |
TRUST_PROXY | غير مضبوط (0 في Helm) | عدد قفزات الوكيل العكسي الموثوق الدقيق المستخدم لاشتقاق عنوان العميل |
CORS_ORIGIN | أصول التطوير المحلية | أصول المتصفح المسموحة، مفصولة بفواصل |
SERVE_FRONTEND | غير مضبوط | تقديم الواجهة المبنية من الخادم عند true |
DOCKER_ENV | غير مضبوط | تفعيل السلوك الموجه إلى Docker عند true |
DATA_DIR | backend/data؛ و~/.libre-webui في CLI المعبأ | دليل البيانات الدائمة |
PLATFORM_PREFLIGHT_TMP_DIR | backend/temp/preflight؛ ذاكرة المستخدم المؤقتة في CLI | مساحة مؤقتة لنسخة فحص بدء تشغيل DB/WAL الخاصة؛ خصص لها حجم قاعدة البيانات وWAL |
PLUGIN_UPLOAD_TEMP_DIR | libre-webui-plugin-uploads تحت دليل النظام المؤقت | مساحة مؤقتة لرفع المكونات الجاري |
PLUGINS_DIR | $DATA_DIR/plugins | دليل قابل للكتابة للمكونات المثبتة أو المخصصة |
BASE_URL | http://localhost:3001 | عنوان الأساس المستخدم لقيم استدعاء OAuth الافتراضية |
LOG_LEVEL | info (warn في الاختبارات) | مستوى سجل الخادم |
LOG_FORMAT | text | تجعل json السجل منظمًا في سطر واحد مع طابع زمني ومعرف ارتباط وتنقيح |
OTEL_EXPORTER_OTLP_ENDPOINT | غير مضبوط | تصدير اختياري لقياس JSON عبر OTLP/HTTP؛ عدم الضبط يعني ألا يغادر قياس العملية |
OTEL_EXPORTER_OTLP_HEADERS | غير مضبوط | ترويسات key=value المرسلة إلى جامع OTLP، مفصولة بفواصل (مثل المصادقة) |
OTEL_SERVICE_NAME | libre-webui | سمة المورد service.name في القياس المصدر |
WEBUI_HOST | الالتفاف؛ 0.0.0.0 في Docker | عنوان استماع HTTP |
OPEN_BROWSER | true عند تقديم الواجهة | اضبط false لمنع فتح المتصفح تلقائيًا |
FULL_DOCUMENT_CONTEXT_MAX_TOKENS | 32000 | حارس رموز وضع المستند الكامل لكل محادثة (1000-2000000) |
GALLERY_RETENTION_DAYS | غير مضبوط (احتفاظ دائم) | حذف وسائط المعرض الأقدم من هذا العدد عبر مسح المجدول |
RECOVERY_DRILL_INTERVAL_HOURS | غير مضبوط (التدريبات متوقفة) | تشغيل تدريب استرداد متحقق تلقائيًا كل N ساعة (ملف solo) |
RECOVERY_DRILL_HISTORY | 60 | عدد مدخلات سجل تدريبات الاسترداد المحتفظ بها |
تربط عمليات التشغيل من المصدر قيم DATA_DIR وPLUGINS_DIR وPLATFORM_PREFLIGHT_TMP_DIR النسبية بدليل الخادم الخلفي بصرف النظر عن دليل الصدفة الحالي. لذلك تستخدم الأوامر من الجذر ومساحة الخادم backend/data عند غياب DATA_DIR أو مع المثال الجديد DATA_DIR=./data. وللتوافق، تظل تهيئة المصدر القائمة DATA_DIR=./backend/data تختار backend/backend/data؛ لا تغيرها إلا ضمن نسخ وترحيل مقصودين والتطبيق متوقف. كما يظل ملف مصدر بلا قيمة يستخدم backend/backend/data إذا كان المخزن الدائم الوحيد. وإذا احتوى الموقعان حالة ولم يُحدد مسار، يفشل البدء بأمان بدل التخمين أو النسخ أو الدمج.
تحفظ مشغلات npx وnpm العامة وHomebrew التفاعلية البيانات تحت ~/.libre-webui. وتُحل قيمة DATA_DIR النسبية الصريحة من دليل المستدعي ثم تتحول إلى مطلقة قبل بدء الخادم. وتتبع PLUGINS_DIR الصريحة القاعدة نفسها؛ وعند غيابها تبقى المكونات القابلة للكتابة تحت $DATA_DIR/plugins. تستخدم مساحة الفحص افتراضيًا ذاكرة مؤقتة قابلة لكتابة المستخدم خارج دليل البيانات: ~/Library/Caches/libre-webui على macOS، و%LOCALAPPDATA%\libre-webui على Windows، و${XDG_CACHE_HOME:-~/.cache}/libre-webui على الأنظمة الأخرى. تثبت خدمة Homebrew دليل البيانات نفسه وتستخدم var/libre-webui/preflight من Homebrew للمساحة المؤقتة. اضبط PLATFORM_PREFLIGHT_TMP_DIR إذا لم تستوعب الذاكرة قاعدة البيانات وWAL. تستخدم عمليات Docker وHelm المسارين المطلقين /app/backend/data و/app/backend/temp/preflight بتركيبات منفصلة.
أساس المنصة
يستخدم ملف solo الافتراضي SQLite وكائنات محلية مشفرة ومتجهات مضمنة مشفرة وتنسيقًا محليًا وعاملًا دائمًا مضمنًا. ويستخدم team PostgreSQL وكائنات خاصة متوافقة مع S3 وPGVector وRedis وعاملًا خارجيًا. تفشل تهيئة الفريق بأمان؛ ويجب اختيار كل التبعيات المشتركة معًا.
| المتغير | الافتراضي | الغرض |
|---|---|---|
LIBRE_PLATFORM_MODE | solo | اختيار ملف solo أو team المتماسك |
DATABASE_BACKEND | sqlite | اختيار sqlite أو postgres |
DATABASE_URL | غير مضبوط | عنوان اتصال PostgreSQL المطلوب مع postgres |
DATABASE_SSL_MODE | verify-full | سياسة TLS لـ PostgreSQL: disable أو require أو verify-full المتحقق من المضيف |
POSTGRES_MIGRATION_MODE | apply | تشغيل الترحيلات المتوافقة تحت قفل القائد، أو validate لفحص مخطط للقراءة فقط |
POSTGRES_POOL_MAX | 10 | أقصى اتصالات PostgreSQL لكل عملية تطبيق أو عامل (1-100) |
POSTGRES_CONNECT_TIMEOUT_MS | 5000 | مهلة اتصال PostgreSQL (1-60000 ms) |
POSTGRES_IDLE_TIMEOUT_MS | 30000 | مهلة خمول اتصال PostgreSQL (1-600000 ms) |
POSTGRES_STATEMENT_TIMEOUT_MS | 30000 | مهلة عبارة PostgreSQL (1-600000 ms) |
POSTGRES_MIGRATION_LOCK_TIMEOUT_MS | 60000 | انتظار قفل قائد الترحيل (1-600000 ms) |
BLOB_STORE_BACKEND | local | اختيار تخزين local مشفر أو s3 خاص |
VECTOR_STORE_BACKEND | embedded مع SQLite | اختيار متجهات embedded مشفرة أو pgvector |
COORDINATION_BACKEND | local في solo؛ وredis في team | اختيار تنسيق داخل العملية أو Redis |
REDIS_URL | غير مضبوط | عنوان redis: أو rediss: المطلوب مع تنسيق Redis |
REDIS_KEY_PREFIX | libre | نطاق من 1 إلى 64 حرفًا لمفاتيح تنسيق Libre |
REDIS_CONNECT_TIMEOUT_MS | 5000 | مهلة اتصال Redis الأولية، بحد 60 ثانية |
JOB_WORKER_MODE | embedded في solo؛ وexternal في team | تشغيل المعالجات في التطبيق أو العامل المشترك المستقل |
RESOURCE_LEASE_TTL_MS | 30000 | عمر إيجار التنسيق لملكية موارد الوظائف الدائمة (5000-300000؛ يفشل البدء خارج النطاق) |
JOB_WORKER_CONCURRENCY | 4 | وظائف دائمة يمكن للعامل تشغيلها معًا (1-32) |
CHAT_STREAM_EVENT_RETENTION_HOURS | 24 | ساعات بقاء أحداث مقاطع المحادثة قبل المسح كل ساعة |
PLATFORM_EVENT_RETENTION_DAYS | 30 | أيام بقاء أي حدث دائم قبل المسح كل ساعة |
PLATFORM_JOB_RETENTION_DAYS | 30 | أيام بقاء الوظائف المنتهية غير الدورية قبل المسح كل ساعة |
LIBRE_SKIP_STARTUP_INTEGRITY_SCAN | غير مضبوط | تتجاوز 1 فحص النص المشفر القديم العميق في البدء التالي (مخرج طوارئ؛ وإلا يُخبأ حسب جيل المخطط) |
STORAGE_ENCRYPTION_KEYS | غير مضبوط | خريطة مفاتيح JSON سرية؛ يجب حاليًا أن تتضمن legacy المطابق لـ ENCRYPTION_KEY |
STORAGE_ENCRYPTION_ACTIVE_KEY_ID | غير مضبوط | معرف مفتاح الكتابات الجديدة للكائنات المحلية والمتجهات المضمنة |
BLOB_QUOTA_BYTES_PER_USER | 10737418240 | أقصى بايتات كائنات نصية دائمة لكل مالك (عدد صحيح آمن موجب) |
BLOB_QUOTA_RESERVATION_TTL_MS | 3600000 | عمر حجز حصة تدفق متروك (60000 ms على الأقل) |
S3_BUCKET | غير مضبوط | حاوية خاصة متوافقة مع S3 مطلوبة مع s3 |
S3_REGION | غير مضبوط | منطقة S3 المطلوبة مع s3 |
S3_ENDPOINT | افتراضي المزوّد | نقطة HTTP(S) مطلقة اختيارية لـ MinIO أو خدمة متوافقة |
S3_ACCESS_KEY_ID | سلسلة بيانات اعتماد SDK | مفتاح وصول S3 صريح اختياري |
S3_SECRET_ACCESS_KEY | سلسلة بيانات اعتماد SDK | مطلوب عند ضبط مفتاح وصول صريح |
S3_SESSION_TOKEN | غير مضبوط | رمز اختياري مع بيانات S3 الصريحة |
S3_FORCE_PATH_STYLE | false | اضبط true للخدمات التي تتطلب عنونة بنمط المسار |
S3_BLOB_PREFIX | libre/blobs | بادئة مفتاح حاوية مبهمة يملكها Libre |
عند غياب خريطة مفاتيح التخزين ذات الإصدار، تستخدم المحولات ENCRYPTION_KEY القائمة بمعرف legacy؛ وعند غيابها أيضًا تقرأ ${DATA_DIR}/.encryption_key القائم بلا توليد أو تعديل. يجب أن تتفق التهيئة الصريحة والملف الدائم. وإذا أُدخلت خريطة إصدار مع وجود مفتاح قديم، احتفظ به تحت المعرف الدقيق legacy حتى تُعاد كتابة أو تغليف كل الكائنات والمتجهات والتحقق منها. تؤدي التعارضات وصلاحيات الملفات غير الآمنة والروابط الرمزية والمفاتيح المفقودة إلى فشل آمن.
Redis للتنسيق لا للاستمرارية الأساسية. اختياره وحده لا يجعل SQLite أو الملفات المحلية أو حالة العملية آمنة عبر النسخ. في وضع الفريق، تستخدم حدود HTTP واتصالات Chat/WebSocket وأعمال STT/TTS/audio واستيراد الأرشيف وطرفيات Work قبولًا مشتركًا عبر Redis. تنطبق السعات على كل النسخ، لا لكل عملية. تعيد أعطال القبول وتجديد التصريح 503 أو توقف العملية؛ ولا يعود Libre إلى عداد محلي مستقل. راجع أساس المنصة.
يمرر ملف Compose للفريق ومخطط Helm كل المحددات والقيم أعلاه إلى التطبيق والعامل. في Helm توجد المحددات غير السرية تحت env؛ واضبط secrets.redisUrl وsecrets.databaseUrl وsecrets.storageEncryptionKeys للاتصالات والمفاتيح. حدود تجمع PostgreSQL لكل عملية؛ خصص على الأقل (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX اتصالًا مع هامش. حافظ على DATABASE_SSL_MODE=verify-full للبعيد أو المُدار. وحده Compose الفريق يختار disable لأن مستمعه معزول على شبكة المشروع الخاصة. يتطلب Helm الفريق أيضًا secrets.jwtSecret ثابتًا مشتركًا بين Pods التطبيق والعامل؛ وإلا ستولد كل عملية مادة توقيع محلية. تستلم S3 مفاتيح مبهمة ونصًا مشفرًا؛ ولا تُخزن عناوين الحاويات والمزوّدين في بيانات التطبيق.
تحفظ أرشيفات solo وteam المتكاملة إعدادات تجمع PostgreSQL والمهل، ومهلة Redis، وقيمتي حصة الكائنات، ومحددات المنصة، وإعدادات عنونة S3 في تهيئة محمية موقعة ومشفرة. وبذلك تستطيع استعادة نظيفة نشر القيم التشغيلية لإعادة إنشاء النشر من دون وضعها نصًا صريحًا في بيانات الأرشيف.
تتلقى أزواج تطبيق/عامل Compose وHelm القيم نفسها لـ OLLAMA_BASE_URL وOLLAMA_TIMEOUT وOLLAMA_LONG_OPERATION_TIMEOUT وOLLAMA_MAX_CONTEXT. تنفذ استدعاءات التضمين والمحادثات الدائمة وWork في العامل، فلا يجوز اختلافها. تحلل نقطتا دخول الخادم القيم الرقمية الثلاث كأعداد موجبة كاملة بالأساس 10 قبل إنشاء الحالة أو الاتصال. تفشل قيم مثل 300000ms أو الأسية/السداسية أو الخارجة عن النطاق، أو مهلة طويلة أقل من العادية.
يقيد Helm TRUST_PROXY بعدد قفزات صحيح من 0 إلى 16 ويرسله إلى Pods HTTP فقط. أبقِ 0 للحركة المباشرة، واضبط العدد الثابت لسلسلة Ingress/موازن؛ لا تستخدم true غير المحدود. العدد الخاطئ يجمع العملاء خلف الوكيل أو يثق بعنوان يرسله العميل.
يتطلب توافق PostgreSQL إصدار مخطط دقيق. يستخدم التطبيق والعامل Recreate؛ أفرغ كل Pod قديم وأنهِه قبل ترقية الفريق، ثم دع عملية جديدة ترحّل تحت القفل الاستشاري. لا تشغّل إصدارات مختلطة أو تدّعِ ترقية بلا توقف. والتراجع هو استعادة أرشيف الفريق المتحقق السابق إلى أهداف PostgreSQL/S3 نظيفة قبل تشغيل البرنامج الأقدم المطابق.
يتطلب تطبيق فريق نشط worker.replicaCount >= 1؛ ويرفض Helm تطبيقًا حيًا بلا عامل دائم. اضبط عددي التطبيق والعامل صفرًا للتعليق الكامل. تطبيق صفر مع عامل موجب هو وضع تصريف أو استرداد مقصود يستمر في استهلاك الوظائف بلا حركة ويب.
مساعد النسخ الاحتياطي الخاص
تهيئ هذه المتغيرات deploy/private/libre-webui-backup وتقرأها أداة الصيانة لا التطبيق:
| المتغير | الافتراضي | الغرض |
|---|---|---|
LIBRE_WEBUI_STACK_DIR | /opt/libre-webui | دليل ملف Compose الخاص |
LIBRE_WEBUI_BACKUP_DIR | /var/backups/libre-webui | دليل محمي لمجموعات النسخ وملف القفل |
LIBRE_WEBUI_BACKUP_RETENTION_DAYS | 14 | عمر حذف مجموعات النسخ المكتملة |
LIBRE_WEBUI_CONTAINER_NAME | libre-webui | حاوية التطبيق المنشورة للفحص |
LIBRE_WEBUI_BACKUP_KEY_DIR | /etc/libre-webui/backup-keys | دليل مفاتيح تشفير الأرشيف وتوقيعه |
LIBRE_WEBUI_RESTORE_IMAGE | مطلوب للاستعادة | معرف أو بصمة صورة Libre ثابتة ومراجعة |
LIBRE_WEBUI_RESTORE_CONFIG_DIR | مسار لكل وحدة تحت /etc/libre-webui/restored | دليل جديد للتهيئة المستردة |
تحمل وحدة systemd التجاوزات من الملف الاختياري /etc/libre-webui/backup.env المملوك للجذر. اضبطه على 0600. ويمكن ضبط دليل الحزمة والاحتفاظ واسم الحاوية ودليل المفاتيح فيه. لا يسمح عزل نظام ملفات الوحدة بالكتابة إلا تحت دليل النسخ الافتراضي. ويتطلب LIBRE_WEBUI_BACKUP_DIR مخصص إضافة دليله الدقيق المنشأ مسبقًا إلى ReadWritePaths= في تجاوز الخدمة؛ راجع النشر البعيد الخاص.
المصادقة والأمان
| المتغير | الافتراضي | الغرض |
|---|---|---|
ENABLE_SIGNUP | false | السماح بالتسجيل بعد أول مسؤول محلي |
JWT_SECRET | مولّد/احتياطي في التطوير | سر توقيع JWT؛ اضبطه صراحة في الإنتاج |
JWT_EXPIRES_IN | 7d | عمر رمز الجلسة |
ENCRYPTION_KEY | مولّد تلقائيًا | مفتاح سداسي من 64 حرفًا للقيم المشفرة |
DEBUG_ENCRYPTION | غير مضبوط | تسجيل مخرجات تصحيح التشفير عند ضبطه |
TURNSTILE_SITE_KEY | غير مضبوط | مفتاح موقع Cloudflare Turnstile للدخول والتسجيل |
TURNSTILE_SECRET_KEY | غير مضبوط | مفتاح Turnstile السري للتحقق الخلفي |
TURNSTILE_EXPECTED_HOSTNAME | اسم مضيف BASE_URL | اسم المضيف المطلوب في استجابة Cloudflare |
MFA_REQUIRED_MODE | غير مضبوط (مفتاح مسؤول، optional) | تثبيت سياسة العاملين على optional أو required |
WEBAUTHN_RP_ID | اسم مضيف الطلب | معرف طرف معتمد ثابت لمفاتيح المرور خلف عدة أسماء |
VAPID_PUBLIC_KEY | مولّد ومخزن مشفرًا | تثبيت مفتاح Web Push VAPID العام (نقطة P-256 base64url) |
VAPID_PRIVATE_KEY | مولّد ومخزن مشفرًا | تثبيت مفتاح Web Push VAPID الخاص (قيمة base64url) |
VAPID_SUBJECT | mailto:admin@localhost | بيان الاتصال في تراخيص Web Push الموقعة |
لا يُفعّل Turnstile إلا عند وجود المفتاحين.
تظل ENABLE_SIGNUP=false تسمح بأول مسؤول محلي في قاعدة فارغة ثم تمنع الحسابات التالية. احمِ مسار التمهيد البعيد بحد هوية خارجي قبل البدء الأول.
يرتبط كل JWT بجلسة على الخادم (ادعاء sid)، ولذلك يبطل الخروج أو الإلغاء من الإعدادات ← الجلسات الرمز فورًا على كل نسخة ويغلق WebSocket الحي. مدة سجل التدقيق قابلة للتهيئة:
| المتغير | الافتراضي | الغرض |
|---|---|---|
AUDIT_RETENTION_DAYS | 180 | أيام الاحتفاظ بصفوف سجل تدقيق الأمان |
تسجيل الدخول الموحد OIDC العام
يمكن استخدام أي مزوّد OpenID Connect له مستند اكتشاف. يستخدم المسار PKCE (S256) وحالة CSRF وnonce متحققًا منه داخل رمز ID ذي توقيع متحقق. وتُربط الهويات بادعاء sub الثابت.
| المتغير | الافتراضي | الغرض |
|---|---|---|
OIDC_ISSUER_URL | غير مضبوط | عنوان مصدر؛ يُجلب الاكتشاف من <issuer>/.well-known/openid-configuration |
OIDC_CLIENT_ID | غير مضبوط | معرف عميل OAuth المسجل لدى المزوّد |
OIDC_CLIENT_SECRET | غير مضبوط | سر عميل OAuth |
OIDC_DISPLAY_NAME | Single Sign-On | التسمية على زر الدخول |
OIDC_SCOPES | openid profile email | النطاقات المطلوبة |
OIDC_CALLBACK_URL | BASE_URL + مسار استدعاء OIDC | URI إعادة التوجيه المسجل |
OIDC_ALLOWED_EMAIL_DOMAINS | غير مضبوط | قائمة بفواصل؛ تتطلب بريدًا متحققًا في أحد النطاقات |
OIDC_GROUP_CLAIM | groups | ادعاء رمز ID الذي يحمل أسماء المجموعات |
OIDC_ADMIN_GROUPS | غير مضبوط | قائمة بفواصل؛ يتبع دور المسؤول عضوية الادعاء عند كل دخول |
OIDC_SYNC_GROUPS | false | توفق true عضوية مجموعات Libre مع الادعاء عند كل دخول |
لا يُفعّل OIDC إلا بوجود عنوان المصدر ومعرف العميل وسره جميعًا. ويُرفض بريد مستخدم في حساب محلي غير مرتبط بدل دمجه بصمت، ويظل إنشاء الحساب يحترم ENABLE_SIGNUP.
يمكن ضبط قبول WebSocket في Chat من دون إضعاف المصادقة:
| المتغير | الافتراضي | الغرض |
|---|---|---|
CHAT_WS_MAX_PAYLOAD_BYTES | 10 MiB | أقصى حجم رسالة WebSocket مقبول |
CHAT_WS_MAX_MESSAGES_PER_MINUTE | 120 | سقف الرسائل لكل اتصال |
CHAT_WS_MAX_ACTIVE_GENERATIONS_PER_USER | 4 | توليدات المزوّد المسموحة لكل حساب |
CHAT_WS_MAX_CONNECTIONS_PER_USER | 5 | المقابس الموثقة المتزامنة لكل حساب |
WEBSOCKET_TICKET_TTL_MS | 30000 | عمر تذكرة Chat/Work لمرة واحدة؛ بحد 60 ثانية |
يستبدل المتصفح ترويسة Authorization المعتادة بتذكرة مبهمة ويضع القيمة القصيرة وحدها في URL ترقية WebSocket. التذاكر لمرة واحدة ومرتبطة بالبروتوكول والجلسة ومخزنة كتجزئات، فتُبعد رموز الجلسة الدائمة عن سجلات أهداف الوكيل. عند تهيئة CORS_ORIGIN أو BASE_URL، يجب أن يطابق Origin في ترقية المتصفح أصلًا مهيأً. اضبط واحدة على الأقل لنشر بعيد؛ ومن دونهما يبقى المرشح متساهلًا للتطوير المحلي. تُدعم الترقيات بلا أصل عمدًا لـ Electron والعملاء غير المتصفحات، لكنها ما تزال تحتاج تذكرة صحيحة وتخضع لفحوص الحساب وWork والمهمة. تعامل مع التذكرة كحد المصادقة وقيّد الوصول غير المتصفحي بـ TLS والجدار الناري والوكيل.
OAuth
| المتغير | الغرض |
|---|---|
GITHUB_CLIENT_ID | معرف عميل GitHub OAuth |
GITHUB_CLIENT_SECRET | سر عميل GitHub OAuth |
GITHUB_CALLBACK_URL | تجاوز عنوان استدعاء GitHub |
HUGGINGFACE_CLIENT_ID | معرف عميل Hugging Face OAuth |
HUGGINGFACE_CLIENT_SECRET | سر عميل Hugging Face OAuth |
HUGGINGFACE_CALLBACK_URL | تجاوز عنوان استدعاء Hugging Face |
إذا لم تُضبط عناوين الاستدعاء، يبنيها Libre WebUI من BASE_URL.
Ollama
| المتغير | الافتراضي | الغرض |
|---|---|---|
OLLAMA_BASE_URL | http://localhost:11434 | عنوان API الأساسي لـ Ollama |
OLLAMA_TIMEOUT | 300000 | مهلة طلب Ollama العادي (1,000-3,600,000 ms) |
OLLAMA_LONG_OPERATION_TIMEOUT | 900000 | مهلة العملية الطويلة (1,000-3,600,000 ms ولا تقل عن OLLAMA_TIMEOUT) |
OLLAMA_MAX_CONTEXT | 32768 | أقصى سياق نموذج معتمد تلقائيًا (128-2,097,152 رمزًا) |
بحث الويب
| المتغير | الافتراضي | الغرض |
|---|---|---|
SEARXNG_URL | غير مضبوط | نقطة SearXNG الافتراضية لإعداد بحث الويب؛ وما يزال المسؤول يفعّلها في الإعدادات > البحث |
Libre Claw
| المتغير | الافتراضي | الغرض |
|---|---|---|
LIBRE_CLAW_BASE_URL | http://127.0.0.1:8766 | عنوان عفريت Libre Claw الاختياري |
LIBRE_CLAW_TIMEOUT_MS | 30000 | مهلة طلب HTTP لـ Libre Claw |
بيئة تشغيل Work
تهيئ هذه المتغيرات Work على الجهاز أو عنقود Kubernetes الذي يشغل خادم Libre WebUI. Docker هو الافتراضي، ويختار Helm Kubernetes عند work.enabled=true.
| المتغير | الافتراضي | الغرض |
|---|---|---|
WORK_RUNTIME_IMAGE | node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3 | صورة مثبتة لبيئات Work المعزولة |
WORK_DOCKER_COMMAND | docker | برنامج CLI لـ Docker متاح للعملية |
WORK_COMMAND_TIMEOUT_MS | 120000 | المهلة الافتراضية؛ يمكن للأداة طلب حتى 600000 ms |
WORK_MAX_OUTPUT_CHARS | 50000 | حد stdout/stderr الملتقط لكل تدفق |
WORK_MAX_AGENT_ROUNDS | 48 | ميزانية جولات النموذج/الأداة لتشغيل واحد |
WORK_STATUS_BLURB_MODEL | 1 | عيّنه إلى 0 لتخطي طلب النموذج الوحيد الذي يكتب سطر حالة الوكيل في الشريط الجانبي بعد التشغيل |
WORK_MEMORY_LIMIT | 2g | حد ذاكرة كل حاوية Work |
WORK_CPU_LIMIT | 2 | حد CPU لكل حاوية |
WORK_PIDS_LIMIT | 256 | حد العمليات لكل حاوية |
WORK_PREVIEW_PORT | 4173 | منفذ خادم المعاينة داخل الحاوية |
WORK_PREVIEW_BIND | 127.0.0.1 | واجهة المضيف التي يُنشر عليها منفذ المعاينة؛ ويجب أن تستخدم عمليات نشر Compose على Docker Engine الأصلي واجهة جسر غير عامة يمكن الوصول إليها |
WORK_DOCKER_PUBLISHED_HOST | الافتراضي في التطبيق: مثل WORK_PREVIEW_BIND؛ والافتراضي في Compose: host.docker.internal | مضيف/IP الذي يراه الخادم لمنافذ المعاينة والشاشة والصوت المنشورة |
WORK_COMPUTER_SCREEN_PORT | 6080 | منفذ جسر شاشة Work Computer (websockify) في البيئات الرسومية |
WORK_COMPUTER_AUDIO_PORT | 6081 | منفذ جسر صوت Work Computer (websockify → PulseAudio monitor) في البيئات الرسومية |
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL | 3 | المهام المتزامنة ذات البيئة في المثيل كله |
WORK_MAX_ACTIVE_RUNTIMES_PER_USER | 2 | المهام المتزامنة ذات البيئة لكل مستخدم |
WORK_MAX_TASKS_GLOBAL | 500 | أقصى مهام Work دائمة في المثيل |
WORK_MAX_TASKS_PER_USER | 100 | أقصى مهام Work دائمة لكل مسؤول |
WORK_NETWORK_NAME | libre-webui-work | شبكة جسر البيئات المُدارة للمهام الشبكية |
WORK_RUN_LEASE_WAIT_MS | 60000 | انتظار إيجار البيئة المشترك قبل الإبلاغ عن تعارض نسخة (team) |
WORK_RUNTIME_DNS | غير مضبوط | عناوين IP للمحللات المفروضة على المهام، مفصولة بفواصل |
WORK_DOCKER_SOCKET | DOCKER_HOST إذا كان unix:// أو tcp://، وإلا /var/run/docker.sock | نقطة Docker Engine للطرفيات والتشخيص |
WORK_TERMINAL_MAX_SESSIONS_PER_TASK | 2 | طرفيات متصفح متزامنة لكل مهمة |
WORK_TERMINAL_IDLE_TIMEOUT_MS | 900000 | مهلة الخمول قبل إغلاق الطرفية |
WORK_RUNTIME_IDLE_TIMEOUT_MS | 0 (معطل) | إيقاف البيئة بعد هذا الخمول (بما فيه المعاينات) |
WORK_HOST_WORKSPACES_ENABLED | false | السماح باستخدام مجلد مضيف بدل وحدة |
WORK_HOST_WORKSPACE_ROOTS | دليل منزل مستخدم الخادم | جذور مفصولة بـ : يجب أن تكون مساحة المضيف داخلها |
WORK_RUNTIME_BACKEND | docker | خلفية العزل: docker أو kubernetes |
WORK_K8S_NAMESPACE | libre-webui-work | نطاق Pods وPVC المعزولة |
WORK_K8S_STORAGE_CLASS | افتراضي العنقود | StorageClass لـ PVC مساحات العمل |
WORK_K8S_WORKSPACE_SIZE | 5Gi | حجم PVC لكل مهمة (حصة قرص فعلية) |
WORK_K8S_POD_READY_TIMEOUT_MS | 900000 | انتظار وصول Pod إلى Running، بما فيه تنزيل الصور |
WORK_K8S_POD_GONE_TIMEOUT_MS | 60000 | انتظار اختفاء Pod محذوف |
AGENT_CLI_MODELS_ENABLED | غير مضبوط (مفتاح مسؤول، متوقف) | تثبيت ميزة Agents تشغيلًا/إيقافًا؛ وإلا مفتاح إدارة المستخدمين، متوقف افتراضيًا |
TOOLS_ACCESS_MODE | غير مضبوط (مفتاح مسؤول، للمسؤولين) | تثبيت أدوات Chat على admins أو all-users وقفل المفتاح |
STT_ACCESS_MODE | غير مضبوط (مفتاح مسؤول، للجميع) | تثبيت STT على admins أو all-users وقفل المفتاح |
TTS_ACCESS_MODE | غير مضبوط (مفتاح مسؤول، للجميع) | تثبيت TTS على admins أو all-users وقفل المفتاح |
VOICE_MODE_ACCESS_MODE | غير مضبوط (مفتاح مسؤول، للجميع) | تثبيت وضع الصوت بلا يدين على admins أو all-users |
VOICE_CLONING_ACCESS_MODE | غير مضبوط (مفتاح مسؤول، للجميع) | تثبيت استنساخ الصوت على admins أو all-users |
TOOLS_PRIVATE_NETWORK_ALLOWLIST | غير مضبوط | أسماء دقيقة يمكن لخوادم الأدوات وwebhooks حلها إلى عناوين خاصة (بفواصل)؛ مثبتة |
AGENT_CLI_TIMEOUT_MS | 600000 | مدة تشغيل CLI الوكيل قبل قتله |
CODEX_OAUTH_MODELS_ENABLED | true | إتاحة مزوّد Codex (ChatGPT) للمسؤولين |
CODEX_HOME | ~/.codex | موضع قراءة دخول CLI Codex (auth.json) |
برامج CLI للوكلاء وبيانات OAuth لـ Codex محلية للعقدة، ولا تُدعم إلا في عملية solo حيث يرى الاكتشاف والتنفيذ البيئة والملفات نفسها. ينفذ team وظائف Chat الدائمة في عامل خارجي، ولذلك يتطلب AGENT_CLI_MODELS_ENABLED=false وCODEX_OAUTH_MODELS_ENABLED=false؛ يرفض البدء خلاف ذلك بدل إعلان مزوّد موجود على نسخة تطبيق فقط. استخدم Ollama أو مكوّنًا تُخزن بياناته وتوجيهه في PostgreSQL المشترك أو تُمرر بالتساوي.
على Docker، تركّب مساحة المضيف دليلًا حقيقيًا على /workspace فتقرأ المهمة ملفاته وتكتبها مباشرة بدل وحدة خاصة. يرفض Kubernetes ذلك. وهذا تقليل مقصود للعزل؛ أبقِ WORK_HOST_WORKSPACES_ENABLED متوقفًا واجعل WORK_HOST_WORKSPACE_ROOTS ضيقة. تُحل الروابط الرمزية قبل فحص الجذور، وتُرفض مجلدات مثل .ssh و.gnupg و.aws و.config دائمًا.
تعرض نماذج CLI للوكلاء أدوات البرمجة المثبتة على الخادم (claude وcodex) كنماذج Chat، فيجيب وكيل اشتراك بلا مفتاح API. لا يراها إلا المسؤولون، ويعمل CLI كمستخدم خادم Libre WebUI ويرث بياناته؛ عامل ذلك كمنح هؤلاء الوكلاء وصولًا إلى الصدفة.
تتصل مهام Docker الشبكية بجسر WORK_NETWORK_NAME مع تعطيل التواصل بين الحاويات، فلا تصل بيئة إلى أخرى أو حاويات النشر. WORK_RUNTIME_DNS خطاف سياسة خروج Docker؛ وجّهه إلى محلل مصفٍ لقوائم الأسماء. تُرفض وتُسجل القيم غير IPv4/IPv6. لا يقيد DNS الخروج المباشر بعناوين IP؛ أضف جدارًا ناريًا عند الحاجة. أما Kubernetes فيستخدم NetworkPolicies وwork.networkPolicy.blockedEgressCidrs.
تتصل الطرفية وتشخيص النظام بـ Docker Engine مباشرة. تتبع WORK_DOCKER_SOCKET ثم DOCKER_HOST — مقبس unix:// أو نقطة tcp:// HTTP بسيطة مثل وكيل المقبس (راجع docker-compose.socket-proxy.yml) — ثم /var/run/docker.sock. تُبلغ قيمة لا يفهمها العميل (ssh:// أو tcp:// مع DOCKER_TLS_VERIFY) أن الطرفية والتشخيص غير متاحين؛ ويظل Work يعمل عبر CLI الذي يفهمها. على Kubernetes تستخدم الطرفية exec ولا تستخدم Docker.
يقرأ Work القيم عند بدء الخادم. منفذ المعاينة داخلي؛ وينشره Libre WebUI على منفذ التفاف ديناميكي بدل كشفه على كل واجهة.
ثبّت صورة التشغيل على إصدار أو بصمة مراجعة. يرفع زيادة التزامن والموارد ما تستهلكه التشغيلات المستقلة. تنطبق WORK_MAX_AGENT_ROUNDS بالتساوي على Ollama والمكونات، بلا حد أقل للمكونات. ميزانية أمان الأدوات هي max(128, WORK_MAX_AGENT_ROUNDS × 8). عند نفاد الجولات، يطلب Work تسليمًا أخيرًا بلا أدوات وينتهي في needs_input بدل خطأ خام أو ادعاء النجاح. يستمر طلب لاحق في المساحة نفسها. ومخرجات الأداة الدائمة محدودة بنحو 20,000 حرف مصدر مع علامة اقتطاع.
تضبط هذه المتغيرات بيئة متاحة أصلًا. تفعل ملفات Compose ذات المثيل الواحد Work افتراضيًا؛ تحتوي الصورة CLI وتُركّب المقابس. ويتحكم متغيران في ذلك:
| المتغير | الافتراضي | الغرض |
|---|---|---|
DOCKER_GID | 0 | معرف مجموعة مقبس المضيف المضاف لمستخدم الحاوية |
DOCKER_SOCKET | /var/run/docker.sock | مسار مقبس المضيف للتركيب |
يجب أن يكون DOCKER_GID مجموعة المقبس كما تظهر داخل حاوية؛ يعطي macOS قيمة مختلفة. لا يركب Compose الفريق الأساسي مقبسًا ويبقي Work غير متاح حتى إضافة docker-compose.team.work.yml. وتعطي الطبقة التطبيق والعامل نقطة وكيل مفلترة مشتركة، لا مقبسًا أو مجموعة. يسمح الوكيل بأقسام API اللازمة فقط، لكن إنشاء الحاويات ما يزال اعتماد تحكم بالمضيف؛ استخدم عفريتًا مخصصًا أو بلا جذر لحد أقوى. لا يركب Helm مقبس عقدة؛ فعّل Pod/PVC عبر work.enabled=true.
يجب أن يظل solo بصفر أو نسخة واحدة بسبب SQLite والملفات والتنسيق المحلي. يقبل Helm الصفر للتعليق ويرفض أكثر والتوسيع التلقائي. يستخدم team نسخًا متعددة وعاملًا خارجيًا لأن PostgreSQL وS3 وPGVector وRedis تملك الحالة. تتوسع Pods Work مستقلة، ويتلقى عامل الفريق صورة Kubernetes وStorageClass وحدود work.env نفسها.
تقبل ملفات Compose أيضًا WEBUI_BIND_ADDRESS (افتراضي 127.0.0.1) وWEBUI_PORT (افتراضي 8080). أبقِ الالتفاف ما لم تحتج شبكة موثوقة أو وكيل مضيف إلى المنفذ.
اكتشاف نماذج المزوّد
يُعاد اكتشاف كتالوج المزوّد تلقائيًا عند غيابه أو قدمه، فتظهر النماذج الحالية بعد إعادة التحميل. تضبط المتغيرات الدورة:
| المتغير | الافتراضي | الغرض |
|---|---|---|
PLUGIN_MODEL_DISCOVERY_TTL_MS | 21600000 (6 h) | عمر تحديث الكتالوج عند قراءة قائمة المكونات التالية |
PLUGIN_MODEL_DISCOVERY_RETRY_MS | 600000 (10 min) | أقل فاصل للمحاولات حتى لا يُستطلع مزوّد فاشل كثيرًا |
PLUGIN_MODEL_DISCOVERY_REFRESH_DEADLINE_MS | 3000 | مدة انتظار استجابة قائمة المكونات للتحديث |
يكتمل التحديث المتجاوز للمهلة ويُقدم في الطلب التالي. ويتصل تحديث النماذج الصريح دائمًا ويتجاهل الفاصل.
مفاتيح المكونات المزوّدة
يمكن استخدام مفاتيح البيئة كقيم افتراضية للنشر:
| المتغير | المزوّد |
|---|---|
OPENAI_API_KEY | OpenAI وOpenAI TTS |
ANTHROPIC_API_KEY | Anthropic |
GROQ_API_KEY | Groq |
GEMINI_API_KEY | Google Gemini |
MISTRAL_API_KEY | Mistral |
OPENROUTER_API_KEY | OpenRouter |
KIMI_API_KEY | Kimi Code من Moonshot AI |
GITHUB_API_KEY | GitHub Models |
HUGGINGFACE_API_KEY | واجهات Hugging Face المهيأة |
ELEVENLABS_API_KEY | ElevenLabs TTS |
COMFYUI_API_KEY | عمليات ComfyUI التي تتطلب مفتاحًا |
يمكن للمستخدمين تخزين بياناتهم في الواجهة. لا تستخدم مفاتيح البيئة إلا مع توجيه ومصادقة تعريف مضمّن غير محجوب. تتطلب التعريفات المستوردة أو القابلة للكتابة التي تعيد استخدام معرف مضمّن أو الطرق المخصصة بيانات الحساب نفسه. ولا يرفق Libre المفتاح بها أو يكشفه في الاكتشاف. تأتي الثقة من تجزئة مترجمة لكل بيان، فتظل تخطيطات الحاويات المشتركة مدعومة بلا اعتبار بيان معدل مضمّنًا.
تُربط المفاتيح المحفوظة بالتعريف والمصدر وعقد المصادقة وقيم التوجيه. يجب إعادة حفظ المفتاح بعد تغيير الوجهة. ولا تُقبل المفاتيح القديمة غير المرتبطة إلا لتعريف مضمّن دقيق؛ وتُربط في أول استخدام.
في المصدر، تُحل PLUGINS_DIR النسبية من دليل الخادم. يحول المشغل المعبأ القيمة الصريحة إلى مطلقة من المستدعي. وللتوافق، يقرأ Libre backend/plugins والمواقع التاريخية. انقل التعريفات إلى $DATA_DIR/plugins؛ يبلغ الاسترداد عنها كحالة خارجية ويمنع لقطة الوحدات فقط ما دامت هناك. يجب أن تكون الأدلة وJSON ملفات فعلية؛ لا تُتبع روابط المكونات الرمزية.
الواجهة
| المتغير | الافتراضي | الغرض |
|---|---|---|
VITE_API_BASE_URL | وكيل تطوير من نفس الأصل أو API الإنتاج | عنوان API الأساسي للواجهة |
VITE_WS_BASE_URL | مستنتج من عنوان API | أساس ws:/wss: المطلق لمقابس Chat وWork |
VITE_APP_VERSION | إصدار الحزمة المحقون من Vite | إصدار التطبيق المعروض |
VITE_DEMO_MODE | false | تفعيل محاكاة العرض عند true |
VITE_API_TIMEOUT | 300000 | مهلة API بالمللي ثانية |
VITE_BACKEND_URL | http://localhost:3001 | تستخدمه بعض مساعدات المصادقة |
VITE_DEBUG_VERBOSE | غير مضبوط | تفعيل سجل واجهة مفصل في التطوير |
VITE_LOG_LEVEL | غير مضبوط | تجاوز مستوى سجل الواجهة |
ELECTRON_BUILD | غير مضبوط | تفعيل سلوك Vite الخاص بـ Electron عند true |
تتجاوز VITE_WS_BASE_URL كل بدائل WebSocket لـ Chat وطرفية Work. يمكن أن تتضمن بادئة وكيل، لكن يجب أن تكون URL مطلقة ws: أو wss: بلا بيانات أو استعلام أو جزء. عند غيابها، يستخدم عملاء Electron file: القيمة ws://localhost:3001؛ ويشتق المتصفح من VITE_API_BASE_URL ثم أصل المتصفح. يوجّه Vite أصل التطوير إلى الخادم الخلفي على المنفذ 3001.
برامج الصيانة
| المتغير | الغرض |
|---|---|
CHANGELOG_AI | اضبط 0 لتعطيل مسودات سجل التغيير بمساعدة AI |
CHANGELOG_AI_MODEL | نموذج Ollama لتوليد الإصدار/السجل |
CHANGELOG_AI_TIMEOUT_MS | مهلة توليد سجل AI بالمللي ثانية |
مثال:
CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
CHANGELOG_AI=0 npm run release:minor
مثال إنتاج
NODE_ENV=production
PORT=3001
SERVE_FRONTEND=true
DATA_DIR=/data/libre-webui
CORS_ORIGIN=https://librewebui.example
BASE_URL=https://librewebui.example
JWT_SECRET=replace-with-a-long-random-secret
ENCRYPTION_KEY=replace-with-64-hex-characters
ENABLE_SIGNUP=false
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_TIMEOUT=300000
OLLAMA_LONG_OPERATION_TIMEOUT=900000
OLLAMA_MAX_CONTEXT=32768
TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...
TURNSTILE_EXPECTED_HOSTNAME=librewebui.example