استضافة Actual Budget على VPS خاص بك عبر Docker

ما الذي ستبنيه

Actual Budget هو تطبيق مستضاف ذاتياً لإدارة الميزانية بنظام الأظرف، وهو الخيار المعتاد لمن يبحثون عن بديل لـ YNAB يمكن استضافته بأنفسهم. يتكوّن الخادم من حاوية واحدة، ووحدة تخزين بيانات واحدة، واسم HTTPS واحد. تعمل عليه كل الوظائف الأساسية للميزانية بسلاسة على أصغر VPS يمكنك استئجاره، لأن الخادم يخزّن الملفات ويزامنها في الغالب.

من المهم فهم البنية قبل كتابة أي أمر. الميزانية نفسها هي قاعدة بيانات SQLite موجودة داخل متصفحك وداخل كل تطبيق جوّال. أما الخادم الذي ستثبّته فهو نقطة نهاية للمزامنة؛ إذ يحتفظ بقائمة الحسابات، وملفات الميزانية، وسجل التغييرات الذي يتيح للهاتف والكمبيوتر المحمول الوصول إلى الحالة نفسها. لذلك يظل التطبيق يعمل عند توقف الخادم، كما أن فقدان الخادم لا يؤدي إلى فقدان ميزانيتك ما دام أحد العملاء لا يزال يحتفظ بنسخة منها.

لماذا يحتاج الخادم إلى HTTPS

يطلب Actual استخدام HTTPS فعلياً، وليس ذلك إجراءً شكلياً. لا تتيح المتصفحات Web Crypto API، وهي الواجهة التي يستخدمها Actual للتشفير من طرف إلى طرف، إلا ضمن ما تسميه المواصفات سياقاً آمناً. السياق الآمن هو https:// أو http://localhost. إذا حمّلت التطبيق من http://203.0.113.10:5006 في متصفح على جهاز آخر، فلن تتوفر هذه الميزات ببساطة، لأن المتصفح لم يسلّمها إلى الصفحة. كما ترفض الإصدارات الرسمية لتطبيق الهاتف عنوان خادم http:// العادي.

لذلك يوجد إعدادان عمليان. ضع شهادة حقيقية على اسم حقيقي أمام الحاوية، وهذا ما يفعله هذا الدليل. أو امنح الخادم شهادة موقّعة ذاتياً باستخدام ACTUAL_HTTPS_KEY وACTUAL_HTTPS_CERT، كما توثّق وثائق المشروع، وتقبّل ظهور تحذير المتصفح على كل جهاز. الحصول على شهادة مجانية من Let's Encrypt يستغرق خمس دقائق، لذا استخدم الخيار الأول.

تثبيت Actual Budget باستخدام Docker Compose

ثبّت Docker أولاً إذا كان الخادم جديداً. إذا كانت صياغة ملف Compose جديدة عليك، يشرح دليل أساسيات Docker Compose لخادم VPS الحقول المستخدمة أدناه.

sudo install -d -m 755 /opt/actual
sudo install -d -m 700 /opt/actual/data

اكتب /opt/actual/docker-compose.yml:

services:
  actual:
    image: actualbudget/actual-server:latest
    container_name: actual
    restart: unless-stopped
    ports:
      - '127.0.0.1:5006:5006'
    volumes:
      - ./data:/data

هناك 3 تفاصيل مهمة في هذا الملف.

الصورة هي actualbudget/actual-server:latest، وقد نشرها المشروع على Docker Hub، كما تتوفر نسخة مطابقة منها في ghcr.io/actualbudget/actual. ويتوفر الوسم latest-alpine للأجهزة منخفضة الطاقة.

يكتب الحاوية كل شيء ضمن /data. ستجد داخله server-files، الذي يحتوي على account.sqlite مع بيانات تسجيل الدخول ورموز الجلسات، وuser-files، الذي يحتوي على ملفات الميزانية نفسها. اربط هذا المسار، وإلا فسيحذف docker compose pull ميزانيتك عند إعادة إنشاء الحاوية. يمكن لـACTUAL_DATA_DIR نقله، لكن الإعداد الافتراضي مناسب.

يُنشر المنفذ على 127.0.0.1 فقط. أما 5006:5006 المجرد فينشر المنفذ على كل الواجهات، ويضيف Docker قواعده قبل قواعد ufw، لذلك سيصبح التطبيق متاحاً على الإنترنت حتى مع وجود جدار ناري يمنع كل الاتصالات. يشرح دليل سبب تجاوز المنافذ التي ينشرها Docker لقواعد ufw هذا السلوك غير المتوقع. يعني الربط بواجهة loopback أن الـreverse proxy الموجود على الخادم نفسه فقط يستطيع الوصول إليه.

شغّله:

cd /opt/actual
docker compose up --detach
docker compose logs -f actual

يستقر السجل بعد أن يعلن الخادم أنه يستمع على المنفذ 5006. تحقّق منه محلياً قبل تعديل DNS:

curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5006/

تعني 200 أن التطبيق يقدّم الخدمة. وتعني curl: (7) Failed to connect أن الحاوية لا تعمل، بينما يعرض docker compose ps أنها توقفت. والسبب المعتاد هو مشكلة في صلاحيات وحدة التخزين المرتبطة، وتظهر في السجل كسطر EACCES.

ضع شهادة واسماً فعلياً أمام الخدمة

وجّه سجل A إلى VPS، budget.example.com، وانتظر حتى يُحلّ الاسم. ثم ثبّت nginx وأصدر الشهادة. يشرح دليل Certbot على Ubuntu 24.04 مع nginx إصدار الشهادة ومؤقت التجديد بالتفصيل.

كتلة الـproxy:

server {
    listen 443 ssl;
    http2 on;
    server_name budget.example.com;

    ssl_certificate     /etc/letsencrypt/live/budget.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/budget.example.com/privkey.pem;

    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:5006;
        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;
    }
}

client_max_body_size هو السطر الذي ينساه الناس. يُرفع ملف الميزانية كاملاً عند إجراء مزامنة كاملة. يعيّن Nginx افتراضياً حجم جسم الطلب إلى 1 MB، لذلك تفشل المزامنة عندما يتجاوز الملف هذا الحجم، ويظهر 413 Request Entity Too Large في سجل وصول nginx، بينما يعرض التطبيق خطأ مزامنة عاماً فقط. لدى الخادم حدوده المنفصلة: القيمة الافتراضية لـACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB هي 20، والقيمة الافتراضية لـACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB هي 50، لذا اضبط حد nginx على قيمة أعلى من الحد المطبّق لديك.

أعد التحميل واختبر:

sudo nginx -t && sudo systemctl reload nginx
curl -fsS -o /dev/null -w '%{http_code}\n' https://budget.example.com/

التشغيل الأول: كلمة المرور وملف الميزانية الأول

افتح https://budget.example.com في متصفح. تطلب منك الشاشة الأولى تعيين كلمة مرور للخادم. تحمي كلمة المرور هذه الخادم بأكمله، لذلك أنشئ كلمة مرور عشوائية وطويلة واحتفظ بها في مكان ستجده لاحقاً، مثل مدير كلمات مرور Vaultwarden مستضاف ذاتياً. لا توجد حسابات مستخدمين لإنشائها. صُمّم خادم Actual ليعمل بكلمة مرور واحدة، لذلك تعني مشاركة ميزانية مشاركة كلمة المرور.

أنشئ بعد ذلك ملف ميزانية. يسألك Actual عما إذا كنت تريد تفعيل التشفير من طرف إلى طرف. اختر نعم، وسيخزّن الخادم النص المشفّر فقط. هذا هو الخيار الصحيح للبيانات المالية على جهاز مستأجر. لكن للتشفير تكلفة فعلية: لا تصل كلمة مرور التشفير إلى الخادم، لذلك إذا فقدتها فسيضيع الملف ولا توجد آلية لإعادة تعيينها. دوّنها قبل تجاوز هذه الشاشة بالنقر.

عيّن أرصدتك الابتدائية استناداً إلى الأرقام الحالية في بنكك، بدلاً من استيراد سجل يمتد لسنوات. تعمل الميزانية بطريقة المظاريف انطلاقاً من الأموال التي تملكها الآن، لذلك لا يسبب غياب السجل السابق أي خسارة.

استيراد المعاملات

هنا تكون الصراحة أهم من الحماس، لأن طريقة استيراد البيانات هي السبب الرئيسي الذي يجعل الناس يتخلون عن تطبيقات إعداد الميزانية المستضافة ذاتياً.

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

يتولى استيراد الملفات الجزء الأكبر من العمل. يقرأ Actual ملفات CSV وQIF وOFX وQFX، وكل بنك يوفّر تصديراً بتنسيق واحد منها على الأقل. استورد البيانات لكل حساب من شاشة الحساب، وعيّن الأعمدة مرة واحدة، وسيحفظ Actual هذا التخطيط للحساب.

تتوفر مزامنة مصرفية تلقائية، لكنها تحتاج إلى خدمة تابعة لجهة خارجية، لأن الخادم لا يستطيع الاتصال بالبنوك بنفسه. يدعم Actual خدمات SimpleFIN Bridge للبنوك في أمريكا الشمالية، وEnable Banking لأوروبا، وAkahu لنيوزيلندا، وPluggy.ai للبرازيل. لا يزال GoCardless مدعوماً، لكنه لا يقبل حسابات جديدة. أنشئ حساباً لدى المزوّد بنفسك، وأنشئ بيانات الاعتماد، ثم أضفها إلى الخادم. تفرض SimpleFIN Bridge رسوماً قدرها 15 دولاراً أمريكياً سنوياً لما يصل إلى 25 مؤسسة، اعتباراً من July 2026، بينما تختلف الأسعار لدى الخدمات الأخرى.

هناك حدّان يجب تقبّلهما قبل الاعتماد على هذه الميزة. تُحفظ بيانات اعتماد API على الخادم، ولا تغطيها التشفيرة من طرف إلى طرف، لأن الخادم يحتاج إلى استخدامها. ولا ينفّذ Actual عملية polling؛ فالمزامنة زر تضغطه، وليست مهمة تعمل في الخلفية.

النسخ الاحتياطية لأن البيانات مجرد ملفات

كل ما يهمك موجود ضمن /opt/actual/data. لا توجد خطوة تصدير، ولا تفريغ لقاعدة بيانات تحتاج إلى برمجته.

المشكلة الوحيدة هي SQLite. قد يؤدي نسخ account.sqlite أثناء كتابة الخادم فيه إلى التقاط معاملة غير مكتملة، ولن تعرف ذلك حتى تحاول الاستعادة. أوقف الحاوية لبضع ثوانٍ، وهي المدة اللازمة لإتمام النسخ:

cd /opt/actual
docker compose stop
restic -r sftp:backup@backup.example.com:/srv/restic backup /opt/actual/data
docker compose start

جدول ذلك باستخدام النهج الوارد في النسخ الاحتياطية باستخدام restic على VPS، الذي يشرح إعداد المستودع، والاحتفاظ بالنسخ، واختبار الاستعادة. نفّذ اختبار الاستعادة. فالنسخة الاحتياطية التي لم تستعدها من قبل ليست سوى تخمين.

النسخ الاحتياطية التي ينشئها عميل Actual على جانب العميل أمر منفصل ويستحق معرفته. يحتفظ المتصفح بنسخ حديثة من ملف الميزانية، ويمكن الوصول إليها من قائمة الملفات. يغطي ذلك حالة «حذفت فئة عن طريق الخطأ» دون لمس الخادم على الإطلاق.

تحديث الخادم

cd /opt/actual
docker compose pull
docker compose up --detach

يعيد Compose إنشاء الحاوية من الصورة الجديدة، ثم يعيد إرفاق وحدة التخزين نفسها، لذلك تبقى البيانات محفوظة. حدّث العملاء أيضاً. من المفترض أن تظل إصدارات الخادم والتطبيق متقاربة، وقد يرفض عميل أقدم بكثير من الخادم المزامنة بسبب عدم تطابق الإصدارات. أنشئ نسخة احتياطية قبل الانتقال بين إصدارين رئيسيين، لأن عمليات الترحيل تُنفَّذ عند التشغيل الأول، ولا يتوفر مسار للرجوع إلى إصدار أقدم. يتسامح Actual مع وسم latest المتحرك لأن حالته عبارة عن دليل من الملفات، لكن التطبيق الذي يستخدم قاعدة بيانات فعلية لا يتسامح معه، ويشرح استضافة Chatwoot ذاتياً الوسوم المثبتة وتفريغ قاعدة البيانات قبل الترقية، وهو الإجراء المطلوب في هذه الحالة.

ما الذي يتعطل وما الذي ستراه

يُحمِّل التطبيق، لكن المزامنة لا تكتمل أبداً. راقب سجل وصول nginx بحثاً عن 413. هذا يعني أن client_max_body_size مضبوط على قيمة منخفضة جداً. أما ظهور 502 فيعني أن nginx يعمل وأن الحاوية لا تعمل.

خيارات التشفير مفقودة، أو يرفض تطبيق الهاتف عنوان URL. الصفحة ليست في سياق آمن. سيعرض شريط العنوان http:// مع عنوان IP أو اسم مضيف ليس localhost. أصلح الشهادة بدلاً من التحايل على المشكلة.

تظهر رسالة تفيد بأن ملف الميزانية غير متوافق مع هذا الإصدار. اختلف إصدارا العميل والخادم. حدّثهما إلى الإصدار نفسه ثم أعد التحميل.

تُعاد تشغيل الحاوية في حلقة متكررة. اقرأ docker compose logs actual. يعني خطأ الصلاحيات على /data أن الدليل المركّب غير قابل للكتابة بواسطة مستخدم الحاوية. ويعني خطأ استخدام العنوان أن شيئاً آخر يستخدم المنفذ 5006 على loopback.

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

FAQ

هل يحتاج Actual Budget إلى HTTPS لكي يعمل؟

نعم، عملياً. يستخدم التشفير التام بين الطرفين في Actual واجهة Web Crypto API في المتصفح، ولا تتيح المتصفحات هذه الواجهة إلا ضمن سياق آمن، أي https:// أو http://localhost. عند استخدام HTTP عادي من جهاز آخر، لا تتوفر هذه الميزات، كما ترفض تطبيقات الهاتف الرسمية عنوان خادم HTTP العادي. استخدم شهادة Let's Encrypt على اسم مضيف حقيقي، أو شهادة موقعة ذاتياً مع ACTUAL_HTTPS_KEY وACTUAL_HTTPS_CERT إذا كنت ستستخدم متصفح سطح مكتب فقط.

هل يستطيع Actual استيراد معاملات حسابي المصرفي تلقائياً؟

فقط عبر خدمة خارجية تنشئ حساباً فيها بنفسك: SimpleFIN Bridge في أمريكا الشمالية، وEnable Banking في أوروبا، وAkahu في نيوزيلندا، وPluggy.ai في البرازيل. يدعم Actual خدمة GoCardless، لكنها لا تقبل حسابات جديدة. تُخزَّن بيانات اعتماد API هذه على خادمك، ولا يشملها التشفير التام بين الطرفين. كما أن المزامنة يدوية، لذلك تضغط زرّاً ولا تجري أي عملية استطلاع في الخلفية. ولا يحتاج استيراد CSV وQIF وOFX وQFX إلى أي جهة خارجية.

ما الذي يجب عليّ نسخه احتياطياً تحديداً؟

دليل البيانات الموصول، وهو /opt/actual/data في هذا الدليل. يحتوي هذا الدليل على server-files/account.sqlite الذي يضم بيانات تسجيل الدخول والجلسات، وعلى user-files الذي يضم ملفات الميزانية. أوقف الحاوية قبل النسخ، لأن نسخ قاعدة بيانات SQLite قيد التشغيل قد يلتقط عملية كتابة غير مكتملة. لا توجد حالة أخرى على الخادم.

ماذا يحدث إذا فقدت كلمة مرور التشفير؟

لا يمكن استرداد الملف. لا تصل كلمة المرور إلى الخادم، وهذا هو الهدف الأساسي من التشفير التام بين الطرفين، لذلك لا توجد طريقة لإعادة تعيينها ولا مسار للحصول على الدعم. خزّنها في مدير كلمات مرور فور إنشاء الملف، واحتفظ بنسخة في مكان لا يعتمد على الخادم نفسه.

ما مقدار موارد الخادم التي يحتاج إليها Actual Budget؟

القليل جداً. تخدم الحاوية الأصول والملفات الثابتة، وتُجرى حسابات الميزانية في المتصفح. يكفيه vCPU مشترك واحد مع 1 GB من RAM، كما يبقى دليل البيانات لميزانية منزلية تحتوي على سجل لعدة سنوات ضمن عشرات الميغابايت. ينتج استهلاك القرص عن النسخ الاحتياطية والحاويات الأخرى، لا عن Actual. إذا كنت تجهّز خادماً يجب أن يشغّل تطبيقاً آخر أكثر استهلاكاً للموارد إلى جانبه، فعادةً ما يكون خادم الصور هو الذي يحدد الحد الأدنى، لذلك راجع مقدار RAM الذي يحتاج إليه PhotoPrism وImmich فعلياً قبل اختيار الخطة. وينطبق المنطق نفسه على حزمة الوسائط: يحدد تحويل الترميز الخطة، بينما تستهلك واجهة أمامية في المتصفح مثل Halcyon، التي تحوّل مكتبة Jellyfin إلى متجر فيديوهات من حقبة التسعينيات يمكن التجول فيه موارد تقارب ما يستهلكه Actual.