1. 为什么要在Django后台里塞一张离线地图做过后台管理系统的朋友大概都有过这种体验项目部署在客户的内网环境里服务器压根连不上外网但业务上又需要在地图上标注设备位置、画出配送范围、圈出服务区域。这时候你打开Django admin发现所有现成的地图插件都在偷偷请求外部瓦片服务页面一片空白控制台一堆请求超时。客户站在你身后问你这地图怎么是白的那个瞬间的尴尬我经历过不止一次。这个项目的核心就是解决内网环境下Django后台依然能显示可交互地图这件事。技术选型上前端用OpenLayers做地图渲染引擎后端用Django提供瓦片和页面瓦片数据提前下载好放在本地或者内网服务器上。整套方案不依赖任何外部网络请求打开后台就能看到地图能缩放、能拖拽、能打点、能画图形。它适合谁参考如果你正在做政企内网项目、工业现场管理系统、离线部署的物联网平台或者任何服务器不能出公网的场景这套思路基本可以直接搬。哪怕你只是想在本地开发环境里摆脱对地图服务商的依赖这篇文章里的瓦片处理和OpenLayers配置部分同样适用。我先把整体思路说清楚免得你看到后面觉得跳跃。整个链路是这样的地图瓦片就是一张张切好的小图片提前准备好放在Django能访问到的目录里Django写一个视图函数根据前端传来的层级、行列号把对应的瓦片图片返回回去前端页面引入OpenLayers配置一个自定义的XYZ图层把瓦片请求指向我们自己的Django接口最后把这个页面挂到admin的某个模型编辑页或者自定义页面上。听起来不复杂但每一步都有坑下面逐个拆。2. 离线瓦片的来源与目录组织方式2.1 瓦片从哪来几种常见获取途径的取舍离线地图的第一步不是写代码是搞到瓦片。瓦片本质上就是按金字塔层级切好的图片常见的格式是PNG或者JPG命名规则一般是z/x/y.pngz是缩放层级x是列号y是行号。获取途径主要有这么几种我按实际项目里的使用频率排一下。第一种是用现成的瓦片下载工具指定一个区域范围和层级范围把瓦片批量抓下来。这种方式适合区域不大、层级不深的场景比如只覆盖一个园区、一个县城层级到15、16级就够了。第二种是拿现成的矢量或栅格数据自己切用一些地图切片工具把大图或者地理数据切成瓦片金字塔。这种方式适合你有自己的底图数据比如客户提供的航拍图、规划图。第三种是直接用别人已经打包好的离线瓦片包网上有一些开源项目会提供某个区域、某个层级的瓦片压缩包下载解压就能用。我个人的经验是如果只是后台里做个位置标注区域固定、层级需求不高第一种方式最省事。但要注意下载瓦片这件事本身要合规用自己有权使用的数据源别去抓那些明确禁止批量下载的服务。内网项目里更稳妥的做法是让客户提供底图数据或者用开源地图数据自己切。2.2 目录结构怎么摆别小看这个细节瓦片下载下来之后目录结构直接决定了后面Django视图怎么写。最常见的两种组织方式我列个表对比一下。组织方式目录示例优点缺点标准金字塔tiles/{z}/{x}/{y}.png结构清晰和OpenLayers默认规则一致层级深了之后文件数量巨大小文件多按区域打包tiles/{region}/{z}/{x}/{y}.png多区域项目好管理前端切换区域时要改URL模板合并大图tiles/{z}/{x}/{y}.jpg但用打包格式减少文件数量需要额外解析逻辑不推荐新手我强烈建议用第一种标准金字塔结构。原因很简单OpenLayers的XYZ图层默认就认这个规则你不需要写任何额外的坐标转换逻辑。目录层级深、小文件多这个问题在后台这种访问量不大的场景里根本不是问题别为了优化这点性能把结构搞复杂。具体摆放位置我习惯在Django项目的根目录下建一个media或者static之外的独立目录比如叫offline_tiles然后在settings里配一个路径常量。为什么不放static里因为static目录在collectstatic的时候会被整体处理几万个小文件复制起来非常慢而且这些瓦片严格来说不算静态资源算数据。放media里也不合适media一般是用户上传的文件。单独建目录用Django的视图去读最干净。# settings.py import os BASE_DIR os.path.dirname(os.path.dirname(os.path.abspath(__file__))) TILE_ROOT os.path.join(BASE_DIR, offline_tiles)目录建好之后把下载的瓦片按z/x/y.png的层级塞进去。这里有个小坑不同工具下载下来的瓦片y轴方向可能不一样。有的工具用TMS规范y是从下往上数的有的用XYZ规范y是从上往下数的。OpenLayers默认用XYZ规范。如果你发现地图显示出来是上下颠倒的八成就是这个问题。解决办法要么在下载时选对规范要么在前端配置里加一个y坐标的转换。3. Django端瓦片服务的实现细节3.1 视图函数怎么写才稳瓦片服务的核心就是一个视图函数接收z、x、y三个参数拼出文件路径读文件返回图片响应。听起来三行代码的事但实际写起来有几个地方不注意就会出问题。# views.py import os import mimetypes from django.http import HttpResponse, Http404 from django.conf import settings def serve_tile(request, z, x, y): # 拼接瓦片路径注意扩展名可能是png也可能是jpg tile_dir os.path.join(settings.TILE_ROOT, str(z), str(x)) tile_path None for ext in (png, jpg, jpeg): candidate os.path.join(tile_dir, f{y}.{ext}) if os.path.isfile(candidate): tile_path candidate break if tile_path is None: raise Http404(tile not found) # 读取文件并返回 with open(tile_path, rb) as f: data f.read() content_type, _ mimetypes.guess_type(tile_path) response HttpResponse(data, content_typecontent_type or image/png) # 关键设置缓存头减少重复请求 response[Cache-Control] public, max-age86400 return response这段代码里有几个点值得展开说。第一扩展名做了兼容处理因为不同来源的瓦片格式可能不统一写死png的话遇到jpg就404了。第二Cache-Control这个响应头一定要加。地图缩放拖拽的时候同一个瓦片会被反复请求没有缓存的话每次都要读磁盘后台页面会卡得你想砸键盘。设成一天浏览器自己就缓存了。第三读文件用二进制模式别用文本模式图片是二进制数据。3.2 URL配置与安全边界URL配置很直接把z、x、y三个参数用正则或者路径转换器接住就行。# urls.py from django.urls import path from . import views urlpatterns [ path(tiles/int:z/int:x/int:y.png, views.serve_tile, nameserve_tile), ]但这里有个安全问题必须提用户传进来的z、x、y是可控的如果不做校验别人可以构造../../这样的路径来读取服务器上的任意文件。虽然Django的URL转换器int:...已经限制了只能是整数天然挡住了大部分路径穿越攻击但我还是建议在视图里加一层范围校验。def serve_tile(request, z, x, y): # 限制层级范围防止有人传个z99来探测 if not (0 z 22): raise Http404 if x 0 or y 0: raise Http404 # 限制x、y的最大值2的z次方 max_xy 2 ** z if x max_xy or y max_xy: raise Http404 # ... 后续逻辑这个校验不只是安全考虑也能避免无效请求打到磁盘上。地图组件在边界处经常会请求一些超出范围的瓦片提前挡掉比让它去读文件再报错要高效。3.3 性能优化什么时候该上缓存后台管理系统访问量通常不大但如果你的地图页面会被多个用户同时打开或者瓦片目录放在机械硬盘上读磁盘还是会成为瓶颈。我一般会加一层内存缓存把最近访问过的瓦片缓存在进程内存里。from django.core.cache import cache def serve_tile(request, z, x, y): cache_key ftile_{z}_{x}_{y} cached cache.get(cache_key) if cached: return HttpResponse(cached, content_typeimage/png) # ... 读文件逻辑 cache.set(cache_key, data, 3600) return response用Django自带的缓存框架本地内存缓存或者Redis都行。缓存时间设一小时左右既能扛住短时间的高频访问又不会占太多内存。注意别把整个瓦片目录都往缓存里塞只缓存被访问到的让缓存自然淘汰。提示如果你的瓦片总量很大比如超过十万张别用文件系统缓存直接上Redis或者Memcached并且给缓存设一个内存上限防止把服务器内存吃满。4. OpenLayers前端的配置与踩坑4.1 引入OpenLayers与基础地图初始化前端这块OpenLayers的引入方式有两种用CDN或者本地文件。内网环境显然只能用本地文件把OpenLayers的js和css下载下来放到static目录里。版本选择上我建议用比较新的稳定版老版本有些API写法不一样网上搜到的教程可能对不上。!-- 在admin的模板里引入 -- link relstylesheet href{% static ol/ol.css %} script src{% static ol/ol.js %}/script初始化地图的代码大概长这样const map new ol.Map({ target: map-container, layers: [ new ol.layer.Tile({ source: new ol.source.XYZ({ url: /tiles/{z}/{x}/{y}.png, // 关键配置告诉OpenLayers瓦片的坐标系 projection: EPSG:3857, // 瓦片大小默认256 tileSize: 256, }) }) ], view: new ol.View({ center: ol.proj.fromLonLat([116.4, 39.9]), // 初始中心点 zoom: 12, minZoom: 3, maxZoom: 18, }) });这里有几个配置项必须说清楚。url里的{z}、{x}、{y}是OpenLayers的占位符它会自动替换成当前视图需要的瓦片编号请求发到我们Django的接口上。projection设成EPSG:3857这是Web墨卡托投影绝大多数在线地图瓦片都用这个坐标系。如果你下载的瓦片是别的坐标系这里要对应改否则地图会偏移或者变形。center那里用了ol.proj.fromLonLat把经纬度转成地图坐标系。如果你直接填经纬度数值地图会跑到不知道哪里去。这个转换函数是新手最容易漏的一步。4.2 瓦片请求404了怎么办排查链路地图显示空白或者部分区域空白最常见的原因就是瓦片请求404。排查这个问题的完整链路我梳理一下你按顺序走一遍基本都能定位。第一步打开浏览器开发者工具切到Network面板筛选图片请求。看看请求的URL长什么样是不是/tiles/12/3372/1552.png这种格式。如果URL里出现了{z}没被替换的情况说明OpenLayers的配置有问题检查url模板字符串是不是写错了。第二步看请求的响应状态码。如果是404说明Django那边没找到文件。这时候去服务器上看对应的目录下有没有这个文件。比如请求的是z12, x3372, y1552就去offline_tiles/12/3372/1552.png看文件在不在。不在的话要么是瓦片没下载全要么是下载工具的命名规则和OpenLayers的请求规则对不上。第三步如果文件在但依然404检查Django的URL配置和视图逻辑。可以在视图里加一行日志把拼接出来的路径打出来看看和实际文件路径差在哪里。常见的问题是路径拼接时多了或者少了一层目录或者扩展名不匹配。第四步如果请求返回200但地图还是白的检查返回的Content-Type对不对。有时候Django返回的content_type是application/octet-stream浏览器不认就不渲染。手动设成image/png。第五步如果只有部分层级正常其他层级空白检查minZoom和maxZoom的设置以及瓦片实际下载的层级范围。你只下载了10到15级的瓦片但地图视图允许缩放到18级那16到18级自然就是空白。4.3 坐标系偏移那个让人抓狂的几百米误差比404更隐蔽的问题是坐标偏移。地图能显示瓦片也能加载但你打的那个点实际位置偏了几百米。这个问题十有八九是坐标系不匹配导致的。国内的地图数据很多时候用的是GCJ-02或者BD-09坐标系而OpenLayers默认的EPSG:3857是基于WGS-84的。这两套坐标系之间有几百万米的偏移量。如果你下载的瓦片是国内某地图服务的而你的标注点用的是GPS原始坐标两者一叠加位置就对不上。解决办法有两个方向。一是统一坐标系要么把瓦片转成WGS-84的要么把标注点转成和瓦片一致的坐标系。二是用转换库在前端做实时转换。我一般推荐第一个方向因为转换一次一劳永逸前端逻辑简单。转换工具网上有开源的输入输出都是标准格式批量处理一下就行。注意坐标系转换涉及合规问题确保你使用的数据来源和转换方式符合相关规定别拿未经授权的数据做商业用途。5. 把地图嵌进Django admin的几种姿势5.1 自定义admin模板最直接的方式地图页面做好了怎么让它出现在admin里最简单的方式是覆盖某个模型的编辑模板在表单旁边或者下方嵌入地图。Django admin的模板继承体系很清晰你找到对应的模板路径在自己的项目里建一个同名文件继承原来的模板然后在合适的block里插入地图的div和脚本。比如你要在某个模型的编辑页加地图可以这样做{% extends admin/change_form.html %} {% load static %} {% block after_field_sets %} {{ block.super }} div idmap-container stylewidth: 100%; height: 400px;/div script src{% static ol/ol.js %}/script script // 地图初始化代码 /script {% endblock %}这种方式的好处是改动小不用动admin的注册逻辑。缺点是地图和表单数据是分离的如果你想在地图上点击来填充表单里的经纬度字段需要额外写JS来同步。5.2 自定义admin视图更灵活的方案如果你需要的地图功能比较复杂比如要展示多个模型的数据、要做空间查询那覆盖模板就不够用了。这时候可以写一个自定义的admin视图单独做一个地图页面然后在admin的导航里加个入口。# admin.py from django.contrib import admin from django.urls import path from django.shortcuts import render class MapAdminSite(admin.AdminSite): def get_urls(self): urls super().get_urls() custom_urls [ path(map/, self.admin_view(self.map_view), namemap-view), ] return custom_urls urls def map_view(self, request): return render(request, admin/map.html, { title: 地图总览, })这种方式适合做数据可视化大屏或者综合态势页面。你可以在这个视图里查询数据库把需要标注的点位数据序列化成JSON传给前端渲染。5.3 数据联动地图和表单怎么配合实际项目里地图往往不是单独存在的它要和后台的数据联动。比如你在编辑一个设备信息设备有经纬度字段你希望在地图上点一下就能自动填充这两个字段。这个需求实现起来不难但有几个细节要注意。前端监听地图的点击事件拿到点击位置的坐标然后转换坐标系最后把值写到对应的input里。map.on(click, function(evt) { const coord ol.proj.toLonLat(evt.coordinate); const lon coord[0].toFixed(6); const lat coord[1].toFixed(6); document.getElementById(id_longitude).value lon; document.getElementById(id_latitude).value lat; });这里toLonLat把地图坐标转回经纬度toFixed(6)保留六位小数精度足够了。注意input的id要和Django表单生成的id一致一般是id_字段名的格式。如果字段名有下划线或者特殊字符id可能会变去页面上检查一下实际生成的id。反过来如果表单里已经有经纬度数据页面加载时要把地图中心定位到那个位置并且打一个标记。这个逻辑写在页面初始化的时候先读input的值有值就定位没值就用默认中心点。6. 实测中遇到的几个典型问题与处理6.1 瓦片加载慢从磁盘IO到浏览器缓存的完整优化后台地图页面打开慢原因可能出在好几个环节。我按从后端到前端的顺序把能优化的点都列一下。后端层面瓦片文件如果放在网络存储或者机械硬盘上读取速度会明显慢于本地SSD。如果条件允许把瓦片目录放在本地磁盘上。另外前面提到的Django缓存一定要开重复请求直接走内存不碰磁盘。传输层面确保服务器开启了gzip压缩。PNG图片本身压缩率不高但HTTP响应头和其他文本资源压缩后能省不少带宽。如果瓦片是JPG格式压缩效果会更明显。前端层面OpenLayers本身有一些优化参数。比如设置cacheSize控制内存中缓存的瓦片数量。默认值可能偏小适当调大能减少重复请求。new ol.source.XYZ({ url: /tiles/{z}/{x}/{y}.png, cacheSize: 512, // 默认好像是256调大一些 transition: 0, // 关闭淡入效果加载更快 })transition设成0能去掉瓦片加载时的淡入动画视觉上会感觉快一些。这个看个人喜好有人觉得有动画更平滑。6.2 跨域与静态文件服务的坑开发环境下Django的runserver能直接服务静态文件但生产环境一般用Nginx或者Apache来服务静态资源。瓦片如果走Django视图返回那没问题不涉及跨域。但如果你把瓦片放在单独的静态文件服务器上前端页面和瓦片不在同一个域名下就会遇到跨域问题。解决办法是在瓦片服务器上设置CORS响应头允许你的admin域名访问。Nginx里加一行add_header Access-Control-Allow-Origin *;就行。但生产环境别用*指定具体的域名。另一个坑是Django的DEBUG模式。开发时DEBUGTrueDjango会自动服务static和media文件。部署时DEBUGFalse这些自动服务就关了如果你没配Nginx瓦片和OpenLayers的js文件都会404。这个坑我踩过本地好好的一部署就白屏查了半天才发现是DEBUG的问题。6.3 移动端适配与触摸操作后台管理系统现在也经常要在平板或者手机上用地图的触摸操作需要额外注意。OpenLayers默认支持触摸缩放和拖拽但有些交互在移动端体验不好。比如默认的双指旋转在后台场景里基本用不到还容易误触可以关掉。new ol.interaction.defaults({ altShiftDragRotate: false, pinchRotate: false, })把旋转相关的交互关掉只保留缩放和拖拽。另外地图容器的尺寸在移动端要用相对单位别写死像素宽度用百分比或者vw让它自适应屏幕。7. 几个能直接抄的配置片段与经验参数7.1 完整的settings与URL配置清单把前面散落的配置集中列一下方便你直接对照。# settings.py 需要加的部分 import os BASE_DIR os.path.dirname(os.path.dirname(os.path.abspath(__file__))) TILE_ROOT os.path.join(BASE_DIR, offline_tiles) # 如果用缓存 CACHES { default: { BACKEND: django.core.cache.backends.locmem.LocMemCache, LOCATION: tile-cache, TIMEOUT: 3600, } }# 项目urls.py from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(map/, include(your_app.urls)), ]# your_app/urls.py from django.urls import path from . import views urlpatterns [ path(tiles/int:z/int:x/int:y.png, views.serve_tile, nameserve_tile), ]7.2 OpenLayers初始化的推荐参数const map new ol.Map({ target: map-container, layers: [ new ol.layer.Tile({ source: new ol.source.XYZ({ url: /map/tiles/{z}/{x}/{y}.png, projection: EPSG:3857, tileSize: 256, cacheSize: 512, transition: 0, }) }) ], view: new ol.View({ center: ol.proj.fromLonLat([116.4, 39.9]), zoom: 12, minZoom: 3, maxZoom: 18, constrainResolution: true, // 缩放时对齐到整数层级 }), interactions: new ol.interaction.defaults({ altShiftDragRotate: false, pinchRotate: false, }), });constrainResolution: true这个参数值得说一下。默认情况下OpenLayers缩放时会有小数层级比如12.3级这时候它会去请求13级的瓦片然后缩放显示看起来会有点模糊。设成true之后缩放会吸附到整数层级瓦片显示更清晰。代价是缩放动画没那么平滑但后台场景里清晰比平滑重要。7.3 瓦片层级与文件数量的估算下载瓦片之前最好估算一下文件数量和磁盘占用免得下到一半发现硬盘满了。瓦片数量的计算公式是4的z次方但实际只下载你需要的区域所以数量远小于这个值。我列个表给你参考假设你只需要覆盖一个城市范围大概占整个地球表面积的百万分之一量级层级范围大致瓦片数量磁盘占用PNG适用场景0-10几百张几十MB省级概览0-14几千张几百MB市级地图0-16几万张几个GB区县级详细地图0-18几十万张几十GB街道级精细地图后台管理系统一般到14或15级就够用了再往下层级文件数量增长太快收益不大。除非你的业务需要精确到每栋楼那另说。8. 写在最后一些个人体会这套离线地图方案我在几个内网项目里都用过整体跑下来很稳。最深的体会是瓦片数据的准备比代码本身重要得多。代码就那么几十行但瓦片下载不全、坐标系不对、层级范围没规划好任何一个问题都会让地图显示不正常。所以动手写代码之前先把瓦片的事情理清楚目录结构、命名规则、坐标系、层级范围这四样确认无误了后面基本就是顺水推舟。另一个体会是关于缓存的。后台地图页面一旦用起来用户会频繁地缩放拖拽瓦片请求量比想象中大。Django那层缓存加上浏览器缓存两个都配上体验会好很多。别等到用户抱怨卡了才去加。最后说个扩展方向。这套方案目前是纯展示和打点如果你需要在地图上做空间查询比如找出这个矩形范围内的所有设备那就要在后端引入空间数据库或者空间索引。Django有对应的空间扩展库配合PostGIS能实现比较完整的空间查询能力。不过那是另一个话题了等有需求的时候再折腾。