BTCPay Server مع دعم Zcash: دليل كامل للتثبيت والتكامل
يتيح BTCPay Server للشركات عبر الإنترنت قبول مدفوعات العملات المشفّرة مباشرة، من دون وسطاء أو أوصياء حفظ. يشرح لك هذا الدليل العملية الكاملة لإعداد BTCPay Server مع دعم أصلي لمدفوعات Zcash المحمية.
تركز هذه الوثائق على دمج Zcash في مثيل BTCPay Server الخاص بك.
وهي تدعم كلاً من إعدادات العقدة الكاملة (Zebra) وإعدادات المبنية على lightwalletd.
جدول المحتويات
لماذا تستخدم BTCPay Server مع Zcash
يزداد اعتماد التجارة الإلكترونية على العملات المشفّرة. فهي سريعة، وعالمية، وتعمل من دون بنوك. وهذا يفيد كلاً من التجار والعملاء. لكن هناك تفصيلاً مهماً يغفل عنه كثيرون.
عند تقديم طلب شراء، يقدّم العميل عادةً معلومات شخصية: الاسم، وعنوان الشحن، ورقم الهاتف. وإذا تم الدفع باستخدام بلوكشين عامة - مثل Bitcoin أو Ethereum أو العملات المستقرة على Ethereum أو Tron - تصبح المعاملة مرئية بشكل دائم للتحليل.
يمكن لأي شخص، حتى من دون معرفة ما الذي تم طلبه، أن:
- يرى متى تم الدفع وكم كان المبلغ
- يتتبّع مصدر الأموال وإلى أين ذهبت
- يربط عنوان عملة مشفّرة بشخص حقيقي إذا وُجدت أي نقطة ترابط (مثل بريد إلكتروني مسرّب أو اسم الشحن)
وهذا يعني أن عملية شراء واحدة قد تكشف التاريخ المالي الكامل للعميل.
وينطبق الأمر أيضاً في الاتجاه المعاكس. فإذا ظهر عنوان التاجر على السلسلة في أي وقت، يصبح مكشوفاً. ويمكن للمنافسين والمراقبين الخارجيين تتبّع أحجام المدفوعات، ونشاط المورّدين، وبنية تدفقات الأعمال.
إن الجمع بين BTCPay Server وZcash يمكنه حل هذه المشكلة.
BTCPay Server هو نظام مجاني ولامركزي لاستقبال مدفوعات العملات المشفّرة.
وهو ليس وسيط دفع ولا يحتفظ بأي أموال. تذهب جميع المدفوعات مباشرة إلى محفظة التاجر.
ويمكن أن تكون هذه محفظة شخصية أو إعداد multisig داخل مؤسسة.
يتولى الخادم مهام التنسيق التالية:
- إنشاء عنوان فريد لكل طلب
- تتبّع وقت استلام الدفعة وربطها بالطلب
- إصدار الإيصالات والإشعارات
- توفير واجهة دفع للعميل
كل شيء يعمل تحت سيطرة صاحب المتجر، من دون الاعتماد على خدمات طرف ثالث.
Zcash هي عملة مشفّرة مبنية على براهين انعدام المعرفة. وهي تدعم نموذج معاملات خاص بالكامل.
وعند استخدام العناوين المحمية (وسيشار إليها من الآن فصاعداً ببساطة باسم “العناوين”)، لا يتم الكشف عن المُرسِل أو المستلم أو مبلغ المعاملة على البلوكشين.
بالنسبة للمتاجر الإلكترونية، فهذا يعني:
- يمكن للمشتري إتمام الدفع من دون الكشف عن تاريخه المالي
- يتلقى البائع الدفعة من دون كشف عنوانه أو حجم مبيعاته أو بنية معاملاته
- لا يمكن لأي مراقب خارجي ربط الدفعة بالطلب أو ببيانات العميل
مثال عملي
يقوم مستخدم بتقديم طلب ويختار Bitcoin أو USDT كوسيلة للدفع.
يُنشئ الموقع عنوان دفع ويعرض المبلغ.
بعد تنفيذ الدفع، يتم تخزين هذا العنوان على البلوكشين ويصبح عاماً.
ولا يحتاج المهاجم إلا إلى ربط طلب واحد بذلك العنوان ليحصل على رؤية طويلة الأمد لتاريخ معاملاته بالكامل.
تخيّل الآن الوضع نفسه مع Zcash.
يُنشئ BTCPay Server عنواناً محمياً. ويرسل المشتري الدفعة.
ومن منظور البلوكشين، لا يحدث شيء. لا توجد بيانات عامة يمكن تحليلها.
يتلقى الخادم التأكيد، ويربطه بالطلب، ويُكمل العملية.
وبالنسبة لأي طرف خارجي، يبدو الأمر وكأن شيئاً لم يحدث.
يبقى كل المنطق محصوراً بين المتجر والعميل - كما ينبغي أن يكون.
هذا الحل لا يساوم على الأتمتة أو سهولة الاستخدام.
فكل شيء يعمل بالطريقة نفسها كما في العملات المشفّرة الأخرى، ولكن من دون خطر تسرّب البيانات.
كيف يعمل BTCPay Server
يعمل BTCPay Server كجسر لمعالجة المدفوعات بين منصة التجارة الإلكترونية الخاصة بك والبلوكشين. وإليك كيفية سير التدفق:
-
يقدّم العميل طلباً على موقعك الإلكتروني (مثل WooCommerce أو Magento أو أي منصة تدعم تكامل BTCPay).
-
يطلب المتجر فاتورة دفع من BTCPay Server. ويولّد الخادم فاتورة فريدة تتضمن:
- مبلغ الطلب
- مؤقّتاً تنازلياً
- عنوان Zcash موحّداً (UA) - مثل
u1... - يتضمن مستقبِل Orchard (محمياً) بشكل افتراضي.
-
يرى العميل صفحة الدفع ويرسل ZEC إلى العنوان المقدم.
-
يراقب BTCPay Server البلوكشين، ويفحص الدفعة مقارنةً بـ:
- المبلغ المتوقع
- عنوان الاستلام
- الطابع الزمني للفاتورة
-
بمجرد اكتشاف المعاملة وتأكيدها، يقوم BTCPay بإخطار المتجر.
-
يتلقى العميل تأكيد الدفع. ويمكن للخادم، اختيارياً، إرسال إيصال عبر البريد الإلكتروني.
تحدث هذه العملية بالكامل بشكل تلقائي، من دون وسطاء أو أوصياء حفظ.
ولا يقوم BTCPay Server بالاحتفاظ بأي أموال - بل يربط ببساطة نظام الطلبات بالبلوكشين بطريقة آمنة وخاصة.
أين يتم تخزين الأموال؟ ومن يتحكم في المفاتيح الخاصة؟
BTCPay Server ليس محفظة ولا يتطلب مفاتيح خاصة.
تذهب جميع الأموال مباشرة إلى محفظة التاجر. ويتم ضمان الأمان من خلال استخدام بنية قائمة على مفاتيح العرض.
كيف يعمل ذلك
-
يتم إنشاء المحفظة مسبقاً.
يستخدم التاجر محفظة Zcash تدعم مفاتيح العرض - مثل Zkool أو Zingo! Wallet.
وتتوفر قائمة كاملة على ZecHub.wiki.
-
يتصل BTCPay Server عبر مفتاح عرض.
مفتاح العرض هو مفتاح للقراءة فقط: يمكنه اكتشاف المدفوعات الواردة وإنشاء عناوين استلام جديدة،
لكنه لا يستطيع إنفاق الأموال. ولا يخزّن الخادم عبارات الاسترداد أو المفاتيح الخاصة.
-
يتم الوصول إلى بيانات البلوكشين عبر خادم lightwalletd.
يمكنك استخدام عقدة عامة مثل https://zec.rocks، أو تشغيل حزمة Zebra + lightwalletd الخاصة بك للحصول على سيادة كاملة.
-
يحصل كل طلب على عنوان فريد.
تسمح مفاتيح العرض للخادم باشتقاق عناوين Zcash محمية جديدة لكل فاتورة،
ما يتيح تتبّع المدفوعات بأمان ويمنع إعادة استخدام العناوين.
-
تحتفظ بالتحكم الكامل في الأموال.
حتى إذا تم اختراق الخادم، فلن يتمكن أحد من سرقة أموالك - إذ إن بيانات وصف المدفوعات فقط هي التي قد تنكشف.
يفصل هذا التصميم بين البنية التحتية والتحكم في الأصول.
ويمكنك تحديث BTCPay Server أو نقله أو إعادة تثبيته من دون تعريض أي أموال للخطر.
كيفية إعداد BTCPay Server لقبول Zcash
في الأقسام السابقة، شرحنا كيف يعمل BTCPay Server مع Zcash ولماذا يهم ذلك للمدفوعات التي تحافظ على الخصوصية. والآن حان وقت التطبيق العملي.
سيعتمد الإعداد الدقيق الخاص بك على عدة عوامل:
- هل لديك بالفعل مثيل BTCPay Server؟
- هل تريد استخدام lightwalletd عامة أم تشغيل عقدتك الكاملة الخاصة؟
- هل سيعمل الخادم على VPS أم في المنزل؟
يغطي هذا الفصل جميع سيناريوهات الإعداد الحالية - من التهيئات الدنيا إلى عمليات النشر ذات السيادة الكاملة.
سنستعرض ما يلي:
- كيفية نشر كل شيء من الصفر على VPS، بما في ذلك العقدة الكاملة (Zebra)
- كيفية تشغيل BTCPay Server في المنزل مع إبقاء عنوان IP الخاص بك مخفياً باستخدام Cloudflare Tunnel
- كيفية تفعيل ودعم Zcash وإعداده داخل واجهة الويب الخاصة بـ BTCPay Server
- كيفية دمج BTCPay مع موقعك الإلكتروني أو متجرك عبر الإنترنت
نشر BTCPay Server مع دعم Zcash
لننتقل الآن إلى الإعداد الفعلي. في هذا القسم، سنثبّت BTCPay Server مع دعم Zcash - سواء على VPS جديد أو بإضافة دعم ZEC إلى مثيل موجود.
إذا كان BTCPay Server يعمل لديك بالفعل (مثلاً لـ BTC أو Lightning)، فلا حاجة إلى إعادة تثبيت كل شيء - فقط فعّل إضافة ZEC.
سنستعرض تهيئات مختلفة، من الإعدادات الدنيا التي تستخدم عقدة lightwalletd عامة إلى عمليات التثبيت ذات السيادة الكاملة باستخدام عقدتك الكاملة الخاصة.
ويعتمد الخيار الأفضل على موقع الخادم لديك ومدى الاستقلالية التي تريدها عن البنية التحتية الخارجية.
وثائق الإضافة الرسمية:
https://github.com/btcpay-zcash/btcpayserver-zcash-plugin
تحذير - محفظة واحدة لكل مثيل:
تستخدم إضافة Zcash محفظة مشتركة واحدة عبر جميع المتاجر في مثيل BTCPay.
إذا كنت تستضيف عدة متاجر مستقلة على مثيل واحد، فستتشارك جميعها محفظة Zcash نفسها.
استخدم مثيلات منفصلة إذا كنت بحاجة إلى عزل صارم للمحافظ.
إعداد VPS الموصى به
قبل التثبيت، تأكد من توفر ما يلي:
- VPS يعمل بنظام Ubuntu 22.04+
- اسم نطاق يشير إلى عنوان IP الخاص بخادمك (عبر DNS)
- تثبيت
git وdocker وdocker-compose
- وصول SSH إلى الخادم
تحضير الخادم الخاص بك (جزء مخفي)
انقر للتوسيع
لنشر BTCPay Server مع دعم Zcash، ستحتاج إلى ما يلي:
1. VPS بنظام Ubuntu 22.04 أو أحدث
نوصي باستخدام تثبيت أدنى لنظام Ubuntu Server 22.04 LTS.
وسيعمل أي مزود VPS يوفّر عنوان IP مخصصاً.
الحد الأدنى للمتطلبات:
- نواتا CPU
- 4 GB RAM
- 40 GB من مساحة القرص
هذا الإعداد كافٍ إذا كنت تستخدم lightwalletd من أجل Zcash.
أما إذا كنت تخطط لتشغيل عقدة Zcash كاملة، فستحتاج إلى 300 GB على الأقل من مساحة التخزين الحرة.
2. اسم نطاق يشير إلى خادمك
في لوحة تحكم مزود DNS الخاص بك، أنشئ سجل A لنطاق فرعي
(مثل btcpay.example.com) يشير إلى عنوان IP الخاص بـ VPS.
سيُستخدم هذا النطاق للوصول إلى BTCPay Server من المتصفح
ولإنشاء شهادة SSL مجانية تلقائياً عبر Let's Encrypt.
3. وصول SSH إلى الخادم
لتثبيت BTCPay Server، يجب أن تتصل بـ VPS عبر SSH.
من الطرفية، شغّل:
ssh root@YOUR_SERVER_IP
إذا كنت تستخدم macOS أو Linux أو WSL على Windows، فإن SSH متاح بالفعل في الطرفية.
أما على Windows العادي، فاستخدم عميل SSH مثل PuTTY.
4. تثبيت Git وDocker وDocker Compose
بعد الاتصال عبر SSH، حدّث حزم النظام وثبّت المكونات المطلوبة:
Code-highlight
sudo apt update && sudo apt upgrade -y
sudo apt install git curl docker.io docker-compose-plugin -y
sudo systemctl enable docker
في Ubuntu 22.04 والإصدارات الأحدث، أصبح docker-compose من APT قديماً.
الحزمة الموصى بها هي docker-compose-plugin، وهي التي توفّر الأمر docker compose (لاحظ المسافة بدلاً من الشرطة).
أصبحت بيئة خادمك الآن جاهزة لتثبيت BTCPay Server.
الخطوة 1: استنساخ المستودع
أنشئ دليل عمل ونزّل نشر Docker الخاص بـ BTCPay Server:
Code-highlight
mkdir BTCPayServer
cd BTCPayServer
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker
الخطوة 2: تصدير متغيرات البيئة
استبدل btcpay.example.com بنطاقك الفعلي:
Code-highlight
export BTCPAY_HOST="btcpay.example.com"
export NBITCOIN_NETWORK="mainnet"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_CRYPTO2="zec"
export BTCPAYGEN_REVERSEPROXY="nginx"
export BTCPAYGEN_LIGHTNING="none"
إذا كنت تخطط لإضافة Monero أو Litecoin لاحقاً، يمكنك تضمينهما الآن:
Code-highlight
export BTCPAYGEN_CRYPTO3="ltc"
export BTCPAYGEN_CRYPTO4="xmr"
يمكنك إضافة عملات جديدة في أي وقت عبر تصدير المتغيرات المناسبة وإعادة تشغيل سكربت الإعداد:
. ./btcpay-setup.sh -i
في هذا الدليل، سنركّز على Zcash فقط.
الخطوة 3: تشغيل المثبّت
شغّل سكربت الإعداد لبناء الخادم وتشغيله:
. ./btcpay-setup.sh -i
سيقوم السكربت بتثبيت التبعيات، وإنشاء docker-compose.yml، وبدء الخدمات، وتهيئة systemd.
ويستغرق ذلك نحو 5 دقائق.
بمجرد اكتمال العملية، سيكون مثيل BTCPay Server الخاص بك متاحاً على:
https://btcpay.example.com
إذا كنت تعدّل تثبيتاً موجوداً (مثل إضافة ZEC)، فتأكد من إيقاف الخادم وإعادة تشغيله بالإعدادات الجديدة:
Code-highlight
cd ~/BTCPayServer/btcpayserver-docker
btcpay-down.sh
. ./btcpay-setup.sh -i
ثم انتقل إلى القسم التالي لإعداد Zcash في واجهة الويب الخاصة بـ BTCPay Server.
تشغيل عقدة Zcash كاملة خاصة بك
إذا كنت تفضّل عدم الاعتماد على عقد lightwalletd العامة، فيمكنك نشر عقدة Zcash كاملة خاصة بك مع lightwalletd على الخادم نفسه.
ويمنحك هذا استقلالية كاملة - من دون تبعيات خارجية ومن دون حاجة إلى الثقة بأي طرف.
الخطوة 1: التأكد من توفر مساحة قرص كافية
تتطلب عقدة Zcash الكاملة (Zebra + lightwalletd) حالياً أكثر من 300 GB من مساحة القرص، وهي تواصل النمو.
التفصيل:
- قاعدة بيانات بلوكشين Zebra: نحو 260-270 GB
- فهرسة lightwalletd: نحو 15-20 GB
التخزين الموصى به:
- 400 GB+ إذا كان الخادم يُستخدم فقط لمدفوعات Zcash
- 800 GB+ إذا كان الخادم يشغّل أيضاً BTCPay Server وPostgreSQL وNginx وغيرها
من المثالي استخدام قرص SSD/NVMe بسعة 1 TB، خصوصاً إذا لم تكن تخطط لتقليم البيانات بانتظام.
الخطوة 2: تعيين متغيرات البيئة
أضف ما يلي إلى إعداد البيئة لديك لتفعيل تهيئة العقدة الكاملة:
Code-highlight
export BTCPAYGEN_EXCLUDE_FRAGMENTS="zcash"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="zcash-fullnode"
سيؤدي ذلك إلى تضمين الجزء zcash-fullnode، الذي يشغّل كلاً من zebrad وlightwalletd داخل BTCPay Server.
الخطوة 3: إعادة تشغيل المثبّت
. ./btcpay-setup.sh -i
سيقوم السكربت بما يلي:
- تنزيل صور Docker الخاصة بـ Zebra وlightwalletd
- إعداد الخدمات داخل حزمة BTCPay
- ربط إضافة Zcash بمثيل
lightwalletd المحلي
قد تستغرق مزامنة البلوكشين الكاملة عدة أيام، خاصة على خوادم VPS منخفضة الموارد.
وحتى تكتمل المزامنة، لن تكون المدفوعات المحمية متاحة.
الاتصال بعقدة lightwalletd خارجية
في معظم الحالات، لا تكون الاستقلالية الكاملة مطلوبة - وقد لا يرغب التجار في إنفاق الوقت ومساحة القرص لتشغيل عقدة Zcash كاملة.
وبشكل افتراضي، يتصل BTCPay Server بعقدة lightwalletd عامة للتعامل مع المدفوعات المحمية من دون تنزيل البلوكشين بالكامل.
نقطة النهاية الافتراضية هي:
https://zec.rocks:443
ومع ذلك، يمكنك إعداد BTCPay Server للاتصال بأي عقدة lightwalletd خارجية، مثل:
https://lightwalletd.example:443
يوضح هذا القسم كيفية القيام بذلك باستخدام جزء Docker مخصص.
يتوفر مثال إعداد كامل بجميع متغيرات البيئة في مستودع الإضافة.
وتعرض الخطوات أدناه إعداداً أدنى صالحاً للعمل.
الخطوة 1: إنشاء جزء Docker مخصص
في دليل مشروع BTCPayServer لديك، أنشئ ملف جزء مخصص:
Code-highlight
cd ~/BTCPayServer/btcpayserver-docker
mkdir -p docker-compose-generator/docker-fragments
nano docker-compose-generator/docker-fragments/zcash-lightwalletd.custom.yml
أضف المحتوى التالي:
Code-highlight
exclusive:
- zcash
يضمن التوجيه exclusive أن يكون جزء واحد فقط يحمل التسمية نفسها (zcash في هذه الحالة) نشطاً في الوقت نفسه.
وهذا يمنع تعارضات الإعداد - فعلى سبيل المثال، لا يمكنك تشغيل جزء zcash-fullnode وجزء lightwalletd الخارجي المخصص هذا في الوقت نفسه.
ومن خلال وضع exclusive: zcash، سيقوم BTCPay Server تلقائياً بتعطيل الحاويات الافتراضية الخاصة بـ zcash-fullnode وlightwalletd الداخلية، ما يتيح لك الاتصال بعقدتك الخارجية الخاصة بدلاً من ذلك.
الخطوة 2: تعيين متغيرات البيئة
في الطرفية:
Code-highlight
export BTCPAYGEN_EXCLUDE_FRAGMENTS="$BTCPAYGEN_EXCLUDE_FRAGMENTS;zcash"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;zcash-lightwalletd.custom"
الخطوة 3: تحديد عنوان العقدة الخارجية
افتح ملف .env:
nano .env
أضف السطر التالي، مع استبدال الرابط بنقطة النهاية التي اخترتها:
ZCASH_LIGHTWALLETD=https://lightwalletd.example:443
يمكنك استخدام:
- عقدة عامة، مثل
https://zec.rocks:443
- عقدتك المستضافة ذاتياً، المنشورة بشكل منفصل عن BTCPay Server
إذا أصبحت lightwalletd الخارجية غير متاحة أو مثقلة بالتحميل، فستفشل المدفوعات المحمية.
وبالنسبة للخدمات الحرجة، اختر نقطة نهاية مستقرة ومجرّبة (مثل zec.rocks الافتراضية).
هل تريد استضافة lightwalletd ذاتياً؟
يمكنك استخدام الملف docker-compose.lwd.yml من مستودع Zebra.
تحذير: هذا الإعداد غير موثّق رسمياً ويتطلب إعداد TLS يدوياً، وإعادة توجيه المنافذ، وتهيئة الجدار الناري - ويوصى به فقط للمستخدمين المتقدمين.
الخطوة 4: إعادة تشغيل المثبّت
. ./btcpay-setup.sh -i
سيطبّق BTCPay Server إعدادك المخصص وسيتصل بعقدة lightwalletd المحددة.
ومن الآن فصاعداً، ستستخدم إضافة Zcash نقطة النهاية الخارجية تلك للتعامل مع المعاملات المحمية.
استضافة BTCPay Server في المنزل باستخدام Cloudflare Tunnel
هل تريد قبول مدفوعات Zcash أثناء استضافة BTCPay Server على جهاز منزلي - مثل Raspberry Pi 5 أو أي خادم محلي من دون عنوان IP ثابت؟
يمكنك تعريض مثيلك للإنترنت بأمان باستخدام Cloudflare Tunnel.
تتجنب هذه الطريقة إعادة توجيه المنافذ وتخفي عنوان IP الحقيقي الخاص بك عن العامة - مع إبقاء خادمك متاحاً عبر HTTPS.
كما تساعدك أيضاً على تجنّب تكلفة استئجار VPS، وهو ما يعد مثالياً إذا كانت مدفوعات العملات المشفّرة ميزة اختيارية وليست جوهر عملك.
الخطوة 1: تثبيت Cloudflare Tunnel
- أنشئ حساباً على cloudflare.com وأضف نطاقك.
- على الخادم المنزلي لديك، ثبّت Cloudflare Tunnel باستخدام مستودع الحزم الرسمي لـ Cloudflare:
Code-highlight
sudo mkdir -p --mode=0755 /usr/share/keyrings
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main" | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt update
sudo apt install cloudflared
إذا فشل apt install cloudflared، فثبّت .deb المطابق بدلًا من ذلك:
Code-highlight
# Raspberry Pi / ARM64
curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64.deb
sudo dpkg -i cloudflared.deb
Code-highlight
# x86_64
curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb
- صادِق مع Cloudflare:
cloudflared tunnel login
سيفتح هذا الأمر نافذة متصفح. سجّل الدخول واسمح بالوصول إلى نطاقك.
وسيُنشئ Cloudflare تلقائياً ملف credentials يحتوي على رمز مميز على خادمك.
- أنشئ نفقاً جديداً (يمكنك تسميته
btcpay أو أي اسم آخر):
cloudflared tunnel create btcpay
سيؤدي ذلك إلى إنشاء ملف btcpay.json يحتوي على معرّف النفق وبيانات الاعتماد - وستحتاج إليه في الخطوة التالية.
الخطوة 2: إنشاء ملف إعداد النفق
أنشئ دليل الإعداد (إذا لم يكن موجوداً) وافتح ملف الإعداد:
Code-highlight
sudo mkdir -p /etc/cloudflared
sudo nano /etc/cloudflared/config.yml
الصق الإعداد التالي:
Code-highlight
tunnel: btcpay # اسم النفق الخاص بك
credentials-file: /root/.cloudflared/btcpay.json
ingress:
- hostname: btcpay.example.com # نطاقك
service: http://127.0.0.1:80
- service: http_status:404
الشرح:
tunnel - اسم النفق الذي أنشأته سابقاًcredentials-file - مسار ملف الرمز المميز الذي تم إنشاؤه أثناء cloudflared tunnel loginhostname - نطاقك المسجّل لدى Cloudflare (مثل btcpay.example.com)service - العنوان المحلي لـ BTCPay Server لديك (عادةً http://127.0.0.1:80 من أجل Nginx)
سيقوم Cloudflare بتمرير الحركة بأمان إلى خادمك المحلي، من دون كشف عنوان IP المنزلي الخاص بك.
الخطوة 3: إضافة سجل DNS لنفقك
بعد إنشاء النفق، سيقوم Cloudflare عادةً بإضافة سجل DNS من نوع CNAME تلقائياً لنطاقك. وينبغي أن يبدو كالتالي:
btcpay.example.com -> <UUID>.cfargotunnel.com
إذا لم يظهر تلقائياً، فأضفه يدوياً:
- اذهب إلى لوحة تحكم Cloudflare
- انتقل إلى قسم DNS
- أضف سجل CNAME جديداً:
يضمن هذا السجل أن جميع الطلبات المرسلة إلى btcpay.example.com يتم توجيهها عبر Cloudflare Tunnel، مما يخفي عنوان IP الحقيقي الخاص بك عن العامة.
الخطوة 4: تفعيل النفق عند بدء تشغيل النظام
لجعل النفق يعمل تلقائياً عند الإقلاع، ثبّته كخدمة نظام:
sudo cloudflared service install
ثم فعّل الخدمة وابدأ تشغيلها:
Code-highlight
sudo systemctl enable cloudflared
sudo systemctl start cloudflared
تحقق من الحالة:
sudo systemctl status cloudflared
يجب أن ترى رسالة مثل Active: active (running) مع تأكيد أن btcpay.example.com متصل.
من الآن فصاعداً، سيبدأ النفق تلقائياً عند كل إعادة تشغيل، وسيكون BTCPay Server الخاص بك متاحاً للعامة - من دون إعادة توجيه المنافذ ومن دون كشف عنوان IP الحقيقي الخاص بك.
الخطوة 5: إنهاء إعداد BTCPay Server
إذا كنت على وشك تثبيت BTCPay Server لأول مرة، فعيّن نطاقك قبل تشغيل سكربت الإعداد:
export BTCPAY_HOST="btcpay.example.com"
وهذا يضمن استخدام النطاق الصحيح عند إنشاء إعدادات Nginx وشهادات SSL.
إذا كان BTCPay Server مثبتاً بالفعل وكنت تضيف النفق فقط:
Code-highlight
cd ~/BTCPayServer/btcpayserver-docker
. ./btcpay-setup.sh -i
سيعيد الإعداد إنشاء التهيئات وتطبيق النطاق الجديد.
ويفترض الآن أن تتمكن من الوصول إلى خادمك على:
https://btcpay.example.com
سواء كنت تستخدم lightwalletd عامة أو عقدتك الكاملة الخاصة، فهذا لا يؤثر على النفق.
كل ما يهم هو أن BTCPay Server يستمع محلياً على 127.0.0.1:80.
إعداد إضافة Zcash في واجهة الويب الخاصة بـ BTCPay Server
مهم للإعدادات متعددة المتاجر:
محفظة Zcash التي يتم إعدادها هنا عالمية على مستوى المثيل. ستستخدمها جميع المتاجر ما لم تشغّل مثيلات BTCPay منفصلة.
بعد نشر مثيل BTCPay Server الخاص بك بنجاح، ستحتاج إلى تنفيذ بعض الإعدادات الأساسية عبر واجهة الإدارة على الويب.
توفر الوثائق الرسمية تعليمات كاملة باللغة الإنجليزية - وهنا سنستعرض الخطوات الأساسية ونركّز تحديداً على إعداد إضافة Zcash.
الخطوة 1: تسجيل الدخول إلى واجهة الويب
قم بزيارة مثيلك على:
[https://btcpay.example.com](https://btcpay.example.com)
- أدخل اسم المستخدم الإداري وكلمة المرور.
- إذا كانت هذه أول مرة تسجّل فيها الدخول، فسيُطلب منك إنشاء حساب.
- سيُمنح أول حساب تقوم بتسجيله صلاحيات المسؤول تلقائياً.
الخطوة 2: تثبيت إضافة Zcash
- من القائمة الرئيسية، انتقل إلى:
Plugins -> Browse Plugins
- اعثر على إضافة Zcash (ZEC). استخدم شريط البحث إذا لزم الأمر.
- انقر على Install وقم بالتأكيد.
كرّر هذه العملية لأي عملات بديلة أخرى قمت بتفعيلها أثناء إعداد الخادم.
بعد التثبيت، انقر على Restart Server لإعادة تحميل الواجهة مع الإضافات النشطة.
الخطوة 3: ربط محفظتك عبر مفتاح العرض
بعد تثبيت الإضافة، سيظهر قسم Zcash جديد في قائمة الإعدادات.
- انتقل إلى:
Zcash -> Settings
- الصق Unified Full Viewing Key (UFVK) الخاص بك - سيقوم BTCPay باشتقاق Unified Address لكل فاتورة واكتشاف المدفوعات المحمية الواردة.
ملاحظة: مفاتيح العرض القديمة الخاصة بـ Sapling مدعومة، ولكن لاستخدام Orchard/Unified Addresses يجب عليك تقديم UFVK.
تنسيق مثال:
uview184syv9wftwngkay8d...
- أدخل قيمة في حقل ارتفاع الكتلة
- الإعداد لأول مرة باستخدام محفظة جديدة (عبارة استرداد جديدة): أدخل ارتفاع كتلة Zcash الحالي (يمكنك التحقق منه على 3xpl.com/zcash) - فهذا يسرّع الفحص الأولي.
- الانتقال على الخادم نفسه من إعداد قديم يعتمد على Sapling فقط إلى Unified Addresses / Orchard: اترك هذا الحقل فارغاً.
- نقل متجرك إلى خادم جديد باستخدام المحفظة/UFVK نفسها: يمكنك اختيارياً إدخال ارتفاع الولادة - وهو ارتفاع تقريبي لأول طلب مدفوع في متجرك (طابق تاريخ الطلب على 3xpl لتضييق نطاق الفحص). وإذا لم تكن متأكداً، فاتركه فارغاً.
لا تدعم جميع المحافظ بعد تصدير Unified Full Viewing Key (UFVK).
الخيارات الموصى بها:
– Zkool
– Zingo! Wallet (إصدار الحاسوب)
في كلا التطبيقين، ابحث عن تصدير UFVK في قسم النسخ الاحتياطي/التصدير.
تدعم هذه المفاتيح التدوير التلقائي للعناوين، ما يعني:
- يحصل كل عميل على عنوان دفع فريد
- ترى رصيداً موحداً واحداً
يمكنك العثور على قائمة توافق أوسع على ZecHub -> Wallets.
بمجرد تعبئة جميع الحقول، انقر على Save.
اختبر تدفق الدفع بـ ZEC
تهانينا - لقد أصبحت محفظة Zcash الخاصة بك متصلة الآن بـ BTCPay Server.
لنقم بإجراء اختبار:
- انتقل إلى:
Invoices -> Create New
- أنشئ فاتورة اختبارية بمبلغ صغير من ZEC.
- أرسل الأموال من محفظة مختلفة (وليست المحفظة المتصلة بـ BTCPay).
- بمجرد اكتشاف المعاملة، ستعرض صفحة الفاتورة احتفالاً بصرياً.
- تأكد من أن حالة الفاتورة تتغير إلى Paid.
إذا كان كل شيء يعمل - فأنت جاهز لدمج مدفوعات ZEC في موقعك الإلكتروني باستخدام API أو إضافات CMS.
دمج BTCPay Server مع موقعك الإلكتروني
بمجرد توصيل محفظة Zcash الخاصة بك بـ BTCPay Server، يمكنك دمج نظام الدفع في موقعك الإلكتروني.
توجد عدة طرق للقيام بذلك - من الوصول المباشر عبر API إلى الإضافات الجاهزة للاستخدام لمنصات CMS الشهيرة.
خيارات التكامل
-
التكامل عبر API
مثالي للمواقع أو الأنظمة المبنية خصيصاً من دون CMS.
يمنحك تحكماً كاملاً في إنشاء الفواتير وتتبع المدفوعات والإشعارات - وكل ذلك داخل واجهتك ومنطقك الخاصين.
ويتطلب معرفة برمجية أساسية، لذا من الأفضل أن يتولى هذه المهمة مطوّرك.
-
إضافات CMS
متوفرة لمنصات مثل WooCommerce وPrestaShop وغيرها.
تتيح لك هذه الإضافات قبول المدفوعات خلال دقائق قليلة فقط - من دون حاجة إلى البرمجة.
-
زر دفع أو Iframe
أبسط طريقة.
مثالية لصفحات الهبوط، والمواقع الشخصية، أو أي موقع تريد فقط تضمين رابط تبرع أو أداة دفع فيه.
التكامل عبر API
إذا كنت تستخدم منصة مخصصة (أو لا تستخدم CMS إطلاقاً)، فإن API هو الخيار الأفضل.
فهو يمنحك مرونة كاملة: يمكنك إنشاء الفواتير، وتتبع حالتها، وتلقي الإشعارات، والتحكم الكامل في تجربة المستخدم.
ملاحظة: حتى بعض إضافات CMS تستخدم API في الخلفية، لذا فإن إنشاء مفتاح API يكون غالباً الخطوة الأولى المطلوبة، بغض النظر عن طريقة التكامل التي تختارها.
الخطوة التالية: أنشئ مفتاح API لمتجرك وابدأ باستخدام Greenfield API لبناء التكامل الخاص بك.
إنشاء مفتاح API
لدمج BTCPay Server مع موقعك الإلكتروني أو تطبيقك، ستحتاج إلى إنشاء مفتاح API.
-
سجّل الدخول إلى BTCPay Server وافتح قائمة المستخدم (الزاوية العلوية اليمنى)
-
انتقل إلى API Keys
-
انقر على Create a new API key
-
أدخل اسماً لمفتاحك
-
في قسم Permissions، فعّل:
Can create invoiceCan view invoice- (اختياري)
Can modify store settings - فقط إذا كنت بحاجة إلى إدارة على مستوى المتجر
-
انقر على Generate. سيظهر مفتاح API الشخصي الخاص بك - انسخه واحفظه بأمان.
يمنح هذا المفتاح إمكانية الوصول إلى فواتير متجرك.
لا تشاركه علناً ولا تكشفه في الشيفرة التي تعمل على جهة العميل.
مثال: إنشاء فاتورة عبر API
نقطة النهاية:
Code-highlight
POST /api/v1/stores/{storeId}/invoices
Authorization: token {apiKey}
Content-Type: application/json
جسم الطلب:
Code-highlight
{
"amount": 5,
"currency": "ZEC",
"checkout": {
"speedPolicy": "HighSpeed",
"paymentMethods": ["Zcash"]
}
}
الاستجابة:
ستتلقى كائن JSON يحتوي على:
invoiceId- رابط دفع يمكنك تضمينه في موقعك الإلكتروني أو إرساله إلى العميل
راجع الوثائق الكاملة:
Greenfield API – إنشاء فاتورة
إعداد Webhook (اختياري)
لتلقي إشعارات فورية عند تغيّر حالات الفواتير (مثلاً عند استلام دفعة):
- انتقل إلى إعدادات متجرك -> Webhooks
- أضف عنوان URL لنقطة النهاية الخلفية الخاصة بك التي ستتعامل مع طلبات
POST الواردة من BTCPay Server
- سيقوم BTCPay تلقائياً بإرسال إشعارات عندما يتم دفع فاتورة أو تنتهي صلاحيتها
تم شرح حمولات Webhook ومنطق إعادة المحاولة في وثائق webhook الرسمية.
تتوفر أمثلة تكاملات بلغات برمجة مختلفة في وثائق BTCPay ومستودعات GitHub الخاصة به.
التكامل مع أنظمة CMS
يدعم BTCPay Server إضافات لأنظمة إدارة المحتوى (CMS) الشائعة.
وأكثر التكاملات نضجاً واستخداماً على نطاق واسع هو مع WordPress + WooCommerce، مما يجعل قبول مدفوعات ZEC سهلاً من دون كتابة شيفرة.
WooCommerce (WordPress)
يدعم BTCPay Server رسمياً إضافة لـ WooCommerce.
خطوات التكامل:
- ثبّت إضافة BTCPay for WooCommerce من دليل إضافات WordPress أو من GitHub.
- في لوحة إدارة WordPress، انتقل إلى:
WooCommerce -> Settings -> Payments
- اعثر على BTCPay في القائمة وانقر على Set up
- أدخل رابط BTCPay Server الخاص بك واتبع تعليمات التفويض
(يُوصى بإنشاء مفتاح API تلقائياً)
- فعّل وسيلة الدفع واحفظ إعداداتك
تتوفر تعليمات مفصلة، ودروس فيديو، وأدلة استكشاف الأخطاء وإصلاحها في وثائق الإضافة.
ستجد أيضاً خيارات أخرى للتكامل مع CMS في هذا القسم نفسه من وثائق BTCPay.
زر دفع أو Iframe (من دون CMS أو API)
إذا كنت لا تستخدم CMS ولا ترغب في العمل مع APIs، فإن أسهل طريقة لقبول مدفوعات ZEC هي تضمين رابط دفع أو أداة مباشرة في موقعك الإلكتروني.
هذه الطريقة مثالية لـ:
- صفحات الهبوط
- مواقع المعارض الشخصية
- المدونات أو الصفحات الثابتة
- المشاريع التي لا تحتوي على خادم خلفي
الخيار 1: زر دفع (رابط)
- في BTCPay Server، أنشئ فاتورة يدوياً في قسم Invoices
- انسخ رابط الدفع، مثلاً:
[https://btcpay.example.com/i/abc123](https://btcpay.example.com/i/abc123)
- أضف الرابط إلى HTML الخاص بك:
Code-highlight
<a href="https://btcpay.example.com/i/abc123" target="_blank">
Pay with ZEC
</a>
الخيار 2: فاتورة مضمّنة (Iframe)
لعرض الفاتورة مباشرة على موقعك، استخدم iframe:
<iframe src="https://btcpay.example.com/i/abc123" width="600" height="350" frameborder="0"></iframe>
يمكنك تنسيق الزر أو حاوية iframe بما يتناسب مع تصميم موقعك - يتيح BTCPay Server مرونة كبيرة في تخصيص مظهر صفحة الفاتورة.
الخلاصة
كان هذا الدليل طويلاً - لكنه لا يغطي سوى الجوانب الأساسية لدمج مدفوعات Zcash مع BTCPay Server.
توفّر واجهة BTCPay Server وظائف أكثر بكثير مما عرضناه هنا. ولحسن الحظ، تتوفر الواجهة بعدة لغات (من بينها الروسية)، مما يجعل من السهل الاستكشاف والتجربة بشكل أوسع.
BTCPay أداة مرنة للغاية. يمكنك:
- استضافة عدة متاجر مستقلة على مثيل واحد
- تعريف أدوار وصلاحيات مخصصة لأعضاء الفريق - من عرض الطلبات فقط إلى صلاحيات الإدارة الكاملة
- استخدام نطاقاتك وعلامتك التجارية الخاصة
- إعداد webhooks، ومحافظ احتياطية، وحتى الوصول عبر Tor
- تهيئة إعدادات متقدمة مثل قواعد الضرائب، وأكواد الخصم، وتخصيص صفحة الدفع، وقيود وسائل الدفع، وغير ذلك
تم بناء BTCPay كبديل مفتوح المصدر لمزودي الدفع المركزيين. وإذا كنت تبحث عن قبول مدفوعات ZEC خاصة من دون وسطاء، فهذه المنصة تستحق اهتمامك بالتأكيد.
نتمنى لك التوفيق في استكشاف منظومة BTCPay وجعل مدفوعاتك ملكاً لك حقاً.
الموارد
