AI 驱动的实时全球情报仪表板
v2.5.24 · 2026-03-03 · GitHub: koala73/worldmonitor

项目概览

维度详情
项目名称World Monitor (worldmonitor.app)
当前版本v2.5.24（最新提交 2026-03-03）
开源协议AGPL v3（商业使用需注意）
主技术栈TypeScript + Vite + deck.gl + MapLibre GL JS
后端/APIVercel Edge Functions + Railway 中继服务器
数据库/缓存Upstash Redis（跨用户 AI 去重）+ IndexedDB（客户端 RAG）
桌面端Tauri（macOS / Windows / Linux 原生应用）
AI 支持Ollama（本地）/ Groq / OpenRouter / Transformers.js（浏览器端）
API 设计Proto-first，Protobuf 定义 + 自动生成 TypeScript 客户端/服务端
测试框架Playwright（E2E）
部署平台Vercel（前端 + API）+ Railway（实时中继）

一、整体架构分析

1.1 系统架构全景

WorldMonitor 是一个典型的「全栈单体仓库（Monorepo）」项目，前后端、桌面端、脚本工具均在同一仓库管理。整体可分为五大层次：

层次技术职责
客户端（浏览器/PWA）Vite + TypeScript + deck.gl3D 地图渲染、面板交互、本地 AI 推理
桌面客户端Tauri（Rust 壳 + WebView）macOS/Win/Linux 原生封装
前端 API 层Vercel Edge Functions20 个 Protobuf 服务，鉴权、缓存、限流
实时中继服务Railway Node.js（ais-relay.cjs）AIS 船舶追踪、OpenSky 航班、RSS 代理
数据库/状态Upstash Redis + IndexedDB + ConvexAI 结果缓存、语义索引、邮件注册

1.2 Proto-First API 合约

项目采用 Protobuf + buf CLI 生成所有 API 客户端与服务端代码，共 20 个 TypeScript 服务，涵盖：

  • intelligence — 情报分析：风险评分、事件分类、AI 推演
  • conflict — 冲突追踪：ACLED、UCDP、伊朗事件
  • market — 市场数据：股票、加密货币、ETF、大宗商品
  • economic — 经济指标：FRED、BIS 汇率、能源价格
  • maritime / aviation — 海事 + 航空
  • supply-chain / trade — 供应链、贸易流动
  • news / climate / seismology / wildfire — 新闻、气候、地震、野火
  • displacement / giving — 难民流离、慈善捐助

1.3 AI 推理四级降级链

系统设计了极具韧性的 AI 推理降级策略，确保 UI 永不阻塞：

优先级提供商特点超时
1（最优）Ollama（本地）完全本地，零 API 费用，数据不出机器5 秒
2Groq（云端）免费层 14,400 请求/天，速度快5 秒
3OpenRouter（云端）免费层 50 请求/天，兜底5 秒
4（最终）Transformers.js（浏览器）T5 模型，无需服务端，纯前端运行无限制

1.4 数据源生态

项目整合了超过 30 个外部数据源 API，覆盖从冲突监控到金融市场的完整情报链：

类别数据源
冲突/地缘ACLED、UCDP、GDELT、伊朗战事数据库
金融/市场Finnhub、Yahoo Finance、CoinGecko、BIS、FRED
能源EIA（美国能源信息署）
海事/航空AISStream.io、OpenSky Network、AviationStack、FAA
卫星/自然灾害NASA FIRMS（野火）、USGS（地震）、NASA EONET
气候/人道Open-Meteo、UNHCR（难民数据）、WorldPop
网络安全Cloudflare Radar（互联网中断）
情报媒体100+ RSS 新闻源，含 17 语言地区版本

二、代码结构深度解析

2.1 目录结构说明

目录/文件说明
src/前端核心：组件、服务、Store、工具、国际化
src/components/40+ 功能面板（CII、市场雷达、AI 推演、地缘等）
src/services/数据获取层：航空、冲突、气候等模块化服务
src/workers/Web Workers：AI 嵌入、AIS 解析等后台线程
src/generated/Proto 自动生成的 TS 客户端/服务端代码（不可手改）
server/worldmonitor/20 个 Vercel Edge Functions，按业务域分组
server/_shared/Redis 缓存、限流、响应头等共享工具
scripts/数据构建脚本：军事基地、UCDP 事件种子、GPS 干扰等
proto/Protobuf 协议定义文件（API 合约的唯一真实来源）
src-tauri/Tauri 桌面端 Rust 配置
convex/Convex 数据库（用户注册存储）
data/静态数据：220 军事基地、88 条管道、55 条海底电缆等
deploy/nginx/Nginx 配置（自托管场景）

2.2 前端核心组件分析

项目采用原生 TypeScript（非 React/Vue），通过自定义事件系统实现组件通信：

组件功能复杂度
DeckGLMap.ts3D WebGL 地球，40+ 图层切换，Supercluster 聚合★★★★★
InsightsPanel.tsAI 世界简报，四级 LLM 降级，Redis 去重★★★★☆
CIIPanel.ts国家不稳定性指数，23 个国家基线风险画像★★★★☆
DeductionPanel.tsAI 地缘推演，wm:deduct-context 跨面板联动★★★★☆
MacroSignalsPanel.ts7 信号宏观雷达，BUY/CASH 综合判断★★★☆☆
CountryBriefPage.ts国家情报档案页，可导出 JSON/CSV/图片★★★☆☆
LiveNewsPanel.ts实时新闻，RAG 语义索引，向量数据库（IndexedDB）★★★☆☆
GulfEconomiesPanel.ts海湾经济体实时数据，每 60 秒轮询★★☆☆☆

2.3 关键技术亮点

Headline Memory（RAG 系统）

这是项目最有技术含量的特性之一——完全在浏览器端运行的检索增强生成系统：

  • 使用 ONNX 模型 all-MiniLM-L6-v2（384 维 float32 向量）嵌入每条新闻标题
  • 向量存储在 IndexedDB（worldmonitor_vector_store）中，LRU 淘汰，上限 5000 条
  • 查询时进行暴力余弦相似度搜索，全链路零服务端依赖
  • 嵌入模型运行在专用 Web Worker 中，不阻塞主线程

GPS/GNSS 干扰检测

通过 ADS-B 应答机数据分析 GPS 干扰区域，使用 H3 六边形网格进行空间聚合，干扰强度分级分类，可视化为地图图层。

超簇聚合（Supercluster）

标记点聚合阈值随缩放级别动态调整，不同数据层有差异化聚合逻辑：冲突按国家聚合，科技 HQ 按城市聚合，相互间使用 Haversine 公式去重。

三、问题发现与风险评估

3.1 部署依赖复杂度（⚠ 高风险）

⚠ 落地风险：项目深度依赖 Vercel + Railway 双平台，自托管门槛较高。

必须同时配置以下平台才能完整运行：

  • Vercel：前端托管 + 20 个 Edge Functions + Cron 任务
  • Railway：ais-relay.cjs 中继服务（AIS 船舶 + OpenSky 航班 + RSS 代理 + Telegram OSINT）
  • Upstash Redis：AI 结果跨用户缓存（无此则每个请求都调用 LLM）
  • Convex（可选）：用户邮件注册
❗ 其中 Railway 中继服务是有状态服务，包含 WebSocket 长连接，不能简单替换为 Vercel Serverless。

3.2 API 密钥矩阵（⚠ 中风险）

要解锁所有功能，需要准备至少 12 个外部 API 密钥：

API 密钥用途免费层难度
GROQ_API_KEY主要 AI 推理14,400 次/天简单
OPENROUTER_API_KEY备用 AI 推理50 次/天简单
UPSTASH_REDIS_REST_URL/TOKENAI 结果缓存10,000 命令/天简单
FINNHUB_API_KEY股票行情60 次/分钟简单
EIA_API_KEY能源价格数据无限制简单
FRED_API_KEY美联储经济数据无限制简单
ACLED_ACCESS_TOKEN武装冲突数据需注册为研究者中等
UCDP_ACCESS_TOKEN冲突历史数据免费，2025年需注册中等
NASA_FIRMS_API_KEY卫星野火检测免费简单
CLOUDFLARE_API_TOKEN互联网中断监控需 CF 账户中等
AISSTREAM_API_KEY实时船舶追踪免费层有限简单
OPENSKY_CLIENT_ID/SECRET航班追踪免费，限速较低简单
WINGBITS_API_KEY飞机信息增强需联系商务困难
TELEGRAM_*Telegram OSINT免费，需认证中等

3.3 代码质量问题

问题 1：混合 .ts 和 .mjs 文件

server/worldmonitor/supply-chain/v1/_scoring.mjs 与其他 .ts 文件混用，新闻模块中 dedup.mjs 也存在同样问题，增加了工具链复杂度。

修复方案：将 .mjs 文件统一迁移为 .ts，并在 tsconfig.api.json 中更新 include 路径。

问题 2：静态数据文件体量较大

data/ 目录下存储大量 JSON 静态数据（军事基地、管道、电缆等），部分数据包含经过多次脚本处理的嵌套结构，更新流程不透明。建议建立数据版本追踪机制。

问题 3：缺乏统一错误边界

各个 Panel 组件错误处理不统一，部分 Edge Function 在外部 API 失败时直接返回 500，虽然存在 error-mapper.ts，但覆盖不完整。

问题 4：测试覆盖有限

E2E 测试（Playwright）覆盖了核心页面加载流程，但缺乏单元测试和集成测试，核心算法（CII 评分、focal point 检测、RAG 查询）均未见单元测试。

问题 5：CSP 仍含 unsafe-inline

vercel.json 中 Content-Security-Policy 的 style-src 仍包含 'unsafe-inline'，虽然脚本部分已在 v2.5.24 切换为 hash，但样式端仍存在 XSS 风险。

四、落地部署指南

4.1 快速启动（最小配置）

按以下顺序操作，可以用最少配置让项目跑起来（约 30-60 分钟）：

步骤操作预计时间
1Fork 项目到自己的 GitHub 账号2 分钟
2注册 Vercel 账号，导入 Fork 的仓库5 分钟
3注册 Upstash，创建 Redis 数据库，拷贝 REST URL 和 Token5 分钟
4注册 Groq，获取免费 API Key3 分钟
5在 Vercel 项目设置中添加以上 3 个环境变量5 分钟
6Vercel 自动部署（首次约 3-5 分钟）5 分钟
7访问分配的 Vercel URL，基础功能即可使用验证
8（可选）在 Railway 部署 scripts/ais-relay.cjs，配置 WS_RELAY_URL20 分钟

4.2 环境变量配置优先级

✅ 必须配置（影响核心 AI 功能）：GROQ_API_KEY、UPSTASH_REDIS_REST_URL、UPSTASH_REDIS_REST_TOKEN

⚠️ 建议配置（影响数据完整性）：FINNHUB_API_KEY、FRED_API_KEY、EIA_API_KEY、NASA_FIRMS_API_KEY、ACLED_ACCESS_TOKEN

🔘 可选配置（高级功能）：AISSTREAM_API_KEY（船舶追踪）、OPENSKY_*（航班）、TELEGRAM_*（电报 OSINT）、WINGBITS_*（商业功能）

4.3 Railway 中继服务部署

Railway 中继服务是实现实时数据（船舶/航班/RSS）的关键，独立于 Vercel 部署：

  1. 在 Railway 创建新项目，选择从 GitHub 部署（选 worldmonitor 仓库）
  2. 设置启动命令：node scripts/ais-relay.cjs
  3. 配置 Railway 环境变量：AISSTREAM_API_KEY、OPENSKY_CLIENT_ID、OPENSKY_CLIENT_SECRET、RELAY_SHARED_SECRET
  4. 获取 Railway 部署 URL，在 Vercel 中设置 WS_RELAY_URL=https://your-app.railway.app
  5. 同时在 Vercel 中设置 RELAY_SHARED_SECRET（与 Railway 侧相同的值）
💡 RELAY_SHARED_SECRET 建议用 openssl rand -hex 32 生成，两侧必须一致。

4.4 本地开发环境搭建

  • 环境要求：Node.js 20+、Go 1.21+（如需重新生成 Proto 代码）
  • 执行 cp .env.example .env.local 并填写最小配置
  • 运行 npm install 安装依赖
  • 运行 npm run dev 启动开发服务器（默认 http://localhost:5173）
  • 如需 Proto 代码重新生成：make install && make generate
  • 桌面端开发：npm run tauri（需提前安装 Rust 工具链）

五、优化建议与改进方案

5.1 立即可执行的优化（低成本高收益）

优化 1：统一 .mjs 为 .ts

将 server/worldmonitor/supply-chain/v1/_scoring.mjs 和 server/worldmonitor/news/v1/dedup.mjs 重命名为 .ts，更新 tsconfig.api.json 的 include 路径，消除工具链混乱。

优化 2：添加 API 健康检查端点

在 Vercel 添加 /api/health 端点，汇总所有外部 API 的可用状态，方便运维排查问题。建议返回结构：

{ "redis": "ok", "groq": "ok", "acled": "degraded" }

优化 3：环境变量验证启动

在服务启动时（server/_shared/constants.ts）添加关键环境变量存在性校验，缺失时打印清晰的配置引导消息，而非运行时报错。

优化 4：静态数据版本化

为 data/ 目录中的静态 JSON 文件添加版本字段和最后更新时间戳，在管理界面显示数据新鲜度，并建立定期更新 CI/CD 流水线。

5.2 中期架构优化

优化 5：引入 Zustand 或 Nanostores 状态管理

当前项目使用自定义事件（CustomEvent）进行跨组件通信（如 wm:deduct-context），随着面板增多，事件总线难以追踪。建议引入轻量状态库集中管理应用状态。

优化 6：添加 Vitest 单元测试

为以下核心模块添加单元测试（建议覆盖率 > 70%）：

  • CII 评分算法（src/services/cached-risk-scores.ts）
  • RAG 余弦相似度搜索
  • 新闻去重逻辑（dedup.mjs）
  • 市场信号合成（MacroSignalsPanel）

优化 7：优化 CSP 策略

将 style-src 中的 'unsafe-inline' 替换为严格的 CSP hash 列表（与脚本端已完成的工作对齐），或引入 nonce-based CSP。这需要对所有内联样式进行系统性审计。

优化 8：数据库迁移（可选）

若用户规模扩大，考虑将 Upstash Redis 的 AI 缓存层迁移到 Cloudflare KV 或自托管 Redis，降低长期运营成本。同时评估 Convex 替换为 PlanetScale 或 Neon（更成熟的关系型数据库）。

5.3 功能扩展方向

功能方向实现思路优先级
多用户权限系统在 Convex 中添加 Role/Permission 模型，实现团队共享仪表板高
自定义告警规则允许用户设置「当 CII > 阈值」或「关键词触发」时发送 Email/Webhook 通知高
历史数据回放录制事件时间线，支持「倒带」查看过去 30 天的地缘演变中
报告自动生成定时生成 PDF/DOCX 格式的地区情报周报，通过邮件推送中
移动端 App将 Tauri 换为 Tauri Mobile（目前仍在 beta），或使用 Capacitor 封装低
API 商业化基于现有 Proto API 合约，对外提供付费 API 服务低

六、总体评价与落地建议

6.1 项目综合评分

评估维度评分说明
代码架构设计9 / 10Proto-first API 合约、模块化清晰、多层降级设计优秀
技术栈选型8 / 10deck.gl + MapLibre 组合专业，Tauri 跨端支持完整
功能完整性10 / 1040+ 数据图层、20+ API 服务、4 个变体，业内罕见的全栈情报平台
落地难度6 / 10双平台部署（Vercel+Railway）、12+ API 密钥，有一定门槛
代码质量7 / 10TypeScript 覆盖好，但缺乏单元测试，部分 .mjs 混用
安全性7 / 10v2.5.24 大幅安全加固，但 CSP unsafe-inline 仍存在
文档完善度8 / 10README 详尽，CHANGELOG 持续维护，docs/ 有专业文档
社区活跃度9 / 10最新提交仍是今天（2026-03-03），持续高速迭代

6.2 落地三阶段策略

第一阶段（1-3 天）：最小可用部署

  • Fork 仓库 → Vercel 部署 → 配置 Groq + Upstash Redis → 验证 AI 摘要功能
  • 此阶段即可获得：新闻聚合、3D 地图基础图层、AI 世界简报、CII 评分

第二阶段（1-2 周）：数据丰富化

  • 逐步申请 ACLED、FRED、EIA、NASA FIRMS、Cloudflare Radar API
  • 部署 Railway 中继服务，开启 AIS 船舶 + OpenSky 航班实时追踪
  • 配置 UCDP 令牌，补充武装冲突历史数据

第三阶段（持续）：定制化与生产加固

  • 添加 Vitest 单元测试，提升核心算法可靠性
  • 修复 CSP unsafe-inline，实现 .mjs → .ts 迁移
  • 根据业务需求选择性扩展：多用户、自定义告警、API 商业化
  • 配置自定义域名，接入 Sentry 进行错误监控（VITE_SENTRY_DSN）

WorldMonitor 是目前开源社区中功能最完整的全球情报监控平台之一，代码质量与迭代速度均处于行业前列。