لماذا تقدّم خرائطك بنفسك بدل استئجار البلاطات
صفحة اتصال بخريطة، أو محدّد مواقع المتاجر، أو خريطة توصيل: تكاد كل مواقع العملاء تحمل واحدة. والتصرف المعتاد هو دمج واجهة خرائط تجارية بمفتاح. تظهر مع الوقت مشكلتان. الأولى الفاتورة: فهي تتبع عدد مرات تحميل الخريطة، أي حركة زوار الموقع التي لا تتحكم بها الوكالة. والثانية المفتاح: فهو موضوع في شيفرة الصفحة ويقرؤه أي زائر. وتقييده بالنطاقات المسموح بها يحدّ من إساءة الاستخدام ولا يلغيها، لأن الترويسة التي تحدد الموقع المصدر يمكن تزويرها من سكربت بسيط. الحل أن تتوقف عن الاعتماد على مفتاح: تستضيف البلاطات بنفسك، في ملف واحد، على الخادم الذي يستضيف الموقع أصلًا.
ما الذي يغيّره ملف PMTiles
- أرشيف واحد — تتسع كل البلاطات المتجهة لمنطقة ما في ملف واحد، من دون مجلد يضم ملايين الصور الصغيرة لمزامنتها.
- لا خادم خرائط — يقرأ المتصفح الملف عبر طلبات HTTP Range، أي على أجزاء من البايتات. يكفي خادم ويب عادي.
- لا مفتاح في الصفحة — لا سرّ يُسرق ولا حصة تُستنفد: الخريطة مورد ثابت من نطاقك أنت.
- فاتورة لا تتبع الزيارات — تصبح التكلفة هي تكلفة VPS وعرض النطاق الترددي، وهما بندان تعرفهما.
- ملف لكل منطقة، مشترك بين العملاء — يمكن لاستخراج إقليمي واحد أن يخدم كل مواقع عملائك الواقعة في تلك المنطقة.
- نمط حرّ — MapLibre GL JS مفتوح المصدر، وتُضبط الألوان والتسميات والطبقات من جهة العميل.
كم يزن فعليًا: الكوكب، المنطقة، الأقمار الصناعية
الاعتراض المعتاد كلمة واحدة: الحجم. تبلغ الخريطة الأساسية الكاملة للكوكب نحو 120 جيجابايت بحسب توثيق Protomaps، وكانت النسخة التي استعلمنا عنها تعلن نحو 140 جيجابايت. هذا ليس ما يوضع على موقع عميل، ولا حاجة إليه. تقتطع أداة pmtiles extract منطقة من الأرشيف البعيد من دون تنزيله كاملًا. على إطار نحو 22 كم في 17 كم حول باريس، وبكل مستويات التكبير، يزن الملف الناتج 49 ميغابايت، واستغرق الاستخراج نحو خمس عشرة ثانية. كل مستوى تكبير إضافي يضاعف الحجم تقريبًا: والخيار --maxzoom هو الرافعة إن كانت خريطة متجر لا تحتاج أقصى تفصيل.
وهناك حدّ يجب قوله بصراحة. هذا الملف خريطة أساسية متجهة: يرسم الخريطة ولا يحوّل العناوين إلى إحداثيات ولا يحسب المسارات. أما صور الأقمار الصناعية عالية الدقة فتبقى باهظة التخزين وتخرج عن نطاق هذا الدليل.
الاختيار بين واجهة بمفتاح وOpenFreeMap وPMTiles على VPS
مرّر الجدول أفقيًا
| المعيار | واجهة تجارية بمفتاح | OpenFreeMap (نسخة عامة) | PMTiles على VPS الخاص بك |
|---|---|---|---|
| التكلفة | بحسب الاستخدام، وتتبع مرات تحميل الخريطة | بلا رسوم ولا مفتاح؛ يغطي المشروع تكاليفه بالتبرعات | تكلفة VPS وعرض النطاق الترددي |
| مفتاح في الصفحة | نعم، يقرؤه أي زائر | لا مفتاح ولا حساب | لا مفتاح |
| الاعتماد | مزوّد وشروطه | خدمة عامة يديرها مشروع خارجي | خادمك وقواعدك |
| الإعداد | مفتاح وبضعة أسطر | عنوان نمط واحد | استخراج وكتلة nginx وصفحة |
| صور الأقمار الصناعية | بحسب المزوّد | لا: خريطة أساسية متجهة من OpenStreetMap | لا: تخزين ثقيل جدًا على عاتقك |
| اخترها عندما | تحتاج صورًا أو تحويل عناوين أو مسارات | نموذج أولي أو موقع قليل الأهمية بلا بنية تحتية تديرها | محفظة مواقع عملاء تريد التحكم في فاتورتها وتوفرها |
المتطلبات الواجب توفيرها قبل البدء
VPS بقرص مقاس على حجم أرشيفاتك، مع هامش لاستبدال ملف دون انقطاع: احسب ضعف أكبر أرشيف. nginx محدّث، أو Caddy إن فضّلت أن يتولى HTTPS وحده؛ والمقارنة في مقال Caddy أم Nginx على VPS. نطاق فرعي مخصص للبلاطات بشهادة TLS: فصفحة HTTPS تحمّل بلاطات عبر HTTP تُحظر بوصفها محتوى مختلطًا. وأخيرًا جهاز بوصول SSH لتشغيل سطر الأوامر pmtiles. تقديم ملف ثابت بنطاقات البايتات خفيف على المعالج: القرص وعرض النطاق هما ما يحدد حجم الجهاز.
الإعداد في سبع خطوات
تثبيت سطر الأوامر pmtiles
هو ملف تنفيذي واحد بلا تبعيات، منشور في صفحة الإصدارات لمستودع
protomaps/go-pmtilesعلى GitHub. على لينكس:tar -xzf go-pmtiles_*_Linux_x86_64.tar.gzsudo mv pmtiles /usr/local/bin/استخراج منطقتك
اختر نسخة مدرجة في
maps.protomaps.com/buildsوحدّد الإطار بالصيغةMIN_LON,MIN_LAT,MAX_LON,MAX_LAT، خط الطول قبل خط العرض:pmtiles extract https://build.protomaps.com/YYYYMMDD.pmtiles paris.pmtiles --bbox=2.2,48.8,2.5,48.95تنصح Protomaps بعدم توجيه موقعك مباشرة إلى تنزيلاتها: أما المقتطع فهو ملكك. ويجب أن يكون الأرشيف المصدر «clustered»، وهو حال النسخ الرسمية.
فحص الأرشيف الناتج
يعرض
pmtiles show paris.pmtilesالحدود ومستويات التكبير والضغط الداخلي؛ ويتحققpmtiles verify paris.pmtilesمن الترتيب والترويسة. لاحظ الضغط الداخلي gzip: فهو سببgzip offأدناه.نسخ الملف إلى VPS
rsync -avP paris.pmtiles deploy@your-vps:/var/www/tuiles/ولتحديث لاحق، أرسل الملف الجديد باسم آخر إلى المجلد نفسه، ثم أعد تسميته بالأمر
mv.تعريف خادم nginx
أضف هذه الكتلة للنطاق الفرعي، مع أسطر
ssl_certificateالمعتادة لديك:server {listen 443 ssl;server_name tiles.your-domain.com;root /var/www/tuiles;default_type application/octet-stream;location / {gzip off;add_header Access-Control-Allow-Origin "https://your-domain.com" always;add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always;add_header Access-Control-Allow-Headers "Range, If-Match" always;add_header Access-Control-Expose-Headers "ETag" always;add_header Cache-Control "public, max-age=86400" always;if ($request_method = OPTIONS) {add_header Access-Control-Allow-Origin "https://your-domain.com" always;add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always;add_header Access-Control-Allow-Headers "Range, If-Match" always;add_header Access-Control-Max-Age 3600 always;return 204;}}}إعادة تحميل nginx والتحقق من الرمز 206
sudo nginx -t && sudo systemctl reload nginxثم اطلب أول 16384 بايتًا، وهي التي يقرؤها العميل قبل أي بلاطة:
curl -s -o /dev/null -D - -H "Origin: https://your-domain.com" -r 0-16383 https://tiles.your-domain.com/paris.pmtilesالمتوقع
HTTP/2 206وcontent-range: bytes 0-16383/متبوعًا بالحجم الكلي للملف وcontent-length: 16384وaccept-ranges: bytesوالترويسةaccess-control-allow-origin. الرمز200يعني أن النطاق أُهمل: انتقل إلى قائمة حل الأخطاء أدناه.عرض الخريطة باستخدام MapLibre GL JS
npm install maplibre-gl pmtiles @protomaps/basemapsثم في سكربت الصفحة، مع عنصر
<div id="map">:import maplibregl from 'maplibre-gl';import 'maplibre-gl/dist/maplibre-gl.css';import { Protocol } from 'pmtiles';import { layers, namedFlavor } from '@protomaps/basemaps';const protocol = new Protocol();maplibregl.addProtocol('pmtiles', protocol.tile);const map = new maplibregl.Map({container: 'map',center: [2.35, 48.86],zoom: 11,style: {version: 8,glyphs: 'https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf',sprite: 'https://protomaps.github.io/basemaps-assets/sprites/v4/light',sources: {protomaps: {type: 'vector',url: 'pmtiles://https://tiles.your-domain.com/paris.pmtiles',attribution: '<a href="https://protomaps.com">Protomaps</a> © <a href="https://openstreetmap.org">OpenStreetMap</a>'}},layers: layers('protomaps', namedFlavor('light'), { lang: 'en' })}});توضع البادئة
pmtiles://أمام عنوان HTTPS الكامل للملف. تشير الخطوط والأيقونات هنا إلى الموارد التي تنشرها Protomaps؛ وللاستغناء عن أي طرف، انسخ مستودعprotomaps/basemaps-assetsإلى خادمك وغيّر العنوانين.
قراءة كتلة nginx سطرًا سطرًا
لا توجد توجيهة لتفعيل نطاقات البايتات: يتولاها nginx بنفسه على ملف ثابت، ولا يذكر التوثيق سوى max_ranges التي تعطّلها القيمة 0. ويحمي gzip off هذه النطاقات: فالبايتات المطلوبة هي بايتات الملف كما هو مخزّن، وإعادة ضغط الاستجابة في الطريق تفسدها؛ والضغط موجود أصلًا داخل الأرشيف. وتتضمن الترويسة Access-Control-Allow-Headers القيمة Range لأن المتصفح يرسل أولًا طلب preflight من نوع OPTIONS قبل قراءة جزئية، ومن هنا كتلة if التي تجيب 204. وتتيح Access-Control-Expose-Headers: ETag للمكتبة اكتشاف أن ملفًا قد استُبدل. وأخيرًا لا يرث nginx أسطر add_header من مستوى أعلى إلا إذا لم يعرّف المستوى الحالي أيًّا منها: لذلك تكرر كتلة if أسطرها، ويرسلها always مع استجابات الأخطاء أيضًا.
خلف Cloudflare: ما يتيح التوثيق قوله
يسيء ملف الخرائط التصرف خلف وكيل إن أُهملت ثلاث قواعد، كلها من توثيق Cloudflare. الامتداد .pmtiles ليس في قائمة الامتدادات المخزّنة مؤقتًا افتراضيًا: وبلا قاعدة تخزين مؤقت يُقرأ الملف من خادم المصدر في كل مرة. والحجم الأقصى لملف مخزّن مؤقتًا هو 512 ميغابايت في خطط Free وPro وBusiness: يتسع مقتطع إقليمي ولا يتسع أرشيف الكوكب. ولا تُخزَّن استجابة 206 مؤقتًا إلا إن كانت غير مرمّزة، مع Content-Range متسق. تحقق من النتيجة بالترويسة cf-cache-status. وإعدادات المنطقة من هذا النوع مفصّلة في Cloudflare لموقع عميل. أما نطاق فرعي بـ DNS فقط فيتجنب المسألة، بثمن كشف عنوان IP للمصدر: قرّره مع بقية محفظتك.
حل الأخطاء: ما ستصادفه فعلًا
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource— الترويسة مفقودة أو المصدر لا يطابق تمامًا:httpبدلhttps، أوwwwزائدة. صحّح قيمةAccess-Control-Allow-Originولا تنسَalways.Request header field range is not allowed by Access-Control-Allow-Headers in preflight response— لا يذكر الـ preflight القيمةRange. أضفها إلىAccess-Control-Allow-Headersوأجب204على طلباتOPTIONS.Server returned no content-length header or content-length exceeding request. Check that your storage backend supports HTTP Byte Serving.— أعاد الخادم الملف كاملًا بالرمز200بدل206. أعد تشغيلcurl: السبب وكيل أوmax_ranges 0أو ضغط في الطريق.Wrong magic number for PMTiles archive— ما يتلقاه العميل ليس أرشيف PMTiles: صفحة خطأ HTML أو مسار خاطئ أو ملف مبتور بسبب رفع منقطع. قارن الحجم على الخادم وعلى جهازك.Server returned non-matching ETag … after one retry— تغيّر الملف أثناء القراءة، أو اختلطت نسختان في ذاكرة تخزين مؤقت. استبدل الملف بالأمرmv، لا بنسخ فوق الملف نفسه.- خريطة بيضاء، وخلفية بلا تسميات ولا طرق — لا تُحمَّل الخطوط أو الأيقونات: افتح تبويب الشبكة وابحث عن استجابات
404علىglyphsوsprite. - لا إشارة إلى OpenStreetMap على الشاشة — تظهر الخريطة لكن الترخيص غير محترم. انظر القسم التالي.
نسب OpenStreetMap: التزام الترخيص
تأتي البيانات من OpenStreetMap وهي منشورة بترخيص ODbL. وتُوزَّع الخريطة الأساسية من Protomaps بوصفها عملًا منتجًا بموجب هذا الترخيص، مع اشتراط نسبتها إلى OpenStreetMap. تطلب OpenStreetMap ذكر المشروع وبيان أن البيانات مرخّصة بـ ODbL، مثلًا برابط إلى openstreetmap.org/copyright. وفي MapLibre يظهر الحقل attribution للمصدر في زاوية الخريطة: أبقه ظاهرًا ولا تخفِ هذا العنصر في ورقة أنماط عميل. لا يبلغ أي خطأ عن هذا السهو، ولذلك يسهل تسليمه دون أن تنتبه.
تأمين خادم البلاطات وصيانته
اسمح بمصدر واحد مطابق تمامًا، وليس * أبدًا: تنصح Protomaps بذكر نطاقك أنت. ولعدة مواقع عملاء، استبدل القيمة الثابتة بـ map $http_origin لا يعيد إلا نطاقات قائمة. راقب عرض النطاق الترددي للنطاق الفرعي في سجلات nginx: فقد صار بند تكلفتك. وجدوِل الاستخراج على فترات منتظمة، نحو ملف مؤقت، ثم mv.
ربط خادم الخرائط هذا بمحفظة مواقعك
بما أن الأرشيف ملف ثابت، يمكن لنطاق فرعي واحد للبلاطات أن يخدم خرائط كل مواقع العملاء في المنطقة نفسها: ملف واحد وشهادة واحدة ونسخة احتياطية واحدة. وهو يقيم بطبيعته على VPS الذي يستضيف مواقعك أصلًا، فتتجنب مزوّدًا آخر لمتابعته؛ والمفاضلة بين VPS والاستضافة المشتركة معالجة في استضافة مشتركة أم VPS لموقع عميل الوكالة. وإذا طلب عميل صور أقمار صناعية أو مسارات فأبقِ واجهة تجارية لذلك الموقع وحده، واترك البقية على أرشيفك.
servorbit.com/ma-ar/المدونة/استضافة-خرائط-pmtiles-على-vps
