الدخول والترخيص¶

يدعم Solar AI Optimizer ثلاث طرق لمصادقة الوصول إلى لوحة المعلومات وواجهة برمجة التطبيقات:

** دخول مساعد المنزل ** — تسجيل الدخول HA يغلف التطبيق؛ تأتي هوية المستخدم من رؤوس الوكيل.
تسجيل دخول المسؤول المحلي — اسم المستخدم/كلمة المرور مع ملف تعريف الارتباط للجلسة الموقعة للوصول المباشر المستقل.
الرمز المميز لحامل واجهة برمجة التطبيقات —Authorization: Bearer <API_TOKEN>للنصوص والأتمتة.

يحظى الدخول دائمًا بالأولوية: عند وجود رؤوس مستخدم HA الموثوق بها، يتم تجاوز صفحة تسجيل الدخول المحلية.

أنماط النشر¶

أ. مستقل مع تسجيل الدخول المحلي¶

يُستخدم عند تعريض لوحة المعلومات مباشرة (على سبيل المثال.http://server:8000).

LOCAL_ADMIN_USERNAME=admin
LOCAL_ADMIN_PASSWORD_HASH=$2b$12$...   # bcrypt hash; prefer over plain password
SESSION_SECRET=long-random-string
TRUST_INGRESS_HEADERS=false

إنشاء تجزئة bcrypt:

python -c "import bcrypt; print(bcrypt.hashpw(b'your-password', bcrypt.gensalt()).decode())"

يعرض المتصفح صفحة تسجيل الدخول حتىPOST /api/auth/loginينجح. قم بتسجيل الخروج من الإعدادات → أمان واجهة برمجة التطبيقات. يدعم نموذج تسجيل الدخول حفظ كلمة مرور المتصفح والملء التلقائي (Chrome وEdge وFirefox).

إعادة تعيين كلمة مرور المسؤول المحلي¶

يمكن إعادة تعيين بيانات الاعتماد دون تحرير ملفات env يدويًا. يكتب البرنامج النصي لإعادة التعيين إلى$DATA_DIR/local_auth.envعلى حجم البيانات.run.shيقوم بتحميل هذا الملف عند بدء التشغيل، متجاوزًا بيئة الحاوية لمفاتيح المصادقة.

Docker Compose (من جذر الريبو):

./scripts/reset-local-password.sh

Proxmox LXC (داخل مضيف الحاوية):

bash /opt/solar-ai-optimizer/reset-local-password.sh
# or, after sourcing solar-common.sh:
solar_reset_local_password

خيارات:--password PASS, --username USER, --keep-sessions, --no-restart.

يطبع البرنامج النصي اسم المستخدم وكلمة المرور الجديدين مرة واحدة ويعيد تشغيل الحاوية افتراضيًا.

ب. مستقل + hass_ingress (Docker)¶

يصل مستخدمو HA إلى التطبيق من خلال الشريط الجانبي HA؛ ولا يستخدمون صفحة تسجيل الدخول المحلية. احتفظ بتسجيل الدخول المحلي المباشر:8000الوصول إذا تم نشر المنفذ.

حاوية المحسن:

LOCAL_ADMIN_USERNAME=admin
LOCAL_ADMIN_PASSWORD_HASH=...
SESSION_SECRET=...
TRUST_INGRESS_HEADERS=true

لا تنشر المنفذ8000بشكل عام عند استخدام الوصول للدخول فقط.

عندما يكون الدخول موثوقًا به - الوظيفة الإضافية الأصلية (SUPERVISOR_TOKEN) أوTRUST_INGRESS_HEADERS=true- مجموعات الخلفيةX-Frame-Options: SAMEORIGINلذلك يمكن لإطار iframe للشريط الجانبي HA تضمين اللوحة، ويثق في رؤوس هوية المستخدم الوكيل. يحتفظ بالوصول المباشر المستقل (أي علم).DENYولا يثق في رؤوس الدخول.

مساعد منزليconfiguration.yaml:

ingress:
  solar_ai:
    title: Solar AI
    icon: mdi:solar-power-variant
    require_admin: false
    work_mode: ingress
    url: http://solar-ai-optimizer:8000
    headers:
      X-Remote-User-Id: $user_id
      X-Remote-User-Name: $username
      X-Remote-User-Display-Name: $user_name

أعد تحميل الدخول في أدوات المطورين → YAML → INGRESS.

لhass_ingress(HACS)، استخدمwork_mode: ingressوui_mode: normal. لا تستخدمui_mode: replace- هذا الوضع مخصص لتضمين صفحات HA، وليس التطبيقات الخارجية. يدعم hass_ingres v1.3.0+$user_id, $username، و$user_nameفيheadersحاجز.

ج. الوظيفة الإضافية لمساعد المنزل¶

متىSUPERVISOR_TOKENتم تعيينه، ويتم الوثوق بالدخول تلقائيًا (رؤوس المستخدم وإطار iframe للشريط الجانبي). تسجيل الدخول المحلي اختياري ويتم إيقافه بشكل افتراضي. افتح اللوحة من الشريط الجانبي HA.

الأدوار في لمحة

يرى مستخدمو المسؤولون جميع علامات تبويب لوحة المعلومات الخمس (بما في ذلك المساعد والإعدادات). يرى مستخدمو العارض النظرة العامة والتوقعات والسجل فقط، مع تجاوزات محدودة في النظرة العامة. انظردليل مستخدم لوحة المعلومات → أدوار لوحة المعلوماتللحصول على لقطات الشاشة ومصفوفة الميزات الكاملة.

المشرف مقابل العارض (مستخدمي الدخول)¶

الدور	كيف تحدد	لوحة القيادة
المسؤول	مالك HA أو`system-admin`مجموعة؛ أو`ADMIN_USER_IDS`القائمة المسموح بها	لوحة تحكم كاملة (نظرة عامة، توقعات، سجل، مساعد، إعدادات)
المشاهد	مستخدمو HA الآخرون عبر الدخول	نظرة عامة، وتوقعات، وسجل فقط — عناصر تحكم محدودة للمشغل في نظرة عامة

يمكن للمشاهدين إيقاف/استئناف المحرك وكل نظام فرعي (تخفيف الأحمال، شحن الشبكة، التحسين) وتشغيل مفتاح الإيقاف (مع التأكيد). لا يمكنهم تثبيت SOC الاحتياطي، أو فرض شحن الشبكة، أو تشغيل دورة تحكم، أو تحديث التوقعات، أو مسح التجاوزات، أو تبديل الظل/المباشر في الواجهة، أو استخدام المساعد، أو فتح الإعدادات.

تفرض مسارات واجهة برمجة التطبيقات المتغيرة نفس الحدود على الواجهة الخلفية. تبقى واجهات برمجة التطبيقات للتكوين والنموذج مخصصة للمسؤول فقط.

القائمة المسموح بها الاختيارية لكسر الزجاج:

ADMIN_USER_IDS=abc123,def456

مرجع واجهة برمجة التطبيقات¶

نقطة النهاية	مصادقة	الوصف
`GET /api/me`	جلسة	المستخدم الحالي والدور
`POST /api/auth/login`	عام	تسجيل دخول المسؤول المحلي؛ مجموعات ملفات تعريف الارتباط
`POST /api/auth/logout`	عام	مسح ملف تعريف الارتباط للجلسة
`GET /api/auth/status`	عام	`{ local_auth_enabled, login_required }`
`GET /api/health`	عام	مسبار الحياة
`GET /api/config`	المشرف	تكوين لوحة القيادة الكاملة (تم رفض المشاهدين)
`GET /api/entities`	المشرف	قائمة كيانات HA للإكمال التلقائي للإعدادات
`POST /api/override`	جلسة	المشرف: أي حقل تجاوز؛ المشاهد: `shadow_mode`, `pause_engine`, `pause_shedding`, `pause_grid_charge`, `pause_optimization`, `force_grid_charge`, `kill_switch` (`kill_switch` يتطلب `confirm=true`)

قائمة التحقق الأمنية¶

يستخدمLOCAL_ADMIN_PASSWORD_HASH، ليس عادياLOCAL_ADMIN_PASSWORD، في الإنتاج.
تعيينSESSION_SECRETإلى قيمة عشوائية طويلة عند تمكين المصادقة المحلية.
تعيينSESSION_COOKIE_SECURE=trueعند العرض عبر HTTPS.
يحفظAPI_TOKENلCI/البرامج النصية؛ فهو يمنح وصول المشرف دون صفحة تسجيل الدخول.
منع الوصول المباشر إلى المنفذ LAN8000عندما يجب على جميع المستخدمين المرور عبر دخول HA.

استكشاف الأخطاء وإصلاحها¶

يرى المالك أو المسؤول شارة VIEWER¶

افتح DevTools → الشبكة وتحققGET .../api/me. يتوقعauth_mode: "ingress"وis_admin: trueلأصحاب HA.
إذاis_adminغير صحيح، تحقق من سجلات المحسنconfig/auth/list failedأوFailed to fetch HA config/auth/list.
تأكد من أن رمز HA طويل العمر (envHA_TOKENأو الإعدادات → اتصال Home Assistant) من حساب المسؤول/المالك - تتطلب واجهة برمجة تطبيقات قائمة المستخدمين بيانات اعتماد المسؤول على الرمز المميز.
كسر الزجاج: مجموعةADMIN_USER_IDS=<your-user-id>(ينسخuser_idمن/api/me) وأعد تشغيل الحاوية.

يومض iframe الفارغ أو HA UI داخل اللوحة عند التحميل الأول¶

إطار iframe فارغ قبل ظهور Solar AI: تعرض الإصدارات الحالية بداية تشغيل ذات علامة تجارية ("التحقق من الوصول...") بمجرد قيام إطار iframe بتحميل HTML، قبل تشغيل JavaScript. قم بالترقية إلى v0.5.7+ إذا كنت لا تزال ترى فجوة بيضاء.

الواجهة الأمامية لـ HA لفترة وجيزة داخل اللوحة: شائعة مع hass_ingress عندما يفتقر عنوان URL للدخول إلى شرطة مائلة زائدة - يتم حل مسارات الأصول النسبية إلى/api/ingress/assets/...بدلاً من/api/ingress/<panel>/assets/...، تحميل الواجهة الأمامية لـ HA لفترة وجيزة.

استخدمwork_mode: ingressوui_mode: normalفي تكوين لوحة hass_ingress.
في DevTools → Network، تأكد من تحميل حزم JS منها/api/ingress/<panel>/assets/...، لا/api/ingress/assets/....
حقن البنيات الحالية أ<base href>وإعادة توجيه الشرطة المائلة الزائدة في HTML للوحة المعلومات لمنع ذلك؛ قم بالترقية إذا كنت لا تزال ترى الفلاش على صورة قديمة.