وصول ثابت إلى كاظمه داخل WSL (Windows)

وصول ثابت إلى كاظمه في WSL2

يعيّن WSL2 عنوان IP افتراضيًا متغيّرًا (مثل 172.28.225.216). ذلك يكسر الإشارات المرجعية مثل http://172.28.x.x:9090/ بعد إعادة التشغيل.

لا يمكنك بسهولة تجميد عنوان IP الخاص بـ WSL في Hyper-V إلى الأبد. بدلًا من ذلك، ثبّت عنوانًا ثابتًا من جهة Windows:

عنوان URL ثابت	كيف
`http://127.0.0.1:9090/`	portproxy في Windows ← عنوان WSL الحالي
`http://localhost:9090/`	نفس الشيء
`http://kazma.wsl:9090/`	ملف hosts ← عنوان WSL الحالي

بعد إعادة التشغيل (قائمة فحص قصيرة)

افعل هذا بعد إعادة تشغيل Windows أو wsl --shutdown:

1. Windows — تثبيت localhost ‏(PowerShell كمسؤول، مرة كل إقلاع)

cd G:\GitHubRepos\kazma
.\scripts\wsl_fixed_access.ps1 -Distro Hermes_API_1 -Port 9090

اختياري: مجدول المهام ← التشغيل بأعلى الصلاحيات ← عند تسجيل الدخول ← نفس الأمر، فلا تكتبه مرة أخرى أبدًا.

2. WSL — ابدأ كاظمه (كل إقلاع)

cd ~/kazma          # or your WSL clone path
./scripts/start-web.sh

انتظر:

Uvicorn running on http://0.0.0.0:9090

3. المتصفح

إن أعادت واجهات API خطأ 401، فافتح /login وأدخل KAZMA_SECRET، أو تأكد من KAZMA_TRUST_LAN=1 في .env.

لا تحتاجه في كل مرة	فقط عندما
إعادة كتابة الأسرار	الإعداد الأول (استخدم `.env`)
`git pull`	تريد تحديثات الكود
`export KAZMA_HOST=…` يدويًا	غائب عن `.env` / سكربت البدء

سكربت portproxy أحادي التشغيل

من PowerShell كمسؤول (مسار نسخة Windows):

cd G:\GitHubRepos\kazma
.\scripts\wsl_fixed_access.ps1 -Distro Hermes_API_1 -Port 9090

ماذا يفعل:

يقرأ IPv4 الحالي لتوزيعة WSL
يضبط portproxy: ‏127.0.0.1:9090 ← <wsl-ip>:9090
يضبط hosts: ‏kazma.wsl ← <wsl-ip> (يُتخطى إن كان ملف hosts مقفلًا)
يطبع عناوين URL الثابتة

أعد تشغيله بعد كل إعادة تشغيل أو wsl --shutdown ما لم تكن قد أتمتَه (انظر أعلاه).

سكربت البدء (`scripts/start-web.sh`)

مُودَع في المستودع للاستخدام في WSL (وأي Linux):

chmod +x scripts/start-web.sh   # once
./scripts/start-web.sh          # default port 9090
./scripts/start-web.sh 9091     # custom port

`.env` الموصى به (جذر المستودع، مرة واحدة)

# ~/kazma/.env  (do not commit real secrets)
KAZMA_HOST=0.0.0.0
KAZMA_SECRET=your-strong-secret-here
KAZMA_TRUST_LAN=1

KAZMA_HOST=0.0.0.0 — مطلوب كي يستطيع Windows ← عنوان eth الخاص بـ WSL / portproxy الاتصال
KAZMA_SECRET — مطلوب للربط على غير الاسترجاع المحلي (loopback)
KAZMA_TRUST_LAN=1 — ملف تعريف ارتباط تلقائي اختياري لمشغّل واحد للعملاء الخاصين (مثل مضيف Windows ‏172.28.224.1)

يقرأ سكربت البدء .env إن وُجد، ثم يشغّل .venv/bin/kazma serve.

المكافئ اليدوي بلا السكربت:

cd ~/kazma
export KAZMA_HOST=0.0.0.0
export KAZMA_SECRET='your-strong-secret'
export KAZMA_TRUST_LAN=1
.venv/bin/kazma serve 9090

لماذا كان `localhost:9090` معطوبًا

صف portproxy متقادم أمر شائع مع Docker/WSL:

127.0.0.1:9090  →  old-or-wrong-WSL-IP:9090

الأعراض: ERR_CONNECTION_RESET على localhost بينما http://172.28.x.x:9090/ يعمل.

netsh interface portproxy show all
# fix with wsl_fixed_access.ps1, or:
# netsh interface portproxy delete v4tov4 listenaddress=127.0.0.1 listenport=9090

أيضًا: يجب أن تستمع كاظمه على 0.0.0.0، لا على 127.0.0.1 فقط داخل WSL — فـ portproxy يتصل بعنوان eth الخاص بالتوزيعة.

أتمتات اختيارية

تسجيل الدخول في Windows ← تثبيت portproxy

مجدول المهام ← إنشاء مهمة ← التشغيل بأعلى الصلاحيات ← عند تسجيل الدخول ← الإجراء:

powershell.exe -ExecutionPolicy Bypass -File G:\GitHubRepos\kazma\scripts\wsl_fixed_access.ps1 -Distro Hermes_API_1 -Port 9090

اختصار Windows ← بدء كاظمه في WSL

wsl -d Hermes_API_1 -- bash -lc 'cd ~/kazma && ./scripts/start-web.sh'

بديل: الشبك المتطابق في WSL ‏(Windows 11)

في %UserProfile%\.wslconfig:

[wsl2]
networkingMode=mirrored
localhostForwarding=true

ثم wsl --shutdown وأعد التشغيل. يمكن للوضع المتطابق أن يجعل localhost يعمل بلا portproxy على بعض الإصدارات — جرّبه على جهازك. قواعد portproxy المتقادمة ما زالت قادرة على التعارض؛ أزلها عند الحاجة.

عنوان IP ثابت «حقيقي» لـ WSL

غير مدعوم رسميًا لـ WSL2 العادي. فضّل portproxy + hosts + start-web.sh. تجنّب عناوين Hyper-V الثابتة اليدوية ما لم تقبل الكسر عند ترقيات WSL.

قائمة الفحص الكاملة

مرة واحدة: .env فيه KAZMA_HOST / KAZMA_SECRET / KAZMA_TRUST_LAN
مرة واحدة: chmod +x scripts/start-web.sh
كل إقلاع (مسؤول Windows): wsl_fixed_access.ps1 (أو مجدول المهام)
كل إقلاع (WSL): ./scripts/start-web.sh
المتصفح: http://127.0.0.1:9090/
عند أخطاء 401: /login بالسر، أو تأكيد KAZMA_TRUST_LAN=1