jore4-map-matching 镜像文档

镜像概述

jore4-map-matching是一个基于Docker容器化的地图匹配服务，旨在将原始GPS轨迹数据或位置序列精确匹配到道路网络，解决轨迹漂移、数据噪声等问题，为交通数据分析和智能交通系统提供高质量的基础数据处理能力。该服务与HSLdevcom的Jore4交通管理系统深度集成，支持多种数据格式和自定义匹配参数。

核心功能与特性

• 高效匹配算法：采用优化的隐马尔可夫模型（HMM）路径匹配算法，支持大规模轨迹数据实时处理
• 多格式兼容性：原生支持GeoJSON、CSV、GPX等主流轨迹数据格式输入输出
• 可配置匹配精度：提供低/中/高三级匹配精度模式，平衡处理速度与结果准确性
• Jore4生态集成：无缝对接Jore4道路网络数据库，支持标准化交通数据导入导出
• RESTful API：提供完整的HTTP接口，支持批量轨迹提交和异步任务处理

使用场景与适用范围

• 城市交通数据分析：为交通流量监测、拥堵分析提供精确的轨迹-道路匹配数据
• 出行行为研究：辅助分析居民出行路径特征、换乘模式等行为规律
• 智能交通系统：为实时公交调度、路径规划提供基础数据支撑
• 物流与车队管理：优化车辆行驶路径分析，提升配送效率监控能力

使用方法与配置说明

基础部署（Docker Run）

docker run -d \
  --name jore4-map-matching \
  -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e ROAD_NETWORK_DB_URL=jdbc:postgresql://db-host:5432/jore4_roads \
  -e ROAD_NETWORK_DB_USER=dbuser \
  -e ROAD_NETWORK_DB_PASSWORD=dbpass \
  hsldevcom/jore4-map-matching:latest

Docker Compose 部署

version: '3.8'
services:
  map-matching:
    image: hsldevcom/jore4-map-matching:latest
    container_name: jore4-map-matching
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=prod
      - LOG_LEVEL=INFO
      - MATCHING_PRECISION=medium
      - ROAD_NETWORK_DB_URL=jdbc:postgresql://road-db:5432/jore4_roads
      - ROAD_NETWORK_DB_USER=mapuser
      - ROAD_NETWORK_DB_PASSWORD=securepass
    depends_on:
      - road-db
    restart: unless-stopped

  road-db:
    image: postgis/postgis:14-3.3
    volumes:
      - road-network-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=jore4_roads
      - POSTGRES_USER=mapuser
      - POSTGRES_PASSWORD=securepass

volumes:
  road-network-data:

环境变量配置

API 使用示例

提交单条轨迹匹配请求

curl -X POST http://localhost:8080/api/v1/match \
  -H "Content-Type: application/json" \
  -d @single-trajectory.geojson

请求体示例（GeoJSON格式）：

{
  "type": "Feature",
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [24.9384, 60.1699],
      [24.9390, 60.1702],
      [24.9395, 60.1705]
    ]
  },
  "properties": {
    "timestamp": "2023-10-01T12:00:00Z",
    "vehicle_id": "BUS-1234"
  }
}

批量轨迹匹配请求

curl -X POST http://localhost:8080/api/v1/match/batch \
  -H "Content-Type: application/json" \
  -d @batch-trajectories.json

匹配结果响应示例

{
  "requestId": "req-7f92b34",
  "status": "completed",
  "matchedFeatures": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [24.9383, 60.1698],
          [24.9389, 60.1701],
          [24.9394, 60.1704]
        ]
      },
      "properties": {
        "originalId": "BUS-1234",
        "matchQuality": 0.94,
        "processingTimeMs": 187,
        "matchedRoadSegments": ["road-567", "road-568"]
      }
    }
  ],
  "totalProcessed": 1,
  "successRate": 1.0
}

注意事项

• 首次启动需确保道路网络数据库已初始化完成，可通过 GET /health 接口检查服务就绪状态
• 高并发场景建议调整 MAX_BATCH_SIZE 和容器资源限制（CPU/内存）
• 生产环境需配置数据库连接池参数（通过 application-prod.properties 挂载自定义配置）
• 大规模历史数据处理建议使用异步任务接口 POST /api/v1/match/async