⏱️ تثبيت Wakapi — متتبع وقت البرمجة المستضاف ذاتياً والمتوافق مع WakaTime على Docker
نشر منصة Wakapi على Ubuntu باستخدام Docker — متتبع وقت البرمجة وإحصائيات المطورين مفتوح المصدر والمستضاف ذاتياً بالكامل والمتوافق 100% مع إضافات WakaTime على المنفذ 3056.
📦 الملفات والأكواد المطلوبة
قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.
التثبيت السريع:
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/wakapi/wakapi-ubuntu.sh
chmod +x wakapi-ubuntu.sh
sudo bash wakapi-ubuntu.sh
خطوات التنفيذ
1 تحميل السكريبت
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/wakapi/wakapi-ubuntu.sh
2 منح صلاحية التنفيذ
chmod +x wakapi-ubuntu.sh
3 تشغيل المثبت
يقوم السكريبت بتثبيت Docker وتجهيز مجلد التخزين الدائم (`./data`) وضبط متغيرات الأمان (`WAKAPI_PASSWORD_SALT`) وتشغيل منصة Wakapi على المنفذ 3056 (المحول من 3000 الداخلي).
sudo bash wakapi-ubuntu.sh
4 إنشاء الحساب وربط محررات الأكواد
افتح متصفحك على الرابط http://ip-سيرفرك:3056. أنشئ حسابك، وانسخ مفتاح الـ API الخاص بك، واضبط ملف `.wakatime.cfg` في محرر VS Code أو بيئات JetBrains لتبدأ بمتابعة وقت برمجتك فورياً.
http://<your-server-ip>:3056
المنافذ المستخدمة
| المنفذ | الغرض |
|---|---|
| 3056 | Dashboard + WakaTime-compatible API (host → container 3000) |
نظرة عامة
تعد Wakapi منصة مفتوحة المصدر وخفيفة لتتبع ساعات البرمجة وإحصائيات المطورين تمت برمجتها بلغة Go لتكون متوافقة بنسبة 100% مع بروتوكول WakaTime. تعمل المنصة عبر المنفذ 3056 (المحول من منفذ 3000 الداخلي) لتستقبل نبضات النشاط البرمجي التلقائية (Heartbeats) من الإضافات الرسمية المثبتة في محررات الأكواد (مثل VS Code وعائلة JetBrains وNeovim وSublime Text). وتقدم لوحات تحكم تفاعلية توضح الساعات البرمجية اليومية، وتوزيع لغات البرمجة، والمشاريع، وفروع Git، مع خصوصية تامة دون إرسال أي بيانات لخوادم تجارية.
لماذا تستخدمه
تفرض المنصات السحابية التجارية (مثل WakaTime Pro) اشتراكات شهرية مدفوعة للاحتفاظ بسجلات الوقت التاريخية، وتخزن أسماء مشاريعك ومسارات ملفاتك البرمجية الحساسة على سحابات خارجية. يمنحك Wakapi سيادة كاملة على بياناتك بنسبة 100%، واحتفاظاً غير محدود بالسجلات التاريخية لسنوات، وبدون أي تكاليف اشتراكات، مع توافق كامل ومباشر مع كافة إضافات محررات الأكواد على سيرفرك الخاص.
متى تحتاجه
- تريد تتبع ساعات البرمجة اليومية آلياً عبر كافة محررات الأكواد دون الحاجة لبدء وإيقاف مؤقتات يدوياً
- تريد بديلاً خاصاً ومستضافاً ذاتياً لمنصة WakaTime يحافظ على سرية أسماء مشاريعك وملفاتك البرمجية
- تريد تحليلات بصرية للغات البرمجة الأكثر استخداماً وتوزيع الوقت على المشاريع والميزات
- تريد توليد شارات ورسوم بيانية تفاعلية (SVG Badges) لعرض نشاطك البرمجي في ملفك الشخصي بـ GitHub
- تحتاج لنظام تتبع إنتاجية خفيف لفريق التطوير بشركتك يعمل مع إضافات WakaTime الرسمية
من يحتاجه
- مهندسو البرمجيات والمطورون المستقلون لتتبع وحساب ساعات العمل الفعلية على مشاريع العملاء
- قادة الفرق البرمجية ومديرو المشاريع لقياس سرعة الإنجاز وتوزيع الجهد البرمجي على اللغات
- مساهمو المشاريع مفتوحة المصدر لتضمين شارات النشاط البرمجي في ملفات التعريف بـ GitHub
- المهتمون بالخصوصية الرقمية وأصحاب السيرفرات المنزلية للقضاء على أدوات التتبع السحابية التجارية
- الطلاب والمتعلمون لمراقبة عادات البرمجة اليومية والالتزام بساعات التدريب والتطوير
حالات الاستخدام الشائعة
- تتبع ساعات العمل البرمجية آلياً في محررات VS Code وPyCharm وNeovim دون تشغيل أي ساعة توقيت
- تضمين شارات حية لملف تعريف GitHub: `https://wakapi.example.com/api/badge/username/interval:any`
- مقارنة الساعات المستغرقة في إعادة هيكلة أكواد بايثون القديمة مقابل كتابة خدمات Go الجديدة
- استخراج تقارير أسبوعية مفصلة لساعات البرمجة لتسهيل محاسبة العملاء وإصدار الفواتير
- مقارنة النشاط البرمجي للفريق عبر فروع Git المختلفة في الوقت الفعلي
الميزات الرئيسية
- توافق كامل مع إضافات WakaTime على المنفذ 3056: يعمل مباشرة مع إضافات VS Code وJetBrains وVim الرسمية
- لوحة تحليلات تفاعلية غنية: رسوم بيانية للغات البرمجة والمشاريع وأنظمة التشغيل والمحررات وفروع Git
- شارات بصرية ديناميكية (SVG Badges): تضمين إحصائيات البرمجة الحية داخل ملفات README بـ GitHub والمواقع الشخصية
- احتفاظ غير محدود بالسجلات: تخزين سجلات سنوات من النشاط البرمجي دون أي قيود اشتراكات
- دعم تعدد المستخدمين ولوحات الصدارة: دعوة أعضاء الفريق ومقارنة الإحصائيات في لوحات صدارة عامة أو خاصة
- توافق مع WakaTime API v1: سهولة استيراد وتصدير البيانات والربط مع أدوات تجميع الإحصائيات
- استهلاك فائق الضآلة للذاكرة: مبرمج بلغة Go ويستهلك ما بين 30 إلى 60 ميجابايت فقط من الرام داخل Docker
- معمارية Docker Compose تجمع Wakapi مع ربط مجلد `./data` لحفظ قاعدة بيانات SQLite وسجلات المستخدمين
كيفية الاستخدام بعد التثبيت
- افتح المتصفح وانتقل إلى الرابط http://ip-سيرفرك:3056 لعرض لوحة تحكم Wakapi
- سجل حسابك الجديد (أو عطل التسجيل العام في ملف `.env` بعد إنشاء حسابك)
- توجه إلى Settings وانسخ مفتاح الـ API Key الخاص بحسابك
- افتح ملف `~/.wakatime.cfg` في حاسوبك واضبط `api_url = http://ip-سيرفرك:3056/api/v1` ومفتاح `api_key`
- ثبت إضافة WakaTime في محرر VS Code أو بيئة التطوير المفضلة لديك
- ضع Wakapi خلف وكيل عكسي مشفر بـ HTTPS (مثل Nginx) مع شهادة SSL صالحة
- أعد سكريبت نسخ احتياطي دوري لمجلد البيانات `./data`
أفضل ممارسات الأمان
- تنبيه أمني حاسم: عيّن قيمة معقدة وعشوائية لمتغير `WAKAPI_PASSWORD_SALT` قبل إنشاء الحسابات
- عطّل التسجيل العام للمستخدمين (`WAKAPI_ALLOW_SIGNUP=false`) بعد إنشاء حسابك الخاص
- استخدم تشفير HTTPS دائماً؛ فمفاتيح الـ API ونبضات النشاط تحتوي على أسماء مشاريعك وملفاتك البرمجية الحساسة
- لا تكشف المنفذ 3056 للإنترنت العام مباشرة دون وكيل عكسي مشفر بـ SSL
- احمِ مجلد البيانات `./data` الذي يحتوي على قاعدة بيانات SQLite بصلاحيات نظام صارمة (`chmod 700`)
- حدّث صورة الحاوية دورياً للحصول على التحديثات الأمنية وإصلاحات الاستقرار
المنافذ وإعدادات جدار الحماية
يقدم Wakapi لوحة الويب والواجهة البرمجية المتوافقة مع WakaTime عبر منفذ TCP 3056 (المحول من 3000 الداخلي). اسمح بالمنفذ 3056 للشبكة المحلية (`ufw allow 3056/tcp`). وفي الإنتاج، وجه حركة المرور عبر وكيل عكسي مشفر بـ SSL على المنفذ 443 ووجهه لمنفذ 3056، مع إبقاء المنفذ 3056 مغلقاً خارجياً.
النسخ الاحتياطي والصيانة
- انسخ مجلد `./data` احتياطياً، والذي يحتوي على ملف قاعدة بيانات `wakapi.db` (SQLite) بكافة سجلات ونبضات البرمجة
- احتفظ بنسخة من ملف `docker-compose.yml` وملف المتغيرات `.env` المحتوي على `WAKAPI_PASSWORD_SALT`
- إذا كنت تستخدم قاعدة PostgreSQL، أتمت استخراج النسخ الدورية عبر `pg_dump`
- أتمت النسخ الاحتياطي اليومي للمجلدات وارفعه إلى مساحة تخزين سحابية عبر restic أو rsync
- اختبر الاستعادة بنسخ ملف `wakapi.db` بحاوية تجريبية والتأكد من ظهور الرسوم البيانية بنجاح
الأخطاء الشائعة
- ترك خيار التسجيل العام `WAKAPI_ALLOW_SIGNUP=true` مفعلاً على سيرفر عام، مما يتيح للغرباء استهلاك موارد السيرفر
- تغيير قيمة `WAKAPI_PASSWORD_SALT` بعد إنشاء الحسابات، مما يؤدي لتعطيل كلمات مرور المستخدمين القائمة
- كتابة الرابط بـ `https://` في ملف `~/.wakatime.cfg` بينما السيرفر يعمل بـ HTTP غير مشفر مما يعطل إرسال النبضات
- عدم ربط مجلد التخزين الدائم `./data`، مما يسبب مسح كافة إحصائيات البرمجة التاريخية عند تحديث الحاوية
- نسيان إضافة مسار `/api/v1` في نهاية الرابط بملف الإعدادات `~/.wakatime.cfg`
استكشاف الأخطاء وإصلاحها
- نبضات البرمجة لا تظهر باللوحة — راجع سجلات الإضافة في ملف `~/.wakatime.log` بحاسوبك للتأكد من عدم وجود أخطاء مصادقة
- رفض الاتصال بالواجهة — تأكد من عمل الحاوية بالأمر `docker compose ps` وافحص السجلات: `docker logs wakapi -f`
- ظهور خطأ مفتاح API غير صالح بالإكستنشن — أعد نسخ مفتاح الـ API بدقة من شاشة إعدادات Wakapi لملف `~/.wakatime.cfg`
- عدم التعرف على لغة البرمجة — يتعرف Wakapi على اللغات من امتدادات الملفات؛ تأكد من حفظ ملفاتك بالامتداد القياسي
- فشل تسجيل حساب جديد — تأكد من تفعيل متغير `WAKAPI_ALLOW_SIGNUP=true` في ملف البيئة
البدائل
منصة WakaTime السحابية التجارية الأصلية. برنامج ActivityWatch مفتوح المصدر للتتبع المحلي. برنامج RescueTime التجاري لتتبع التطبيقات. أداة Clockify لتسجيل ساعات العمل يدوياً. منصة Toggl Track لإدارة الوقت للفرق.
متى لا تستخدمه
تجنب استخدام Wakapi إذا كنت تبحث عن برنامج محلي يعمل على حاسوبك فقط دون أي سيرفر لتتبع عناوين نوافذ المتصفح والتطبيقات الأخرى (حيث يعمل ActivityWatch محلياً بالكامل). وإذا كنت تحتاج لنظام فواتير وإصدار عروض أسعار للعملاء بالساعة، فإن Clockify أو Invoice Ninja مخصصة للفواتير.
هل تحتاج مساعدة احترافية؟
توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.
- التثبيت وتجهيز السيرفر
- الإعداد المتقدم وإعداد التوجيه
- تصليب الأمان وتحسين جدار الحماية
- إعداد شهادات SSL/TLS مع Let's Encrypt
- ربط النطاق المخصص والوكيل العكسي
- جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
- المراقبة الفورية وتنبيهات الجاهزية
- الترحيل من المنصات القائمة
- استكشاف مشكلات الاتصال والأداء وإصلاحها
- سكريبتات أتمتة مخصصة وعقود دعم مستمر
الأسئلة الشائعة
ما هو برنامج Wakapi وكيف يتكامل مع WakaTime؟
يعد Wakapi خادماً مفتوح المصدر ومستضافاً ذاتياً متوافقاً مع واجهات WakaTime API. يتيح لك استخدام إضافات WakaTime الرسمية بمحرراتك البرمجية مع توجيه وتخزين كافة البيانات على سيرفرك الخاص بدلاً من سحابة WakaTime التجارية.
ما هي محررات الأكواد التي يدعمها Wakapi؟
يدعم Wakapi أي محرر كود تتوفر له إضافة WakaTime رسمية! ويشمل ذلك VS Code، وبيئات JetBrains (IntelliJ، PyCharm، WebStorm، PhpStorm)، وNeovim، وVim، وSublime Text، وEmacs، وEclipse، وإضافات المتصفحات.
كيف أقوم بضبط محرر الأكواد لإرسال البيانات إلى سيرفر Wakapi؟
عدل ملف `~/.wakatime.cfg` في مجلد المستخدم بحاسوبك وأضف: `api_url = https://رابط-سيرفرك/api/v1` ومفتاح `api_key = مفتاح_الـ_API_الخاص_بك`.
هل يمكن تضمين شارات إحصائيات البرمجة في ملف تعريفي بـ GitHub؟
نعم! يوفر Wakapi روابط شارات SVG عامة (مثل `https://رابطك/api/badge/اسم_المستخدم/interval:any`) يمكنك تضمينها مباشرة في ملفات Markdown كملف الـ README الشخصي بـ GitHub.
كم يستهلك Wakapi من الذاكرة العشوائية (RAM)؟
تمت برمجة Wakapi بلغة Go بكفاءة عالية، ويستهلك عادة ما بين 30 إلى 60 ميجابايت فقط من الذاكرة العشوائية داخل Docker.