GlobalThreatMap 全球威胁情报地图技术分析
一、项目概述
1. 项目简介
GlobalThreatMap 是一个实时全球态势感知平台，将安全事件、地缘政治发展和威胁指标绘制在交互式地图上。这是一个开源情报（OSINT）指挥中心类型的工具，旨在为研究人员、情报分析师和安全专业人士提供可视化的全球威胁情报。
2. 核心定位
- 实时事件映射：将冲突、抗议、自然灾害等突发事件标记在世界地图上
- 国家冲突情报：查看任何国家的历史冲突和当前冲突
- 军事基地可视化：展示美国和北约全球军事基地分布
- 深度情报研究：基于 Valyu AI 的实体情报档案生成
3. 项目信息
- 仓库地址：https://github.com/unicodeveloper/globalthreatmap
- 开源协议：MIT License
- 开发状态：活跃开发中（66 次提交）
- 社区关注：353 星，60 分叉
二、技术架构
1. 整体架构
graph TB
User[用户界面] --> Frontend[Next.js 前端]
Frontend --> Mapbox[Mapbox 地图组件]
Frontend --> ValyuAPI[Valyu 智能API]
Frontend --> Backend[Next.js API Routes]
ValyuAPI --> Search[搜索API]
ValyuAPI --> Answer[答案API]
ValyuAPI --> DeepResearch[深度研究API]
Backend --> MilitaryDB[军事基地数据]
Backend --> ConflictData[冲突数据]
Mapbox --> EventMarkers[事件标记]
Mapbox --> MilitaryMarkers[军事基地标记]
Mapbox --> EntityMarkers[实体位置标记]
Frontend --> State[Zustand 状态管理]
Frontend --> Auth[OAuth 认证系统]
2. 技术栈
A. 前端框架
- Next.js 16：使用 App Router 架构
- React：基于 React 18+ 构建
- TypeScript：96.9% 的代码使用 TypeScript
B. 地图组件
- Mapbox GL JS：核心地图渲染引擎
- react-map-gl：Mapbox 的 React 封装
- 支持深色主题、聚类、热力图可视化
C. UI 框架
- Tailwind CSS v4：样式框架
- 自定义组件库
- react-markdown + remark-gfm：Markdown 渲染
D. 状态管理
- Zustand：轻量级状态管理库
- 管理地图视口、图层、基地数据等状态
E. 数据验证
- Zod：TypeScript 优先的模式验证
F. 智能引擎
- valyu-js：Valyu AI 客户端库
- 提供搜索、答案生成、深度研究功能
3. 项目目录结构
globalthreatmap/
├── app/
│ ├── layout.tsx # 根布局
│ ├── page.tsx # 主仪表板
│ ├── globals.css # 全局样式
│ └── api/ # API 路由
│ ├── events/ # 事件获取
│ ├── entities/ # 实体研究
│ ├── reports/ # 深度研究报告
│ ├── countries/
│ │ └── conflicts/ # 国家冲突情报
│ └── military-bases/ # 军事基地数据
├── components/
│ ├── map/ # 地图组件
│ │ ├── threat-map.tsx # 主地图组件
│ │ ├── timeline-scrubber.tsx # 自动平移控制
│ │ └── country-conflicts-modal.tsx # 冲突详情弹窗
│ ├── feed/ # 事件源组件
│ ├── search/ # 实体搜索组件
│ ├── alerts/ # 告警管理
│ └── ui/ # 基础 UI 组件
├── lib/
│ ├── valyu.ts # Valyu 客户端
│ ├── geocoding.ts # 位置提取
│ └── event-classifier.ts # 事件分类
├── stores/
│ └── map-store.ts # 地图状态管理
├── types/ # TypeScript 类型定义
└── hooks/ # React 自定义 Hooks三、核心功能
1. 实时事件映射
A. 功能描述
在地图上实时绘制全球安全事件，包括冲突、抗议、自然灾害等。事件使用颜色编码的威胁级别进行标记。
B. 事件分类
- Conflict（冲突）：军事冲突、武装冲突
- Protest（抗议）：示威活动
- Disaster（灾难）：自然灾害
- Diplomatic（外交）：外交事件
C. 威胁级别
- Critical（严重）：红色标记
- High（高）：橙色标记
- Medium（中）：黄色标记
- Low（低）：蓝色标记
- Info（信息）：灰色标记
2. 国家冲突情报
A. 功能描述
点击地图上的任意国家，可查看该国家详细的冲突情报，包括历史冲突和当前冲突。
B. 数据组织
使用标签页界面分别展示：
- Current（当前）：红色主题，显示活跃冲突
- Historical（历史）：蓝色主题，显示历史战争和军事冲突
C. 交互体验
- 选中国家时会填充红色并闪烁（加载动画）
- 数据来源引用（排除 Wikipedia）
- 基于 Valyu Answer API 合成的冲突数据
sequenceDiagram
participant User as 用户
participant Map as 地图组件
participant API as 后端 API
participant Valyu as Valyu API
User->>Map: 点击国家
Map->>Map: 高亮国家（红色闪烁）
Map->>API: 请求冲突数据
API->>Valyu: 查询冲突情报
Valyu-->>API: 返回结构化数据
API-->>Map: 返回冲突列表
Map->>User: 显示冲突详情弹窗
3. 军事基地可视化
A. 功能描述
可视化全球军事存在，包括美国和北约军事基地。
B. 基地分类
- 美国军事基地：绿色标记（30+ 个基地）
- 北约设施：蓝色标记
C. 覆盖范围
- 欧洲
- 亚太地区
- 中东
- 非洲
- 美洲
D. 数据缓存
军事基地数据使用 1 小时缓存，减少 API 调用。
4. 情报档案（深度研究）
A. 功能描述
使用 Valyu 的深度研究 API 构建综合情报档案。可输入任何实体，包括国家、民兵组织、私营军事公司、贩毒集团、政治人物等。
B. 输出产物
- 约 50 页情报报告：涵盖背景、组织结构、关键人物、地理分布、近期活动、威胁评估和时间线
- CSV 数据导出：结构化数据，包括位置、坐标、关键人物、相关组织、重大事件及日期、来源 URL
- PowerPoint 简报：8 页执行情报简报
- PDF 报告：可下载的完整报告
C. 数据来源
- 数百个网络来源
- 学术论文
- 专有数据库
D. 生成时间
报告生成需要 5-10 分钟，但非常详细和全面。
四、地图可视化
1. 自动平移模式
- 播放/暂停按钮控制地图自动向东平移
- 创建动态的全局监视效果
2. 事件聚类
- 在较低缩放级别将附近事件分组
- 保持地图整洁清晰
3. 热力图视图
- 可切换热力图来可视化事件密度
- 快速识别热点区域
4. 实体位置标记
- 研究实体时，其已知位置在地图上显示为紫色标记
五、认证系统
1. 应用模式
GlobalThreatMap 支持两种应用模式，通过 NEXT_PUBLIC_APP_MODE 环境变量控制。
A. Self-Hosted 模式（默认）
NEXT_PUBLIC_APP_MODE=self-hosted
VALYU_API_KEY=your_valyu_api_key_here特点：
- 无需身份验证
- 所有功能完全开放
- API 使用计入您的 Valyu 账户
B. Valyu OAuth 模式
NEXT_PUBLIC_APP_MODE=valyu
NEXT_PUBLIC_VALYU_AUTH_URL=https://auth.valyu.ai
NEXT_PUBLIC_VALYU_CLIENT_ID=your-client-id
VALYU_CLIENT_SECRET=your-client-secret特点：
- 用户使用 Valyu 账户登录
- 访问额外功能
2. 功能门控
在 Valyu 模式下，某些功能需要身份验证：
| 功能 | 未认证用户 | 认证用户 |
|---|---|---|
| 查看地图和事件 | 免费 | 免费 |
| 事件源 | 免费 | 免费 |
| 国家冲突 | 2 次免费查询 | 无限制 |
| 实体搜索 | 阻止 | 无限制 |
| 军事基地 | 免费 | 免费 |
3. OAuth 流程
使用 OAuth 2.0 和 PKCE（Proof Key for Code Exchange）：
sequenceDiagram
participant User as 用户
participant App as 应用
participant Valyu as Valyu 认证服务
User->>App: 点击"使用 Valyu 登录"
App->>App: 生成 PKCE 代码验证器和挑战
App->>Valyu: 重定向到授权页面
Valyu->>User: 显示登录界面
User->>Valyu: 输入凭据
Valyu->>App: 重定向到 /auth/valyu/callback
App->>Valyu: 交换授权代码获取访问令牌
Valyu-->>App: 返回访问令牌
App->>App: 将用户信息存储在 localStorage
六、API 路由
项目提供以下 API 端点：
| 路由 | 方法 | 描述 |
|---|---|---|
| /api/events | GET | 从 Valyu 获取全球事件 |
| /api/events | POST | 使用自定义查询获取事件 |
| /api/entities | GET/POST | 研究实体并获取位置 |
| /api/deepresearch | POST | 创建异步深度研究任务 |
| /api/deepresearch/[taskId] | GET | 轮询深度研究任务状态 |
| /api/reports | POST | 生成深度研究报告 |
| /api/countries/conflicts | GET | 获取国家的冲突数据 |
| /api/military-bases | GET | 获取美国和北约军事基地位置 |
七、环境配置
1. 必需依赖
- Node.js 18+
- Mapbox 账户和 API 令牌
- Valyu API 密钥
2. 环境变量
创建 .env.local 文件：
# 必需
NEXT_PUBLIC_MAPBOX_TOKEN=your_mapbox_token_here
VALYU_API_KEY=your_valyu_api_key_here
NEXT_PUBLIC_APP_MODE=self-hosted
# 可选：启用 AI 驱动的位置提取以提高准确性
OPENAI_API_KEY=your_openai_api_key_here3. API 密钥获取
A. Mapbox
访问 https://account.mapbox.com/access-tokens/ 获取令牌
B. Valyu
访问 https://valyu.ai 获取 API 密钥
C. OpenAI（可选）
访问 https://platform.openai.com/api-keys 获取 API 密钥，启用 AI 驱动的位置提取
八、安装与运行
1. 安装依赖
npm install2. 配置环境变量
cp .env.example .env.local
# 编辑 .env.local 填入 API 密钥3. 启动开发服务器
npm run dev4. 访问应用
打开浏览器访问 http://localhost:3000
九、应用场景
1. OSINT 分析师
- 实时监控全球安全事件
- 生成可导出的情报简报
- 深度研究实体背景
2. 安全研究人员
- 追踪地缘政治发展
- 分析军事部署
- 研究冲突历史
3. 新闻机构
- 快速了解事件地理分布
- 获取背景情报
- 生成可视化报告
4. 学术研究
- 收集冲突数据
- 军事基地分布研究
- 地缘政治分析
十、技术亮点
1. 前沿技术栈
- Next.js 16 App Router
- TypeScript 全覆盖
- 现代化的状态管理
2. 智能集成
- Valyu AI 深度集成
- 自动化情报收集
- 结构化数据输出
3. 可视化设计
- 交互式地图
- 实时数据更新
- 多层级信息展示
4. 灵活部署
- 支持自托管
- OAuth 认证模式
- 功能门控机制
十一、未来展望
1. 功能增强
- 地理区域告警（开发中）
- 更多实体类型支持
- 增强的数据导出格式
2. 性能优化
- 更高效的数据缓存
- 实时数据流
- 移动端优化
3. 社区协作
- 开放 API
- 数据贡献机制
- 多语言支持