# tilefuser-server

**Repository Path**: geoair/tilefuser-server

## Basic Information

- **Project Name**: tilefuser-server
- **Description**: 谷歌服务瓦片转换4490瓦片服务解决方案
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-17
- **Last Updated**: 2026-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 3857转4490, 谷歌网格转换, 4490瓦片服务, 谷歌瓦片服务

## README

# 瓦片融合服务 (TileFuser) 使用文档

## 1. 项目概述

### 1.1 简介
瓦片融合服务（TileFuser）是一个基于 Spring Boot 的 GIS 瓦片服务中间件，提供多种坐标系之间的瓦片转换、图层代理和预缓存功能。

### 1.2 核心功能
- **坐标系转换**：支持 EPSG:3857（Web Mercator）与 EPSG:4326（WGS84）之间的瓦片实时转换
- **图层代理**：支持网络（HTTP）和本地文件两种瓦片数据源
- **网络代理**：支持通过代理服务器访问外部瓦片服务
- **预缓存**：支持按地理范围和层级预生成瓦片，提升访问性能
- **多格式支持**：支持 PNG、JPG、WebP 等图片格式

### 1.3 转换示例
#### 示例一：3857 → 4490 坐标系转换
将 Web Mercator（EPSG:3857）网格的 OSM 地图转换为 CGCS2000（EPSG:4490）网格的地图。

![3857转4490示例](./doc/wm2gs84_example.png)

*图1：3857坐标系瓦片转换为4490坐标系效果图*

#### 示例二：3857 → 4490 坐标系转换
将 Web Mercator（EPSG:3857）网格的 arcgis 地图转换为 CGCS2000（EPSG:4490）网格的地图。

![4490转3857示例](./doc/arcgis.png)

*图2：3857坐标系瓦片转换为4490坐标系效果图*

 

### 1.3 技术架构
```
┌─────────────────────────────────────────────────────────────┐
│                      客户端请求                              │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   TileServiceTranController                  │
│              (REST API 接口层)                               │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   TileServiceTran                            │
│              (业务逻辑层 - 坐标系转换)                       │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│              GirFuserLayerTileGetterImpl                    │
│              (图层获取器实现)                                │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   数据库 (PostgreSQL)                        │
│               tgwc_layer_pxy_info 表                        │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│           TileGetterFactory → LayerTileGetter               │
│              (瓦片获取器工厂)                                │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│              FileTileCache (本地缓存)                       │
│              缓存目录: /path/to/cache/                       │
└─────────────────────────────────────────────────────────────┘
```

---

## 2. 环境要求

### 2.1 基础环境
| 组件 | 版本要求 |
|------|----------|
| JDK | 1.8+ |
| Spring Boot | 2.x |
| PostgreSQL | 9.6+ |
| Maven | 3.6+ |

### 2.2 依赖说明
- **PostgreSQL**：存储图层配置信息
- **Liquibase**：数据库版本管理
- **Hutool**：工具类库
- **Lombok**：代码简化

---

## 3. 快速开始

### 3.1 克隆项目
```bash
git clone https://gitee.com/geoair/tilefuser-server.git
cd tile-fuser
```

### 3.2 配置数据库
编辑 `application.yml`：
```yaml
spring:
  datasource:
    driverClassName: org.postgresql.Driver
    url: jdbc:postgresql://192.168.0.XXX:5432/your_database
    username: postgres
    password: your_password
    hikari:
      maximum-pool-size: 50
      minimum-idle: 5
```

### 3.3 配置缓存目录（可选）
```bash
# 方式一：JVM 参数
-DGTC_CACHE_DIR=/data/tile_cache

# 方式二：环境变量
export GTC_CACHE_DIR=/data/tile_cache
```

### 3.4 启动服务
```bash
mvn clean package
java -jar target/tile-fuser.jar
```

启动成功后看到：
```
========== 瓦片融合服务启动成功 ==========
服务端口: 26889
访问地址: http://localhost:26889/geoair/
瓦片融合缓存目录: /data/tile_cache/gwc_fuser/tile_cache/
```

---

## 4. 配置管理

### 4.1 图层配置

#### 4.1.1 插入图层配置
```sql
-- 示例：OpenStreetMap 图层（带代理）
INSERT INTO public.tgwc_layer_pxy_info (
    id,
    layer_name,
    type,
    path,
    enable_cache,
    use_web_pxy,
    web_pxy_host,
    web_pxy_port,
    origin_type,
    grid_srid,
    image_type
) VALUES (
    gen_random_uuid()::varchar,
    'osm',
    'web',
    'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
    'true',
    'true',
    '192.168.0.196',
    8887,
    'google',
    3857,
    'png'
);

-- 示例：本地瓦片图层
INSERT INTO public.tgwc_layer_pxy_info (
    id,
    layer_name,
    type,
    path,
    enable_cache,
    use_web_pxy,
    origin_type,
    grid_srid,
    image_type
) VALUES (
    gen_random_uuid()::varchar,
    'local_tiles',
    'local',
    '/data/tiles/{z}/{x}/{y}.png',
    'true',
    'false',
    'google',
    3857,
    'png'
);
```

#### 4.1.2 配置字段说明

| 字段 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| layer_name | varchar | ✅ | 图层唯一标识 | `osm` |
| type | varchar | ✅ | 数据源类型：`web`/`local` | `web` |
| path | varchar | ✅ | URL或本地路径模板 | `https://tile.osm.org/{z}/{x}/{y}.png` |
| enable_cache | varchar | ❌ | 是否启用缓存：`true`/`false` | `true` |
| use_web_pxy | varchar | ❌ | 是否使用代理：`true`/`false` | `true` |
| web_pxy_host | varchar | ❌ | 代理服务器地址 | `192.168.0.196` |
| web_pxy_port | int | ❌ | 代理服务器端口 | `8887` |
| origin_type | varchar | ❌ | 原点类型：`google`/`tms` | `google` |
| grid_srid | int | ❌ | 坐标系SRID，默认3857 | `3857` |
| image_type | varchar | ❌ | 图片格式，默认`png` | `png` |

### 4.2 服务配置
```yaml
server:
  port: 26889
  tomcat:
    uri-encoding: UTF-8
    max-threads: 1000
    min-spare-threads: 30

logging:
  level:
    root: INFO
    cn.geoair.map.tile.forge.fuser: DEBUG  # 开启调试日志
```

---

## 5. API 接口文档

### 5.1 3857 → 4326 瓦片转换

**接口描述**：将 Web Mercator 投影（EPSG:3857）的瓦片转换为 WGS84 经纬度投影（EPSG:4326）

**请求方式**：`GET`

**URL**：`/geoair/wm2gs84/{layerName}/{z}/{x}/{y}`

**路径参数**：

| 参数 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| layerName | String | ✅ | 图层名称（需在数据库中配置） | `osm` |
| z | Integer | ✅ | 缩放层级 | `10` |
| x | Integer | ✅ | 瓦片 X 坐标 | `256` |
| y | Integer | ✅ | 瓦片 Y 坐标 | `128` |

**查询参数**：

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| format | String | ❌ | `png` | 图片格式：`png`/`jpg`/`webp` |

**请求示例**：
```bash
# 获取 PNG 格式瓦片
curl "http://localhost:26889/geoair/wm2gs84/osm/10/256/128?format=png"

# 获取 JPG 格式瓦片
curl "http://localhost:26889/geoair/wm2gs84/osm/10/256/128?format=jpg"
```

**响应**：
- 成功：返回图片流（image/png、image/jpeg 等）
- 失败：返回 HTTP 错误状态码

---

### 5.2 4326 → 3857 瓦片转换

**接口描述**：将 WGS84 经纬度投影（EPSG:4326）的瓦片转换为 Web Mercator 投影（EPSG:3857）

**请求方式**：`GET`

**URL**：`/geoair/gs84ToWm/{layerName}/{z}/{x}/{y}`

**路径参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| layerName | String | ✅ | 图层名称 |
| z | Integer | ✅ | 缩放层级 |
| x | Integer | ✅ | 瓦片 X 坐标 |
| y | Integer | ✅ | 瓦片 Y 坐标 |

**查询参数**：

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| format | String | ❌ | `png` | 图片格式 |

**请求示例**：
```bash
curl "http://localhost:26889/geoair/gs84ToWm/china_map/10/256/128?format=png"
```

---

### 5.3 预缓存

**接口描述**：对指定区域和层级进行瓦片预生成，异步执行

**请求方式**：`GET`

**URL**：`/geoair/preCache`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| layerName | String | ✅ | 图层名称 | `osm` |
| wkt4326String | String | ✅ | WKT格式的地理范围（EPSG:4326） | `POLYGON((73.5 18.1, 135.1 18.1, 135.1 53.6, 73.5 53.6, 73.5 18.1))` |
| minZoom | int | ✅ | 最小缩放层级 | `5` |
| maxZoom | int | ✅ | 最大缩放层级 | `12` |

**请求示例**：
```bash
# 中国区域预缓存
curl "http://localhost:26889/geoair/preCache?layerName=osm&wkt4326String=POLYGON((73.5%2018.1,135.1%2018.1,135.1%2053.6,73.5%2053.6,73.5%2018.1))&minZoom=5&maxZoom=12"
```

**响应**：
```json
"预缓存任务已提交，正在后台执行"
```

**注意事项**：
- 大范围预缓存耗时较长，建议分批次执行
- 缓存文件保存在 `{GTC_CACHE_DIR}/gwc_fuser/tile_cache/` 目录
- 可通过日志查看缓存进度

---

## 6. 使用示例

### 6.1 前端调用示例

#### HTML + JavaScript
```html
<!DOCTYPE html>
<html>
<head>
    <title>瓦片服务测试</title>
    <style>
        #map {
            width: 800px;
            height: 600px;
            border: 1px solid #ccc;
        }
    </style>
</head>
<body>
    <h3>瓦片服务测试 - 3857转4326</h3>
    <div id="map"></div>
    <button onclick="loadTile()">加载瓦片</button>

    <script>
        function loadTile() {
            const layerName = 'osm';
            const z = 10;
            const x = 256;
            const y = 128;
            const format = 'png';
            
            // 构建URL
            const url = `http://localhost:26889/geoair/wm2gs84/${layerName}/${z}/${x}/${y}?format=${format}`;
            
            // 显示在页面上
            const img = document.createElement('img');
            img.src = url;
            img.style.width = '256px';
            img.style.height = '256px';
            
            const mapDiv = document.getElementById('map');
            mapDiv.innerHTML = '';
            mapDiv.appendChild(img);
            
            console.log('加载瓦片:', url);
        }
    </script>
</body>
</html>
```

#### Leaflet 集成
```javascript
// 自定义瓦片图层
const tileUrl = 'http://localhost:26889/geoair/wm2gs84/osm/{z}/{x}/{y}?format=png';

const customLayer = L.tileLayer(tileUrl, {
    maxZoom: 18,
    attribution: 'TileFuser Service'
});

// 添加到地图
const map = L.map('map').setView([39.9, 116.4], 10);
customLayer.addTo(map);
```

#### OpenLayers 集成
```javascript
import TileLayer from 'ol/layer/Tile.js';
import XYZ from 'ol/source/XYZ.js';

const tileLayer = new TileLayer({
    source: new XYZ({
        url: 'http://localhost:26889/geoair/wm2gs84/osm/{z}/{x}/{y}?format=png',
        crossOrigin: 'anonymous'
    })
});

const map = new Map({
    target: 'map',
    layers: [tileLayer],
    view: new View({
        center: [0, 0],
        zoom: 2
    })
});
```

### 6.2 后端集成示例

#### 获取图层配置
```java
@Autowired
private GirFuserLayerTileHelper layerTileHelper;

public void getLayerInfo() {
    PxyLayerInfo info = layerTileHelper.getPxyLayerInfo("osm");
    if (info != null) {
        System.out.println("图层名称: " + info.getLayerName());
        System.out.println("路径模板: " + info.getPath());
        System.out.println("启用缓存: " + info.getEnableCache());
    }
}
```

#### 获取瓦片数据
```java
@Autowired
private GirFuserLayerTileHelper layerTileHelper;

public byte[] getTile(String layerName, int z, int x, int y) {
    LayerTileGetter getter = layerTileHelper.getLayerTileGetter(layerName);
    if (getter == null) {
        throw new RuntimeException("图层不存在");
    }
    return getter.getTile(z, x, y);
}
```

---

## 7. 缓存管理

### 7.1 缓存目录结构
```
{GTC_CACHE_DIR}/gwc_fuser/tile_cache/
├── osm/                          # 图层名
│   ├── 3857/                     # 坐标系
│   │   ├── 5/                    # 缩放层级
│   │   │   ├── 16/               # X 目录
│   │   │   │   └── 32.png        # 瓦片文件
│   │   │   └── 17/
│   │   │       └── 32.png
│   │   └── 6/
│   └── 4326/
└── china_map/
    └── 3857/
        └── ...
```

### 7.2 查看缓存大小
```bash
# Linux/Mac
du -sh /data/tile_cache/gwc_fuser/tile_cache/

# 查看各图层缓存大小
du -sh /data/tile_cache/gwc_fuser/tile_cache/*
```

### 7.3 清理缓存
```bash
# 清理所有缓存
rm -rf /data/tile_cache/gwc_fuser/tile_cache/*

# 清理特定图层
rm -rf /data/tile_cache/gwc_fuser/tile_cache/osm/
```

---

## 8. 性能优化

### 8.1 数据库优化
```sql
-- 创建索引加速查询
CREATE INDEX idx_layer_name ON tgwc_layer_pxy_info(layer_name);

-- 查询分析
EXPLAIN ANALYZE SELECT * FROM tgwc_layer_pxy_info WHERE layer_name = 'osm';
```

### 8.2 缓存配置
```java
// 调整缓存线程池
@Bean
public ThreadPoolTaskExecutor taskExecutor() {
    ThreadPoolTaskExecutor pool = new ThreadPoolTaskExecutor();
    pool.setCorePoolSize(50);      // 核心线程数
    pool.setMaxPoolSize(500);      // 最大线程数
    pool.setQueueCapacity(1000);   // 队列容量
    return pool;
}
```

### 8.3 JVM 优化
```bash
# 增加内存
java -Xms2g -Xmx4g -XX:+UseG1GC -jar tile-fuser.jar

# 开启 GC 日志
java -Xloggc:gc.log -XX:+PrintGCDetails -jar tile-fuser.jar
```

---

## 9. 监控与日志

### 9.1 日志配置
```yaml
logging:
  level:
    root: INFO
    cn.geoair.map.tile.forge.fuser: DEBUG
    cn.geoair.gishubteam: DEBUG
  file:
    name: logs/tile-fuser.log
    max-size: 100MB
    max-history: 30
```

### 9.2 关键日志
```log
# 启动日志
2026-06-17 10:00:00.000 INFO  - 瓦片融合缓存目录: /data/tile_cache/gwc_fuser/tile_cache/
2026-06-17 10:00:00.000 INFO  - 瓦片融合器日志已开启

# 请求日志
2026-06-17 10:00:01.000 INFO  - 收到预缓存请求 - 图层: osm, 层级: 5-12

# 错误日志
2026-06-17 10:00:02.000 ERROR - 查询图层信息失败: unknown_layer
```

---

## 10. 故障排查

### 10.1 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 服务启动失败 | 数据库连接失败 | 检查数据库配置和网络连通性 |
| 404 Not Found | 图层不存在 | 检查数据库中是否有该图层配置 |
| 瓦片加载失败 | 路径模板错误 | 验证 path 字段中的占位符是否正确 |
| 缓存目录无权限 | 目录权限不足 | `chmod -R 755 /data/tile_cache` |
| 内存溢出 | 缓存过多 | 增加 JVM 内存或定期清理缓存 |

### 10.2 调试技巧

#### 查看数据库配置
```sql
SELECT * FROM tgwc_layer_pxy_info WHERE layer_name = 'osm';
```

#### 测试图层可用性
```bash
# 直接请求原始瓦片服务
curl "https://tile.openstreetmap.org/10/256/128.png"

# 对比转换后的瓦片
curl "http://localhost:26889/geoair/wm2gs84/osm/10/256/128?format=png"
```

#### 查看缓存目录
```bash
# 查看是否生成缓存文件
find /data/tile_cache -name "*.png" | head -10
```

---

## 11. 最佳实践

### 11.1 图层命名规范
- 使用小写字母和下划线：`world_map`、`china_terrain`
- 避免特殊字符和空格
- 建议包含数据源和类型信息：`osm_streets`、`google_satellite`

### 11.2 缓存策略
- **热数据**：高频访问区域建议预缓存全部层级
- **冷数据**：按需缓存，减少存储占用
- **定期清理**：设置缓存过期策略，避免磁盘满
 
 
## 12. 附录

### 12.1 常见坐标系
| 名称 | SRID | 说明 |
|------|------|------|
| Web Mercator | 3857 | Google Maps、OpenStreetMap 使用 |
| WGS84 | 4326 | GPS 经纬度坐标系 |
| CGCS2000 | 4490 | 中国大地坐标系 |

### 12.2 WKT 格式示例
```sql
-- 中国区域
POLYGON((73.5 18.1, 135.1 18.1, 135.1 53.6, 73.5 53.6, 73.5 18.1))

-- 矩形区域
POLYGON((116.3 39.8, 116.5 39.8, 116.5 40.0, 116.3 40.0, 116.3 39.8))

-- 圆形（近似）
POLYGON((120 30, 120.1 30.05, 120.05 30.1, 119.95 30.1, 119.9 30.05, 120 30))
```

### 12.3 工具推荐
- **PostgreSQL 客户端**：DBeaver、pgAdmin
- **瓦片查看器**：QGIS、MapTiler
- **性能测试**：JMeter、Apache Bench

---

## 13. 更新日志

| 版本 | 日期 | 更新内容 | 作者 |
|------|------|----------|------|
| v1.0 | 2026/06/17 | 初始版本 | zfj |

---

## 14. 技术支持

- **作者**：zfj
- **邮箱**：1159856928@qq.com
- **创建日期**：2026/06/17
- **模块**：TileFuser WCS