NEGIAO's WebGIS

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

🌟 核心功能预览

🗺️ 底图卷帘对比	🧭 罗盘寻龙点穴

📐 二维数据管理	☁️ 三维漫游云景

🤖 智能助手交互	🌊 动态淹没分析

🗺️ 矢量瓦片逆向解析

📑 目录

🌟 核心功能预览
📑 目录
🎯 项目简介
- 核心能力
- 建筑抓取合规声明（必读）
🚀 快速开始
📁 项目结构
🏗️ 系统架构
- 分层架构总览
- 域名映射
🧭 文档导航
- 开发文档
- 架构文档
  - 系统级架构
  - 功能架构
Star History
📜 版本演进
📄 许可证
👤 作者与托管

🎯 项目简介

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

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

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

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

核心能力

领域	说明
🗺️ 2D/3D 双引擎	OpenLayers 2D + Cesium 3D 一键切换，视图状态双向同步，URL 分享还原
🌐 丰富底图源	80+ 瓦片图源、熔断回退、GCJ-02 纠偏、自定义 XYZ 接入
📥 多格式数据导入	GeoJSON / KML / SHP / GLB / CZML / 3D Tiles 拖拽加载，2D/3D 双管线
🏢 建筑白模抓取	支持建筑1 / 建筑2 / 矢量瓦片三类数据源：框选范围抓取建筑轮廓、楼高及相关属性（WGS-84 GeoJSON），自动入库 2D/3D 图层管理；支持分源级别与凭证配置，并提供跨瓦片同标识建筑融合能力
📐 空间分析	缓冲区 / 叠加 / 泰森多边形 / 聚合 / 渔网等 8 算子（Shapely 后端精确计算）
✨ 三维特效	体积云 ray marching、Bruneton 大气、BSM 云影、风场粒子、洪水淹没模拟
🛩️ 面状航线规划	测区绘制、弓字形/五向倾斜采集、AGL 仿地、DJI KMZ 导入导出，toolPanel 模块卡片直驱并接入统一图层管理
🛣️ 路径规划	天地图驾车/公交双管线、搜索选点与路线渲染
🤖 AI 空间助手	LLM 集成，三种接入模式（默认 / 个人 Key / 后端代理）
🔐 账号体系	邮箱注册登录、Google/GitHub 一键注册登录与绑定、三级身份、会话鉴权、双 AI 配额管理
🧰 实用工具	测量、坐标拾取、风水罗盘、卷帘分析、天气、主题切换、图层管理

建筑抓取合规声明（必读）

仅允许在你已获得官方授权的场景下使用建筑抓取能力；
严禁绕过权限、规避访问控制、破解或其他未授权技术手段；
严禁批量采集、离线库化、二次分发或用于未授权商用；
使用者必须自行遵守数据源服务条款、当地法律法规及平台政策；
项目默认提供范围/频率控制与前端合规确认提示，使用者仍需承担最终合规责任。

🚀 快速开始

环境要求

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

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

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

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

层	放哪里	做什么
L1	`deploy/.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

本地开发默认管理员：账号 admin，密码 123456。仅在 SUPER_USER 未配置且 APP_ENV 为 development/dev/local/test 时生效（load.py → get_admin_password()）；生产环境必须通过 HF Secrets 配置 SUPER_USER，否则管理员登录直接禁用。

手动启动（高级用户）

前端本地开发

cd frontend
npm install
npm run dev
# → http://localhost:5173

全栈一键（Docker 单容器，推荐）

# nginx(前端静态+/api 反代) + FastAPI 同容器，单端口 7860
# 首次运行需 --build 构建镜像（文件较大，需等待几分钟）
docker compose -f deploy/docker-compose.yml up -d --build

# 后续运行
docker compose -f deploy/docker-compose.yml up -d
# → http://localhost:7860 （API 文档 /docs）

环境文件统一收敛在 deploy/（.env / .env.local）；后端不再支持直接运行 uvicorn。

双轨部署（生产）

# 前端静态轨：GitHub Actions 自动执行（Pages / 主页仓库 / HF Static），无需本地操作
# 全栈轨：push main 后 CI 组装 {Dockerfile, deploy/, backend/, frontend/}
#         推送 Hugging Face Space，镜像内自行 npm ci + vite build + uv sync

# 手动等价：构建全栈单容器镜像（nginx + FastAPI 同容器，单端口 7860）
docker build -t negiao/webgis -f deploy/Dockerfile .
docker run -p 7860:7860 negiao/webgis

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

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

docker pull negiao/webgis_dev:V3.5

镜像与 deploy/docker-compose.yml 本地编排同源（构建文件 deploy/Dockerfile），适用于 WebGIS-Dev 本地开发环境启动。

📁 项目结构

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

🏗️ 系统架构

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

分层架构总览

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

域名映射

个人主页：

域名	平台	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

🧭 文档导航

开发文档

文档	内容
项目结构详解	完整目录树与各模块职责说明
交接文档 handover	接手必读：文档地图、三大架构速览、代码坐标、门禁流程与坑清单
开发约定	强制规范、分层边界、坐标系统约定、提交前检查
开发指南与贡献指南	新增页面/API 标准流程、前后端通信、代码风格
技术栈与常见问题	前后端技术栈、参考资源、FAQ、TODO
更新日志 CHANGELOG	完整版本演进历史
配置指南 configuration	三层配置（deploy .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`	80+ 图源、熔断回退、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 流体管线详解（三维特效配套）
面状航线	`cesium-planar-route.md`	模块卡片直驱宿主 Viewer：测区绘制、弓字形/五向规划、KMZ 导入导出与图层管理接入
三层配置架构	`configuration-three-tier.md`	L1/L2/L3 全景：来源→统一入口→业务/前端消费与门禁
Cesium 统一图层管理	`cesium-unified-layer-management.md`	设计评审稿：3D 数据接入统一 TOC 的两步走方案

Star History

📜 版本演进

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

版本	日期	概要
V3.6.20	2026-10-17	多批次归并：TOC 重命名链修复 + 区划图层字段修复 + 游客序号 guest_no + 落地页南师大风格重构 + 图层属性弹窗/TopBar UI 重写 + 落地页主卡预览图。① TOC 右键「重命名」只写 Pinia store、不改地图侧托管记录，被下一次 `user-layers-change` 广播冲回旧名（无法真正应用）：改为经 ActionRouter 路由 `MapContainer.renameUserLayer`，改托管记录 + 广播回流，与可见性/透明度同为单一事实源；区划节点走 tocStore 元数据；地图未就绪降级 store 兜底。② 行政区划托管记录 OL 图层字段 `_layer` → `layer`（对齐托管约定），修复坐标转换/导出/编辑/导入3D 被误判"不是矢量图层"。③ 后端游客登录回传 `guest_no`（guest_identity_records 自增真序号），前端未设昵称游客展示 `guest_<序号>`（旧会话按 uid 哈希兜底）。④ 落地页南师大风格全量重构：SectionTitle 三件套组件（印章+衬线标题+水印）、Hero 数字滚动 + 三环轨道纹样（mask 染金，URL 经 ASSET_BASE_URL 派生）、技术栈三层架构卡、中部锚点导航 + scroll spy、移动端全屏两级菜单、滚动条品牌定制、页脚云海光带；自托管思源宋体子集（16.7KB woff2）入 `--font-serif` 栈。⑤ 落地页主卡（2D/3D 双引擎）嵌入 `preview.webp` 产品预览图（lazy，桌面主卡右下按原比适配，窄屏整行）。⑥ 图层属性弹窗按项目设计令牌重写（品牌渐变头部 + 统计卡 + 明细行，--z-modal、Esc 关闭）。⑦ TopBar 背景收敛版重设计：左上柔光 + 160° 品牌渐变 + 30/150px 双规格经纬网格（向右渐隐），导航按钮玻璃质感。⑧ 品牌徽牌无底牌单色 logo（mask 染品牌深绿）+ 注册页白 logo 直放；顺带修复 RegisterView 引用全仓未定义 `--brand-primary-darker` 致背景声明被丢弃的真 bug。⑨ 审查修复：触屏档（pointer:coarse ≥40px 目标）、KMZ 包内附带资源静默跳过、ActionRouter 异步错误状态清理、ui-panel-theme.css 通用面板模板抽离。详见完整更新日志
V3.6.19	2026-10-16	URL 底图参数延迟修复 + 矢量多面图层叠放定序（2D/3D）+ 移除假删除修复。① 分享链接 `l` 参数底图近 10s 才生效：hash 路由下 `location.search` 恒为空导致判断失效，改走 urlQueryReader 快照。② 3D 按 Folder run 递进 zIndex；③ 2D 根因级修复（RBush 乱序→`_drawRank`+`renderOrder`，与 QGIS 图例语义一致）；④ 移除以分发结果为准。⚠️ 2D/3D 定序方向相反待定夺。详见完整更新日志
V3.6.17	2026-10-14	暂存区多批次归并：天地图矢量全量抓取 + AP 拓扑修复 + 裁剪多环化 + 建筑抓取合规强化。新建浏览器版 12 层矢量解码与分层拓扑（逐函数/逐规则对齐权威 mjs），修复「全层 0 要素」与「AP 跨瓦 union 全失败 → 自相交/叠片」；面裁剪由单环 Sutherland–Hodgman 改为半平面多环裁剪，修复 CE 7 个「环被瓦片边切开后沿边重复走」的自相交（CE 非法几何 10 → 3，残留 3 个为上游源数据缺陷）；天地图 tab 更名「矢量瓦片」并支持多选分层入库；建筑源匿名化为建筑1/建筑2 并新增合规勾选与首次弹窗确认。AP 专项回归 35/35、mjs selftest 11/11、12 层统计逐层一致、CE 与 mjs 权威 out=1311 完全一致。详见完整更新日志
更早版本（V3.6.14 及以前）请查阅完整更新日志 →

📄 许可证

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

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

👤 作者与托管

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

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

_{V3.6.20 · 开发中 · 最后更新 2026-10-17}

Navigation Menu

Repository navigation

About

Repository files navigation

NEGIAO's WebGIS

🌟 核心功能预览

📑 目录

🎯 项目简介

核心能力

建筑抓取合规声明（必读）

🚀 快速开始

环境要求

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

一键启动（推荐）

手动启动（高级用户）

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

📁 项目结构

🏗️ 系统架构

分层架构总览

域名映射

🧭 文档导航

开发文档

架构文档

系统级架构

功能架构

Star History

📜 版本演进

📄 许可证

👤 作者与托管

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
Docs		Docs
Scripts		Scripts
backend		backend
deploy		deploy
frontend		frontend
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
LocalDev.bat		LocalDev.bat
README.md		README.md
Write-Color.ps1		Write-Color.ps1

Latest commit

History

Folders and files

Repository files navigation

NEGIAO's WebGIS

🌟 核心功能预览

📑 目录

🎯 项目简介

核心能力

建筑抓取合规声明（必读）

🚀 快速开始

环境要求

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

一键启动（推荐）

手动启动（高级用户）

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

📁 项目结构

🏗️ 系统架构

分层架构总览

域名映射

🧭 文档导航

开发文档

架构文档

系统级架构

功能架构

Star History

📜 版本演进

📄 许可证

👤 作者与托管

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages