🇨🇳 中文 | 🇬🇧 English

NEGIAO's WebGIS

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

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

最近活跃	今日访客	今日访问量	昨日访客	昨日访问量	本月访问量	总访问量

_{数据统计时间}

🌟 核心功能预览

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

🗺️ 腾讯 / 高德 / 天地图 矢量瓦片解析

📑 目录

• 🌟 核心功能预览
• 📑 目录
• 🎯 项目简介
  • 规模速览
  • 核心能力 · 地图内核
  • 核心能力 · 三维与分析
  • 核心能力 · 数据与协作
  • 核心能力 · 账号与运维
• 🧰 功能模块全景
• 🛠️ 技术栈
• ⚠️ 建筑抓取合规声明（必读）
  • 数据来源
  • 使用边界
• 🚀 快速开始
  • 环境要求
  • 配置（双 env 文件架构，先看这一处）
  • 一键启动（推荐）
  • 手动启动（高级用户）
  • 本地开发镜像
• 📁 项目结构
• 🏗️ 系统架构
  • 分层架构总览
  • 后端 API 面
  • 域名映射
• 🧭 文档导航
  • 开发文档（Docs/Guide/）
  • 架构文档（Docs/Architecture/）
• 🚧 已知限制与当前状态
• Star History
• 📜 版本演进
• 📄 许可证
• 👤 作者与托管

🎯 项目简介

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

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

📐 架构文档统一存放于 Docs/Architecture/，使用 Mermaid 流程图 / 时序图 / 状态图描述各子系统的模块关系、数据流向与文件交互，供技术交接与方案审查参考。

🤖 在本仓库使用 AI Agent 协作开发，请先阅读 Docs/Force_command.md（强制执行规范，含红线与门禁）。

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

规模速览

核心能力 · 地图内核

核心能力 · 三维与分析

核心能力 · 数据与协作

核心能力 · 账号与运维

🧰 功能模块全景

按「引擎域」罗列的模块清单，便于快速定位代码：

Cesium 工具面板（cesium/composables/toolModules/）

场景导航 · 大气·光照·天空 · 体积云 · 风场 · 流体淹没 · 浅水叠加 · 人物漫游 · 面状航线 · 航线飞行 · 三维分析（限高/可视域）

OpenLayers 工具（ol/）

绘制 drawing · 空间分析 spatial-analysis · 路径规划 routing · 地名检索 search · 底图 basemap · 瓦片源 tile-source · 行政区划 DistrictManager · URL 状态 url-state · 启动编排 startup

公共域（common/）

侧栏外壳 shell（SidePanel/TopBar/公告条/全局加载） · 图层树 layer-tree · 数据导入 data-import · AI 对话 chat（agent/工具注册/命令总线） · 罗盘 compass · 天气 weather · 用户与账号 user · 命令总线 command-bus · 地图视图 map-view · 数据协议 data-protocol · 界面 ui

侧栏标签页（共 8 个，按使用懒加载，首次切到后保持挂载以保留状态）：新闻热榜（info 默认页）/ 工具箱 / 驾车规划 / 公交规划 / 风水罗盘 / 建筑抓取 / 天气 / AI 助手

🛠️ 技术栈

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

数据来源

三类数据源均为公开可访问的矢量瓦片服务，分属商业平台与政府机构：

三者共用同一套瓦片解码与几何装配链路，差别只在图层过滤与凭证策略。 前端只实现了腾讯、高德的建筑层级（CE）抓取，天地图做了全量解析； 在同一套解析器上放开图层过滤，即可对腾讯、高德做全量解析——这也是本项目开源的意义之一。

此前三类来源在界面与文档中曾以「建筑 1 / 建筑 2 / 矢量瓦片」匿名标识（出于合规考虑），现已恢复真实来源；历史版本日志仍保留当时的匿名化说明与原因。

使用边界

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

🚀 快速开始

环境要求

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

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

说明与检查清单：Docs/Guide/configuration.md · 全景：configuration-three-tier.md

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

代理相关：后端部署在 Hugging Face，其政策禁止挂载任何 /proxy/*、/tiles/* 中转。瓦片代理与外部站点反代由 VPS 上的独立服务（vpn.negiao.cn，仓库 tile-proxy）承接，前端通过 VITE_TILE_PROXY_BASE_URL 拼接 ${base}/proxy/<host>/<path>。

一键启动（推荐）

# 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

# 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）

# 前端静态轨：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，可直接拉取用于本地开发，无需本地构建：

docker pull negiao/webgis_dev:V3.5      # 2026-08-03 构建，对应前端 V3.5.10
docker pull negiao/webgis_dev:latest    # 2026-08-23 构建，较新但仍滞后于源码

⚠️ 两个标签均构建于 2026-08 月，与当前代码（V3.6.23+）存在代差。镜像与 deploy/docker-compose.yml 同源（构建文件 deploy/Dockerfile），如需与源码一致请本地 --build 重建。

📁 项目结构

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

• 项目根级目录总览 + Docs 文档树
• 前端完整文件树 frontend/src/
• 后端完整文件树 backend/

🏗️ 系统架构

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

分层架构总览

flowchart TB
    subgraph SRC["📦 源码层"]
        direction LR
        REPO_DEV["WebGIS-Dev
前端 + 后端源码"]
        REPO_HOME["NEGIAO.github.io
个人主页仓库"]
        REPO_PROXY["tile-proxy
VPS 代理 / 瓦片服务"]
    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"]
        PR["VPS 反代
vpn.negiao.cn"]
        R2["瓦片存储
tiles.negiao.cc.cd"]
    end

    REPO_DEV --> JOB_BUILD
    REPO_PROXY --> PR
    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 -->|"外部站点反代 / 瓦片代理"| PR
    FE_WEBGIS -->|"加载自定义瓦片"| R2

后端 API 面

后端共 15 组路由，均为 /api/* 前缀（Hugging Face 政策禁止 /proxy/*、/tiles/*）：

域名映射

个人主页：

WebGIS 前端：

后端、代理与存储：

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

🧭 文档导航

开发文档（Docs/Guide/）

架构文档（Docs/Architecture/）

系统级

功能级

历史重构记录（Docs/Architecture/decisions/） —— 记录「当时怎么改的」，非现行架构

其它目录：Docs/Force_command.md（Agent 强制规范）· Docs/TODO/（方案与待办，入口见其 README 索引）· Docs/LLM_record/（逐次开发记录）· Docs/Demo/（演示页与样例数据，非文档）· Docs/Refactor.md

🚧 已知限制与当前状态

坦白列出「README 容易说得比实际好」的部分，避免误判：

Star History

📜 版本演进

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

📄 许可证

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

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

👤 作者与托管