# tileserverfull

**Repository Path**: cubic8/tileserverfull

## Basic Information

- **Project Name**: tileserverfull
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-15
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PostGIS MVT 瓦片服务器

基于 Node.js + PostGIS 的高性能矢量瓦片（MVT）和 PNG 瓦片服务器，支持服务端栅格化缓存。

## 功能特性

- 支持 MVT（Mapbox Vector Tile）矢量瓦片输出
- 支持 PNG 栅格瓦片输出（服务端渲染）
- 自动 MVT 缓存机制，减少数据库查询
- 支持任意空间参考系统（SRID），如 CGCS2000 (EPSG:4490)
- 支持 PostgreSQL 大小写敏感的表名和字段名
- 可配置的属性字段输出
- Docker Compose 一键部署

## 技术栈

| 组件 | 版本 |
|------|------|
| Node.js | 18 |
| PostgreSQL | 15 |
| PostGIS | 3.3 |
| Express | 4.18 |

## 快速开始

### 环境要求

- Docker 和 Docker Compose
- 已有 PostGIS 数据库（包含 geometry 字段的数据表）

### 配置

编辑 `.env` 或 `.env_ex` 文件，配置数据库连接参数：

```bash
# 数据库连接配置
PG_HOST=172.19.99.32        # PostgreSQL 主机地址
PG_PORT=25432               # PostgreSQL 端口
PG_DATABASE=dltb            # 数据库名称
PG_USER=sull                # 数据库用户
PG_PASSWORD=sulele          # 数据库密码

# 服务配置
PORT=3000                   # 服务端口
TILE_SIZE=512               # 瓦片像素大小

# 数据表配置
PG_TABLE_NAME=LTBSample     # 数据表名（区分大小写）
PG_GEOMETRY_COLUMN=smgeometry  # Geometry 字段名（区分大小写）
PG_ATTR_COLUMNS=smid,dlbm,dlmc,tbmj  # 要输出的属性字段，使用逗号分隔，或使用 * 输出所有字段
PG_SRID=4490                # 数据的空间参考系统（SRID），3857 则不需要坐标转换
```

### 启动服务

#### 方法一：使用 Docker Compose（推荐）

```bash
# Linux/Mac
./start.sh

# Windows
start.bat
```

或直接运行：

```bash
docker-compose up -d --build
```

#### 方法二：本地运行

```bash
# 安装依赖
npm install

# 复制环境变量文件
cp .env_ex .env

# 启动服务
node server.js
```

## API 接口

### MVT 矢量瓦片

```
GET /mvt/{z}/{x}/{y}
```

**响应：**
- Content-Type: `application/x-protobuf`
- X-Cache: `HIT`（缓存命中）或 `MISS`（从数据库获取）

**示例：**
```bash
curl http://localhost:3000/mvt/12/3300/1782
```

### PNG 栅格瓦片（支持自定义样式）

```
GET /tile/{z}/{x}/{y}.png[?style=STYLE]
```

**响应：**
- Content-Type: `image/png`
- Cache-Control: `public, max-age=86400`

**样式参数：**

1. **简单参数格式** - 直接指定颜色：
```bash
# 红色填充，黑色描边
curl "http://localhost:3000/tile/12/3300/1782.png?fill=rgba(255,0,0,0.5)&stroke=#000000&width=2&background=#ffffff"
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `fill` | 填充颜色 | rgba(59, 178, 208, 0.3) |
| `stroke` | 描边颜色 | #3bb2d0 |
| `width` | 描边宽度 | 1.5 |
| `background` | 背景颜色 | #f5f5f5 |

2. **Mapbox Style JSON 格式** - 使用标准 Mapbox Style：
```bash
curl "http://localhost:3000/tile/12/3300/1782.png?style=%7B%22layers%22:%5B%7B%22type%22:%22fill%22,%22paint%22:%7B%22fill-color%22:%22%23ff0000%22,%22fill-opacity%22:0.5%7D%7D,%7B%22type%22:%22line%22,%22paint%22:%7B%22line-color%22:%22%23000000%22,%22line-width%22:2%7D%7D%5D%7D"
```

Mapbox Style 格式（URL Encode 后作为 `style` 参数）：
```json
{
  "layers": [
    {
      "type": "fill",
      "paint": {
        "fill-color": "#ff0000",
        "fill-opacity": 0.5
      }
    },
    {
      "type": "line",
      "paint": {
        "line-color": "#000000",
        "line-width": 2
      }
    }
  ]
}
```

3. **样式文件参数** - 使用预定义的样式文件：
```bash
# 使用地类图斑彩色样式
curl "http://localhost:3000/tile/12/3300/1782.png?styleFile=dltb-style.json"

# 使用纯色填充样式
curl "http://localhost:3000/tile/12/3300/1782.png?styleFile=dltb-solid.json"

# 使用 Sprite 图案样式
curl "http://localhost:3000/tile/12/3300/1782.png?styleFile=dltb-sprite.json"
```

### 属性查询接口

```
GET /api/query?lng={lng}&lat={lat}&zoom={z}&fields={field1,field2,...}
```

**查询参数：**
| 参数 | 说明 | 必填 |
|------|------|------|
| `lng` | 经度 | 是 |
| `lat` | 纬度 | 是 |
| `zoom` | 缩放级别 | 否（默认 12） |
| `fields` | 返回字段列表，逗号分隔 | 否（默认返回所有字段） |

**响应：**
```json
{
  "success": true,
  "count": 10,
  "features": [
    {
      "smid": 2,
      "dlbm": "013",
      "zldwdm": "450902004203",
      "zldwmc": "罗竹村委会"
    }
  ]
}
```

**示例：**
```bash
# 查询指定位置的地块属性（返回所有字段）
curl "http://localhost:3000/api/query?lng=110.1&lat=22.73&zoom=12"

# 只返回指定字段
curl "http://localhost:3000/api/query?lng=110.1&lat=22.73&zoom=12&fields=smid,dlbm,zldwdm,zldwmc"
```

### 健康检查

```
GET /health
```

**响应：** `ok`

## 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 | 必填 |
|--------|------|--------|------|
| `PG_HOST` | PostgreSQL 主机地址 | - | 是 |
| `PG_PORT` | PostgreSQL 端口 | 5432 | 否 |
| `PG_DATABASE` | 数据库名称 | - | 是 |
| `PG_USER` | 数据库用户 | - | 是 |
| `PG_PASSWORD` | 数据库密码 | - | 是 |
| `PORT` | 服务端口 | 3000 | 否 |
| `TILE_SIZE` | 瓦片像素大小 | 512 | 否 |
| `PG_TABLE_NAME` | 数据表名（区分大小写） | supermap | 否 |
| `PG_GEOMETRY_COLUMN` | Geometry 字段名（区分大小写） | geometry | 否 |
| `PG_ATTR_COLUMNS` | 属性字段列表，逗号分隔 | * | 否 |
| `PG_SRID` | 数据的空间参考系统 | 3857 | 否 |

### 瓦片坐标系

本服务器使用 Web 墨卡托（EPSG:3857）瓦片网格系统。如果数据使用其他坐标系（如 CGCS2000/EPSG:4490），系统会自动进行坐标转换。

## 缓存机制

- MVT 瓦片首次请求时从数据库获取并保存到 `mvt_cache/` 目录
- 后续请求直接读取缓存文件，大幅提升响应速度
- 缓存目录结构：`mvt_cache/{z}/{x}/{y}.mvt`

## 使用示例

### 在 MapLibre GL JS 中使用

```html
<script src="https://unpkg.com/maplibre-gl/dist/maplibre-gl.js"></script>
<link href="https://unpkg.com/maplibre-gl/dist/maplibre-gl.css" rel="stylesheet" />

<div id="map" style="width: 100%; height: 100vh;"></div>

<script>
const map = new maplibregl.Map({
  container: 'map',
  style: {
    version: 8,
    sources: {
      mvt: {
        type: 'vector',
        tiles: ['http://localhost:3000/mvt/{z}/{x}/{y}'],
        minzoom: 0,
        maxzoom: 18
      }
    },
    layers: [{
      id: 'mvt-layer',
      type: 'fill',
      source: 'mvt',
      'source-layer': 'LTBSample',
      paint: {
        'fill-color': '#3bb2d0',
        'fill-opacity': 0.3
      }
    }]
  }
});
</script>
```

### 在 OpenLayers 中使用

```javascript
import { Map, View } from 'ol';
import { XYZ } from 'ol/source';
import { Tile as TileLayer } from 'ol/layer';

// MVT 矢量瓦片
const mvtSource = new XYZ({
  url: 'http://localhost:3000/mvt/{z}/{x}/{y}',
  tileLoadFunction: function(tile, src) {
    fetch(src).then(r => r.arrayBuffer()).then(data => {
      tile.getImage().src = URL.createObjectURL(new Blob([data]));
    });
  }
});

// PNG 栅格瓦片
const pngSource = new XYZ({
  url: 'http://localhost:3000/tile/{z}/{x}/{y}.png'
});

const map = new Map({
  target: 'map',
  layers: [
    new TileLayer({ source: pngSource })
  ],
  view: new View({
    center: [12280000, 3280000],
    zoom: 12,
    projection: 'EPSG:3857'
  })
});
```

## 常见问题

### Q: MVT 返回空数据（0 字节）

1. 检查瓦片坐标是否正确（数据所在区域）
2. 检查 `PG_SRID` 配置是否与数据一致
3. 检查表名和字段名的大小写是否正确

### Q: PNG 瓦片显示空白

1. 检查 MVT 是否有数据返回
2. 确认 geometry 字段包含有效几何数据
3. 检查颜色配置是否透明度过高

### Q: 如何自定义瓦片样式

**方法一：URL 参数（推荐）**
```bash
# 红色填充
curl "http://localhost:3000/tile/12/3300/1782.png?fill=rgba(255,0,0,0.8)&stroke=#ff0000"

# 绿色填充，Mapbox Style
curl "http://localhost:3000/tile/12/3300/1782.png?style=%7B%22layers%22:%5B%7B%22type%22:%22fill%22,%22paint%22:%7B%22fill-color%22:%22%2300ff00%22%7D%7D%5D%7D"
```

**方法二：修改默认配置**

编辑 `server.js` 中的 `DEFAULT_COLORS` 配置：

```javascript
const DEFAULT_COLORS = {
  fill: 'rgba(59, 178, 208, 0.3)',    // 填充颜色
  stroke: '#3bb2d0',                   // 描边颜色
  background: '#f5f5f5'                // 背景颜色
};
```

## 数据库表要求

数据表应包含：
- 一个 geometry 类型的字段（支持任意 SRID）
- 可选的属性字段（ID、名称、类型等）

示例表结构：
```sql
CREATE TABLE "LTBSample" (
  "smid" INTEGER PRIMARY KEY,
  "dlbm" VARCHAR(10),
  "dlmc" VARCHAR(100),
  "tbmj" DOUBLE PRECISION,
  "smgeometry" GEOMETRY(POLYGON, 4490)
);
```

## 停止服务

```bash
# Docker Compose
docker-compose down

# 或使用脚本
./stop.sh      # Linux/Mac
stop.bat       # Windows
```

## License

MIT