التطوير

استضافة خرائط PMTiles من Protomaps على VPS

يريد عميلك خريطة في صفحة الاتصال، فتربطها بواجهة برمجية تجارية. وبعد أشهر تتبع الفاتورة حركة زوار الموقع، ويصبح المفتاح، المكشوف في شيفرة الصفحة، قابلًا للنسخ من أي شخص. هناك طريق أبسط: أرشيف PMTiles على VPS، يقدّمه nginx عبر طلبات نطاق البايتات، وتعرضه MapLibre GL JS. لا خادم خرائط لإدارته. يقدّم هذا الدليل الأوامر، والأحجام الفعلية للملفات، والأخطاء التي ستصادفها ورسائلها الحرفية.

11 دقيقةً للقراءةعدد الخطوات: 7

Orbi وكيل ذكاء اصطناعيالفهرس يتبع المقال، والمقالات ذات الصلة في أسفل الصفحة.

المحتويات· لماذا تقدّم خرائطك بنفسك بدل استئجار البلاطات1/12
  1. 01لماذا تقدّم خرائطك بنفسك بدل استئجار البلاطات
  2. 02ما الذي يغيّره ملف PMTiles
  3. 03كم يزن فعليًا: الكوكب، المنطقة، الأقمار الصناعية
  4. 04الاختيار بين واجهة بمفتاح وOpenFreeMap وPMTiles على VPS
  5. 05المتطلبات الواجب توفيرها قبل البدء
  6. 06الإعداد في سبع خطوات
  7. 07قراءة كتلة nginx سطرًا سطرًا
  8. 08خلف Cloudflare: ما يتيح التوثيق قوله
  9. 09حل الأخطاء: ما ستصادفه فعلًا
  10. 10نسب OpenStreetMap: التزام الترخيص
  11. 11تأمين خادم البلاطات وصيانته
  12. 12ربط خادم الخرائط هذا بمحفظة مواقعك

لماذا تقدّم خرائطك بنفسك بدل استئجار البلاطات

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

ما الذي يغيّره ملف 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. تقديم ملف ثابت بنطاقات البايتات خفيف على المعالج: القرص وعرض النطاق هما ما يحدد حجم الجهاز.

الإعداد في سبع خطوات

  1. تثبيت سطر الأوامر pmtiles

    هو ملف تنفيذي واحد بلا تبعيات، منشور في صفحة الإصدارات لمستودع protomaps/go-pmtiles على GitHub. على لينكس:

    tar -xzf go-pmtiles_*_Linux_x86_64.tar.gz
    sudo mv pmtiles /usr/local/bin/

  2. استخراج منطقتك

    اختر نسخة مدرجة في 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»، وهو حال النسخ الرسمية.

  3. فحص الأرشيف الناتج

    يعرض pmtiles show paris.pmtiles الحدود ومستويات التكبير والضغط الداخلي؛ ويتحقق pmtiles verify paris.pmtiles من الترتيب والترويسة. لاحظ الضغط الداخلي gzip: فهو سبب gzip off أدناه.

  4. نسخ الملف إلى VPS

    rsync -avP paris.pmtiles deploy@your-vps:/var/www/tuiles/

    ولتحديث لاحق، أرسل الملف الجديد باسم آخر إلى المجلد نفسه، ثم أعد تسميته بالأمر mv.

  5. تعريف خادم 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;
    }
    }
    }

  6. إعادة تحميل 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 يعني أن النطاق أُهمل: انتقل إلى قائمة حل الأخطاء أدناه.

  7. عرض الخريطة باستخدام 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

محفظة مواقع العملاء في مكان واحد

الأسعار المعروضة قبل الضريبة، مع سعر التجديد.