tonyolives/argus
GitHub: tonyolives/argus
一个基于免费开源数据的实时OSINT监控平台，将航班追踪与地缘政治事件在3D地球仪上统一可视化，填补低成本情境感知的空白。
Stars: 0 | Forks: 0
# 🛰️ Argus
**实时全球OSINT监控平台**
Argus 在交互式3D地球仪上可视化实时空中交通、地缘政治事件和世界事件。以希腊神话中百眼巨人Argus命名，Argus为记者、OSINT分析师和安全研究人员提供统一的情境感知仪表板——完全由免费、开源数据驱动。
## 问题
目前没有一个免费、统一的平台能够将实时航班追踪与地缘政治事件监控结合在单一的可视化界面中。航班追踪器缺乏地缘政治背景。新闻聚合器缺乏空间感知能力。像Palantir Maven这样的企业平台虽然提供全面的情境感知，但每年成本高达数万美元。Argus填补了这一空白。
## 功能（MVP）
- **交互式3D地球仪** — 暗色主题的Globe.gl可视化，支持流畅旋转、缩放和点击交互
- **实时航班追踪** — 来自OpenSky网络的实时飞机位置，以航向旋转的飞机图标渲染
- **自动检测事件** — 来自GDELT的全球事件，通过多阶段流水线过滤（Goldstein Scale、CAMEO代码、地理去重、时效性）
- **事件详情面板** — 点击任意事件可查看元数据、严重性评分及相关新闻文章
- **新闻集成** — 通过GDELT DOC API按需获取文章，并带有服务器端缓存
- **事件过滤** — 按类别（冲突、灾难、政治、基础设施）和严重性过滤事件
## 技术栈
| 层 | 技术 | 版本 |
|---|---|---|
| **前端** | React、TypeScript、Globe.gl、Vite | 18.x、5.x |
| **后端** | Spring Boot、Java | 3.2.x、17 |
| **数据库** | PostgreSQL、PostGIS | 16、3.4 |
| **测试** | JUnit 5、Mockito、Jest、React Testing Library | — |
| **CI/CD** | GitHub Actions | — |
| **基础设施** | Docker Compose | — |
## 架构
Argus采用三层架构：React SPA用于表示层，Spring Boot REST API用于应用层，PostgreSQL与PostGIS用于数据层。计划任务轮询器从外部API（OpenSky、GDELT）聚合数据，通过过滤和转换服务处理数据，并通过文档化的REST端点提供服务。
如需完整详情，请参阅[系统架构文档](docs/Argus_Architecture_v1_0.md)和[架构决策记录](docs/Argus_ADRs_v1_0.md)。
## 快速开始
### 先决条件
- **Docker Desktop**（用于PostgreSQL + PostGIS）
- **JDK 17+**（推荐使用 [Eclipse Temurin](https://adoptium.net/)）
- **Node.js 18+** 和 npm 9+
### 安装设置
```
# 1. 克隆仓库
git clone https://github.com/tony-olivares/argus.git
cd argus
# 2. 配置环境
cp .env.example .env
# 使用您的 OpenSky 凭据和数据库密码编辑 .env
# 3. 启动数据库
docker-compose up -d db
# 4. 启动后端
./mvnw spring-boot:run
# 5. 启动前端（新终端中）
cd frontend
npm install
npm run dev
```
打开 [http://localhost:5173](http://localhost:5173) 查看地球仪。
后端运行时，API文档可在 [http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html) 访问。
### 运行测试
```
# Backend（JUnit 5 + Mockito + TestContainers）
./mvnw test
# Frontend（Jest + React Testing Library）
cd frontend && npm test
# 前端带覆盖率
cd frontend && npm test -- --coverage
```
## 项目结构
```
argus/
├── .github/ # Issue templates, PR template, CI workflows
├── frontend/ # React + TypeScript SPA
│ ├── src/
│ │ ├── components/ # Globe, FlightPanel, IncidentPanel, FilterBar
│ │ ├── hooks/ # useFlights, useIncidents, useNews
│ │ ├── services/ # API client functions
│ │ ├── types/ # TypeScript interfaces
│ │ └── __tests__/ # Jest + RTL tests
│ └── ...
├── src/main/java/com/argus/ # Spring Boot backend
│ ├── controller/ # REST controllers (/api/v1/*)
│ ├── service/ # Core business logic (FlightService, IncidentService)
│ ├── service/poller/ # Scheduled polling tasks
│ ├── service/filter/ # Incident filter pipeline
│ ├── repository/ # Spring Data JPA + PostGIS queries
│ ├── model/ # JPA entities
│ ├── dto/ # API response objects
│ ├── client/ # External API clients (OpenSky, GDELT)
│ └── config/ # Spring configuration
├── src/main/resources/
│ └── db/migration/ # Flyway SQL migrations
├── docs/ # Architecture docs, ADRs, diagrams
├── docker-compose.yml
├── CHANGELOG.md
├── CONTRIBUTING.md
└── LICENSE
```
## 测试方法
Argus遵循严格的**测试驱动开发（TDD）**——为所有服务层代码和交互式前端组件在实现之前编写测试。请参阅[ADR-005](docs/Argus_ADRs_v1_0.md)了解完整原理，以及[CONTRIBUTING.md](CONTRIBUTING.md)了解TDD流程。
| 层 | 工具 | 目标覆盖率 |
|---|---|---|
| 后端单元测试 | JUnit 5 + Mockito | >80% |
| 后端集成测试 | Spring Boot Test + TestContainers | 所有API端点 |
| 前端测试 | Jest + React Testing Library | >70% |
## 文档
| 文档 | 描述 |
|---|---|
| [产品需求文档（PRD）](docs/Argus_PRD_v1_0.md) | 范围、用户故事、成功指标 |
| [架构决策记录](docs/Argus_ADRs_v1_0.md) | 8个技术决策及其理由 |
| [系统架构](docs/Argus_Architecture_v1_0.md) | 组件设计、数据流、API契约 |
| [冲刺待办列表](docs/Argus_Sprint_Backlog_v1_0.md) | 7个冲刺中的36个任务 |
| [API参考](http://localhost:8080/swagger-ui.html) | 自动生成的OpenAPI文档（运行后端后访问） |
## 数据来源
| 来源 | 用途 | 成本 |
|---|---|---|
| [OpenSky网络](https://opensky-network.org/) | 实时飞机位置 | 免费 |
| [GDELT事件API](https://www.gdeltproject.org/) | 自动检测全球事件 | 免费 |
| [GDELT DOC API](https://blog.gdeltproject.org/gdelt-doc-2-0-api-expanded/) | 相关新闻文章 | 免费 |
## 许可证
本项目采用MIT许可证授权——详细信息请参阅[LICENSE](LICENSE)文件。
## 作者
**Tony Olivares** — 项目负责人
*以希腊神话中百眼巨人Argus Panoptes命名，他曾担任永恒的守望者。*
标签：3D地球可视化, GDELT, Globe.gl, JS文件枚举, OpenSky Network, PostGIS, PostgreSQL, React, SEO, Spring Boot, Syscalls, TypeScript, Vite, 严重性评分, 事件过滤, 交互式仪表盘, 全球监控, 前端可视化, 地理空间分析, 地缘政治事件, 安全插件, 实时OSINT, 实时数据, 新闻聚合, 测试用例, 版权保护, 监控平台, 航班追踪