hsldevcom/pelias-data-container

Pelias 数据容器镜像文档

镜像概述

Pelias数据容器镜像是Pelias开源地理编码服务的官方数据存储组件，专为存储和管理Pelias服务运行所需的各类地理空间数据而设计。该镜像作为Pelias架构中的数据层，提供稳定的数据存储环境，支持地址数据、POI（兴趣点）数据、行政区划数据等Pelias核心数据的持久化存储，确保Pelias服务在启动、运行及重启过程中能够高效访问所需数据。

核心功能与特性

1. 数据持久化存储

• 通过Docker卷（Volume）挂载机制，确保数据独立于容器生命周期，容器重启或重建后数据不丢失。
• 支持数据长期存储，满足生产环境中数据持久化需求。

2. 数据兼容性

• 兼容Pelias官方数据导入工具（如pelias/importer）生成的标准数据格式，无需额外格式转换。
• 支持多种地理数据类型，包括但不限于OSM（OpenStreetMap）数据、Gazetteer数据、TIGER/Line数据等。

3. 轻量级与高效访问

• 优化的文件系统结构，针对地理空间数据的读取模式进行调整，减少I/O开销。
• 精简镜像体积，降低资源占用，适合在有限资源环境中部署。

4. 版本化兼容

• 与Pelias服务的各稳定版本保持兼容，可通过指定标签（Tag）选择匹配版本的镜像。

使用场景与适用范围

适用场景

• Pelias本地部署：在开发、测试或生产环境中部署Pelias服务时，作为数据存储组件使用。
• 数据备份与迁移：通过数据卷快照实现Pelias数据的备份，或在不同环境间迁移数据。
• 多节点集群：在Pelias多节点集群中，通过共享数据卷实现多服务实例的数据共享访问。

适用范围

• 所有基于Pelias的地理编码应用，包括地址解析、反向地理编码、POI搜索、行政区划查询等服务。
• 需要稳定存储地理空间数据的Pelias衍生项目或二次开发场景。

使用方法与配置说明

前提条件

• 已安装Docker Engine（20.10+版本推荐）。
• 已创建用于持久化存储的Docker卷（建议提前创建，避免自动创建卷的权限问题）。

基本使用（Docker Run）

1. 创建数据卷（推荐）

bash
docker volume create pelias_data_volume

2. 启动数据容器

bash
docker run -d \
  --name pelias-data \
  --volume pelias_data_volume:/data \
  docker.xuanyuan.run/pelias/data-container:latest

• --name pelias-data：指定容器名称，便于后续操作。
• --volume pelias_data_volume:/data：将数据卷挂载到容器内的/data目录（Pelias数据存储路径）。
• pelias/data-container:latest：使用最新版本镜像，生产环境建议指定具体版本标签（如v1.8.0）。

与Pelias服务配合使用（Docker Compose）

典型的Pelias服务栈包含数据容器、API服务、导入工具等组件，以下是docker-compose.yml示例：

yaml
version: '3.8'

volumes:
  pelias_data:  # 定义数据卷，用于持久化存储Pelias数据

services:
  # Pelias数据容器
  pelias-data:
    image: docker.xuanyuan.run/pelias/data-container:latest
    volumes:
      - pelias_data:/data
    restart: unless-stopped  # 确保容器稳定运行

  # Pelias数据导入工具（示例）
  pelias-importer:
    image: docker.xuanyuan.run/pelias/importer:latest
    volumes:
      - pelias_data:/data  # 共享数据卷，将数据导入到数据容器中
    environment:
      - DATA_DIR=/data  # 指定数据存储路径
    command: ["import", "openstreetmap"]  # 导入OSM数据示例

  # Pelias API服务（示例）
  pelias-api:
    image: docker.xuanyuan.run/pelias/api:latest
    volumes:
      - pelias_data:/data  # 从数据容器读取数据
    ports:
      - "4000:4000"  # API服务端口
    depends_on:
      - pelias-data  # 依赖数据容器启动
    restart: unless-stopped

数据导入方法

Pelias数据通常通过专用导入工具（如pelias/importer）导入到数据容器中，步骤如下：

1. 确保数据容器已启动且数据卷已挂载。
2. 运行Pelias导入工具容器，指定数据卷和导入命令，例如导入OSM数据：

   bash
   docker run --rm \
     --volume pelias_data_volume:/data \
     docker.xuanyuan.run/pelias/importer:latest \
     import openstreetmap --file /path/to/local/osm/file.osm.pbf
   

3. 导入完成后，数据将存储在数据容器的/data目录下，Pelias API服务可直接访问。

数据备份与恢复

备份数据卷

bash
# 创建数据卷快照
docker run --rm -v pelias_data_volume:/source -v $(pwd):/backup docker.xuanyuan.run/alpine tar -czf /backup/pelias_data_backup.tar.gz -C /source .

恢复数据卷

bash
# 从快照恢复数据
docker run --rm -v pelias_data_volume:/target -v $(pwd):/backup docker.xuanyuan.run/alpine sh -c "rm -rf /target/* && tar -xzf /backup/pelias_data_backup.tar.gz -C /target"

注意事项

• 数据容器本身不提供数据导入功能，需配合Pelias导入工具使用。
• 生产环境中建议定期备份数据卷，避免数据丢失。
• 选择与Pelias服务版本匹配的镜像标签，确保兼容性。