MapProxy 是一个 地图服务“加速代理 + 瓦片缓存”中间层，专门帮你把已有的 WMS、WMTS、XYZ 瓦片等地图服务：

  • 缓存成瓦片，加速访问、抗高并发
  • 按需要 重投影 到别的坐标系（例如 EPSG:3857）
  • 统一对外提供 WMS / TMS / WMTS / XYZ 等服务给 WebGIS 或桌面 GIS 使用

它本身不生产数据，它只是一个非常强的 “地图网关 + 缓存层”。

MapProxy 基本使用流程

安装

以常见的 Linux / macOS + Python 环境为例（建议虚拟环境）：

python -m venv venv
source venv/bin/activate

python -m pip install MapProxy

安装完成后可以用：

mapproxy-util --version

确认 MapProxy 是否可用。

创建配置

MapProxy 提供一个命令帮你生成「最小可运行」的配置：

mapproxy-util create -t base-config mymapproxy

在 mymapproxy/ 目录下会得到：

  • mapproxy.yaml —— 主配置（服务 / 源 / 缓存等）
  • seed.yaml —— 预生成瓦片（seeding）配置
  • 以及一些示例配置文件

启动开发服务器

在配置所在目录执行：

mapproxy-util serve-develop mapproxy.yaml

默认会在本机开启一个开发用服务器（一般是 http://localhost:8080）。

打开浏览器访问：

  • http://localhost:8080/demo/ —— 自带 Demo 页面，可以点开每一个 Layer 直接预览
  • WMS 地址大致形如：http://localhost:8080/service?SERVICE=WMS&...

mapproxy.yaml 的结构：从上到下看一遍

官方教程里已经说明：MapProxy 的配置是一个 YAML 字典，核心几块分别是：services、layers、sources、caches、grids、globals。

下面结合配置，逐块说明“这是干嘛的”。

对外提供服务

services 配置开头类似这样：

services:
  # sets up how to make the source data available
  demo:
  tms:
  wms:
    srs: ['EPSG:900913', 'EPSG:3857']
    image_formats: ['image/jpeg', 'image/png']
    md:
      title: MapProxy WMS Proxy
      abstract: This is the fantastic MapProxy.
      online_resource: http://mapproxy.org/
      contact:
        person: Your Name
        position: Technical Director
        ...
      access_constraints: |
        This service is intended for private and evaluation use only.
        ...
      fees: 'None'

这里做了几件事：

  1. 开启 demo 服务：

    • demo: —— 让 http://localhost:8080/demo/ 可用，用来预览所有 layer。

  2. 开启 TMS 服务：

    • tms: —— 对外提供 TMS 瓦片服务（常用于 Web 地图）。

  3. 开启 WMS 服务，并配置元数据：

    • wms: 节点下设置：

      • srs：对外支持的坐标系（这里是常见的 Web Mercator）。
      • image_formats：客户端可以请求的图片格式。
      • md：填写 WMS Capabilities 里展示的标题、简介、联系人、访问限制、费用说明等。

可以把 services 理解成： “我要对外开哪些协议？这些协议的名片（Capabilities）上写什么信息？”

对外发布图层

layers 对应的配置中大概是这样：

layers:
  # sets up which layers you want to make available...
  - name: osm
    title: Open Streetmap Tiles
    sources: [osm_cache]

  - name: google
    title: Google Maps
    sources: [google_cache]

这里定义了两个对外服务的图层：

  • osm：对外叫这个名字（WMS/WMTS 请求时会用到）。
  • title：对人看的标题。
  • sources: 指向的是 缓存（cache），而不是直接的数据源。

简单理解：

  • layers = 给用户看、给客户端访问的“门面”

  • 里面的 sources 可以是：

    • 直接的数据源（sources 里定义的 WMS/XYZ 等）
    • 或者缓存（caches 里定义的缓存层）

推荐做法是 对外的图层 → 读缓存 → 缓存再去读真实数据源，性能更好。

怎么缓存瓦片

caches 中间段大致是：

caches:
  # cache for OpenStreetMap tiles
  osm_cache:
    sources: [osm_tiles]
    format: image/png

  google_cache:
    sources: [google_tiles]
    format: image/png

含义：

  • osm_cache / google_cache 是两个缓存名字。
  • sources：这个缓存遇到 cache miss 时，应该去哪个 source 请求新数据。
  • format：缓存瓦片的格式（通常是 png 或 jpeg）。

MapProxy 的工作流程大致是：

  1. 客户端请求 layers.osm；
  2. layers.osm 的 source 是 osm_cache；
  3. MapProxy 去 osm_cache 的目录里找已经缓存好的瓦片；
  4. 如果有： 直接返回（非常快）；
  5. 如果没有： 向 osm_tiles 请求一张图，切成瓦片，存到 osm_cache 目录，下次再用。

真实的数据源

以官方 OSM/Google 为例，sources 的配置如下：

sources:
  osm_tiles:
    type: tile
    url: http://a.tile.openstreetmap.org/%(z)s/%(x)s/%(y)s.png
    grid: osm_grid

  google_tiles:
    type: tile
    url: http://khm2.google.com/kh/v=878s&x=%(x)s&y=%(y)s&z=%(z)s&s=Galileo
    grid: osm_grid

说明：

  • type: tile：表示这是一个“XYZ 瓦片服务”源。
  • url：如何拼接出真实请求 URL，%(x)s/%(y)s/%(z)s 会由 MapProxy 根据当前瓦片坐标替换。
  • grid：这批瓦片使用的网格/投影定义（后面在 grids 中配置）。

可以把 sources 想成：“后台真实地图服务的配置清单”。

瓦片坐标系与切片规则

grids 配置里的内容：

grids:
  osm_grid:
    # grid settings correct for openstreetmap.org tiles
    srs: EPSG:900913
    origin: nw

  google_grid:
    srs: EPSG:3857

说明：

  • osm_grid：
    • srs: EPSG:900913（相当于 Web Mercator）。
    • origin: nw：瓦片坐标从左上角（北西）开始算，这是 OSM/Google 标准。
  • google_grid：同样是 Web Mercator（EPSG:3857），一般跟 OSM 那套是兼容的。

grids 定义了「瓦片是怎么切的」：

  • 用哪个坐标系（srs）
  • 坐标原点在哪里（origin）
  • 分辨率、级别（可以继续配置 res / res_factor 等）([mapproxy.github.io][3])

若 source 跟 grid 的 SRS 不同，MapProxy 会帮你做重投影。

全局设置（缓存目录、图片质量等）

global 的配置示例如下：

globals:
  cache:
    base_dir: "./cache_data"
    lock_dir: "./cache_data/locks"

  image:
    resampling_method: bilinear
    jpeg_quality: 90

含义：

  • cache.base_dir：所有缓存瓦片保存的根目录（记得给进程写权限）。
  • lock_dir：并发写缓存时，用来放锁文件。
  • image：
    • resampling_method：重采样算法，常见有 nearest, bilinear 等。
    • jpeg_quality：如果缓存/输出 jpeg 时的压缩质量。

实际使用步骤

假设你已经准备好 mapproxy.yaml 文件，并且目录结构大致是：

project/
  mapproxy.yaml
  cache_data/       # 启动后自动生成

第 1 步：创建虚拟环境并安装 MapProxy

cd project
python -m venv venv
source venv/bin/activate
python -m pip install MapProxy

第 2 步：启动开发服务器

mapproxy-util serve-develop mapproxy.yaml

终端会提示监听的地址（通常是 http://localhost:8080）。

第 3 步：在浏览器里验证

  • 打开 http://localhost:8080/demo/

    • 能看到 osm / google 两个 Layer；
    • 点进去可以用内置的 OpenLayers 客户端预览。([mapproxy.github.io][3])

  • 在 WebGIS 或 QGIS 中，配置 WMS 服务地址，例如：

    http://localhost:8080/service?

    然后在图层列表里选 osm 或 google。

Step 4：观察缓存目录

第一次访问时，cache_data/ 目录会逐渐被填满不同层级的瓦片。

如果你修改了源地址或网格配置，需要清缓存的话，可以手动删除对应子目录，再重启服务。