إن كنت تستضيف خريطتك بنفسك، فستجد نفسك يومًا أمام أرشيف بلاطات (tile archive): ملف واحد .pmtiles أو .mbtiles يحتوي كل بلاطات منطقة ما. قد يأتي من مولّد vector tiles، أو من تصدير طبقة raster، أو من عمل شخص آخر. الملف مريح في النسخ والنقل. لكن مكتبة الخرائط في المتصفح لا تقرأ الأرشيفات من قرصك. هي تطلب عناوين من الشكل /{z}/{x}/{y} وتنتظر الجواب الصحيح لكل واحد.
إذن لا بد من شيء يقف بين الملف والخريطة، وعليه أن يضبط قائمة من التفاصيل الصغيرة. بلاطات الـ vector تُخزَّن عادةً مضغوطة بـ gzip، والمتصفح يحتاج الترويسة Content-Encoding: gzip ليفكّها. وصيغة MBTiles ترقّم الصفوف من الأسفل، بينما عناوين XYZ تعدّ من الأعلى. والبلاطة الغائبة في وسط البحر ليست خطأ. والبلاطات يجب أن تُحفظ في الـ cache، وإلا فكل تحريك للخريطة يطرق خادمك من جديد.
tileserver خادم بلاطات صغير مكتوب بـ Rust مع axum، يعالج هذه التفاصيل لأرشيفات PMTiles و MBTiles. تضع الملفات في مجلد، فيقدّم الخادم كل ملف كبلاطات XYZ مع TileJSON، بترويسات محتوى صحيحة، و ETag، وصفحة معاينة بـ MapLibre.
ماذا يقدّم
مجلد واحد، ومصدر لكل ملف. كل ملف *.pmtiles أو *.mbtiles موجود مباشرة داخل --dir يصير مصدرًا (source) باسم الملف: roads.pmtiles يصير roads. الملفات غير المقروءة والمعرّفات المكررة تُسجَّل في الـ log وتُتجاوز، ولا توقف الخادم.
قائمة قصيرة من نقاط الوصول.
-
GET /صفحة المعاينة: قائمة المصادر، وطبقات vector بتنسيق تلقائي أو raster، والنقر يعرض خصائص المعلم. وإضافة?debugتُظهر حدود البلاطات. -
GET /sourcesقائمة JSON بالمصادر مع النوع والصيغة ومستويات التكبير والحدود وعنوان TileJSON. -
GET /{id}.jsonملف TileJSON 3.0.0، معvector_layersلمصادر الـ vector. -
GET /{id}/{z}/{x}/{y}[.ext]البلاطة نفسها. الامتداد اختياري، لكن إن وُجد فيجب أن يطابق (pbf/mvt،png،jpg،webp،avif). -
GET /healthيجيب بـok.
ترويسات مضبوطة. هذه هي التفاصيل التي تحدد هل تظهر الخريطة أم لا:
-
Content-Typeيؤخذ من نوع البلاطات في الأرشيف:application/vnd.mapbox-vector-tile، أوimage/png، وهكذا. -
Content-Encoding: gzip(أوbr/zstd) تُضاف حين يخزّن الأرشيف بلاطات مضغوطة. البلاطات تُقدَّم كما هي مخزّنة، دون إعادة ضغط. وإن كان العميل لا يقبل gzip، تُفكّ البلاطة في لحظتها. والترويسةVary: Accept-Encodingموجودة دائمًا. -
ETagمدقّق قوي (strong validator)، وهو hash من نوع FNV-1a للبايتات المخزّنة. والطلب الذي يحملIf-None-Matchمطابقًا يأخذ304 Not Modified. -
Cache-Control: public, max-age=Nبقيمة افتراضية 3600، وAccess-Control-Allow-Origin: *.
رموز حالة كما تنتظرها مكتبات الخرائط. 204 No Content لبلاطة داخل مجال التكبير لكن الأرشيف لا يحتويها، و MapLibre يعتبرها فارغة. و404 للمصادر المجهولة أو التكبير خارج المجال. و400 للإحداثيات غير الصالحة أو الامتداد الخاطئ.
عناوين TileJSON تعمل خلف proxy. تستعمل --base-url إن حددته، وإلا فالترويسة Host مع X-Forwarded-Proto.
طريقة الاستعمال
ثبّته من GitHub بواسطة Cargo، ثم ولّد الأرشيفات التجريبية وقدّمها:
cargo install --git https://github.com/AbdeldjalilChougui/tileserver --locked
tileserver fixtures tiles && tileserver serve --dir tiles
أو من نسخة محلية للمستودع:
cargo run --release -- fixtures tiles # generate 4 small demo archives
cargo run --release -- serve --dir tiles # http://127.0.0.1:3000/
cargo test
وسطر الأوامر كله في سطرين:
tileserver serve [--dir DIR] [--addr 127.0.0.1:3000] [--base-url URL] [--max-age SECONDS]
tileserver fixtures DIR
الأمر fixtures مفيد في حد ذاته. لا يحتاج أي بيانات خارجية: مرمِّز PNG صغير يرسم شبكة debug لمستويات التكبير من 0 إلى 3، وفيها z/x/y لكل بلاطة على شكل أعمدة، ومرمِّز MVT مكتوب يدويًا ينتج بلاطات نقاط للمستويات من 0 إلى 6 فيها ست مدن جزائرية. وكلاهما يُكتب بصيغة PMTiles وبصيغة MBTiles. فتحصل على مصدر raster ومصدر vector بكل صيغة لتجرّب الخادم قبل أن تأتي بملفاتك.
كيف يعمل من الداخل
PMTiles v3 يقرؤه module مكتوب انطلاقًا من المواصفة (spec). يحلّل القارئ الترويسة ذات 127 بايتًا، ثم الدليل الجذر (root directory) المضغوط بـ gzip، ثم بيانات JSON الوصفية. معرّف البلاطة (tile id) هو عدد البلاطات في المستويات الأدنى زائد موضع البلاطة على منحنى Hilbert. ويبحث القارئ بحثًا ثنائيًا في الدليل عن آخر مدخل أصغر من المعرّف أو يساويه. المداخل التي فيها run_length > 0 تشير إلى بيانات البلاطات، وrun_length == 0 يشير إلى دليل فرعي (leaf directory). والأدلة الفرعية تُحفظ في cache. وقراءة الملف تتم بـ pread، فيخدم ملف واحد مفتوح طلبات متزامنة دون قفل.
وفي الـ module نفسه كاتب (writer). يزيل تكرار البلاطات المتطابقة، ويرمّز التكرارات المتتالية بطريقة run-length، ويقسّم إلى أدلة فرعية حين يكبر الجذر. تستعمله الاختبارات والأمر fixtures.
ملفات MBTiles قواعد بيانات SQLite، تُفتح للقراءة فقط عبر rusqlite مع SQLite مضمَّنة. وتُقلب قيمة y في XYZ إلى صف TMS بالعلاقة 2^z − 1 − y. وجدول الـ metadata (format، bounds، center، minzoom/maxzoom، وjson من أجل vector_layers) يغذّي TileJSON. ويُكتشف gzip من البايتات الأولى (magic bytes) لأول بلاطة بدل افتراضه.
طبقة HTTP مبنية بـ axum 0.8. وقراءة البلاطات تجري داخل spawn_blocking، لأن كلا المصدرين يقوم بعمليات إدخال وإخراج حاجبة (blocking I/O).
ما يجب معرفته
- المصادر تُكتشف عند الإقلاع. أعد تشغيل الخادم ليأخذ الملفات الجديدة.
- ملفات محلية فقط. لا يوجد دعم لـ HTTP range ولا لـ PMTiles عن بعد.
- لا brotli ولا zstd في الضغط الداخلي (للأدلة) في PMTiles. أما ضغط البلاطات نفسها، مهما كان نوعه، فيُمرَّر كما هو.
- cache الأدلة الفرعية خريطة بسيطة محدودة الحجم، وليست LRU.
- صفحة المعاينة تستعمل موارد خارجية. تحمّل MapLibre من unpkg، وبلاطات OSM كخلفية، والخطوط (glyphs) من demotiles.maplibre.org للتسميات.
ما تم اختباره. الأمر cargo test يشغّل 13 اختبار تكامل على fixtures مولَّدة للتو في مجلد مؤقت. من جهة PMTiles: معرّفات البلاطات مقابل قيم المواصفة، والتحويل بين المعرّف و z/x/y ذهابًا وإيابًا للمستويات من 0 إلى 6 ومستويات عميقة، وترميز الأدلة وفكّها، والبحث عن المداخل داخل السلاسل والفراغات، والكتابة ثم القراءة مع بلاطات "محيط" مزالة التكرار، بدليل جذر فقط وبأدلة فرعية مفروضة. ومن جهة HTTP: ترويسات raster ومحتواها، و ETag مع 304، وتمرير gzip أو فكّه حسب Accept-Encoding، وحالات 204/404/400، و TileJSON مع X-Forwarded-Proto و--base-url، وقلب الصفوف في MBTiles مع التحقق بلاطة بلاطة مقابل صور PNG المولَّدة.
لماذا بنيته
تقديم البلاطات من أرشيف مهمة ضيقة، وتستحق أداة ضيقة: ملف تنفيذي واحد، ومجلد واحد، ولا ملف إعدادات. والصعوبة ليست في حجم الكود. الصعوبة أن كل خطأ صغير ينتج خريطة فارغة دون رسالة خطأ: ترويسة Content-Encoding ناقصة، أو صف مقلوب، أو 404 حيث كان يُنتظر 204. أردت خادمًا تُكتب فيه كل حالة من هذه ويغطيها اختبار.
وكتابة قارئ PMTiles وكاتبه انطلاقًا من المواصفة كانت السبب الآخر. فهي تجعل الصيغة ملموسة: الترويسة، والأدلة، ومعرّفات منحنى Hilbert، وحيلة run-length للبلاطات المتكررة. ووجود كاتب يعني أن الاختبارات لا تحتاج بيانات محمَّلة من الخارج.
الكود
الكود والاختبارات موجودة على GitHub: https://github.com/AbdeldjalilChougui/tileserver. الرخصة MIT. والـ fixtures المولَّدة لا تحتوي بيانات من طرف ثالث (مواقع المدن تقريبية ومكتوبة يدويًا)، وخلفية المعاينة © OpenStreetMap contributors (ODbL).
نُشر في الأصل على abdeldjalilchougui.biz.
Top comments (0)