geokrety/osm-static-maps

osm-static-maps 镜像文档

镜像概述和主要用途

osm-static-maps 是一个用于生成 OpenStreetMap (OSM) 静态地图的守护进程镜像。该镜像集成了尚未合并到上游版本的自定义修复，解决了官方版本中存在的特定渲染问题，为需要嵌入静态地图的应用提供稳定、可靠的地图生成服务。

核心功能和特性

• 静态地图生成：支持生成高质量 OSM 静态地图图片
• 自定义修复集成：包含上游版本未合并的特定问题修复，提升地图渲染准确性
• 守护进程模式：以服务形式持续运行，提供实时地图生成能力
• 灵活参数配置：支持通过 API 调整地图中心坐标、缩放级别、尺寸等参数
• 高效缓存机制：内置请求缓存功能，优化重复地图请求的响应速度

使用场景和适用范围

• 网站或移动应用中需要嵌入静态 OSM 地图的场景
• 对地图渲染质量有特定要求，需要解决上游版本问题的应用
• 开发环境和生产环境中需要独立地图生成服务的系统
• 报告生成、文档插图等需要静态地图资源的场景

使用方法和配置说明

基本部署（Docker Run）

通过以下命令快速启动服务：

bash
docker run -d -p 8080:8080 --name osm-static-maps docker.xuanyuan.run/geokrety/osm-static-maps

服务启动后，可通过 http://localhost:8080 访问地图生成 API。

Docker Compose 配置

创建 docker-compose.yml 文件进行更灵活的部署：

yaml
version: '3'
services:
  osm-static-maps:
    image: docker.xuanyuan.run/geokrety/osm-static-maps
    container_name: osm-static-maps
    ports:
      - "8080:8080"  # 端口映射
    restart: always  # 自动重启
    environment:
      - PORT=8080     # 服务监听端口（默认8080）
      - CACHE_SIZE=5000  # 缓存大小（默认1000，单位：请求数）
    volumes:
      - ./cache:/app/cache  # 可选：持久化缓存目录

启动服务：

bash
docker-compose up -d

配置参数（环境变量）

API 使用示例

通过 HTTP GET 请求生成地图：

GET http://localhost:8080/map?lat=46.2276&lon=8.2263&zoom=13&width=800&height=600&format=png

请求参数说明

响应

成功请求将返回指定格式的静态地图图片，HTTP 状态码 200。若请求参数无效或生成失败，将返回相应错误信息。