# osm-example

**Repository Path**: sobercoding/osm-example

## Basic Information

- **Project Name**: osm-example
- **Description**: 基于OSM的私有化地图部署方案(Dokcer方式)，支持地图渲染、地理/逆地理解析、周边要素特征搜索
- **Primary Language**: Docker
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-01-28
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OSM Server Docker 部署指南

本项目基于 Docker Compose 部署一套完整的 OpenStreetMap 服务栈，包含以下组件：
1.  **Nominatim**: 地理编码与逆地理编码服务 (端口 `8081`)
2.  **Tile Server**: 栅格瓦片地图服务 (端口 `8080`)
3.  **Overpass API**: OSM 数据查询服务 (端口 `8082`)
4.  **Nginx 网关 + 前端**：统一入口（默认端口 `8088`）

> 说明：本仓库的 `docker-compose.yml` 位于 `docker/` 目录。下面所有 `docker compose ...` 命令默认在 `docker/` 目录执行。
```bash
cd docker
```
---

## 1. 准备工作

在启动之前，请确保宿主机上已准备好 OSM 数据文件（`.osm.pbf`）。

### 1.1 目录结构建议
建议在宿主机建立如下目录结构（示例路径 `/e/WSL/app/osm/`）：
```text
/e/WSL/app/osm/
├── data/
    ├── jiangsu-260122.osm.pbf  <-- 你的 PBF 数据文件放这里 文件可以到 https://download.geofabrik.de/ 下载
    ├── postgresql/             <-- Nominatim 数据库 (自动生成)
    ├── osm_data/               <-- Nominatim 数据目录 (自动生成)
    ├── tile_data/              <-- Tile Server 瓦片库 (自动生成)
    └── overpass/               <-- Overpass 数据库 (自动生成)
```
> **注意**：本项目已禁用 Nominatim 的 `flatnode` 模式，以节省磁盘空间（对于省级/国家级数据不需要）。如果你之前运行过，请删除宿主机上的 `flatnode` 目录或文件。

---

## 2. 配置说明 (docker/.env)

[docker/.env](docker/.env) 文件包含了所有关键配置（位于 `docker/` 目录）。首次使用前请务必检查以下项：

1.  **数据文件设置**：
    *   `OSM_PBF_DIR_HOST`: 存放 PBF 文件的**宿主机目录** (例如 `/e/WSL/app/osm/data`)。
    *   `OSM_PBF_FILENAME`: **PBF 文件名** (例如 `jiangsu-260122.osm.pbf`)。
    *   **注意**：请确保 `${OSM_PBF_DIR_HOST}/${OSM_PBF_FILENAME}` 路径下真实存在该文件。

2.  **数据持久化路径**：
    *   根据实际情况修改 `NOMINATIM_PG_HOST`、`TILE_DATA_HOST` 等路径，确保宿主机磁盘空间充足。

3.  **服务端口**：
    *   如果端口冲突，可修改 `NOMINATIM_PORT`、`TILE_SERVER_PORT` 等变量。

---

## 3. 首次启动 (初始化)

由于 Nominatim、Tile Server 和 Overpass 都需要从 PBF 文件导入数据，首次启动分为**导入阶段**和**运行阶段**。

### 第一步：导入 Tile Server 数据 (耗时)
运行以下命令进行瓦片数据导入：
```bash
docker compose --profile init run --rm tile-import
```
> **注意**：此过程可能需要较长时间，取决于 PBF 文件大小。

### 第二步：初始化 Overpass API (耗时)
运行以下命令初始化 Overpass 数据库：
```bash
docker compose --profile init up overpass-init
```
待日志显示初始化完成后（容器可能会自动退出，或显示 Ready），按 `Ctrl+C` 停止或直接移除该容器：
```bash
docker compose rm -f overpass-init
```

### 第三步：启动所有服务 (包含 Nominatim 初始化)
```bash
docker compose up -d
```
*   **Nominatim 初始化**：Nominatim 容器在检测到数据库为空时，会自动开始导入 PBF 数据。
    *   可以通过 `docker logs -f nominatim` 查看导入进度。
    *   导入完成前，服务端口可能无法访问或返回错误。
*   **Tile Server & Overpass**：这两个服务会直接使用前两步生成的数据启动。

---

## 4. 日常运维

### 启动与停止
*   **后台启动所有服务**：
    ```bash
    docker compose up -d
    ```
*   **停止所有服务**：
    ```bash
    docker compose down
    ```
*   **重启特定服务**：
    ```bash
    docker compose restart tile-server
    ```

### 查看日志
```bash
docker compose logs -f nominatim
docker compose logs -f tile-server
docker compose logs -f overpass-api
```

---

## 5. 数据更新 (更新 PBF)

当需要更新地图数据（更换新的 PBF 文件）时，需要重新导入数据。

**警告：以下操作会清空旧数据！**

### 1. 更新配置
1.  将新的 PBF 文件放入 `OSM_PBF_DIR_HOST` 目录。
2.  修改 `.env` 中的 `OSM_PBF_FILENAME` 为新文件名。

### 2. 清理旧数据 (宿主机)
为了确保数据一致性，建议手动清空各服务的持久化目录内容（保留目录本身）：
*   清空 `NOMINATIM_PG_HOST` 目录内容
*   清空 `NOMINATIM_OSM_DATA_HOST` 目录内容 (除了新的 PBF 文件)
*   清空 `TILE_DATA_HOST` 目录内容
*   清空 `OVERPASS_DB_HOST` 目录内容

### 3. 重新执行初始化
参考 **“3. 首次启动”** 章节：
1.  运行 `tile-import`
2.  运行 `overpass-init`
3.  运行 `docker compose up -d` (触发 Nominatim 重新导入)

---

## 6. 前端与 Nginx 网关（统一入口）

### 6.1 统一入口与路由约定

项目新增 Nginx 作为统一入口，负责：
*   托管 Vue3 前端静态资源（SPA）
*   反向代理后端 API，并进行 apikey 访问控制
*   反向代理瓦片服务，并进行限流防护
*   统一开启 CORS（便于本地前端用 Vite 跨域联调）

默认路由：
*   前端页面：`http://localhost:${NGINX_PORT}/`
*   瓦片服务：`http://localhost:${NGINX_PORT}/tiles/{z}/{x}/{y}.png`
*   Nominatim：`http://localhost:${NGINX_PORT}/api/nominatim/*`
*   Overpass：`http://localhost:${NGINX_PORT}/api/overpass/*`

### 6.2 apikey 访问控制（/api/*）

Nginx 对所有 `/api/*` 路由强制校验请求头 `apikey`，未携带或无效时返回 `401`。

在 [docker/.env](docker/.env) 中配置：
*   `OSM_API_KEY`：访问密钥

示例：
```bash
curl -i "http://localhost:8088/api/nominatim/search?q=%E5%8D%97%E4%BA%AC&format=jsonv2" \
  -H "apikey: change-me"
```

### 6.3 瓦片防盗链与限流（/tiles/*）
> 暂未开相关配置和nginx.conf已经注释

由于瓦片图片请求无法可靠携带自定义请求头（例如 Leaflet 的 `<img>` 请求），本项目 **不对 `/tiles/*` 强制 apikey**，主要做：
*   **按 IP 限流**：降低爬虫高频抓取风险
    *   超限时返回 `429`（可通过 `TILE_RATE`/`TILE_BURST` 调整阈值）

### 6.4 构建与部署模式

*   **默认模式（nginx 服务）**：使用官方 Nginx 镜像，通过挂载 `frontend/dist` 与 Nginx 配置文件启动（适合本地快速迭代与验证）。首次启动前需要先构建前端：
    ```bash
    cd frontend
    npm ci
    npm run build
    cd ../docker
    docker compose up -d
    ```

前端地图右下角的版权标识为 **构建时配置**（build 后不可变更），可在构建前设置以下环境变量（Vite 读取 `VITE_` 前缀变量）：

*   `VITE_SHOW_MAP_ATTRIBUTION`：是否显示 attribution
*   `VITE_SHOW_LEAFLET_PREFIX`：是否显示 Leaflet 前缀
*   `VITE_MAP_ATTRIBUTION_HTML`：地图 attribution（HTML 字符串）

示例（PowerShell）：
```powershell
$env:VITE_SHOW_MAP_ATTRIBUTION='true'
$env:VITE_SHOW_LEAFLET_PREFIX='false'
$env:VITE_MAP_ATTRIBUTION_HTML='&copy; OpenStreetMap contributors'
npm run build
```
### 6.5 本地运行前端进行调试（Vite）

如果你希望用 `npm run dev` 启动前端（默认 `http://localhost:5173/`），请注意：
*   **后端默认请求地址会跟随当前页面 origin**，也就是默认指向 `5173`（这不是你想要的）
*   解决方式是配置前端的 **后端基础域名**（例如指向 Nginx 的 `http://localhost:8088`）

配置方式：
*   打开页面后，在左侧面板填写“后端地址”，例如 `http://localhost:8088`（会自动保存到 localStorage）
*   如需允许多个来源跨域访问，请在 [docker/.env](docker/.env) 配置 `CORS_ALLOW_ORIGINS`（逗号分隔；可写完整 Origin 或简写 host:port；支持 `*`）

启动示例：
```bash
cd frontend
npm ci
npm run dev
```

前端源码位于 `frontend/`，可单独构建：
```bash
cd frontend
npm ci
npm run build
```