# God’s Eye View 独立技术实测报告

- 实测日期：2026-08-27（UTC）
- 仓库：`https://github.com/bilawalsidhu/gods-eye-view`
- Commit：`b22573a9db28e47c324821ebdd4c67bdb241c0e1`
- Commit 时间：`2026-08-27T14:44:52-05:00`
- Commit 标题：`Streamline README: AI-assisted setup instructions, walkthrough video, consolidated demo flow`
- 测试环境：Linux 容器，Node.js `v24.19.0`，npm `11.9.0`
- 结论等级：**代码可安装、可构建、纯逻辑测试断言全部通过；没有 Google Maps Key 时无法进入主要交互界面；浏览器回归测试受当前容器权限限制，未完成视觉与真实数据验收。**

## 1. 仓库与文件结构

这是一个 Vite + Cesium 的浏览器应用，同时用 `vite.config.js` 实现本地数据代理。它不是只有静态网页的演示仓库。

主要结构：

- `src/`：315 个文件，包含主界面、Cesium 地球、飞机/船舶/卫星/地震/CCTV 等数据层、语音控制及大量单元测试。
- `scripts/`：51 个文件，包含启动脚本、测试调度器、Puppeteer QA 和回归工具。
- `public/`：15 个文件。
- `vite.config.js`：除 Vite 配置外，还包含 OpenSky、CelesTrak、TomTom、FIRMS、Google Places、OpenAI Realtime、AISStream、CCTV、Radio Browser 等本地代理。
- 构建产物 `dist/`：419 个文件，约 31 MB。
- 安装后整个目录约 472 MB。

`package.json` 要求 Node：

```text
>=24.14.0 <25 || >=26 <27
```

当前 Node `24.19.0` 符合要求。

官方脚本：

```text
dev            vite
dev:secure     ./scripts/dev-secure.sh
opensky:import ./scripts/opensky-import-client.sh
build          vite build
preview        vite preview
test           node scripts/run-unit-tests.mjs
test:track     node scripts/track-regression.mjs
qa:map-source-tray node scripts/qa-map-source-tray.mjs
```

直接依赖：`@mapbox/vector-tile`、`cesium`、`egm96-universal`、`mgrs`、`pbf`、`satellite.js`。

开发依赖：`puppeteer`、`sharp`、`vite`、`vite-plugin-cesium`、`ws`。

## 2. 安装与依赖检查

### 安装

第一遍使用 `npm ci --ignore-scripts` 隔离安装脚本，退出码 `0`，安装 201 个包。确认安装脚本来源后，再执行官方形式的 `npm ci`，退出码同样为 `0`，安装 201 个包。

根项目没有 `preinstall`、`install` 或 `postinstall`。锁文件标出的传递依赖安装脚本来自：

- `esbuild@0.25.12`
- `fsevents@2.3.3`
- `puppeteer@24.37.5`
- `sharp@0.34.5`

这些是构建二进制、平台适配或下载浏览器所用的供应链脚本，并非项目自行添加的安装钩子。它们仍然意味着 `npm ci` 不是“零安装脚本”。

安装只出现两类警告：npm 的 `http-proxy` 环境配置未来将不再支持；`sourcemap-codec@1.4.8` 已弃用。没有安装错误。

### 漏洞数据库

执行：

```bash
npm audit --omit=dev --json
```

退出码 `0`。生产依赖报告为 `0` 个已知漏洞（info/low/moderate/high/critical 均为 0）。这只能说明 npm 当前数据库没有命中，不能代替源码安全审计。

## 3. 静态安全检查

### 密钥

对 Git 跟踪源码执行常见 Google、OpenAI、GitHub、AWS 和私钥模式扫描；排除大型公开地理数据和锁文件后，没有发现硬编码真实密钥。

`.env.example` 只有占位值。`.env` 被 `.gitignore` 排除。

密钥边界：

- `OPENAI_API_KEY`、`AISSTREAM_API_KEY`、OpenSky OAuth、FIRMS、TomTom 等由本地 Vite 代理读取，设计上不发送给浏览器。
- `GOOGLE_MAPS_API_KEY` 和 `CESIUM_ION_TOKEN` 会被明确注入浏览器包，用户可在 DevTools 中看到。这是项目的设计选择，必须在提供商端设置 HTTP Referrer、API 和 URL 限制。
- 代码中存在从 macOS Keychain 读取密钥的启动脚本，但本次没有调用，也没有读取或索取任何凭据。

### 网络与代理

项目会访问大量外部公共数据源，不能描述成“纯离线”。主要包括 Google Maps/Places、OpenAI、OpenSky、AISStream、CelesTrak、NASA FIRMS、TomTom、OSM Overpass/Nominatim、Open-Meteo、GDELT、Google News、Radio Browser 等。

代码和 `SECURITY.md` 显示了这些保护：

- 默认绑定 `localhost`，`allowedHosts` 限制为 `localhost`、`127.0.0.1`、`.local`。
- 只有显式设置 `HOST=0.0.0.0` 或 `::` 才开放所有 Host。
- CCTV 客户端不能传入任意上游 URL；服务端只使用已登记来源。
- Radio Browser 对协议、主机、路径、重定向及私有/环回/链路本地/元数据地址进行限制。
- 高风险请求路径有请求体、响应体、超时、缓存或速率方面的边界。
- OpenAI 和 Google 的应用层每 IP 限速是**可选项，默认关闭**；真正的费用保护仍需在提供商后台设预算和配额。

风险判断：默认本机运行边界较合理；如果把 Vite 服务直接开放到局域网或公网，任何可访问者都可能调用代理并消耗配置的额度。项目自己的 `SECURITY.md` 也明确说明它不是强化后的生产服务。

### 子进程

发现的 `child_process` 使用集中在测试/QA：

- `scripts/run-unit-tests.mjs`
- `scripts/qa-l9-matrix.mjs`
- 三个 mutation QA 脚本
- 两个 `*.test.mjs`

没有在面向浏览器的生产功能代码中发现将用户输入送入 shell 的路径。

## 4. 测试与构建

### 单元测试

执行：

```bash
npm test
```

可见测试汇总：

```text
tests 2587
pass 2587
fail 0
skipped 0
```

随后独立的 focus allocation 检查也显示：

```text
tests 1
pass 1
fail 0
```

但是，测试命令在上述汇总后仍未自然退出，等待超过 90 秒后人工中断，最终退出码 `130`。因此准确结论是：**2588 个可见断言全部通过，但官方 `npm test` 在当前环境存在残留句柄或进程未退出问题，不能记为完整的退出码 0 通过。**

### 生产构建

执行：

```bash
npm run build
```

退出码 `0`，Vite 在 6.67 秒完成构建。主要警告：

- 两个模块引用的 `node:fs` 被 Vite 外部化以兼容浏览器。
- 若干 bundle 超过 1.5 MB；最大列出的 `egm96-universal` 产物约 2.77 MB，gzip 约 1.85 MB。

这些警告未阻止构建，但说明首屏体积和代码拆分值得实测。

### 无密钥启动与接口

清除 Google、OpenAI、AIS、Cesium、TomTom、FIRMS 相关环境变量后启动本地 Vite 服务：

- `/`：HTTP `200`，能返回 HTML 外壳。
- `/api/realtime/token`：HTTP `503`，明确返回 `OPENAI_API_KEY is not set`。
- `/api/google/nearby-places`：HTTP `503`，明确返回 `GOOGLE_MAPS_API_KEY is not set`。
- `/api/firms/status`：HTTP `200`，`hasKey:false`。
- `/api/ais-live/status`：HTTP `503`，明确返回 `AISSTREAM_API_KEY is not set`。
- `/api/tomtom/status`：HTTP `200`，`hasKey:false`，应用可使用模拟交通。

### 3D 跟踪回归

首次在未启动服务时执行 `npm run test:track`，退出码 `2`，正确提示服务器不可达。

随后启动服务器并指定 URL 再执行回归工具。它找到了 Puppeteer 下载的 Chrome，但 Chrome 因当前容器禁止创建 process singleton socket 而崩溃：

```text
socket() failed: Operation not permitted (1)
```

命令退出码 `2`。这是测试容器权限限制，不是应用断言失败；但也意味着本报告没有完成真实 Chrome、WebGL、拖动、聚焦、地图瓦片和截图验收。

## 5. 没有 Google Maps Key 能做到哪一步

可以完成：

- 克隆和阅读代码。
- `npm ci` 安装。
- 运行纯逻辑单元测试。
- `npm run build` 生成完整静态产物。
- 启动 Vite 服务并访问 HTML 外壳。
- 检查各个代理的无密钥降级响应。

不能完成：

- 进入项目的主要可交互地球界面。`src/main.js` 在初始化阶段明确检查 `GOOGLE_MAPS_API_KEY`，缺少时直接抛错。
- 加载 Google Photorealistic 3D Tiles。
- 对拖动、聚焦节点/目标、3D 地球视觉、地图瓦片结算进行真实验收。
- 使用 Google Places 位置上下文。

其他可选功能分别还需要 OpenAI、AISStream、FIRMS、TomTom、Cesium ion 或 OpenSky 凭据；部分功能存在无钥匙数据源或模拟降级，但它们不能绕过主界面对 Google Maps Key 的初始化硬门槛。

README 中“Most of the globe is zero keys”和“All of them are optional to start”一类表述容易让人误读。就当前 commit 的实际代码而言，**Google Maps Key 是启动主要应用体验的必需条件，而且是可计费凭据。**

## 6. 最终判断

### 已核验

- 仓库可正常安装，Node 版本约束明确。
- 生产构建成功。
- 2588 个可见测试断言为 0 失败。
- 生产依赖 npm audit 未发现已知漏洞。
- 未发现硬编码真实密钥。
- 私密服务密钥大多走服务端代理；Google Maps 和 Cesium token 会主动暴露给客户端。
- 默认本机绑定和代理目的地约束具备基础安全设计。

### 未通过或未完成

- `npm test` 汇总通过后未自然退出，不能宣称官方测试命令完整通过。
- 当前容器无法启动 Puppeteer Chrome，3D 跟踪与视觉 QA 未完成。
- 无 Google Maps Key 时主要应用初始化失败，无法进行端到端使用实验。
- 未验证真实外部数据的准确性、实时性、费用、速率限制和服务条款。

### 下一步实测条件

如需进入完整视觉实测，必须在用户自行控制的环境中配置一个已限制来源、限制 API、设置预算/配额的 Google Maps Key，并在允许启动 Chrome/WebGL 的桌面环境运行。此步骤涉及可计费凭据，本次实验没有执行，也没有索取凭据。