Skip to content
BranchesTags

Repository files navigation

🇨🇳 中文 | 🇬🇧 English

NEGIAO's WebGIS

专业级前后端分离 WebGIS 平台 · Vue 3 + OpenLayers + Cesium + FastAPI

Vue FastAPI OpenLayers Cesium Frontend Docker Backend License

🚀 在线演示：NEGIAO's WebGIS-Dev — 欢迎点击体验

Views Total Clones Unique Cloners Last Commit

🌟 核心功能预览

🗺️ 底图卷帘对比 🧭 罗盘寻龙点穴
📐 二维数据管理 ☁️ 三维漫游云景
🤖 智能助手交互 🌊 动态淹没分析

📑 目录

🎯 项目简介

NEGIAO's WebGIS 是一个功能完整、架构清晰的前后端分离 WebGIS 平台（当前版本 V3.5.28），前端托管于 GitHub Pages（正式域名 webgis.negiao.cn），后端以 Docker 部署在 Hugging Face Spaces，通过 RESTful API 通信，支持独立扩展。

📚 本 README 仅保留核心概览与导航。完整文档已模块化至 Docs/Guide/，详见下方「文档导航」。

📐 架构文档统一存放于 Docs/Architecture/，使用 Mermaid 流程图 / 时序图 / 状态图描述各子系统的模块关系、数据流向与文件交互，供技术交接与方案审查参考。每篇架构文档聚焦一个功能域，包含设计决策、实现细节与升级方向。

不了解项目全貌？试试 DeepWiki — 向 LLM 提问本项目 Ask DeepWiki

核心能力

领域 说明
🗺️ 2D/3D 双引擎 OpenLayers 2D + Cesium 3D 一键切换，视图状态双向同步，URL 分享还原
🌐 丰富底图源 70+ 瓦片图源、熔断回退、GCJ-02 纠偏、自定义 XYZ 接入
📥 多格式数据导入 GeoJSON / KML / SHP / GLB / CZML / 3D Tiles 拖拽加载，2D/3D 双管线
📐 空间分析 缓冲区 / 叠加 / 泰森多边形 / 聚合 / 渔网等 8 算子（Shapely 后端精确计算）
✨ 三维特效 体积云 ray marching、Bruneton 大气、BSM 云影、风场粒子、洪水淹没模拟
🛣️ 路径规划 天地图驾车/公交双管线、搜索选点与路线渲染
🤖 AI 空间助手 LLM 集成，三种接入模式（默认 / 个人 Key / 后端代理）
🔐 账号体系 邮箱注册登录、Google/GitHub 一键注册登录与绑定、三级身份、会话鉴权、双 AI 配额管理
🧰 实用工具 测量、坐标拾取、风水罗盘、卷帘分析、天气、主题切换、图层管理

🚀 快速开始

环境要求

依赖 用途
Node.js 16+ 前端构建与开发服务器
Docker Desktop 容器化后端环境（强制要求）
LocalDev.bat Windows 一键启动脚本（推荐）

配置（双 env 文件架构，先看这一处）

文件 git 状态 用途 读取时机 APP_ENV
.env git 追踪 部署环境（生产基线） npm run build + 线上部署 production
.env.local git 追踪 本地开发（覆盖 .env） npm run dev + 本地后端 development
.env.example git 追踪 全集 key 目录（不写真值） — —

三层密钥分层（L1/L2/L3）：

层 放哪里 做什么
L1 根 .env / .env.local（不涉密） URL、端口、前端 VITE_*、公开服务端点/超时
L2 管理员面板 + 数据库 地图 token、Agent/LLM Key 与参数、底图、公告（常变、动态生效）
L3 Hugging Face Secrets 绝密：SUPER_USER、OAuth secret、SMTP 密码、Supabase Key、监控令牌

说明与检查清单：Docs/Guide/configuration.md · 执行计划：configuration-architecture-plan.md

# 仓库根目录：.env（部署环境）与 .env.local（本地开发）双文件架构
# 两个文件都提交 git（L1 不涉密）
# 本地开发：Vite 读 .env.local，后端读 .env.local（覆盖 .env 的 production 值为 localhost）
# 部署构建：Vite 只读 .env（selectiveEnvPlugin 按 mode 二选一）

一键启动（推荐）

# Windows：双击 LocalDev.bat，脚本自动完成：
# 1. 检测环境依赖（Node.js / Docker / docker compose）
# 2. 本地开发环境：前端 Vite 读 .env.local，后端 load.py 读 .env.local（覆盖为 localhost 开发值）
# 3. 智能检测 Docker 镜像状态（首次构建 / 代码热重载 / Dockerfile 变更提示）
# 4. 启动前端开发服务器 → http://localhost:5173
# 5. 自动打开浏览器

LocalDev.bat 为纯 ASCII 编码，兼容 GBK/UTF-8 系统；中文彩色输出由同目录 Write-Color.ps1 提供。

访问地址：前端 http://localhost:5173 · 后端 API 文档 http://localhost:7860/docs

手动启动（高级用户）

前端本地开发 
cd frontend
npm install
npm run dev
# → http://localhost:5173
后端（Docker Compose） 
# 首次运行需 --build 构建镜像（文件较大，需等待几分钟）
docker-compose up --build

# 后续运行
docker-compose up
# → http://localhost:7860/docs

后端已升级为 Docker Compose 容器化部署，不再支持直接运行 uvicorn。

生产部署 
# 一键启动前后端
docker-compose up

# 或单独构建后端镜像
cd backend
docker build -t webgis-backend .

本地开发镜像（快速获取）

后端 Docker 镜像已托管至 Docker Hub，构建日期 2026-08-03，对应前端V3.5.10版本；可直接拉取用于本地开发，无需本地构建：

docker pull negiao/webgis_dev:V3.5

镜像与 docker-compose.yml 中 HF 服务的基础镜像一致，适用于 WebGIS-Dev 本地开发环境启动。

📁 项目结构

目录树统一维护于 Docs/Guide/（原子化，不在 README 重复）：

🏗️ 系统架构

完整架构文档已模块化至 Docs/Architecture/： 系统架构总览 · CI/CD 流水线 · 部署关系与域名映射 · HF Space 双向保活机制

分层架构总览

flowchart TB
    subgraph SRC["📦 源码层"]
        direction LR
        REPO_DEV["WebGIS-Dev
前端 + 后端源码"]
        REPO_HOME["NEGIAO.github.io
个人主页仓库"]
    end

    subgraph CI["⚙️ CI / CD"]
        direction LR
        JOB_BUILD["① Build
npm run build → dist"]
        JOB_SYNC["② Sync
dist → 主页仓库WebGIS/目录"]
        JOB_DEPLOY["③ Deploy
多平台部署"]
    end

    subgraph DPL["🚀 部署平台"]
        direction LR
        P_GH["GitHub Pages"]
        P_HF["Hugging Face"]
        P_CF["Cloudflare"]
        P_PC["Posit Connect"]
        P_VC["Vercel"]
    end

    subgraph RT["🌐 运行时"]
        direction LR
        FE_HOME["个人主页
多域名"]
        FE_WEBGIS["WebGIS 前端
多域名"]
        BE["Docker 后端 API"]
        R2["瓦片存储
tiles.negiao.cc.cd"]
    end

    REPO_DEV --> JOB_BUILD
    JOB_BUILD --> JOB_SYNC
    JOB_SYNC --> REPO_HOME
    JOB_BUILD --> JOB_DEPLOY

    JOB_DEPLOY --> P_GH
    JOB_DEPLOY --> P_HF
    REPO_HOME --> P_GH
    REPO_HOME --> P_CF
    REPO_HOME --> P_PC
    REPO_HOME --> P_VC

    P_GH --> FE_HOME
    P_GH --> FE_WEBGIS
    P_HF --> FE_WEBGIS
    P_CF --> FE_HOME
    P_CF --> FE_WEBGIS
    P_PC --> FE_HOME
    P_PC --> FE_WEBGIS
    P_VC --> FE_HOME
    P_VC --> FE_WEBGIS
    P_HF --> BE

    FE_WEBGIS -->|"REST API"| BE
    FE_WEBGIS -->|"加载自定义瓦片"| R2
Loading

域名映射

个人主页：

域名 平台 CDN 国内访问
negiao.github.io GitHub Pages 默认 ❌ ⚠️ 不稳定
negiao.cloud-ip.cc GitHub Pages + 自定义域 ✅ 可配 ✅ 可访问
negiao.cc.cd Cloudflare Pages ✅ Cloudflare ❌ 被屏蔽
negiao.pages.dev Cloudflare Pages 默认 ✅ Cloudflare ✅ 流畅
negiao-pages.share.connect.posit.cloud Posit Connect ❌ ✅ 可访问
negiao.vercel.app Vercel ❌ ❌ 不可访问

WebGIS 前端：

域名 平台 来源
webgis.negiao.cn 正式域名（付费） CNAME → GitHub Pages
negiao.github.io/WebGIS-Dev GitHub Pages WebGIS-Dev 仓库根路径
negiao.github.io/WebGIS GitHub Pages 主页仓库子目录
negiao.cloud-ip.cc/WebGIS-Dev GitHub Pages + 自定义域 自动跳转
webgis.negiao.cc.cd Cloudflare Pages 私有域名挂载
webgis-dev.pages.dev Cloudflare Pages 默认 自动分配
negiao-webgis.share.connect.posit.cloud Posit Connect 主页仓库触发
negiao-web.static.hf.space Hugging Face Static 直接推送

后端与存储：

组件 域名 平台
后端 API negiao-webgis.hf.space Hugging Face Docker
瓦片存储 tiles.negiao.cc.cd Cloudflare R2

完整域名清单、部署来源矩阵、平台能力对比见 deployment-relationship.md

🔁 双向保活机制

HF Spaces 在 24 小时无访问后自动休眠。本平台通过双向互保活机制，让 WebGIS 后端（:7860）与 New API 服务（:3000）每 3~6 分钟互相发送模拟真实用户的 HTTP 请求，保持双方始终活跃。

🧭 文档导航

开发文档

文档 内容
项目结构详解 完整目录树与各模块职责说明
交接文档 handover 接手必读：文档地图、三大架构速览、代码坐标、门禁流程与坑清单
开发约定 强制规范、分层边界、坐标系统约定、提交前检查
开发指南与贡献指南 新增页面/API 标准流程、前后端通信、代码风格
技术栈与常见问题 前后端技术栈、参考资源、FAQ、TODO
更新日志 CHANGELOG 完整版本演进历史
配置指南 configuration 三层配置（根 .env / Admin+DB / HF Secrets）
配置架构执行计划 分阶段收拢配置的落地路线
OAuth 部署配置指南 Google/GitHub 登录：控制台申请、HF Secrets 配置、验收与排错全流程

架构文档

八大核心功能的架构说明沉淀于 Docs/Architecture/：

系统级架构

文档 一句话说明
系统架构总览 五层分层架构：源码 → CI/CD → 部署 → 运行时 → 用户
CI/CD 流水线 五 Job 流水线：Build → Sync → Multi-Deploy 详解
部署关系与域名映射 域名清单、部署来源矩阵、平台能力对比

功能架构

功能 文档 一句话说明
2D/3D 双引擎 ol-cesium-dual-engine.md 一键切换、视图同步与 URL 分享还原
丰富底图源 basemap-source-system.md 70+ 图源、熔断回退、GCJ-02 纠偏
多格式数据导入 multi-format-data-import.md 拖拽加载，2D/3D 双管线与 blob URL 方案
空间分析 spatial-analysis-backend.md 单端点分发，Shapely 后端 8 算子
路径规划 route-planning.md 驾车/公交双管线、搜索选点与路线渲染
三维特效 cesium-3d-effects.md 体积云、风场、浅水叠加与后处理
实用工具 utility-tools.md 测量、坐标拾取、罗盘、分享、GeoTIFF 下载
账号体系 account-system-ai-quota.md 邮箱登录、三级身份、双 AI 配额
洪水淹没模拟 cesium-fluid-flood-simulation.md GPU 流体管线详解（三维特效配套）
三层配置架构 configuration-three-tier.md L1/L2/L3 全景：来源→统一入口→业务/前端消费与门禁
Cesium 统一图层管理 cesium-unified-layer-management.md 设计评审稿：3D 数据接入统一 TOC 的两步走方案

Star History

Star History Chart

📜 版本演进

完整历史见 CHANGELOG.md，以下仅列最近版本摘要。

版本 日期 概要
V3.5.28 2026-08-19 修复 KMZ/KML 标注不显示 + 数据层标注层级上移：标签回退链排除元数据字段（styleUrl 等，杜绝 #LineStyle00 垃圾标签）、空标签不再污染样式缓存、图层名先解码再校验；标注瓦片带 LABEL 800→100（底图之上、数据之下）——数据层标注文字不再被标注瓦片遮挡。详见日志
V3.5.27 2026-08-19 修复 TOC 标注开关失效：右键菜单「开启/关闭标注」不再拿图层名做 isValidLabel 校验（URL 编码名 / "未知"开头名会被误判导致菜单项消失）——标注可用性只看图层能力，标注内容由渲染侧校验；useLayerOperations 标注方法名对齐 MapContainer 暴露面。详见日志
V3.5.26 2026-08-19 TOC 拖拽顺序覆写图层 zIndex：数据层统一落入 Z_BAND.DATA 带（200~799，容量 600），refreshUserLayerZIndex 按 DATA + (N-1-index) 反向映射——TOC 顶部图层 zIndex 最高、最先显示；跨类型拖拽生效（TIF/矢量/KML 统一排序）；固定层（绘制临时/搜索点/起终点/区划/定位）从 DATA 带派生保持层级；根治遗留风险（跨带溢出 + 未知类型兜底）。详见日志

更早版本（V3.5.19 及以前）请查阅 完整更新日志 →

📄 许可证

MIT License — 可自由使用、修改、分发。

告知义务：如果你在任何公开环境（网站、服务器、论文、展览等）运行或部署本项目或其衍生版本，请通过邮件 yaonaigao@gmail.com 或 GitHub Issue 告知作者你的使用即可。

👤 作者与托管

NEGIAO — GitHub · 个人主页 · DeepWiki 项目分析

源代码 前端部署 后端部署
GitHub webgis.negiao.cn（正式域名，GitHub Pages 托管） Hugging Face

V3.5.28 · 开发中 · 最后更新 2026-08-19

About

基于 Vue 的 WebGIS V3.0，前端使用 OpenLayers 与 Cesium，后端使用 FastAPI。 OL 功能： 40+ 内嵌底图、基础空间分析、空间数据查看与管理； Cesium 功能： 体积云、人物漫游、淹没分析、模拟风场 （The WebGIS-Dev platform is a feature-rich, modular WebGIS application built with Vue 3, Vite, OpenLayers and Cesium.）

webgis.negiao.cn/

Topics

webgis

Resources

Readme
License
Activity

Stars

22 stars

Watchers

4 watching

Forks

8 forks
Report repository

Releases

Packages

Used by

Contributors

Languages