استضافة Kimai على VPS: تتبُّع الوقت مفتوح المصدر

لماذا تستضيف Kimai بنفسك؟

• رخصة MIT — بلا رسوم ترخيص وبلا حدّ لعدد المستخدمين يفرضه المزوّد.
• فوترة مدمجة — تُنشأ الفواتير مباشرة من كشوف الساعات، دون أي وحدة خارجية.
• REST API موثّقة — اربط أدواتك الداخلية (التذاكر، الموارد البشرية، لوحات المتابعة) ببياناتك أنت.
• سيادة البيانات — الساعات والأسعار وملفات العملاء تبقى في قاعدة MySQL الخاصة بك.
• منظومة خفيفة — حاوية تطبيق واحدة وقاعدة MySQL، تعمل براحة على خطة VPS للمبتدئين.

البنية: ما الذي يعمل على الـ VPS

مكوّنات المنظومة

• الحاوية kimai — Apache وPHP وتطبيق Symfony في المسار /opt/kimai، والمنفذ 8001 منشور على 127.0.0.1 فقط.
• الحاوية db — MySQL 8.0 مع فحص صحة mysqladmin ping، فلا يبدأ Kimai إلا بعد جاهزية قاعدة البيانات.
• الحجم kimai_db — ملفات بيانات MySQL، أي جميع كشوف الساعات التي تسجّلها.
• الحجم kimai_data — المسار /opt/kimai/var/data، أي الملفات المرفوعة عبر التطبيق (قوالب الفواتير والمستندات).
• الحجم kimai_public — المسار /opt/kimai/public/avatars، أي صور المستخدمين الرمزية.
• الوكيل العكسي — Nginx أو Caddy أو Traefik ينهي اتصال HTTPS ويمرّر الطلبات إلى المنفذ المحلي 8001.

نشر Kimai على ServOrbit

1. 01

   إطلاق النشر

   في منطقة العميل: Marketplace ← ERP والأعمال ← Kimai ← نشر. ينشئ ServOrbit الـ VPS ويثبّت Docker ويشغّل المنظومة (MySQL 8 + Apache/PHP) تلقائيًا.

2. 02

   استلام بيانات الدخول

   انتظر 60 ثانية تقريبًا. تعرض بطاقة التطبيق بيانات الدخول: المعرّف [email protected] وكلمة مرور مولَّدة.

3. 03

   الاتصال دون نطاق

   افتح نفق SSH بالأمر ssh -L 8080:127.0.0.1:8001 root@<IP> ثم افتح http://localhost:8080. أضف نطاقًا من لوحة التحكم متى أصبحت جاهزًا.

4. 04

   إنشاء العميل والمشروع

   أنشئ أول عميل، ثم مشروعًا مرتبطًا به، ونشاطًا واحدًا على الأقل. حدّد سعرًا بالساعة أو ميزانية.

5. 05

   تسجيل الساعات الأولى

   انقر ▶ لتشغيل المؤقّت واختر المشروع والنشاط، وسيسجّل Kimai وقتك أثناء العمل.

التثبيت اليدوي باستخدام Docker Compose

services:
  db:
    image: mysql:8.0
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: kimai
      MYSQL_USER: kimai
      MYSQL_PASSWORD: ${DB_PASSWORD}
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    volumes:
      - kimai_db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
      interval: 10s
      retries: 12

  kimai:
    image: kimai/kimai2:apache-latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:8001:8001"
    environment:
      DATABASE_URL: "mysql://kimai:${DB_PASSWORD}@db/kimai?charset=utf8mb4&serverVersion=8.0.34"
      APP_SECRET: ${APP_SECRET}
      ADMINMAIL: [email protected]
      ADMINPASS: ${ADMIN_PASSWORD}
      TRUSTED_HOSTS: "localhost,127.0.0.1,kimai.your-domain.com"
    volumes:
      - kimai_data:/opt/kimai/var/data
      - kimai_plugins:/opt/kimai/var/plugins
      - kimai_public:/opt/kimai/public/avatars

volumes:
  kimai_db:
  kimai_data:
  kimai_plugins:
  kimai_public:

cat > .env <<EOF
DB_PASSWORD=$(openssl rand -hex 16)
DB_ROOT_PASSWORD=$(openssl rand -hex 16)
APP_SECRET=$(openssl rand -hex 32)
ADMIN_PASSWORD=$(openssl rand -hex 12)
EOF
chmod 600 .env
docker compose up -d
docker compose logs -f kimai

متغيّرات البيئة التي ينبغي معرفتها

• DATABASE_URL — سلسلة اتصال Doctrine: المستخدم وكلمة المرور والمضيف db واسم القاعدة وcharset=utf8mb4 وserverVersion. ولأن كلمة المرور جزء من عنوان URL، تجنّب فيها الرموز @ و/ و:؛ والسرّ الست عشري يحلّ المسألة.
• APP_SECRET — مفتاح Symfony الذي تُوقَّع به الجلسات والرموز. استخدم قيمة عشوائية طويلة تولّدها مرة واحدة ولا تغيّرها دون سبب، لأن تغييرها يُخرج جميع المستخدمين من جلساتهم.
• ADMINMAIL وADMINPASS — حساب المسؤول الأعلى الذي يُنشأ عند التشغيل الأول. بعد أن تعمل النسخة، أدِر الحسابات من الواجهة أو من سطر الأوامر.
• TRUSTED_HOSTS — قائمة أسماء المضيفين المقبولة مفصولة بفواصل. يجب أن تتضمّن نطاقك العام، وإلا رفض Symfony الطلبات.
• MAILER_URL — وسيلة إرسال البريد. يضبطها قالب ServOrbit على null://localhost، فلا تُرسَل أي رسالة. حدّد خادم SMTP لتفعيل استعادة كلمة المرور والإشعارات.

وضع Kimai خلف نطاق مع HTTPS

1. 06

   توجيه DNS

   أنشئ سجل A للنطاق الفرعي kimai.your-domain.com يشير إلى عنوان IP العام للـ VPS، وتحقّق من الانتشار بالأمر dig +short kimai.your-domain.com.

2. 07

   إعداد الوكيل العكسي

   المنفذ 8001 يستمع على 127.0.0.1 فقط، فلا يصل إليه إلا الوكيل المحلي. مثال على كتلة إعداد Nginx:

   server {
       listen 80;
       server_name kimai.your-domain.com;
   
       location / {
           proxy_pass http://127.0.0.1:8001;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
       }
   }

3. 08

   الحصول على الشهادة

   باستخدام certbot وإضافته الخاصة بـ Nginx تُصدَر شهادة Let's Encrypt وتُستكمل كتلة server للمنفذ 443:

   apt install -y certbot python3-certbot-nginx
   certbot --nginx -d kimai.your-domain.com

4. 09

   تعريف Kimai بالنطاق

   أضف kimai.your-domain.com إلى TRUSTED_HOSTS، ثم نفّذ docker compose up -d لإعادة إنشاء الحاوية. إذا بقيت الروابط المولَّدة تبدأ بـ http://، فراجع توثيق Kimai الخاص بالوكلاء العكسيين: لا تُعتمد ترويسات X-Forwarded-* إلا إذا جاءت من وكيل موثوق.

5. 10

   إغلاق ما لا حاجة إليه

   في الجدار الناري افتح المنافذ 22 و80 و443 فقط. لا تنشر MySQL أي منفذ، ولا ينبغي أن تفعل.

إنشاء المستخدمين من سطر الأوامر

docker compose exec kimai /opt/kimai/bin/console kimai:user:create alice [email protected] ROLE_TEAMLEAD

نموذج البيانات: العملاء والمشاريع والأنشطة

الأسعار والميزانيات

• السعر بالساعة — يُحدَّد على مستوى العميل أو المشروع أو النشاط أو المستخدم، ويُطبَّق المستوى الأدق على كل إدخال.
• السعر الثابت — مبلغ مقطوع لكل إدخال، مفيد لخدمة تُفوتَر بسعر محدّد أيًّا كانت مدتها.
• السعر الداخلي — الكلفة الحقيقية للساعة بالنسبة إليك، منفصلة عن السعر المفوتَر، لقياس ربحية كل مشروع.
• ميزانية بالوقت أو بالمال — على مستوى العميل أو المشروع أو النشاط، مع مؤشّر مرئي لنسبة الاستهلاك.
• ميزانية شهرية أو إجمالية — تُتابَع باقة صيانة شهرية بطريقة مختلفة عن مشروع بسعر ثابت طوال مدّته.
• التجاوز — تُظهر لوحات المتابعة نسبة استهلاك الميزانية، ويتيح أحد الإعدادات السماح بالإدخالات التي تتجاوزها أو منعها.

الأدوار والفرق والصلاحيات

• ROLE_USER — يسجّل ساعاته ويراجعها في المشاريع المتاحة له.
• ROLE_TEAMLEAD — يرى ساعات أعضاء فرقه ويعدّلها ويطّلع على تقاريرهم.
• ROLE_ADMIN — يدير العملاء والمشاريع والأنشطة والفواتير والمستخدمين.
• ROLE_SUPER_ADMIN — صلاحيات كاملة، بما فيها إعدادات النظام والصلاحيات.

الفوترة انطلاقًا من كشوف الساعات

إعداد أول قالب فاتورة

1. 11

   إنشاء القالب

   من الفواتير ← القوالب، أدخل اسم الجهة المُصدِرة والعنوان والبيانات البنكية ومهلة الدفع ونص التذييل.

2. 12

   اختيار صيغة الإخراج

   اختر صيغة PDF أو HTML لمستند جاهز للإرسال، أو صيغة مكتبية إن كنت تستكمل الفاتورة في أداة أخرى.

3. 13

   تحديد الترقيم

   اضبط صيغة رقم الفاتورة (بادئة، سنة، عدّاد) للحصول على تسلسل متّصل يوافق ممارساتك المحاسبية.

4. 14

   ضبط الضريبة

   أدخل نسبة الضريبة المطبّقة في القالب، وأنشئ قالبًا لكل نظام ضريبي إن كنت تفوتر عملاء بنسب مختلفة.

واجهة REST API والتكاملات

curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  https://kimai.your-domain.com/api/timesheets

توسيع Kimai بالإضافات

docker compose cp PluginNameBundle kimai:/opt/kimai/var/plugins/
docker compose exec kimai /opt/kimai/bin/console kimai:reload --env=prod

النسخ الاحتياطي والاستعادة

docker compose exec -T db sh -c 'exec mysqldump --single-transaction -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' > kimai-$(date +%F).sql
docker run --rm -v kimai_kimai_data:/data -v "$PWD":/backup alpine tar czf /backup/kimai_data-$(date +%F).tgz -C /data .

docker compose exec -T db sh -c 'exec mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < kimai-YYYY-MM-DD.sql

تحديثات بلا مفاجآت

• النسخ الاحتياطي أولًا — تفريغ قبل التحديث مباشرة يتيح لك التراجع إذا فشل أحد الترحيلات.
• تحديث الصورة — docker compose pull kimai && docker compose up -d kimai، ثم تابع السجلات بالأمر docker compose logs -f kimai. عند الإقلاع تطبّق الحاوية ترحيلات قاعدة البيانات تلقائيًا.
• تثبيت إصدار محدّد — في الإنتاج، استبدل apache-latest بوسم صورة يحمل رقم إصدار، لتقرّر أنت موعد الترقية.
• قراءة ملاحظات الإصدار — بعض الإصدارات الرئيسية تغيّر المتطلبات أو سلوك الإضافات.
• التصدير بانتظام — تصدير كشوف الساعات بصيغة CSV أو XLSX نسخة مقروءة تفيد في التدقيق أو الانتقال إلى أداة أخرى.

حلّ المشكلات الشائعة

• رسالة «Untrusted Host» أو خطأ 400 بعد إضافة نطاق — اسم المضيف غير موجود في TRUSTED_HOSTS. أضفه ثم أعد إنشاء الحاوية.
• خطأ 500 مع «Permission denied» على المجلد var/ — يحدث غالبًا بعد تنفيذ أمر من وحدة التحكّم بمستخدم غير مستخدم خادم الويب. أعد الملكية بالأمر docker compose exec kimai chown -R www-data:www-data /opt/kimai/var ثم نفّذ kimai:reload.
• تعديل في الإعدادات بلا أثر — ذاكرة Symfony المؤقتة تقدّم النسخة القديمة: docker compose exec kimai /opt/kimai/bin/console kimai:reload --env=prod.
• إعادة تشغيل Kimai في حلقة عند الإقلاع الأول — القاعدة غير جاهزة أو DATABASE_URL غير صحيح. راجع فحص صحة db وبيانات الدخول في ملف ‎.env.
• روابط تبدأ بـ http:// خلف وكيل HTTPS — ترويسات X-Forwarded-Proto لا تُرسَل أو لا تُعتبر موثوقة؛ راجع إعدادات الوكيل.
• نسيان كلمة المرور دون بريد مُعَدّ — MAILER_URL يشير إلى null://: أعد تعيين كلمة المرور من حساب مسؤول، أو أنشئ مسؤولًا جديدًا من سطر الأوامر.

Kimai مقارنةً بـ Toggl Track وClockify وHarvest

مرّر الجدول أفقيًا

اختيار حجم الـ VPS المناسب