KurageP/Project-Sentinel

# 项目哨兵 — v0 一个实时 OSINT 情报态势感知仪表板：一个3D地球仪，可以实时显示地理位置事件，并带有透明度区域活动指数和实时流。构建时考虑了独立运行、免费层运行，无需API密钥即可启动。 这是诚实的v0。它是一个聚合器加分析师辅助工具，而不是战争预言家。它不会“预测冲突到78%。”请参阅下面的*评分*。 ## v0实际上做了什么 ``` feed adapter(s) ──poll──> normalize ──dedup──> SQLite ──> REST + WebSocket ──> 3D globe └─> activity index ``` 开箱即用，它运行的是**模拟流**，因此整个管道（地球仪、WebSocket、数据库、评分）在您接触真实API之前就已经工作。只需翻转一个环境变量即可添加**GDELT**（免费、无需密钥、全球、已地理编码——理想的第一真实流）。 ### 架构与原因 | 层 | 选择 | 为什么（对于独立学习构建） | |---|---|---| | 前端 | Next.js + TypeScript | 一个框架用于UI + 路由；庞大的文档/社区 | | 地球仪 | CesiumJS via resium | 真正的3D地球仪（“谷歌地球”感觉）；在OSM图像上无密钥运行 | | 后端 | FastAPI | 异步、WebSocket、自动OpenAPI文档、最小样板 | | 数据库 | SQLite（默认）→ Postgres | 无需设置即可启动；一个环境变量即可升级，无需更改代码 | | 实时性 | WebSocket（进程内） | 最简单的事情，可以推送实时事件；Redis pub/sub稍后 | | 摄入 | asyncio循环（进程内） | 在这个规模上，Celery/Kafka工作器还为时过早 | 故意省略的原始规范堆栈（Kafka、k8s、微服务、向量数据库、TimescaleDB）**没有被删除，只是推迟了**。下面的适配器模式是使它们稍后添加而不是重写的原因。 ### 文件夹结构 ``` project-sentinel/ ├── backend/ │ ├── app/ │ │ ├── main.py # FastAPI app: REST + /ws + startup │ │ ├── config.py # env settings (sensible zero-setup defaults) │ │ ├── db.py # SQLAlchemy engine/session │ │ ├── models.py # Event (the one core entity) │ │ ├── schemas.py # RawEvent (adapter output) + API responses │ │ ├── ingest.py # poll → dedup → store → broadcast loop │ │ ├── ws.py # WebSocket connection manager │ │ ├── scoring.py # transparent activity index (NOT a forecast) │ │ └── adapters/ │ │ ├── base.py # FeedAdapter interface ← the extension point │ │ ├── registry.py # name → adapter mapping │ │ ├── mock.py # works with no keys │ │ └── gdelt.py # first real feed │ ├── requirements.txt │ └── .env.example ├── frontend/ │ ├── app/ # layout, page, globals.css │ ├── components/ # Globe.tsx (Cesium), Sidebar.tsx │ ├── lib/ # config + useEvents hook (WS subscription) │ └── scripts/copy-cesium.mjs └── docker-compose.yml # OPTIONAL Postgres, for later ``` ### 最重要的一个模式：流适配器 每个数据源实现`FeedAdapter.fetch() -> list[RawEvent]`。摄入循环、数据库、评分和前端永远不知道哪些流存在。添加ADS-B、AIS、ACLED、FIRMS等=编写一个类+一个注册行。其他什么都没有改变。针对此构建新的流，您就不会把自己画进角落。 ### 设置 ### 后端 ``` cd backend python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt cp .env.example .env # defaults work as-is uvicorn app.main:app --reload ``` 后端现在在http://localhost:8000（文档在`/docs`）。模拟流立即开始生成事件。 ### 前端 ``` cd frontend npm install # also copies Cesium assets to public/ cp .env.local.example .env.local npm run dev ``` 打开http://localhost:3000——旋转的地球仪，实时出现的点，侧边栏流和活动指数更新。 ### 添加第一个真实流 在`backend/.env`中设置： ``` ACTIVE_FEEDS=mock,gdelt ``` 重启后端。真实的地理位置新闻事件开始与模拟事件一起流动。（如果结果看起来为空，请确认GDELT当前端点在gdeltproject.org——其公共API参数偶尔会更改。） ### 评分——阅读此内容 `scoring.py`为每个国家生成0-100**活动指数**：按严重程度加权的最近事件，以对数形式压缩。它是一个**透明的启发式方法**，在UI的每个地方都标记为如此。它故意**不是**冲突概率的校准概率。 真正的冲突预测（ACLED CAST、ViEWS）是一个困难的研究问题，其输出高度有保留。如果您想要真正的预测，请将其视为一个单独的、诚实的建模工作——不要把这个启发式方法伪装成预测。一个显示编造的自信度的仪表板比一个坦白自己是监控器的仪表板更糟糕。 ### 路线图（附加，大致顺序） 1. 更多适配器：**NASA FIRMS**（卫星火灾，免费），然后**ACLED**（冲突，检查条款），然后**OpenSky**（飞机，免费层有限）。 2. 将国家代码映射到事件→更丰富的评分。 3. AI摘要：按区域聚类最后N小时，并通过LLM API生成简短摘要。将其标记为AI生成。 4. 将摄入移动到工作进程；添加Redis pub/sub以进行WS广播。 5. Postgres + TimescaleDB用于历史趋势和时间序列查询。 每一步都是独立的。在步骤1之后发布和演示。 ### 需要安装的软件/账户 **在您的机器上（一次性）：** - **Node.js** 18+（用于前端）—— nodejs.org - **Python** 3.11+（用于后端）—— python.org - **Git** —— git-scm.com **账户（所有免费，用于部署）：** - **GitHub** —— 存储库位于此处；两个主机都从它部署 - **Vercel** —— 前端（使用GitHub登录） - **Render** —— 后端（使用GitHub登录） **API密钥：** 开始时无需密钥。模拟和GDELT流无需密钥。稍后的流需要：NASA FIRMS（免费密钥）、ACLED（免费注册）、OpenSky（免费账户）。 ### 部署（组合） 前端→Vercel，后端→Render。它们从同一个存储库独立部署。 我无法为您点击这些（它们运行在您的账户上），但存储库已设置好，所以主要是点击。 **0. 推送到GitHub** ``` cd project-sentinel git init && git add . && git commit -m "Project Sentinel v0" # 在github.com上创建一个空仓库，然后： git remote add origin https://github.com//project-sentinel.git git push -u origin main ``` **1. 后端在Render上** - render.com → 新建 + → **蓝图** → 选择您的存储库。它读取`render.yaml`并在免费计划上部署后端。 - 复制生成的URL，例如`https://sentinel-backend.onrender.com`。 **2. 前端在Vercel上** - vercel.com → 添加新项目 → 项目 → 选择您的存储库。 - **设置根目录为`frontend`**（重要——它是一个单仓库）。 - 添加两个环境变量： - `NEXT_PUBLIC_API_BASE` = `https://sentinel-backend.onrender.com` - `NEXT_PUBLIC_WS_URL` = `wss://sentinel-backend.onrender.com/ws` （注意`wss://`——安全的WebSocket通过HTTPS） - 部署。复制您的Vercel URL，例如`https://project-sentinel.vercel.app`。 **3. 将后端指向前端** - 在Render → 您的服务 → 环境 → 设置`CORS_ORIGINS` = 您的Vercel URL → 保存（它将重新部署）。 完成。访问Vercel URL。第一次加载等待免费后端唤醒（约30秒），然后地球仪开始直播。WebSocket在后台睡眠后会自动重新连接，因此它会自行恢复。 **关于免费层的提示：** Render免费服务在空闲时休眠，因此演示有冷启动。Render上的SQLite是短暂的（重启时重置）——在这里没关系，因为模拟流会重新生成事件。对于持久性，稍后添加免费的Postgres并将其指向`DATABASE_URL`（请参阅路线图）。 ### 原始规范的说明 完整的规范（ADS-B、AIS、社交监控、Kafka、k8s、“预测升级”）是一个多个人、多个月份的构建，并且实践中有几个流不是免费的或实时的（实时飞机覆盖需要付费；社交监控昂贵且受ToS限制；没有干净的“导弹袭击”流——这是从新闻/OSINT派生出来的）。这个v0是从它开始的可运行核心。

标签：3D 地球可视化, AI 预测, API 开发, AV绕过, Celery, CesiumJS, ESC4, FastAPI, Kafka, OSINT, Redis, SonarQube插件, SQLite, TypeScript, WebSocket, 不稳定监测, 依赖分析, 全球事件监控, 军事活动追踪, 冲突检测, 地理定位, 安全插件, 实时数据流, 实时数据聚合, 异步编程, 快速开发, 情报分析, 数据去重, 数据库管理, 数据管道, 文档丰富, 架构设计, 活动索引, 消息队列, 环境变量配置, 网络诊断, 软件工程