详细技术介绍与功能架构

OrbitMapper-cn 🛰️ 3D 实时卫星轨道可视化系统

基于 React 18 + Three.js + SGP4 轨道动力学算法构建的现代化高性能 3D 实时卫星追踪系统
深度适配阿里云 ESA (Edge Security Acceleration 边缘安全加速) 与 Edge Routine (ER) 边缘函数，专为国内高可用低延迟网络优化。

📖 项目简介

OrbitMapper-cn 是一套面向低轨卫星互联网星座（如中国星网、千帆星座、Starlink 等）与中高轨导航星座（北斗、GPS、伽利略等）的 3D 交互式实时轨道解算与三维地球可视化平台。

针对 CelesTrak 等海外公开卫星轨道源站存在的网络延迟高、访问受限及跨域问题，本项目研发了基于阿里云 ESA 边缘计算与 EdgeKV 的边缘代理加速层，实现卫星 TLE（两行数根数）数据的毫秒级国内就近分发与 12 小时定时自动预热，为用户带来极速、流畅的深空探索与天基互联观测体验。

✨ 核心特性

🛰️ 全谱系卫星星座覆盖：
- 中国低轨互联网巨型星座：星网 (Hulianwang Digui)、千帆 (Qianfan)
- 国际低轨宽带星座：星链 (Starlink)、一网 (OneWeb)、柯伊伯 (Project Kuiper)
- 全球四大卫星导航系统 (GNSS)：中国北斗 (Beidou)、美国 GPS、欧洲伽利略 (Galileo)、俄罗斯格洛纳斯 (GLONASS)
- 高轨/地球同步/中轨群：地球同步轨道卫星群 (GEO)、SES 卫星群
🌍 电影级 3D 地球与天体光照：
- 高精度地球贴图（NASA Blue Marble 昼夜地表贴图）与地形凹凸质感
- 真实时间同步太阳光照：基于天体黄赤交角与观测时区实时计算太阳入射角，呈现真实昼夜晨昏交界线
- 动态多层大气层辉光（Atmosphere Glow）与 6000+ 颗背景深空恒星系
📐 工业级 SGP4 轨道动力学解算：
- 基于 satellite.js 实时进行精确坐标转换与轨道递推（ECI、GMST、Geodetic 经纬高变换）
- 实时遥测解算：经度、纬度、海拔高度（km）、瞬时运行速度（km/s）
- 3D 空间动态闭合轨道曲线渲染，支持全星座轨迹预览或单星精准追踪
⚡ 阿里云 ESA 边缘加速架构：
- Edge Routine (ER) 边缘函数自动代理并格式化 TLE 数据源，彻底消除跨域 (CORS) 限制
- EdgeKV 分布式键值缓存：全网边缘节点就近缓存（TTL 12 小时），国内毫秒级响应
- Cron Trigger 定时同步：每 12 小时自动化后台刷新预热，避免源站频繁请求
- 客户端容灾：前端集成 LocalStorage 本地离线缓存，网络异常时平滑降级
🔍 极致交互与检索体验：
- 全局智能搜索：支持按卫星名称（如 QIANFAN、HULIANWANG）或 NORAD 编号进行毫秒级模糊检索
- 动态平滑镜头：基于 GSAP 与自定义相机控制器，实现平滑变焦、旋转及锁定卫星跟随
- 中英双语：一键切换简体中文 / 英文界面（i18n）
- 自适应暗黑科技风 UI：Glassmorphism 磨砂玻璃质感设计，完美兼容桌面端与移动端触控
⚖️ 完备的合规与免责体系：
- 内置规范的开源与学术免责声明，明确公开数据来源与学术科普定位

🏗️ 架构与数据流

flowchart TD
    subgraph Client ["用户客户端 (Browser / Mobile)"]
        UI["React 18 + Vite UI (Glassmorphism)"]
        R3F["Three.js / React Three Fiber<br/>(3D 地球 / 光照 / 轨道)"]
        SGP4["satellite.js<br/>(SGP4 动力学实时解算)"]
        LCache["LocalStorage (离线二级缓存)"]
    end

    subgraph ESA ["阿里云 ESA (边缘安全加速平台)"]
        ER["Edge Routine (边缘函数)<br/>worker/src/index.js"]
        EKV[("EdgeKV 分布式缓存<br/>ORBIT_CACHE")]
        Cron["Cron Trigger 定时触发器<br/>(每 12 小时)"]
    end

    subgraph Upstream ["天基公开轨道数据源"]
        CelesTrak["CelesTrak (NORAD TLE 轨道根数)"]
    end

    UI --> SGP4
    SGP4 --> R3F
    UI -->|查询与写入| LCache
    LCache -->|离线数据加载| UI

    Client -->|1. 请求 /api/tle| ER
    Cron -->|定时预热| ER
    ER -->|2. 查询缓存| EKV
    EKV -->|缓存命中返回| ER
    ER -->|3. 缓存未命中时回源| CelesTrak
    CelesTrak -->|4. 返回最新 TLE| ER
    ER -->|5. 异步写入缓存| EKV
    ER -->|6. 高速就近分发| Client

🛠️ 技术栈

层次	技术选型	说明
三维渲染	`Three.js` / `@react-three/fiber` / `@react-three/drei`	现代化声明式 3D 场景与 WebGL 渲染管线
应用框架	`React 18` + `Vite 6`	组件化响应式架构与极速构建打包
轨道计算	`satellite.js` (SGP4/SDP4 算法)	卫星轨道递推与大地坐标系互转
动画系统	`GSAP (GreenSock)`	平滑镜头过渡、视角锁定跟随动效
边缘计算	`Aliyun ESA` (Edge Routine + EdgeKV)	国内边缘节点代理加速、高并发缓存防护
用户界面	原生现代 CSS (Glassmorphism)	深度适配移动端与桌面端，科技感暗色调
国际化	轻量级 React Context i18n	支持中文 (zh) 与英文 (en) 实时切换

📁 目录结构

orbitmapper-cn/
├── DEPLOYMENT_GUIDE_ESA.md     # 阿里云 ESA 部署与配置保姆级指南
├── esa.json / esa.jsonc        # 阿里云 ESA Pages 站点构建配置文件
├── index.html                  # HTML5 入口模版
├── package.json                # 项目依赖及构建脚本
├── vite.config.js              # Vite 构建配置
├── public/                     # 静态公共资源 (Favicon 等)
├── src/                        # 前端主源码目录
│   ├── App.jsx                 # 应用主入口与状态编排
│   ├── App.css / index.css     # 全局设计规范与 Glassmorphism 样式
│   ├── components/             # 3D Three.js 场景组件
│   │   ├── Atmosphere.jsx      # 大气层散射辉光特效
│   │   ├── CameraController.jsx# 相机平滑跟随与轨道控制器
│   │   ├── Earth.jsx           # 3D 高精地球模型 (昼夜贴图/云层/地形)
│   │   ├── Orbits.jsx          # 空间轨道几何体动态绘制
│   │   ├── Satellites.jsx      # 卫星点集与发光材质渲染
│   │   ├── Scene.jsx           # 3D 核心主场景 (星空/光源/网格组装)
│   │   └── SunLight.jsx        # 真实天文太阳直射点计算与光照组件
│   ├── contexts/               # 全局 Context (语言多语言切换)
│   ├── data/                   # 静态数据与常量
│   │   ├── constellations.js   # 支持的星座配置表 (颜色/类型/描述)
│   │   └── disclaimerContent.js# 免责与法律声明中英文双语条目
│   ├── hooks/                  # 自定义 React Hooks
│   │   ├── useSatelliteData.js # 边缘 API 数据获取与本地存储缓存 Hook
│   │   ├── useSatellitePositions.js # 每一帧高频解算卫星 3D 空间坐标
│   │   └── useSunPosition.js   # 太阳赤纬/赤经与光照矢量 Hook
│   ├── locales/                # 国际化语言包 (中文 / 英文)
│   ├── ui/                     # UI 悬浮面板与控件
│   │   ├── Controls.jsx        # 轨道显隐等交互工具栏
│   │   ├── DisclaimerModal.jsx # 免责声明模态弹窗
│   │   ├── LoadingScreen.jsx   # 数据加载与进度屏
│   │   ├── SatelliteInfo.jsx   # 选中卫星实时遥测详情卡片
│   │   ├── Sidebar.jsx         # 星座分类筛选与搜索抽屉
│   │   └── StatusBar.jsx       # 顶部状态栏 (时间/在轨总数/语言切换)
│   └── utils/                  # 工具函数库
│       ├── constants.js        # 物理/渲染常数与 API 接口地址
│       ├── coordinateTransform.js # 经纬度/高程/空间直角坐标换算
│       └── sunPosition.js      # 太阳赤经赤纬算法
└── worker/                     # 边缘函数 (Edge Routine)
    ├── esa.json                # 边缘函数 ESA 配置
    ├── wrangler.toml           # Cloudflare Workers 本地/测试兼容配置
    └── src/
        └── index.js            # ESA ER 边缘函数核心 (CelesTrak 代理与 EdgeKV 缓存)

🚀 快速上手 (本地开发)

1. 环境准备

Node.js：建议使用 Node.js 18.x 或更高版本。
npm：随 Node.js 一并安装。

2. 克隆仓库与安装依赖

git clone https://github.com/yebin1982/orbitmapper-cn.git
cd orbitmapper-cn

# 安装依赖
npm install

3. 本地启动开发服务器

npm run dev

启动成功后，浏览器打开 http://localhost:5173 即可预览应用。

[!NOTE] 在本地纯前端开发模式下，由于生产相对路径 /api/tle 尚未绑定网关，系统默认优先使用浏览器 LocalStorage 中的缓存数据，或可通过配置环境变量 VITE_ESA_WORKER_URL 将请求指向已部署的 ESA 边缘函数地址。

🚢 生产构建与部署

1. 本地打包构建

npm run build

打包成功后，编译产物将输出至 ./dist 目录。

2. 部署至阿里云 ESA (推荐生产方式)

本项目已全面针对 阿里云 ESA (边缘安全加速) / Edge Routine (ER) 进行了深度集成。完整配置步骤请参阅详细教程：

👉 阿里云 ESA 部署与配置全流程指南 (DEPLOYMENT_GUIDE_ESA.md)

核心步骤概括：

站点创建：在阿里云 ESA 控制台添加并绑定站点域名（如 orbitmapper.cn）。
创建 EdgeKV 命名空间：创建名为 ORBIT_CACHE 的 KV 空间。
部署 Edge Routine 边缘函数：
- 将 worker/src/index.js 部署至 ESA 边缘函数，绑定 ORBIT_CACHE 命名空间。
- 配置 Cron 定时器：0 */12 * * *（每 12 小时自动同步数据）。
边缘路由规则：将 /api/tle* 路由转发至该 Edge Routine 边缘函数。
静态站点托管：将 ./dist 打包产物上传至阿里云 OSS 或通过 ESA Pages / CI/CD 自动发布。

⚙️ 环境变量与配置

可在根目录创建 .env 或 .env.production 自定义配置：

变量名	默认值	作用说明
`VITE_ESA_WORKER_URL`	`/api/tle`	边缘函数 API 接入端点（支持绝对地址或同源相对路径）

📡 支持的卫星星座一览

星座标识 (ID)	中文显示名称	轨道类型	包含卫星 / 典型代表
`hulianwang`	星网 Hulianwang	LEO (低轨)	中国星网互联网低轨试验/组网卫星
`qianfan`	千帆 Qianfan	LEO (低轨)	上海垣信“千帆星座”（G60 星座）在轨组网星
`starlink`	星链 Starlink	LEO (低轨)	SpaceX Starlink 低轨宽带星座
`oneweb`	一网 OneWeb	LEO (低轨)	Eutelsat OneWeb 宽带星座
`kuiper`	柯伊伯 Kuiper	LEO (低轨)	Amazon Project Kuiper 前导试验星
`beidou`	北斗 Beidou	MEO / GEO / IGSO	中国北斗三号全球卫星导航系统 (BDS)
`gps-ops`	GPS	MEO (中轨)	美国全球定位系统在轨运行星
`galileo`	伽利略 Galileo	MEO (中轨)	欧洲民用高精度导航星座
`glo-ops`	格洛纳斯 GLONASS	MEO (中轨)	俄罗斯全球卫星导航系统
`ses`	SES 卫星群	MEO / GEO	SES 国际中高轨商业通信卫星
`geo`	地球同步 GEO	GEO (赤道静止)	全球地球同步轨道气象/广播通信卫星群

⚖️ 免责与法律声明

学术与科普目的：本平台仅供航天爱好者、高校师生及空间技术研究人员用于学术研讨、空间科普与轨道可视化演示，不用于任何军事、防御或敏感商业行动。
数据公开性：所有卫星两行根数 (TLE) 均来源于公开发布的国际轨道数据源（如 CelesTrak / Space-Track），本平台不对原始根数发布之完整性、绝对精度及实时性做商业担保。
无官方关联：本项目为独立开源技术探索，与中国星网、上海垣信、SpaceX 等商业实体或官方机构无隶属关联。

🤝 鸣谢与参考

CelesTrak - 提供长期稳定权威的公开卫星轨道 TLE 根数数据
NASA Earth Observatory - 提供高精度 Blue Marble 与 Night Lights 纹理贴图
satellite.js - 优秀的 SGP4/SDP4 轨道计算 JavaScript 实现
Three.js & React Three Fiber - 强大优雅的 Web 3D 渲染框架
Alibaba Cloud ESA - 为项目提供边缘算力加速与 EdgeKV 缓存支持

📄 开源许可证

本项目采用 MIT License 开源许可。欢迎提交 Issue 与 Pull Request！

OrbitMapper 3D 实时卫星轨道可视化系统

应用与工程截图