GeoLibre：一个免费开源、云原生、可在浏览器/桌面/Jupyter 随处运行的轻量级 GIS 平台

开篇引导段：今天在 GitHub Trending 上看到一个有意思的项目：GeoLibre —— 一个免费、开源、轻量且云原生的 GIS 平台，让你在浏览器、桌面、手机和 Jupyter Notebook 里都能可视化与分析地理空间数据，而且数据始终留在本地、隐私可控。

一、项目概述

GeoLibre 的定位很清晰：把专业 GIS（地理信息系统）的能力搬出笨重的桌面软件，进到一个"打开网页就能用、零安装、数据不离开本机"的轻量平台。它既不是某个商业 SaaS 的客户端，也不是只读的地图查看器，而是一个真正具备分析、处理、发布能力的完整 GIS 工作空间。

官方一句话描述：

A free and open-source, lightweight, cloud-native GIS platform for visualizing, exploring, and analyzing geospatial data. It runs everywhere you do, in the web browser, on the desktop, on mobile, and inside Jupyter notebooks, all while keeping your data local and private.

值得注意的几个产品特性：

• 全平台一致体验：基于 Tauri v2 的同一份工作区，既能打包成 Windows / macOS / Linux 原生桌面应用，也能编译为 Android 原生应用，还能以纯 Web 形态运行在任意现代浏览器里，并自适应手机小屏。在 Jupyter（通过 Python 包 + Notebook Panel）里同样可用。
• 数据本地与隐私：强调 “keeping your data local and private”——数据默认不离开你的设备，云原生指的是架构与可部署性，而非强制上云。
• 3D Tiles / 城市级三维：支持在 MapLibre 地图上渲染 3D Tiles，演示里有曼哈顿建筑按建造年代挤压拉伸、叠加 MTA 地铁线、自动生成图例。
• 行星底图：不只地球，还内置 Moon、Mars、Mercury、Venus、木卫一至四、Titan、Pluto、Charon 等行星/卫星底图（来自 OpenPlanetaryMap 与 USGS Astrogeology），并以"每项目椭球体"保证距离、面积、比例尺与所绘天体一致。
• SQL Workspace：内置 DuckDB-WASM 空间查询，让你用 SQL 直接分析 GeoParquet / 矢量 / 栅格数据，无需服务端。
• 700+ 免费 GIS 工具：浏览器内的地理处理（geoprocessing）能力，零安装。

二、技术原理

架构与核心选型

GeoLibre 的技术栈在 README 中明确列出：

• Tauri v2：用 Rust + WebView 把 Web 应用打包成体积小、内存友好的原生桌面/移动应用（相比 Electron 更轻）。
• React + TypeScript：前端 UI 主体。
• MapLibre GL JS：开源的矢量地图渲染引擎（WebGL），承担二维/三维地图绘制。
• DuckDB-WASM Spatial：在浏览器里运行的列式数据库（含空间扩展），支撑 SQL Workspace 的本地高性能分析。
• deck.gl：Uber 开源的 WebGL 大规模数据可视化层，处理海量点/线/面图层叠加。

这种组合带来的结果是：渲染交给 MapLibre / deck.gl 的 GPU 管线，分析交给 DuckDB-WASM，跨端打包交给 Tauri——三者都在客户端完成，所以"数据本地、零服务端依赖"才得以成立。

仓库结构（monorepo）

package.json 揭示了它是一个 npm workspaces monorepo：

"workspaces": [
  "apps/*",
  "packages/*",
  "workers/*"
]

• apps/geolibre-desktop：Tauri 桌面应用入口（含 src-tauri Rust 工程）。
• packages/core、packages/map、packages/plugins、packages/processing、packages/ui：被拆分的领域包（core、地图、插件系统、地理处理、UI）。
• workers/*：包含 geolibre-viewer-worker、geolibre-collab-worker、geolibre-tiles-worker、geolibre-ai-proxy-worker 等 Web Worker，把耗时任务（瓦片生成、协作、AI 代理）放到后台线程，避免阻塞主线程 UI。

package.json 里还有一组值得玩味的 CI 脚本，体现质量门禁：

"ci": "npm run lint && npm run build && npm run test:frontend:coverage && npm run test:worker && npm run test:backend:coverage && npm run check:rust"

覆盖了前端 lint/build、前端单测覆盖率（行/分支/函数阈值）、worker 类型检查、Python 后端测试覆盖率，以及 Rust 编译检查——一个前端为主的项目把 Rust 侧也纳入了 CI。

质量门禁细节：ESLint 只开 Hooks 规则

eslint.config.mjs 刻意保持极简——只启用 react-hooks/rules-of-hooks（error）和 exhaustive-deps（warn），注释解释了原因：错位 Hook（例如在提前 return 之后写 useMemo）tsc 抓不到，但运行时会崩成 “Rendered more hooks than during the previous render”。这是一个从真实踩坑中收敛出来的最小可用规则集，而非"全部 recommended"。

部署形态：Docker 一键起

Dockerfile 把静态 Web 应用（nginx 托管）与一个可选的 Python 转换/Whitebox 侧车（uvicorn，反代在 /sidecar）打包进同一镜像。关键点：

• 构建阶段用 node:22-alpine，运行阶段用 python:3.12-slim-bookworm（glibc 基镜像，因为 duckdb / rasterio / whitebox 等预编译 wheel 依赖 glibc）。
• 侧车负责 Vector→GeoParquet、CSV→GeoParquet、Raster→COG 等转换；freestiler（PMTiles）与 whitebox-workflows 仅在 amd64 有 wheel，所以 arm64 下会优雅跳过（只报 “unavailable”）。
• 通过 GEOLIBRE_CONVERSION_ROOTS=/data 把转换读写限制在 /data，防止同源任意调用读写容器路径——这是个明确的安全隔离设计。

E2E 测试如何驱动 WebGL

playwright.config.ts 里有个细节：MapLibre 需要 WebGL 上下文，因此 CI 无 GPU 时用 --use-gl=angle --use-angle=swiftshader 强制软件渲染初始化地图。同时用 storageState 预置"UI profile 引导已完成"，避免首次启动向导的模态框拦截点击。这些都不是业务功能，却直接决定了项目能否稳定做自动化测试——很有参考价值。

三、安装与快速开始

GeoLibre 提供四种零门槛入口，任选其一即可：

1. 网页版：直接打开 https://web.geolibre.app —— 完整应用，免安装。
2. 桌面端：https://geolibre.app/downloads 下载 Windows / macOS / Linux 安装包（也上架 Microsoft Store、AUR、Flatpak）。
3. Jupyter：pip install geolibre 后在 Notebook 里使用，或打开官方 Colab 示例。
4. 源码运行：

git clone https://github.com/opengeos/GeoLibre.git
cd GeoLibre
npm install
npm run dev        # 启动桌面应用开发模式（Tauri）

Docker 方式：

docker build -t geolibre .
docker run -p 80:80 geolibre

环境要求：Node.js ≥ 22（见 package.json 的 engines），Python 侧为 3.12。

最简验证——在网页版里打开一个示例项目即可看到地图渲染：

• 3D Tiles 示例：https://share.geolibre.app/giswqs/3d-tiles
• 纽约建筑与地铁：https://share.geolibre.app/giswqs/nyc-buildings-and-subways

四、使用方法与实战

基础用法：加载并可视化数据

在 GeoLibre 里新建/打开项目后，通过 Layers 面板添加数据源（矢量文件、GeoParquet、PMTiles、COG 等），地图即时渲染。纽约建筑示例就是典型的"矢量挤压 + 分类着色 + 自动图例"流程：

• 把曼哈顿建筑底面按 construction_year 字段做高度挤压（extrude）；
• 用建造年代做分类配色；
• 叠加 MTA 地铁线/站点图层；
• 图例由图层符号自动生成。

进阶用法：SQL Workspace 做空间分析

打开 SQL Workspace，用 DuckDB 的空间函数直接查询当前数据，例如统计某区域内地块数量、做缓冲区分析、跨图层 JOIN——全部在浏览器本地完成，无需把数据上传到任何服务器。Cloud-native 格式（GeoParquet、PMTiles、COG）可直接查询，省去格式转换。

进阶用法：切换行星底图

在 Layers 面板的 planet switcher 里切换地球之外的天体。因为每个项目有独立椭球体，距离/面积/比例尺测量会贴合所绘天体——做行星科学或科普可视化时很实用。

实战：嵌入与分享

GeoLibre 支持把项目发布为可嵌入的 Web 组件（VITE_GEOLIBRE_EMBED_ORIGINS 控制允许通过 postMessage 驱动的源），适合把交互式地图嵌进自己的网站或报告。Docker 部署时可通过 GEOLIBRE_AUTH_USER/PASSWORD 开启 Basic Auth 保护实例。

五、常见问题与解决方案

1. 安装/构建失败：npm ci 报 missing workspace Dockerfile 注释明确指出：在 apps/ 或 packages/ 下新增包时，必须把新包的 package.json 加进 Dockerfile 的 COPY 列表，否则 npm ci 会因找不到 workspace 而失败。仓库开发同理——新增 workspace 成员后记得同步。

2. 地图在 CI / 无 GPU 环境不渲染 这是 WebGL 上下文缺失导致。playwright.config.ts 的做法是用 --use-gl=angle --use-angle=swiftshader 强制软件渲染（SwiftShader）。本地若无 GPU，可参考此思路配置启动参数。

3. arm64 上部分转换工具"不可用" Dockerfile 说明：freestiler（PMTiles）与 whitebox-workflows 没有 linux/arm64 预编译 wheel，因此 arm64 镜像只跳过这两个工具，其余转换照常工作。属于预期行为，非故障。

4. 公开部署时 CSP 提示 loopback 探测风险 Dockerfile 警告：镜像内 nginx 的 CSP 为本地开发放行了 http://localhost:* / ws://localhost:*，便于连本地 dev server 数据源；公开部署前必须把这些放行从 CSP 中移除，否则会让访客浏览器去探测其本机 loopback。

5. 首次启动向导遮挡交互（自动化/E2E 场景） Playwright 配置里用 storageState 预置 uiProfile.onboarded = true 跳过向导。自己集成/自动化时若遇到点击被拦截，同样先标记 onboarding 已完成。

六、总结

GeoLibre 的思路很值得关注：用现代的 Web 技术栈（Tauri + React + MapLibre + DuckDB-WASM + deck.gl）把一个原本"重、贵、绑定桌面"的 GIS 工作流，重做成"打开网页即用、数据本地、全平台一致"的轻量平台。它在架构上把渲染、分析、跨端打包、后台任务清晰分层，并用 Docker + 侧车 + 严格权限边界把"可自托管"落到实处。如果你做地理数据可视化、空间分析，或只是想在浏览器里快速看一张地图而不想装一整套软件，GeoLibre 值得一试。

License：MIT。如用于学术，官方提供 Zenodo DOI（10.5281/zenodo.20785400）与 CITATION.cff 引用方式。