跳转到主要内容
本指南涵盖在本地设置 WorldMonitor 所需的一切,从先决条件和安装到理解项目结构和 API 依赖。

技术栈

技术用途
语言TypeScript 5.x为 60+ 源文件提供类型安全
构建Vite快速 HMR,优化的生产构建
地图(桌面)deck.gl + MapLibre GL为大型数据集提供 WebGL 加速渲染
地图(移动)D3.js + TopoJSONSVG 备选以节省电池
并发Web Workers主线程外聚类和关联
AI/MLONNX Runtime Web基于浏览器的离线推理用于摘要
网络WebSocket + REST实时 AIS 流,其他 API 使用 HTTP
存储IndexedDB快照、基线(兆字节级状态)
偏好设置LocalStorage用户设置、监视器、面板顺序
部署Vercel Edge全球分布的无服务器代理

地图渲染架构

地图使用针对每个平台优化的混合渲染策略: 桌面(deck.gl + MapLibre GL)
  • WebGL 加速图层可平滑处理数千个标记
  • MapLibre GL 提供底图瓦片(OpenStreetMap)
  • GeoJSON、散点图、路径和图标图层用于不同数据类型
  • 基于 GPU 的聚类和拾取以实现响应式交互
移动(D3.js + TopoJSON)
  • SVG 渲染以节省电池
  • 减少标记数量和简化图层
  • 触摸优化的交互,更大的命中区域
  • WebGL 不可用时自动降级

关键库

  • deck.gl:高性能 WebGL 可视化图层
  • MapLibre GL:开源地图渲染引擎
  • D3.js:SVG 地图渲染、缩放行为(移动端备选)
  • TopoJSON:高效的地理数据编码
  • ONNX Runtime:基于浏览器的 ML 推理
  • 自定义 HTML 转义:XSS 防护(DOMPurify 模式)

不使用外部 UI 框架

整个 UI 是手工制作的 DOM 操作,不使用 React、Vue 或 Angular。这使得包体积小(gzipped 后约 250KB),并提供对渲染性能的精细控制。

构建时配置

Vite 在构建时注入配置值,启用自动版本同步等功能:
变量来源用途
__APP_VERSION__package.json 版本字段页眉显示当前版本
这确保显示的版本始终与发布的包匹配,无需手动同步。
// vite.config.ts
define: {
  __APP_VERSION__: JSON.stringify(pkg.version),
}

// App.ts
const header = `World Monitor v${__APP_VERSION__}`;

安装

WorldMonitor 有三种设置路径,具体取决于你要做什么。

1. 仅应用本地开发

运行 Vite 仪表盘,无需环境变量。可选的 API 密钥(见下文)可解锁额外的图层和数据源。
git clone https://github.com/koala73/worldmonitor.git
cd worldmonitor
npm install
npm run dev          # http://localhost:5173
变体仪表盘可从同一检出运行:npm run dev:techdev:financedev:commoditydev:happydev:energy

2. 贡献者 / 完整代码生成开发

当你修改 .proto 合约或重新生成客户端时需要。需要 Go 1.21+(用于 buf CLI 和 sebuf protoc 插件)以及 Node.js 22+
make install         # buf, sebuf plugins, npm deps, proto deps, Playwright browsers
make generate        # regenerate TypeScript clients, servers, and OpenAPI docs
npm run dev
每当修改 .proto 文件时,在构建或推送之前运行 make generate — 如果生成的输出与提交的文件不一致,CI 的 proto-check.yml 会失败。完整的 proto 工作流请参见添加端点

3. 自托管 Docker 栈

完整的自托管栈(仪表盘 + Railway 式中继 + Redis + 种子脚本)需要 Node.js 22+、Docker 或 Podman,以及没有安全默认值的密钥 — RELAY_SHARED_SECRETREDIS_PASSWORDREDIS_TOKEN 必须在 docker compose up 之前设置。完整的操作步骤请参见仓库中的 SELF_HOSTING.md 指南。

API 依赖

仪表盘从各种公共 API 和数据源获取数据:
服务数据需要认证
RSS2JSON新闻源解析
Finnhub股票报价(主要)是(免费)
Yahoo Finance股票指数和大宗商品(备份)
CoinGecko加密货币价格
USGS地震数据
NASA EONET自然事件(风暴、火灾、火山、洪水)
NWS天气警报
FRED经济指标(美联储数据)
EIA石油分析(价格、产量、库存)是(免费)
USASpending.gov联邦政府合同和拨款
Polymarket预测市场
ACLED武装冲突和抗议数据是(免费)
GDELT Geo新闻衍生的事件地理定位 + 紧张局势
GDELT Doc基于主题的情报源(网络、军事、核)
FAA NASSTATUS机场延误状态
Cloudflare Radar互联网中断数据是(免费)
AISStream实时船舶位置是(中继)
OpenSky Network军用飞机追踪是(免费)
Wingbits飞机增强(所有者、运营方)是(免费)
PizzINT五角大楼区域活动指标

可选 API 密钥

某些功能需要 API 凭证。没有它们,相应的图层会被隐藏:
变量服务获取方式
FINNHUB_API_KEY股票报价(主要)finnhub.io 免费注册
EIA_API_KEY石油分析eia.gov/opendata 免费注册
VITE_WS_RELAY_URLAIS 船舶追踪部署 AIS 中继或使用托管服务
VITE_OPENSKY_RELAY_URL军用飞机使用 OpenSky 凭证部署中继
OPENSKY_CLIENT_IDOpenSky 认证(中继)opensky-network.org 免费注册
OPENSKY_CLIENT_SECRETOpenSky 认证(中继)从 OpenSky 账户设置获取 API 密钥
CLOUDFLARE_API_TOKEN互联网中断具备 Radar 访问权限的免费 Cloudflare 账户
ACLED_ACCESS_TOKEN抗议数据(服务器端)在 acleddata.com 免费注册
WINGBITS_API_KEY飞机增强联系 Wingbits 获取 API 访问权限
仪表盘在没有这些密钥的情况下也能完全运行。受影响的图层只是不会显示。核心功能(新闻、市场、地震、天气)无需配置。

项目结构

src/
├── App.ts                    # Main application orchestrator
├── main.ts                   # Entry point
├── components/
│   ├── DeckGLMap.ts          # WebGL map with deck.gl + MapLibre (desktop)
│   ├── Map.ts                # D3.js SVG map (mobile fallback)
│   ├── MapContainer.ts       # Map wrapper with platform detection
│   ├── MapPopup.ts           # Contextual info popups
│   ├── SearchModal.ts        # Universal search (Cmd+K)
│   ├── SignalModal.ts        # Signal intelligence display with focal points
│   ├── PizzIntIndicator.ts   # Pentagon Pizza Index display
│   ├── VirtualList.ts        # Virtual/windowed scrolling
│   ├── InsightsPanel.ts      # AI briefings + focal point display
│   ├── EconomicPanel.ts      # FRED economic indicators
│   ├── GdeltIntelPanel.ts    # Topic-based intelligence (cyber, military, etc.)
│   ├── LiveNewsPanel.ts      # YouTube live news streams with channel switching
│   ├── NewsPanel.ts          # News feed with clustering
│   ├── MarketPanel.ts        # Stock/commodity display
│   ├── MonitorPanel.ts       # Custom keyword monitors
│   ├── CIIPanel.ts           # Country Instability Index display
│   ├── CascadePanel.ts       # Infrastructure cascade analysis
│   ├── StrategicRiskPanel.ts # Strategic risk overview dashboard
│   ├── StrategicPosturePanel.ts # AI strategic posture with theater analysis
│   ├── ServiceStatusPanel.ts # External service health monitoring
│   └── ...
├── config/
│   ├── feeds.ts              # 500+ RSS feeds, source tiers, regional sources
│   ├── geo.ts                # 30+ hotspots, conflicts, 86 cables, waterways, spaceports, minerals
│   ├── pipelines.ts          # 88 oil & gas pipelines
│   ├── ports.ts              # 62 strategic ports worldwide
│   ├── bases-expanded.ts     # 226 military bases
│   ├── ai-datacenters.ts     # 313 AI compute clusters (Epoch AI dataset)
│   ├── airports.ts           # 111 airports across 5 regions
│   ├── irradiators.ts        # IAEA gamma irradiator sites
│   ├── nuclear-facilities.ts # Global nuclear infrastructure
│   ├── markets.ts            # Stock symbols, sectors
│   ├── entities.ts           # 66 entity definitions (companies, indices, commodities, countries)
│   └── panels.ts             # Panel configs, layer defaults, mobile optimizations
├── services/
│   ├── ais.ts                # WebSocket vessel tracking with density analysis
│   ├── military-vessels.ts   # Naval vessel identification and tracking
│   ├── military-flights.ts   # Aircraft tracking via OpenSky relay
│   ├── military-surge.ts     # Surge detection with news correlation
│   ├── cached-theater-posture.ts # Theater posture API client with caching
│   ├── wingbits.ts           # Aircraft enrichment (owner, operator, type)
│   ├── pizzint.ts            # Pentagon Pizza Index + GDELT tensions
│   ├── protests.ts           # ACLED + GDELT integration
│   ├── gdelt-intel.ts        # GDELT Doc API topic intelligence
│   ├── gdacs.ts              # UN GDACS disaster alerts
│   ├── eonet.ts              # NASA EONET natural events + GDACS merge
│   ├── flights.ts            # FAA delay parsing
│   ├── outages.ts            # Cloudflare Radar integration
│   ├── rss.ts                # RSS parsing with circuit breakers
│   ├── markets.ts            # Finnhub, Yahoo Finance, CoinGecko
│   ├── earthquakes.ts        # USGS integration
│   ├── weather.ts            # NWS alerts
│   ├── fred.ts               # Federal Reserve data
│   ├── oil-analytics.ts      # EIA oil prices, production, inventory
│   ├── usa-spending.ts       # USASpending.gov contracts & awards
│   ├── polymarket.ts         # Prediction markets (filtered)
│   ├── clustering.ts         # Jaccard similarity clustering
│   ├── correlation.ts        # Signal detection engine
│   ├── velocity.ts           # Velocity & sentiment analysis
│   ├── related-assets.ts     # Infrastructure near news events
│   ├── activity-tracker.ts   # New item detection & highlighting
│   ├── analysis-worker.ts    # Web Worker manager
│   ├── ml-worker.ts          # Browser ML inference (ONNX)
│   ├── summarization.ts      # AI briefings with fallback chain
│   ├── parallel-analysis.ts  # Concurrent headline analysis
│   ├── storage.ts            # IndexedDB snapshots & baselines
│   ├── data-freshness.ts     # Real-time data staleness tracking
│   ├── signal-aggregator.ts  # Central signal collection & grouping
│   ├── focal-point-detector.ts   # Intelligence synthesis layer
│   ├── entity-index.ts       # Entity lookup maps (by alias, keyword, sector)
│   ├── entity-extraction.ts  # News-to-entity matching for market correlation
│   ├── country-instability.ts    # CII scoring algorithm
│   ├── geo-convergence.ts        # Geographic convergence detection
│   ├── infrastructure-cascade.ts # Dependency graph and cascade analysis
│   └── cross-module-integration.ts # Unified alerts and strategic risk
├── workers/
│   └── analysis.worker.ts    # Off-thread clustering & correlation
├── utils/
│   ├── circuit-breaker.ts    # Fault tolerance pattern
│   ├── sanitize.ts           # XSS prevention (escapeHtml, sanitizeUrl)
│   ├── urlState.ts           # Shareable link encoding/decoding
│   └── analysis-constants.ts # Shared thresholds for worker sync
├── styles/
└── types/
api/                          # Vercel Edge Functions (two kinds, see Architecture)
├── <domain>/v<N>/[rpc].ts    # Generated domain gateways — aviation, market,
│                             #   conflict, climate, cyber, sanctions, maritime,
│                             #   resilience, ... (34 proto-backed domains)
├── bootstrap.js              # Two-tier Redis hydration for the SPA
├── health/                   # Per-key freshness + cascade status
├── mcp.ts / mcp-proxy.ts     # Model Context Protocol server endpoints
├── create-checkout.ts        # Stripe checkout (hand-written operational)
├── customer-portal.ts        # Stripe billing portal (hand-written operational)
├── user-prefs.ts             # User preference sync (hand-written operational)
└── notify.ts                 # Notification dispatch (hand-written operational)
server/                       # Server-side handlers (bundled into Edge functions)
├── gateway.ts                # createDomainGateway — per-domain Edge bundles
├── worldmonitor/<domain>/    # 34 proto-backed domain handler implementations
└── _shared/                  # Redis client, source tiers, shared utilities
旧版修订中描述的扁平 api/*.js 代理已被 proto 生成的领域网关取代。完整的请求路径请参见架构文档。

数据归属

本项目使用来自以下数据源的数据。请尊重其使用条款。

飞机追踪

数据由 The OpenSky Network 提供。如果你在出版物中使用此数据,请引用:
Matthias Schafer、Martin Strohmeier、Vincent Lenders、Ivan Martinovic 和 Matthias Wilhelm。“Bringing Up OpenSky: A Large-scale ADS-B Sensor Network for Research”。载于《第 13 届 IEEE/ACM 传感器网络信息处理国际研讨会(IPSN)论文集》,第 83-94 页,2014 年 4 月。

冲突与抗议数据

  • ACLED:武装冲突位置与事件数据。来源:ACLED。数据必须根据其归属政策进行归属。
  • GDELT:事件、语言和语调全球数据库。来源:The GDELT Project

金融数据

  • 股票报价:由 Finnhub 提供(主要),Yahoo Finance 作为指数和大宗商品的备份
  • 加密货币:由 CoinGecko API 提供
  • 经济指标:数据来自 FRED,圣路易斯联邦储备银行

地球物理数据

基础设施与交通

其他来源

致谢

最初的仪表盘概念受 Reggie James(@HipCityReg)启发,感谢他对综合态势感知工具的愿景。 特别感谢 Wingbits 的 Yanal 提供 API 访问权限以获取飞机增强数据,从而实现军用飞机分类和所有权追踪。 感谢 @fai9al 的启发和原始 PR,促成了 Tech Monitor 变体。

限制与注意事项

本项目是一个概念验证,展示使用公开数据可能实现的功能。虽然可用,但存在重要限制:

数据完整性

某些数据源需要付费账户才能获得完整访问:
  • ACLED:免费层有 API 限制;编程访问需要研究层
  • OpenSky Network:有速率限制;商业层提供更高配额
  • 卫星 AIS:全球覆盖需要商业提供商(Spire、Kpler 等)
仪表盘可在免费层下工作,但可能存在覆盖范围或更新频率方面的差距。

AIS 覆盖偏差

船舶图层使用通过 AISStream.io 的陆地 AIS 接收器。这造成了地理偏差
  • 覆盖较强:欧洲水域、大西洋、主要港口
  • 覆盖较弱:中东、开阔海域、偏远地区
陆地接收器只能检测到距岸约 50km 范围内的船舶。卫星 AIS(商业)提供真正的全球覆盖,但未包含在此免费实现中。

被封锁的数据源

某些发布商封锁来自云提供商(Vercel、Railway、AWS)的请求:
  • 来自某些媒体的 RSS 源可能因 403 错误而失败
  • 这是常见的反机器人措施,不是仪表盘的 bug
  • 受影响的源通过熔断器自动禁用
系统会优雅降级。被封锁的源会被跳过,而其他源继续运行。

许可证

World Monitor 采用 GNU Affero General Public License v3.0 (AGPL-3.0-only) 许可。当你遵守其 copyleft 和源代码可用条款时,AGPL 允许商业使用。对于私有源代码或定制合同条款,可另行获取商业许可作为替代选项。完整详情请参见许可证页面。

作者

Elie Habib
为态势感知和开源情报收集而构建。