保姆级教程：用Docker在Ubuntu上快速部署Valhalla路径规划服务（附日本关西OSM数据实战）

从零搭建Valhalla路径规划引擎：Docker+Ubuntu实战指南

第一次接触路径规划引擎时，我被Valhalla这个名字吸引——北欧神话中英灵殿的宏伟殿堂，却意外地成为了开源路由引擎的代名词。作为一个长期依赖第三方地图API的后端开发者，当我需要为物流调度系统构建自主路径规划能力时，Valhalla以其开源特性、多交通模式支持和OSM数据兼容性成为了我的首选。但在实际部署过程中，官方文档的碎片化让整个安装过程变成了"踩坑大会"。本文将分享我在Ubuntu 22.04系统上，使用Docker部署Valhalla并加载日本关西地区OSM数据的完整实战经验，重点解决那些文档中没写清楚的关键细节。

1. 环境准备与基础配置

1.1 Ubuntu系统优化

在开始前，建议使用干净的Ubuntu 22.04 LTS系统。我尝试过在Ubuntu 20.04上部署，发现GLIBC版本问题会导致后续步骤报错。如果使用云服务器，推荐选择至少4核CPU、16GB内存和100GB SSD存储的配置——生成日本关西地区的瓦片数据时，我的测试机内存峰值达到了12GB。

# 检查系统版本 lsb_release -a # 更新软件包 sudo apt update && sudo apt upgrade -y

注意：Valhalla的瓦片生成过程是CPU密集型操作，AWS的t3.xlarge或同级别机型是性价比不错的选择

1.2 Docker引擎安装

官方推荐使用Docker部署以避免依赖冲突，但默认的Ubuntu Docker包可能版本过旧。以下是经过验证的安装步骤：

# 卸载旧版本 sudo apt remove docker docker-engine docker.io containerd runc # 设置仓库 sudo apt install -y ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg # 添加源 echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装Docker sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 验证安装 sudo docker run hello-world

关键点在于避免使用snap安装Docker，这会导致后续的volume挂载权限问题。如果遇到Got permission denied错误，需要将当前用户加入docker组：

sudo usermod -aG docker $USER newgrp docker # 立即生效

2. OSM数据获取与处理

2.1 区域数据下载

Geofabrik是获取OSM区域数据的可靠来源。日本关西地区数据约400MB，下载速度取决于你的网络环境：

mkdir -p ~/valhalla_data && cd ~/valhalla_data wget https://download.geofabrik.de/asia/japan/kansai-latest.osm.pbf

如果需要其他区域，替换URL中的asia/japan/kansai部分即可。例如：

• 东京：asia/japan/kanto-latest.osm.pbf
• 全日本：asia/japan-latest.osm.pbf

2.2 磁盘空间预估

处理OSM数据前，务必检查磁盘空间。以下是不同区域的大致需求：

使用df -h查看可用空间，建议至少有原始数据大小20倍的剩余空间。

3. Valhalla容器部署实战

3.1 拉取镜像与初始配置

官方镜像已经包含所有必要组件，直接拉取最新版：

docker pull ghcr.io/valhalla/valhalla:latest

创建用于存储配置和瓦片的目录结构：

mkdir valhalla_tiles valhalla_config

3.2 生成配置文件

Valhalla的核心是valhalla.json配置文件，它决定了路网如何处理。以下命令生成默认配置并映射瓦片目录：

docker run --rm \ -v $(pwd)/valhalla_tiles:/custom_files \ ghcr.io/valhalla/valhalla:latest \ valhalla_build_config \ --mjolnir-tile-dir /custom_files \ --mjolnir-tile-extract /custom_files/valhalla_tiles.tar \ --mjolnir-timezone /custom_files/timezones.sqlite \ --mjolnir-admin /custom_files/admins.sqlite \ > valhalla_config/valhalla.json

关键参数解析：

• mjolnir-tile-dir：临时瓦片存储位置
• mjolnir-tile-extract：最终生成的瓦片打包文件
• mjolnir-timezone：时区数据库
• mjolnir-admin：行政区划数据

3.3 生成路网瓦片

这是最耗时的步骤，使用以下命令开始处理OSM数据：

docker run --rm \ -v $(pwd):/custom_files \ ghcr.io/valhalla/valhalla:latest \ valhalla_build_tiles -c /custom_files/valhalla_config/valhalla.json /custom_files/kansai-latest.osm.pbf

处理过程中可以监控系统资源：

watch -n 5 'docker stats --no-stream $(docker ps -q)'

常见问题：如果进程被OOM killer终止，尝试增加swap空间或使用更大内存的机器

3.4 打包瓦片数据

处理完成后，需要将分散的瓦片打包成单个文件：

docker run --rm \ -v $(pwd)/valhalla_tiles:/custom_files \ ghcr.io/valhalla/valhalla:latest \ bash -c "find /custom_files -type f | sort -n | tar cf /custom_files/valhalla_tiles.tar --no-recursion -T -"

检查生成的文件：

ls -lh valhalla_tiles/valhalla_tiles.tar

4. 服务启动与测试

4.1 启动Valhalla服务

使用以下命令启动服务，映射端口8002：

docker run -d \ --name valhalla_service \ -p 8002:8002 \ -v $(pwd)/valhalla_config:/custom_config \ -v $(pwd)/valhalla_tiles:/custom_files \ ghcr.io/valhalla/valhalla:latest \ valhalla_service /custom_config/valhalla.json 1

验证服务状态：

docker logs -f valhalla_service # 看到"Listening on 0.0.0.0:8002"表示成功

4.2 发起测试请求

使用curl测试路径规划功能，以下是从大阪站到京都站的驾车路线请求：

curl http://localhost:8002/route --data '{ "locations":[ {"lat":34.702485,"lon":135.495951}, {"lat":34.985849,"lon":135.758766} ], "costing":"auto", "directions_options":{ "units":"kilometers" }, "language":"ja-JP" }' | jq

成功响应应包含trip字段，其中legs数组详细描述了路线分段。如果遇到400 Bad Request，检查坐标点是否在关西区域内。

4.3 性能优化建议

默认配置适合开发环境，生产环境需要调整：

// 在valhalla.json中添加 "service_limits": { "auto": {"max_distance": 5000000, "max_locations": 50}, "bicycle": {"max_distance": 500000, "max_locations": 50}, "pedestrian": {"max_distance": 250000, "max_locations": 50} }, "max_concurrent_reader_users": 100

重启服务使配置生效：

docker restart valhalla_service

5. 进阶应用与可视化

5.1 集成QGIS插件

在QGIS中搜索安装Valhalla Tools插件后：

1. 进入Web>Valhalla Tools>Settings
2. 设置API端点为http://你的服务器IP:8002
3. 在插件面板选择路径类型（驾车/步行/骑行）
4. 点击地图设置起点和终点

5.2 自定义前端集成

使用Leaflet等库可以快速构建前端界面。以下是关键API端点：

示例JavaScript调用：

fetch('http://localhost:8002/route', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ locations: [ {lat: 34.702485, lon: 135.495951}, {lat: 34.985849, lon: 135.758766} ], costing: 'auto' }) }) .then(res => res.json()) .then(data => console.log(data.trip.legs[0].summary));

5.3 监控与维护

建议使用Prometheus监控服务健康状态：

# docker-compose.yml示例 version: '3' services: valhalla: image: ghcr.io/valhalla/valhalla:latest ports: - "8002:8002" volumes: - ./valhalla_config:/custom_config - ./valhalla_tiles:/custom_files command: valhalla_service /custom_config/valhalla.json 1 deploy: resources: limits: cpus: '4' memory: 16G prometheus: image: prom/prometheus ports: - "9090:9090" volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml

配套的prometheus.yml配置：

scrape_configs: - job_name: 'valhalla' static_configs: - targets: ['valhalla:8002']

6. 常见问题排查手册

问题1：瓦片生成过程中断

• 检查valhalla_tiles目录权限：确保Docker有写入权限
• 查看系统日志：journalctl -xe
• 尝试减小处理区域：使用更小的OSM文件测试

问题2：服务启动后立即退出

• 检查端口冲突：netstat -tulnp | grep 8002
• 验证配置文件语法：jq empty < valhalla_config/valhalla.json
• 查看容器日志：docker logs valhalla_service

问题3：API返回400错误

• 确认坐标顺序是[lon, lat]（Valhalla使用[lat, lon]）
• 检查区域边界：确保请求点在OSM数据范围内
• 验证交通模式：costing参数必须是auto/bicycle/pedestrian之一

问题4：性能低下

• 优化配置文件：减少service_limits中的距离限制
• 考虑使用valhalla_tiles.tar而非目录结构
• 增加--concurrency参数（默认1，建议设为CPU核心数）

在阿里云上部署时，我发现Valhalla对NVMe磁盘的响应速度比普通SSD快40%。对于高并发场景，可以在Nginx后部署多个Valhalla实例，通过负载均衡分散压力。