项目地址:
- STAC 规范:https://github.com/radiantearth/stac-spec(STAC API 规范:https://github.com/radiantearth/stac-api-spec)
- stac-fastapi:https://github.com/stac-utils/stac-fastapi(PostgreSQL 后端 https://github.com/stac-utils/stac-fastapi-pgstac)
- pgstac:https://github.com/stac-utils/pgstac
- COG 规范:https://github.com/cogeotiff/cog-spec;rio-cogeo:https://github.com/cogeotiff/rio-cogeo
- TiTiler:https://github.com/developmentseed/titiler
官方文档: https://stacspec.org/ / https://stac-utils.github.io/stac-fastapi/ / https://cogeotiff.github.io/rio-cogeo/ / https://developmentseed.org/titiler/
最新版本: STAC 1.1.0(2024-09)、STAC API 1.0.0;stac-fastapi 7.1.1、stac-fastapi-pgstac 7.2.1、pgstac v0.10.1;rio-cogeo 7.0.4、cogeo-mosaic 9.2.0;titiler.core / titiler.application 2.4.0、titiler-pgstac 3.2.0;pystac 1.16.0、pystac-client 0.9.1(截至 2026-11,逐个实测 PyPI 与 GitHub Releases、TiTiler Releases)
许可证: STAC 规范 Apache-2.0;stac-fastapi / pgstac / TiTiler / rio-cogeo / pystac 均 MIT
概述
这条链路解决的是「影像不下载、按需出图」:原始影像转成 COG(云优化 GeoTIFF,带内部分块与金字塔,支持 HTTP Range 随机读)放到对象存储,用 STAC 元数据把资产编目成可检索的条目,再交给 TiTiler 按瓦片请求动态读窗口、重采样、配色并输出 PNG/JPEG。三者各自独立,组合起来才能做到入库即服务。
- STAC:Item/Collection/Catalog 三层 JSON 元数据模型,统一描述时空范围与资产链接,跨厂商可交换
- COG:内部按 512×512 分块、带 overview 金字塔、头部元数据在前,服务端只需几次 Range 请求就能取到任意窗口
- stac-fastapi + pgstac:STAC API 的 Python 实现,pgstac 把 JSONB 条目与空间索引放进 PostGIS,支持 CQL2 过滤与分页
- TiTiler:基于 FastAPI + rio-tiler 的动态切片服务,
/cog直接对单个 COG 出图,/stac对 STAC Item 的资产出图,/mosaicjson把多景拼成虚拟镶嵌 - 零预处理出图:换波段组合、拉伸方式、色带、重采样都通过 URL 查询参数完成,不用重跑切片任务
- 标准接口:OGC Tiles / WMTS 兼容端点,可直接作为 OpenLayers、MapLibre、Leaflet 的瓦片源
与相邻技术的差异:传统方案是 GeoServer + ImageMosaic 预先切片,改样式要重切片;本方案把「切片」推迟到请求时,样式灵活但依赖对象存储的 Range 性能与 CDN。
环境准备
Python 依赖
本链路是纯 Python 生态,要求 Python >= 3.11(stac-fastapi、rio-cogeo、TiTiler 2.x 均要求 3.11+)。
python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
# .venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install "rio-cogeo==7.0.4" "pystac==1.16.0" "pystac-client==0.9.1"
python -m pip install "stac-fastapi.api==7.1.1" "stac-fastapi.types==7.1.1" \
"stac-fastapi.extensions==7.1.1" "stac-fastapi-pgstac==7.2.1" \
"titiler.application==2.4.0" uvicorn
注意: 不要
pip install titiler。TiTiler 在 2025 年末已停止维护该元包(PyPI 上停留在 0.25.0),必须按命名空间安装titiler.core、titiler.application等子包(官方说明)。
COG 生成需要 GDAL
rio-cogeo 依赖 rasterio 与系统 GDAL 库:
# Ubuntu / Debian
sudo apt-get install -y gdal-bin libgdal-dev
# macOS
brew install gdal
# Conda(推荐,自动解决 C 库版本)
conda install -c conda-forge gdal rio-cogeo
服务端组件
# 只用 TiTiler 的官方镜像(COG/STAC/MosaicJSON 端点齐全)
docker run --rm -p 8000:8000 ghcr.io/developmentseed/titiler:latest \
uvicorn titiler.application.main:app --host 0.0.0.0 --port 8000
# STAC API 需要 PostgreSQL + PostGIS + pgstac
docker run --rm -p 5439:5432 -e POSTGRES_USER=username \
-e POSTGRES_PASSWORD=password -e POSTGRES_DB=postgis postgis/postgis:16-3.4
验证
rio cogeo --version # 应显示 7.0.4
python -c "import stac_fastapi.api, titiler.core; print('ok')"
curl -s http://localhost:8000/ | head -c 200 # TiTiler 落地页 JSON
curl -s http://localhost:8000/api.html -o /dev/null -w '%{http_code}\n' # OpenAPI 文档
核心概念与命令
COG:为什么它能按需出图
普通 GeoTIFF 的行按整幅宽存储,读一个小窗口也要下载大段数据。COG 做了三件事:
| 特性 | 作用 |
|---|---|
| 内部 tile(默认 512×512) | 任意窗口只需读少数几个 tile |
| 内部 overview 金字塔 | 缩小时直接读低分辨率层,不用全量重采样 |
| 头部元数据前置 | 客户端读前几百字节即可知道尺寸、分块、概览信息 |
因此服务端只需 Range: bytes=... 请求几次,就能取出渲染一片瓦片所需的数据——这是 TiTiler 能做到「不落盘、不预切」的前提。
rio-cogeo:生成与校验
# 生成 COG(deflate 压缩,默认 512 分块,自动建 overview)
rio cogeo create input.tif output_cog.tif
# 常用选项
rio cogeo create input.tif output_cog.tif \
--cog-profile deflate \ # deflate | zstd | lzw | jpeg | webp
--overview-resampling bilinear \ # 建 overview 用的重采样算法(默认 nearest)
--overview-level 6 \ # 从第 6 级开始建 overview;省略则自动选到最小 overview 小于 blocksize
--blocksize 512 \ # 覆盖 profile 的内部 tile 尺寸
--nodata 0 # 显式声明 nodata
# 校验是否符合 COG 规范
rio cogeo validate output_cog.tif
# 查看栅格与 COG 结构信息
rio cogeo info output_cog.tif
validate 通过是上云前的硬门槛;报错会指出缺失 overview、分块顺序不合法或未按 tile 组织。注意 --overview-level 是从第几级开始建 overview,不是"建几级金字塔";省略时 rio-cogeo 自动建到最小 overview 小于内部 blocksize 为止。
STAC:元数据模型
三层模型,逐层收窄:
Catalog(目录,可嵌套)
└── Collection(数据集,定义时空范围与许可)
└── Item(单景,一个 datetime + 几何 + assets)
Item 的关键字段是 id、bbox、geometry、properties.datetime,以及 assets——资产用 href 指向对象存储里的 COG:
{
"type": "Feature",
"stac_version": "1.1.0",
"id": "S2B_32TMT_20260101",
"bbox": [116.1, 39.7, 116.6, 40.1],
"geometry": { "type": "Polygon", "coordinates": [[]] },
"properties": { "datetime": "2026-01-01T03:20:00Z", "eo:cloud_cover": 3.2 },
"assets": {
"visual": {
"href": "s3://bucket/cogs/S2B_32TMT_20260101.tif",
"type": "image/tiff; application=geotiff; profile=cloud-optimized",
"roles": ["data"]
}
},
"links": []
}
用 pystac 构造与校验,避免手写 JSON 出错:
import pystac
item = pystac.Item(
id="S2B_32TMT_20260101",
geometry=footprint,
bbox=bbox,
datetime=dt,
properties={"eo:cloud_cover": 3.2},
)
item.add_asset("visual", pystac.Asset(
href="s3://bucket/cogs/S2B_32TMT_20260101.tif",
media_type=pystac.MediaType.COG,
roles=["data"],
))
item.set_self_href("./S2B_32TMT_20260101/S2B_32TMT_20260101.json")
item.save_object()
STAC API:stac-fastapi + pgstac
# 配置连接(.env 或环境变量)
export PGUSER=username PGPASSWORD=password PGDATABASE=postgis PGHOST=localhost PGPORT=5439
export STAC_FASTAPI_TITLE="My STAC API"
export STAC_FASTAPI_DESCRIPTION="Imagery catalog"
# 启动
uvicorn stac_fastapi.pgstac.app:app --host 0.0.0.0 --port 8080
数据库需先安装 pgstac 结构(pgstac-migrate migrate,需超级用户权限),并授权:
psql -d postgres://username@localhost:5439/postgis -c "GRANT pgstac_admin TO username"
检索走标准 STAC API:
# 集合与条目
curl -s 'http://localhost:8080/collections' | head -c 300
curl -s 'http://localhost:8080/collections/sentinel-2/items?limit=5'
# bbox + 时间 + 字段过滤(CQL2 需对应扩展)
curl -s 'http://localhost:8080/search?bbox=116,39,117,41&datetime=2026-01-01/2026-12-31&limit=10'
Python 客户端(推荐,处理分页与重试):
from pystac_client import Client
catalog = Client.open("http://localhost:8080")
search = catalog.search(
collections=["sentinel-2"],
bbox=[116, 39, 117, 41],
datetime="2026-01-01/2026-12-31",
max_items=20,
)
items = list(search.items())
TiTiler:动态切片
/cog 端点直接对一个 COG 出图,url 为查询参数(需 URL 编码):
COG='https%3A%2F%2Fexample.com%2Fcog%2Fdem.tif'
# TileJSON(前端地图直接用的配置)
curl "http://localhost:8000/cog/WebMercatorQuad/tilejson.json?url=${COG}"
# 单张瓦片
curl "http://localhost:8000/cog/tiles/WebMercatorQuad/8/210/98.png?url=${COG}" -o tile.png
# 基础信息与统计
curl "http://localhost:8000/cog/info?url=${COG}"
curl "http://localhost:8000/cog/statistics?url=${COG}"
# 预览图(不切瓦片)
curl "http://localhost:8000/cog/preview.png?url=${COG}&max_size=512" -o preview.png
/stac 端点直接对 STAC Item JSON 的 URL 出图,url 指向 Item 本身的 JSON 地址,assets 指定要读的资产名(必填):
ITEM='https%3A%2F%2Fexample.com%2Fstac%2FS2B_32TMT_20260101.json'
curl "http://localhost:8000/stac/tiles/WebMercatorQuad/10/420/196.png?url=${ITEM}&assets=visual"
curl "http://localhost:8000/stac/WebMercatorQuad/tilejson.json?url=${ITEM}&assets=visual"
多资产组合(如多波段分别存放在不同资产)用重复的 assets 参数:assets=red&assets=green&assets=blue。
常用渲染参数(对所有 /tiles 端点通用):
| 参数 | 作用 | 示例 |
|---|---|---|
bidx |
波段组合 | bidx=1&bidx=2&bidx=3 |
rescale |
线性拉伸区间 | rescale=0,4000 |
colormap_name |
命名色带 | colormap_name=terrain |
resampling |
重采样算法 | resampling=bilinear |
nodata |
覆盖 nodata | nodata=0 |
max_size |
预览最大边长 | max_size=512 |
MosaicJSON:多景虚拟镶嵌
当范围跨多景时,用 MosaicJSON 把多个 COG 组织成一张虚拟镶嵌图,TiTiler 的 /mosaicjson 端点按瓦片动态挑选数据源:
python -m pip install "cogeo-mosaic==9.2.0"
# 由 COG 列表生成 MosaicJSON
cogeo-mosaic create cogs.txt -o mosaic.json --minzoom 8 --maxzoom 14
curl "http://localhost:8000/mosaicjson/WebMercatorQuad/tilejson.json?url=https%3A%2F%2Fexample.com%2Fmosaic.json"
典型工作流
链路一:单景影像从 TIFF 到可浏览瓦片
输入:input.tif(任意 GeoTIFF);输出:可通过 TileJSON 浏览的 COG 服务。
- 转 COG:
rio cogeo create input.tif output_cog.tif --cog-profile deflate - 校验:
rio cogeo validate output_cog.tif,必须返回 valid - 上传对象存储:
aws s3 cp output_cog.tif s3://bucket/cogs/(或 MinIO/OSS 等价命令) - 确认 Range 可读:
curl -s -r 0-1023 -o /dev/null -w '%{http_code}' https://.../output_cog.tif应返回 206 - 构造 STAC Item:用 pystac 写入
bbox、datetime、assets.visual.href - 取 TileJSON:
/cog/WebMercatorQuad/tilejson.json?url=...,把返回的tiles填进前端地图 - 校验产物:瓦片图片非空白、
/cog/info的尺寸与波段与原图一致
rio cogeo create input.tif output_cog.tif --cog-profile deflate --blocksize 512
rio cogeo validate output_cog.tif
curl -s -r 0-1023 -o /dev/null -w 'range status: %{http_code}\n' "https://cdn.example.com/output_cog.tif"
链路二:批量入库 STAC API 并按需检索
输入:COG 列表 + 元数据表;输出:可按 bbox/时间检索的 STAC API。
- 批量转 COG:脚本遍历原始影像,逐个
rio cogeo create并validate - 生成 Item:pystac 按集合模板逐景生成 Item JSON
- 入库:写入 pgstac(
INSERT INTO pgstac.items(content)或 pgstac 提供的批量导入工具) - 起服务:
uvicorn stac_fastapi.pgstac.app:app - 检索验证:
/search?bbox=...&datetime=...返回预期条目,/collections能看到集合 - 接出图:把检索到的 Item JSON 地址交给 TiTiler 的
/stac/tiles?url=...&assets=...出图(TiTiler 直接读 Item JSON,不需要额外配置 STAC API 连接)
from pystac_client import Client
from rio_cogeo.cogeo import cog_validate
assert cog_validate("output_cog.tif")[0], "COG 校验未通过,先修正再入库"
catalog = Client.open("http://localhost:8080")
items = list(catalog.search(collections=["sentinel-2"], bbox=[116, 39, 117, 41]).items())
print(len(items), items[0].assets["visual"].href)
链路三:多景镶嵌 + 前端地图接入
输入:跨多景的 COG 集合;输出:一张连续的镶嵌底图。
- 列 COG 清单:
cogs.txt每行一个 COG URL - 生成 MosaicJSON:
cogeo-mosaic create cogs.txt -o mosaic.json --minzoom 8 --maxzoom 14 - 上传 mosaic.json 到对象存储
- 取 TileJSON:
/mosaicjson/WebMercatorQuad/tilejson.json?url=... - 前端接入:OpenLayers/MapLibre 用返回的
tiles模板建瓦片图层 - 校验:拼接处无明显接缝、边缘景号覆盖正确、缩到 minzoom 不出现空白
// 前端:把 TileJSON 的 tiles 直接给 MapLibre
const tilejson = await fetch(
'http://localhost:8000/mosaicjson/WebMercatorQuad/tilejson.json?url=' + encodeURIComponent(mosaicUrl)
).then(r => r.json());
map.addSource('mosaic', { type: 'raster', tiles: tilejson.tiles, tileSize: 256 });
map.addLayer({ id: 'mosaic', type: 'raster', source: 'mosaic' });
性能与工程实践
- COG 内部块别太小:512×512 是通用最优;256 会增加请求次数,1024 会放大单次读取量
- 对象存储必须支持 Range:S3/OSS/MinIO/GCS 都支持;某些 CDN 或代理会忽略
Range返回 200 全量,导致出图极慢 - CDN 缓存瓦片而非 COG:瓦片 URL 带
url参数,可对/cog/tiles/...做短期缓存;COG 本体交给对象存储直读 - 限定
maxzoom:超过数据实际分辨率继续放大只是插值,浪费算力,用源的真实分辨率推导上限 - 服务端并发出图是 CPU 密集:TiTiler 的瓶颈在重采样与编码,多 worker 部署(
--workers N)比单进程调参有效 - MosaicJSON 分层:超大范围按 maxzoom 分块生成多个 mosaics,避免单个 mosaic.json 过大
- 私有数据用签名 URL:不要在前端暴露永久凭据;TiTiler 支持通过环境变量注入 S3 凭据或前置签名
- 入库前必须
cog_validate:不合规的 COG 会在检索正常的情况下出图失败,排查成本高
常见问题
| 问题 | 原因 | 处置 |
|---|---|---|
| 瓦片请求返回 416 Range Not Satisfiable | COG 未按 tile 组织,或文件被部分上传/截断 | rio cogeo validate 重新校验;确认上传对象大小与本地一致;必要时重转 COG |
| 出图全黑或全白 | bidx 波段顺序错误,或缺 rescale 拉伸 |
用 /cog/info 看波段数与 dtype;单波段加 rescale=min,max,多波段用 bidx=1&bidx=2&bidx=3 |
| 403 Forbidden 或 Access Denied | 对象存储桶/对象私有,TiTiler 没拿到凭据 | 给服务进程配置 AWS 凭据或 IAM 角色;或改用预签名 URL 作为 url 参数 |
pip install titiler 装出来的东西不对 |
TiTiler 已弃用该元包,PyPI 上停在 0.25.0 | 改装 titiler.application==2.4.0 或按需装 titiler.core 等子包 |
/stac/tiles 报 400 或读不到资产 |
url 指向的 Item JSON 不可访问,或 assets 名称与 Item 里的 assets 键不一致 |
curl 打开 Item JSON 核对 assets 的键名;url 必须指向 Item 文件而不是 Collection 或 API 检索页 |
| stac-fastapi 启动报缺少 pgstac 表 | 数据库未执行 pgstac 迁移,或用户无权限 | 用 pgstac-migrate migrate 建结构,并 GRANT pgstac_admin 给连接用户 |
| 瓦片拼接处有明显接缝 | 多景镶嵌的重采样/色彩不一致 | 统一 rescale 与 colormap,或先做色彩一致性处理再生成 MosaicJSON |
| 预览图比预期模糊 | 默认预览尺寸受限,或源没有 overview | 设 max_size;确认 COG 带 overview(rio cogeo info 的 overviews 字段) |
| 前端加载瓦片很慢但服务端正常 | CDN/代理忽略 Range,或未缓存瓦片 | 检查 curl -r 0-1023 是否返回 206;对瓦片端点加缓存层 |
AI 使用建议
- 执行环境:
pip install、docker run在终端执行;本链路组件多,装包输出长,重定向到文件再分段读。Windows 下 Docker 需先确认守护进程在运行。 - 先探测版本:
rio cogeo --version、python -c "import stac_fastapi.api as m; print(m.__version__)"、curl -s localhost:8000/ | head -c 200。本技能按 rio-cogeo 7.0.4、stac-fastapi 7.1.1、TiTiler 2.4.0 编写;TiTiler 2.x 与 0.x 的包名和入口完全不同,别混用旧教程。 - 验证产物:COG 用
rio cogeo validate的返回值为准,不只看命令是否退出 0;瓦片用curl -o tile.png后检查文件大小与是否全透明;前端能否出图必须由浏览器确认,AI 助手通常看不到画面。 - 无 GPU/无对象存储环境:可用本地
file://或http.server充当 COG 源验证逻辑,但 Range 行为与真实对象存储不同,不要据此判断生产性能。 - 参数顺序:
/cog/tiles/{tileMatrixSetId}/{z}/{x}/{y}.png?url=...中tileMatrixSetId缺省为WebMercatorQuad;url必须 URL 编码,否则带查询串的对象地址会被截断。 - 常见症状:400 多为参数名拼错或
bidx越界;404 是路由或 item 不存在;416 是文件不是合法 COG;500 先看服务端日志里的 rasterio 异常。 - 安全与权限:不要在前端或汇报里回显云凭据;公开服务前确认影像的许可与分发范围,个别数据源禁止二次发布。
相关技能
- gdal — COG 生成与校验的底层工具链(
gdal_translate -of COG):../gdal/SKILL.md - pdal — 点云/高程数据的处理,与 DEM 类 COG 配合:../pdal/SKILL.md
- postgis — pgstac 的空间检索基础(PostGIS 索引与查询):../postgis/SKILL.md
- openlayers — 前端接入 TileJSON 瓦片源:../openlayers/SKILL.md
- maplibre-gl-js — 矢量/栅格瓦片前端渲染:../maplibre-gl-js/SKILL.md
- cesiumjs — 影像与地形在三维地球上的叠加:../cesiumjs/SKILL.md
参考资源
- STAC 规范:https://stacspec.org/
- STAC 规范仓库:https://github.com/radiantearth/stac-spec
- STAC API 规范:https://github.com/radiantearth/stac-api-spec
- stac-fastapi 文档:https://stac-utils.github.io/stac-fastapi/
- pgstac:https://github.com/stac-utils/pgstac
- COG 规范:https://github.com/cogeotiff/cog-spec
- rio-cogeo 文档:https://cogeotiff.github.io/rio-cogeo/
- rio-cogeo CLI:https://cogeotiff.github.io/rio-cogeo/CLI/
- TiTiler 文档:https://developmentseed.org/titiler/
- TiTiler COG 端点:https://developmentseed.org/titiler/endpoints/cog/
- TiTiler STAC 端点:https://developmentseed.org/titiler/endpoints/stac/
- TiTiler 镜像:https://github.com/developmentseed/titiler/pkgs/container/titiler
- pystac-client 文档:https://pystac-client.readthedocs.io/
- 中文教程:https://znlgis.github.io/gis/tutorial/STAC-COG-TiTiler/