God's Eye View 本地运行指南：一键或终端，5 分钟选对启动方式

【免费下载链接】gods-eye-viewA spy satellite simulator in your browser, except the data is real. Live open source spatial intelligence on a photorealistic 3D globe.项目地址: https://gitcode.com/GitHub_Trending/go/gods-eye-view

God's Eye View 是跑在浏览器里的实时 3D 地球情报台：照片级地球叠加真实公开数据，飞机、船舶、卫星、地震、城市摄像头全部在线。这篇本地运行教程解决一个问题——把它在你电脑上跑起来。5 分钟、不花一分钱、不用任何 Key，卡住有排障表，跑通有验收清单。

🧭 30 秒自检：你该走哪条路

• 你愿意打开命令行吗？不愿意——直接走 Pinokio 一键路径；愿意且装过 Node——直接走终端路径。
• 以后想不想改代码、加图层、提 PR？想——终端路径；只是想看看效果——Pinokio。
• 你在 Windows / macOS / Linux 哪台机器上？三条都支持；普通用户默认选 Pinokio。

两条路打开的是同一个应用，端口、图层、功能完全一致，随时可以切换，不必纠结。

🚀 最快路径：3 步跑通 God's Eye View 一键启动

第 1 步：把启动器升到 8.2 以上。操作：安装（或更新）Pinokio 到8.2 或更高版本。 该看到的：Pinokio 能正常打开应用列表页。 没看到怎么办：旧版 8.0.40 有安装缺陷，升级 Pinokio 本身即可，别急着重装应用。

第 2 步：安装 God's Eye View。操作：在 Pinokio 里搜到God's Eye View，点Install，等它跑完。 该看到的：安装脚本跑完无报错，应用页出现Start按钮（菜单定义在 pinokio/pinokio.js，Install / Start / Update / Repair 四个动作一目了然）。 没看到怎么办：报"安装失败"就跳到下方自救表第 1 条。

第 3 步：启动并打开页面。操作：点Start，等浏览器自动弹出页面。 该看到的：浏览器打开一个127.0.0.1的本地地址（端口由启动器自动找空闲的，不是固定值），出现 3D 地球和首次运行面板——四个任务：Live Contacts（实时航空）、Space Missions（太空任务）、Environmental（环境层）、Explore Manually（自由探索）。选一个，地球开始转，数据开始流。 没看到怎么办：卡在 "Starting" 超过 1 分钟，点菜单里的Repair installation（对应 pinokio/reset.js）一键修复。

启动逻辑本身在 pinokio/start.js：服务绑定127.0.0.1，所有 Key 从应用内环境文件读取，没配 Key 也照常启动。

⌨️ 另一条路：给想深挖 God's Eye View 源码的人

只说和上面不一样的地方。

• 环境要求更硬：Node.js24.14.0+（24.x）或 26.x，Node 25 已停止维护，体检脚本会直接报错；版本范围与 package.json 的engines字段一致。
• 命令不同，克隆后在项目目录里依次执行：

git clone https://gitcode.com/GitHub_Trending/go/gods-eye-view cd gods-eye-view npm ci npm run doctor npm run dev

npm ci装锁定版本依赖；npm run doctor做体检（Node/npm 版本、各数据源主链路可达性、Key 从哪里读到——不打印密钥明文，逻辑在 scripts/setup-doctor.mjs），不建议跳过；npm run dev起服务后打开http://localhost:4173，固定端口，与一键路径的随机空闲端口不同。

• 首次运行面板、无 Key 可用图层：同②，不再重复。
• 密钥位置不同：写入仓库根目录的.env（一键路径写pinokio/ENVIRONMENT，见后文）。
• macOS 专属捷径：./scripts/dev-fresh.sh会清 Vite 缓存，还能直接从 macOS 钥匙串（Keychain）拉取已存的密钥，同样支持无 Key 启动。
• 启动有多快：官方在 Apple M5 + Chrome 环境实测冷启动中位数约1.86 秒（单次对比基线，不代表你的机器），数据详见 docs/PERFORMANCE.md。

🩹 卡住了？照这张表自救

• 症状：Pinokio 点 Install 失败或卡在 Installing。大概率原因：Pinokio 版本低于 8.2（8.0.40 有已知安装缺陷）。解法：升级 Pinokio 到 8.2+ 重试；仍失败就点Repair installation。
• 症状：终端跑npm run dev报依赖缺失或启动异常。大概率原因：没跑npm ci或跑了一半。解法：回到项目目录重跑npm ci，再npm run doctor确认[OK]全绿。
• 症状：doctor 报 Node 版本 ERROR。大概率原因：Node 低于 24.14.0 或正处在已停止维护的 25.x。解法：换成 Node 24.14.0+ 或 26.x 后重跑 doctor。
• 症状：浏览器打开http://localhost:4173提示无法访问。大概率原因：服务没起来，或 4173 端口被其他程序占用。解法：看终端里 Vite 的日志先找报错；确认端口被占就换端口，例如PORT=4174 npm run dev。
• 症状：Traffic、Mapped Installations、ALPR 图层全是空的。大概率原因：你跑的是旧版本——旧版查询的 Overpass 公开服务器已拒绝其请求。解法：更新到最新版再启动。
• 症状：局域网里另一台设备打不开你的地球仪。大概率原因：不是故障，服务默认只绑定 localhost。解法：官方设计如此，LAN 共享的开关与风险见 SECURITY.md。

✅ 跑通 ≠ 完成：90 秒验收清单

• 首次运行面板出现 4 个任务选项。做对了长这样：Live Contacts / Space Missions / Environmental / Explore Manually 四项都在，点谁地球就往谁飞。
• Live Flights 图层里点一架飞机。做对了长这样：相机锁定该目标，身后画出航迹，弹出实时遥测卡片（高度、速度、航班号）。
• 对锁定中的飞机按C进 Cockpit。做对了长这样：视角贴着真实地形下潜，跟机飞行，还能中途切换 NVG / FLIR 传感器。
• 打开 Satellites 图层，点击 ISS。做对了长这样：相机以轨道距离跟飞，轨道环实时显示。
• 按1–7切换光学滤镜。做对了长这样：整个地球在 CRT、NVG、FLIR 等传感器风格之间实时重渲染。

5 项全部对得上，说明两条主链路（实时数据 + 3D 渲染）都正常。想继续了解架构，读 docs/CURRENT-STATE.md 和 docs/APPLICATION.md。

🔑 可选项：Key、花费与上限

所有 Key 都不是启动门槛，是"升级项"。想加就点右下角POWER UP芯片，在应用内 Provider Settings 里粘贴，不用手改任何文件。

另外还有 TomTom（真实路况配色）和 Mapillary（街景）两个免费档 Key，加不加随意。密钥存放位置随入口不同：一键路径写pinokio/ENVIRONMENT，终端路径写.env——两个文件落盘前都会先设成"仅所有者可读写"，且都不进版本库。安全边界一句话：服务器默认只绑定 localhost，外部访问不到；要开 LAN 共享的风险与限制看 SECURITY.md。

决策卡：照着你的情况选

• 若你想最快看到效果、完全不想碰命令行，就选Pinokio。
• 若你是 Windows / Linux 普通用户，就选Pinokio（官方跨平台测试完善）。
• 若你要读源码、加数据层、提 PR，就选终端（配合 CONTRIBUTING.md）。
• 若你跑在无头服务器或 CI 里，就选终端，Key 用环境变量直接注入。
• 若你在 macOS 且密钥已经存在钥匙串，就选终端跑./scripts/dev-fresh.sh，一键取钥免粘贴。

最后必须说清楚数据边界：本项目是公开数据的探索性可视化，数据可能存在延迟、缺失或推断成分。请不要用它做飞行/航海导航、应急决策或投资判断。

【免费下载链接】gods-eye-viewA spy satellite simulator in your browser, except the data is real. Live open source spatial intelligence on a photorealistic 3D globe.项目地址: https://gitcode.com/GitHub_Trending/go/gods-eye-view