wiktorn/overpass-api

Overpass API Docker镜像文档

镜像概述和主要用途

基于NGINX的Overpass API镜像，用于部署可查询OpenStreetMap(OSM)数据的服务。支持通过init（从OSM数据dump初始化）或clone（克隆现有实例）两种模式快速搭建，可通过环境变量自定义数据来源、更新频率、性能参数等，适用于需要本地OSM数据查询服务的场景，如区域数据服务、开发测试环境或私有数据部署。

核心功能和特性

• 双模式初始化：支持init（从OSM数据dump下载并索引）和clone（克隆现有已索引实例，初始化更快）。
• 灵活数据配置：可指定全行星、区域OSM数据或现有Overpass实例作为数据源，支持差异更新（分钟级、小时级等）。
• 全面环境变量控制：支持元数据保留、压缩方式、性能调优（并发数、速率限制、超时等）及安全访问（cookie/OAuth2）。
• 集成数据工具：包含pyosmium和osmium-tool，支持数据格式转换（如PBF转OSM.bz2）。
• 持久化存储：数据存储于/db目录，支持通过卷挂载实现持久化。

使用场景和适用范围

• 全行星OSM服务：部署覆盖全球的Overpass实例，用于全球OSM数据查询。
• 区域数据服务：针对特定区域（如城市、国家）部署，减少存储和资源占用。
• 快速克隆部署：克隆现有Overpass实例，适用于本地开发测试或紧急灾备。
• 私有数据源对接：通过cookie或OAuth2访问受保护的内部OSM数据源。

详细配置说明

环境变量

模式说明

init模式

• 数据流程：从OVERPASS_PLANET_URL下载OSM数据dump（全行星/区域）→ 索引数据 → 通过OVERPASS_DIFF_URL更新。
• 适用场景：自定义数据源（如特定区域）或无克隆源时。
• 特点：初始化较慢（需索引数据），数据来源灵活。

clone模式

• 数据流程：从OVERPASS_CLONE_SOURCE克隆已索引数据 → 通过OVERPASS_DIFF_URL更新。
• 适用场景：快速部署（无需重新索引），默认克隆源提供分钟级更新的全球数据。
• 特点：初始化快，依赖克隆源可用性。

使用方法

基本运行

监控初始化进度

添加-i（保持标准输入）和-t（分配终端）参数监控进度：

bash
docker run -i -t wiktorn/overpass-api

端口映射与数据持久化

映射80端口至主机，挂载/db目录实现数据持久化：

bash
docker run -p 80:80 -v /host/path:/db wiktorn/overpass-api

初始化后操作

初始化完成后容器自动停止，再次启动即开始更新并提供服务：

bash
docker start <container_name>

部署示例

示例1：区域数据实例（Monaco）

通过init模式部署摩纳哥区域数据：

bash
docker run \
  -e OVERPASS_META=yes \
  -e OVERPASS_MODE=init \
  -e OVERPASS_PLANET_URL=http://download.geofabrik.de/europe/monaco-latest.osm.bz2 \
  -e OVERPASS_DIFF_URL=http://download.openstreetmap.fr/replication/europe/monaco/minute/ \
  -e OVERPASS_RULES_LOAD=10 \
  -v /big/docker/overpass_db/:/db \
  -p 12345:80 \
  -i -t \
  --name overpass_monaco wiktorn/overpass-api

示例2：全行星克隆实例

通过clone模式快速部署全球数据：

bash
docker run \
  -e OVERPASS_META=yes \
  -e OVERPASS_MODE=clone \
  -e OVERPASS_DIFF_URL=https://planet.openstreetmap.org/replication/minute/ \
  -v /big/docker/overpass_clone_db/:/db \
  -p 12346:80 \
  -i -t \
  --name overpass_world \
  wiktorn/overpass-api

示例3：带OAuth2认证的区域实例

访问需要认证的内部数据源，使用osmium转换PBF格式：

1. 准备OAuth配置文件/home/osm/oauth-settings.json：

json
{
  "user": "your-username",
  "password": "your-secure-password",
  "osm_host": "https://www.openstreetmap.org",
  "consumer_url": "https://osm-internal.download.geofabrik.de/get_cookie"
}

2. 运行容器：

bash
docker run \
  -e OVERPASS_META=yes \
  -e OVERPASS_MODE=init \
  -e OVERPASS_PLANET_URL=https://osm-internal.download.geofabrik.de/europe/monaco-latest-internal.osm.pbf \
  -e OVERPASS_DIFF_URL=https://osm-internal.download.geofabrik.de/europe/monaco-updates/ \
  -e OVERPASS_RULES_LOAD=10 \
  -e OVERPASS_COMPRESSION=gz \
  -e OVERPASS_UPDATE_SLEEP=3600 \
  -e OVERPASS_PLANET_PREPROCESS='mv /db/planet.osm.bz2 /db/planet.osm.pbf && osmium cat -o /db/planet.osm.bz2 /db/planet.osm.pbf && rm /db/planet.osm.pbf' \
  -e USE_OAUTH_COOKIE_CLIENT=yes \
  --mount type=bind,source=/home/osm/oauth-settings.json,target=/secrets/oauth-settings.json \
  -v /big/docker/overpass_db/:/db \
  -p 12347:80 \
  -i -t \
  --name overpass_monaco wiktorn/overpass-api

访问Overpass API

直接查询

API地址为http://localhost:<host_port>/api/interpreter，例如查询都柏林酒吧：

http://localhost:12346/api/interpreter?data=node(3470507586);out geom;

在Overpass Turbo中使用

1. 打开Overpass Turbo
2. 进入设置（Settings）→ 服务器（Server）
3. 设置为http://localhost:<host_port>/api/，即可使用本地实例查询。