متتبّع ميزانية ذاتي الاستضافة: مفتوح المصدر مع Docker وPostgres

لا يكتمل إعداد Docker Compose الحالي حتى تختار وضع المصادقة. ولتشغيله محليًا من دون تسجيل دخول، استخدم الأمر الصريح التالي:

AUTH_MODE=none make up

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

Expense Budget Tracker متتبّع ميزانية مفتوح المصدر بترخيص MIT، مبني باستخدام Next.js وPostgres. يشرح هذا الدليل ما يتيحه المستودع حاليًا: مسار Docker محلي لمستخدم تقني واحد، ومسار إنتاج موثّق عبر AWS/CDK، ونقاط نهاية مُدارة منفصلة لواجهة المستخدم المستضافة وMCP وAgent API.

اختر أولًا الحدود التي تريدها فعلًا

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

الإعداد	مكان وجود البيانات المالية	ما تتولى تشغيله	الأنسب لـ
Docker Compose محلي	Postgres داخل وحدة تخزين Docker على جهازك	الحاويات والتحديثات والوصول المحلي والنسخ الاحتياطية	مستخدم تقني واحد يريد أساسًا واجهة الويب على جهاز واحد
حساب AWS الخاص بك مع حزمة CDK الموثّقة	RDS وخدمات التطبيق في حساب AWS الخاص بك	AWS وCloudflare والنطاقات والشهادات وتسليم البريد الإلكتروني والأسرار والمراقبة والنسخ الاحتياطية	نشر عام أو متعدد المستخدمين تكون مستعدًا فيه لتحمّل أعباء البنية التحتية
تطبيق الويب المُدار	بيئة Expense Budget Tracker المستضافة	حسابك وسير عمل إدخال البيانات	من يريد واجهة المستخدم من دون تشغيل الخوادم
موصل MCP المستضاف	مساحة العمل المستضافة، عبر خدمة MCP	الموافقة على OAuth واتصال العميل	وكيل يدعم MCP ويحتاج إلى وصول محدد النطاق للقراءة أو الكتابة
Agent API المستضافة	مساحة العمل المستضافة، عبر خدمة API	مفتاح ApiKey طويل الأمد، واختيار مساحة العمل، ومراجعة تعليمات SQL	البرامج النصية ووكلاء سطر الأوامر القادرون على استدعاء HTTP مباشرةً

لا ينشئ أمر Compose المحلي api.your-domain.com أو mcp.your-domain.com. واجهات الوصول الآلي هذه جزء من بنية AWS ومن الخدمة المُدارة. وعندما توجّه عميلًا إلى https://mcp.expense-budget-tracker.com/mcp، فأنت تستخدم مساحة العمل المستضافة، ولا تصل إلى حاوية Postgres على حاسوبك المحمول.

هذا التمييز هو أول قرار ينبغي حسمه عند اختيار متتبّع ميزانية ذاتي الاستضافة: هل تريد تحكمًا محليًا في تطبيق الويب وقاعدة البيانات، أم تكاملات بعيدة تتطلب نشرًا أوسع؟

شغّل متتبّع المصروفات محليًا باستخدام Docker

تحتاج إلى Git وDocker وDocker Compose. استنسخ المستودع وشغّل الخدمات من مجلده الجذر:

git clone https://github.com/kirill-markin/expense-budget-tracker.git
cd expense-budget-tracker
AUTH_MODE=none make up

ثم افتح http://localhost:3000.

المتغير AUTH_MODE إلزامي في Compose. إذا لم تكن قد نسخت .env.example إلى .env، فكرّر البادئة مع كل أمر Compose. وهذا مقصود في الأوامر أدناه.

الأمر make up هو اختصار بسيط لما يلي:

AUTH_MODE=none docker compose -f infra/docker/compose.yml up -d

يعرّف ملف Compose الحالي قاعدة Postgres 18، وخدمة ترحيل تعمل مرة واحدة، وتطبيق الويب المبني بـ Next.js، وخدمة المصادقة، وعامل أسعار الصرف. عند استخدام AUTH_MODE=none، يستخدم تطبيق الويب الهوية المحلية بدلًا من طلب تسجيل الدخول عبر Cognito. اعتبر هذا الوضع مخصصًا للوصول المحلي في بيئة التطوير فقط، ولا تستخدمه مطلقًا للمصادقة على خادم عام.

يمكنك فحص حالة الحاويات ومتابعة سجلات التطبيق بأوامر Compose المعتادة:

AUTH_MODE=none docker compose -f infra/docker/compose.yml ps
AUTH_MODE=none docker compose -f infra/docker/compose.yml logs -f web

أوقف الخدمات باستخدام:

AUTH_MODE=none make down

يربط Makefile هذا الأمر بـ docker compose down من دون -v. وتبقى بيانات Postgres في وحدة التخزين المسماة pgdata، لتُستخدم مجددًا عند تشغيل الخدمات في المرة التالية.

استمرار البيانات على هذا النحو مريح، لكنه لا يُعد نسخة احتياطية. فقد تفقد النسخة الوحيدة بسبب تعطل الجهاز أو تلف القرص أو حذف وحدة التخزين عرضًا أو تنفيذ docker compose down -v صراحةً.

أبقِ هذا الإعداد محليًا

ينشر إعداد Compose تطبيق الويب على المنفذ 3000 في الجهاز المضيف، وPostgres على 5432، وخدمة المصادقة على 8081. كما يتضمن بيانات اعتماد لقاعدة بيانات مخصصة للتطوير. لا تضع هذا الإعداد على مضيف مكشوف للإنترنت وتفترض أن Docker جعله خاصًا.

عند التثبيت على محطة عمل:

• استخدم جدار حماية الجهاز لتقييد الوصول عبر الشبكة؛
• لا تُعِد توجيه المنافذ 3000 أو 5432 أو 8081 من جهاز التوجيه؛
• لا تكشف AUTH_MODE=none عبر وكيل عكسي عام؛
• أبقِ المستودع وملفات .env وملفات تفريغ قاعدة البيانات بعيدًا عن المجلدات العامة أو المشتركة على نطاق واسع.

يوثّق المستودع AWS/CDK بوصفه مسار النشر الإنتاجي. ولا يقدّم إعدادًا جاهزًا ومُحصّنًا لكل خادم VPS أو NAS أو عنقود Kubernetes أو خادم منزلي، حتى لو استطاع مشغّل متمرس تكييف الشيفرة معها.

ما الذي يعمل وما الذي يبقى في Postgres

البنية المحلية صغيرة بما يكفي لفحصها:

• تطبيق الويب Next.js: يقدّم واجهات الميزانية والمعاملات والأرصدة ولوحة المعلومات والعرض التجريبي والدردشة.
• Postgres: يخزّن دفتر الأستاذ وخطط الميزانية وإعدادات مساحة العمل والبيانات الوصفية للحسابات وحالة التطبيق.
• حاوية الترحيل: تطبّق ترحيلات SQL الموجودة في المستودع قبل بدء خدمة الويب.
• عامل أسعار الصرف: يجلب بيانات أسعار الصرف العامة ويكتبها عبر دور محدود الصلاحيات في قاعدة البيانات.
• خدمة المصادقة: تدعم بنية النشر التي تتطلب المصادقة؛ ويتجاوز الاستخدام المحلي للويب Cognito عند ضبط AUTH_MODE=none.

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

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

أنشئ نسخة احتياطية حقيقية قبل اعتبار البيانات آمنة

بالنسبة إلى قاعدة بيانات Compose المحلية الافتراضية، ينشئ الأمر التالي أرشيف Postgres مضغوطًا على المضيف:

AUTH_MODE=none docker compose -f infra/docker/compose.yml exec -T postgres \
  pg_dump -U tracker -d tracker --format=custom \
  > expense-budget-tracker.dump

تعامل مع هذا الملف كما تتعامل مع كشف حساب بنكي. فقد يحتوي على أوصاف المعاملات والأرصدة والفئات والملاحظات وتفاصيل أخرى تكشف الهوية.

يحتاج أي روتين عملي للنسخ الاحتياطي إلى أربعة قرارات:

1. الوتيرة: حدّد مقدار العمل الأخير الذي يمكنك تقبّل فقدانه.
2. موقع ثانٍ: انسخ الملف إلى مكان بعيد عن مضيف Docker حتى لا يؤدي تعطل قرص واحد إلى فقدان النسختين.
3. التشفير والوصول: احمِ الأرشيف أثناء التخزين وقيّد من يمكنه قراءته.
4. اختبار الاستعادة: استعِد النسخة دوريًا على مثيل Postgres منفصل ومتوافق، وتحقق من المعاملات والميزانيات والأرصدة.

أنشئ ملف تفريغ جديدًا قبل تحديث التطبيق. ثم اسحب الشيفرة الجديدة، وأعِد بناء صور Docker، وشغّل الخدمات مجددًا:

git pull
AUTH_MODE=none make build
AUTH_MODE=none make up

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

الاستضافة الذاتية لا تُبقي كل بايت محليًا تلقائيًا

يمكن تشغيل واجهة المستخدم المحلية الأساسية وقاعدة بيانات Postgres على جهازك. لكن البيانات تغادر هذه الحدود عندما تختار ميزة أو نقطة نهاية ترسلها إلى مكان آخر.

دردشة الذكاء الاصطناعي المدمجة

تستخدم الدردشة المدمجة متغير OPENAI_API_KEY. وعند استخدامها، قد تصل المطالبات والمحتوى المرفق أو المستخرج والسياق المالي اللازم لاستدعاءات النموذج إلى OpenAI. يضبط مسار الطلب الحالي store: false، لكن لا بد للمزوّد من معالجة الطلب، كما تتوقف ضوابط الاحتفاظ الأخرى على مؤسسة API الخاصة بك. راجع ضوابط OpenAI الحالية لبيانات API قبل إرسال كشوف الحسابات البنكية أو تفاصيل دفتر الأستاذ.

التتبّع باستخدام Langfuse اختياري، ولا يُفعّل إلا عند ضبط قيم الاتصال وقيمة الإصدار معًا. وعند تفعيله، تُصدَّر بيانات تتبّع الدردشة إلى LANGFUSE_BASE_URL الذي اخترته. يضيف عنوان Langfuse Cloud جهة خارجية أخرى تعالج البيانات؛ أما نشر Langfuse باستضافة ذاتية فينقل تلك الوجهة إلى بنية تحتية تديرها أنت.

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

نشرك الخاص على AWS

يضع نشر AWS الموثّق خدمات التطبيق وRDS في حساب AWS الخاص بك. كما يضيف أنظمة وعلاقات ثقة أخرى: Cloudflare لإدارة DNS وحركة المرور عند الحافة، وCognito للمصادقة، وResend لإرسال رسائل تسجيل الدخول، وشهادات للنطاقات العامة، وSecrets Manager، والمراقبة، واتصالات OpenAI وLangfuse الاختيارية.

تتضمن حزمة CDK بنية تحتية مُدارة للنسخ الاحتياطي لقاعدة البيانات. ومع ذلك، تظل أنت المسؤول عن تحديد ما إذا كانت مدة الاحتفاظ تلائم احتياجاتك، ومراقبة حالات الفشل، واختبار الاستعادة، وتدوير الأسرار، وتطبيق التحديثات، والاستجابة للحوادث. يشكّل «حساب AWS الخاص بي» حدًا واضحًا لما تتحكم فيه، لكنه لا يعني «من دون أطراف ثالثة».

واجهة المستخدم المُدارة وMCP المستضاف وAgent API المستضافة

تبدأ واجهة المستخدم المُدارة من app.expense-budget-tracker.com. إنها المسار الأقل عبئًا تشغيليًا، لكن مشغّل الخدمة ومزوّدي الاستضافة يصبحون جزءًا من حدود البيانات. اقرأ سياسة الخصوصية قبل وضع بيانات مالية حقيقية هناك.

يمكن لعميل يدعم MCP الاتصال بـ:

https://mcp.expense-budget-tracker.com/mcp

يستخدم موصل MCP المستضاف OAuth عبر المتصفح. يسمح النطاق المطلوب expenses:read باكتشاف مساحات العمل وفحص المخطط وإجراء استعلامات القراءة. أما expenses:write فهو منفصل ومطلوب لاستدعاء sql_execute. ابدأ بصلاحية القراءة فقط ما لم يحتج العميل فعلًا إلى إنشاء سجلات مالية أو تغييرها أو حذفها. ويمكن لعميل MCP أيضًا تلقي البيانات التي تعيدها الأدوات، لذلك تظل سياسة الخصوصية الخاصة بالعميل مهمة أيضًا. راجع دليل موصل MCP للاطلاع على الخطوات كاملة.

تمثل Agent API المستضافة واجهة مختلفة تستخدم بيانات اعتماد مختلفة. ابدأ من:

curl --fail --silent --show-error \
  https://api.expense-budget-tracker.com/v1/

بعد إتمام خطوات الإعداد عبر رمز يصل إلى بريدك الإلكتروني، تحصل على مفتاح طويل الأمد. ثم تستخدم الطلبات المباشرة ترويسة المصادقة التالية:

Authorization: ApiKey <key>

تفصل نقاط نهاية SQL الأساسية عمدًا بين استعلام قراءة واحد وعملية كتابة واحدة تمت الموافقة عليها:

• تقبل POST /v1/sql/query تعليمة SELECT أو WITH ... SELECT واحدة ومقيّدة.
• تقبل POST /v1/sql/execute تعليمة واحدة معتمدة من نوع INSERT أو UPDATE أو DELETE.

يُطبّق اختيار مساحة العمل وأمان Postgres على مستوى الصفوف في الخادم. لكنهما لا يحوّلان طلبًا مستضافًا إلى طلب مستضاف ذاتيًا، كما أن مفتاح ApiKey غير مقبول في نقطة نهاية MCP المعتمدة على OAuth. يوثّق مرجع API الاستكشاف واختيار مساحة العمل وفحص المخطط وحدود الطلبات وسياسة SQL الدقيقة. ويتناول دليل API لتتبّع المصروفات الموافقة والمطابقة بمزيد من التفصيل.

ما الذي تتحمل مسؤوليته عند الاستضافة الذاتية

قد تبدو إدارة الشؤون المالية الشخصية للمطورين بسيطة ومريحة من منظور التطبيق: مستودع واحد، وأمر Compose واحد، وقاعدة بيانات واحدة. لكن العمل التشغيلي يستمر بعد نجاح تحميل الصفحة للمرة الأولى.

في إعداد Docker المحلي، تكون مسؤولًا عن:

• تحديثات Docker ونظام تشغيل المضيف؛
• تحديثات التطبيق ومراجعة الترحيلات؛
• ملفات تفريغ قاعدة البيانات، والنسخ المشفرة خارج الجهاز، وسياسة الاحتفاظ، واختبارات الاستعادة؛
• سعة القرص وحالة الحاويات؛
• قواعد جدار الحماية والوصول المادي إلى الجهاز؛
• حماية ملفات .env ومفاتيح API ومفاتيح النماذج والنسخ الاحتياطية.

وللنشر العام، أضف إلى ذلك:

• نطاقًا وإعداد DNS؛
• شهادات TLS وآليات تجديدها؛
• وصولًا خاضعًا للمصادقة بدلًا من AUTH_MODE=none؛
• إرسال رسائل OTP وبيانات اعتماد خدمة الإرسال؛
• مراقبة قاعدة البيانات والخدمات؛
• معالجة التنبيهات والاستجابة للحوادث والتعافي منها؛
• تكاليف السحابة وأمان حساب المزوّد.

دليل الاستضافة الذاتية هو مرجع الإعداد المختصر. وتبقى وثائق النشر في مستودع المصدر المرجع المعتمد لبنية AWS المدعومة.

قائمة تحقق لاتخاذ قرار عملي

يكون متتبّع المصروفات ذاتي الاستضافة خيارًا مناسبًا عندما تنطبق عليك معظم النقاط التالية:

• لا تمانع في تولّي تشغيل Docker وPostgres وصيانتهما بدلًا من استخدامهما مرة واحدة فحسب.
• ستؤتمت النسخ الاحتياطية وتختبر الاستعادة، ولن تعتمد على وحدة التخزين وحدها.
• تريد وصولًا مباشرًا إلى قاعدة بيانات قياسية وشيفرة مصدر يمكنك تدقيقهما أو تغييرهما.
• يكفيك الوصول عبر متصفح محلي، أو أنك مستعد لتشغيل حزمة AWS الموثّقة.
• يمكنك إبقاء AUTH_MODE=none بعيدًا عن الشبكات العامة.
• ستراجع كل مسار اختياري لنقل البيانات إلى الخارج، وخصوصًا دردشة الذكاء الاصطناعي والقياس عن بُعد.

استخدم التطبيق المُدار أو خيارًا مستضافًا آخر إذا كانت النقاط التالية أدق في وصف احتياجاتك:

• تريد إدخال بياناتك المالية ومراجعتها من دون صيانة البنية التحتية.
• تحتاج إلى وصول موثوق عن بُعد، لكنك لا تريد إدارة النطاقات وTLS والمصادقة والبريد الإلكتروني والأسرار والمراقبة.
• قد لا تلاحظ فشل نسخة احتياطية أو تأخر تحديث أمني.
• يلبّي MCP المستضاف والمحدود بنطاقات OAuth أو Agent API المستضافة حاجتك إلى التكامل من دون امتلاك المنظومة كاملةً.

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

ابدأ بالأمر AUTH_MODE=none make up، وأدخل بضع معاملات اختبارية غير حساسة، ثم أوقف الخدمات وشغّلها مجددًا، وأنشئ ملف تفريغ لقاعدة البيانات وتحقق منه. إذا بدت لك هذه الدورة التشغيلية الصغيرة معقولة، فانقل بياناتك الحقيقية. أما إذا بدت عبئًا منذ الآن، فربما يكون الإعداد المُدار الخيار الأكثر واقعية.