AndrewCTF/velocity
GitHub: AndrewCTF/velocity
一个自托管的 OSINT 态势感知控制台，将全球实时飞机、船只、卫星和事件数据融合在 3D 地球仪上，提供完整的位置历史存档和证据链管理。
Stars: 35 | Forks: 3
# Velocity
一个自托管、免 API key 的态势控制台：实时飞机、船只、卫星、GPS 干扰、黑暗船只、TFR 空域、军事基地、航海警告、地震、停电和冲突事件，全部融合在一个 3D 地球仪上，并在服务器端进行关联，而不是让你费力查看六个标签页。
其他地方很难找到的真正亮点在于：它保留属于*你*自己的历史记录。Flightradar24 将免费回放限制在 7 天，MarineTraffic 将其免费时间窗口缩短至 24 小时，ADS-B Exchange 直接彻底关闭了其免费 API 层级——而自托管工具根本没有这个问题。开启 archive profile，只要你给它足够的存储空间，Velocity 就会将位置历史记录持续录制到你自己的磁盘上，并通过一个滑动条让你可以倒退至过去的任意时刻。无需账户，无需 API key，没有人可以对你的存档进行付费墙限制、过滤或切断。
一旦你发现了值得保留的东西，它就会成为证据：一个监管链**证据柜**会使用 SHA-256 对每次捕获（URL 快照、上传、feed 冻结）进行哈希处理，并生成一个仅追加的监管日志，然后将案例汇总成一个独立的 **HTML / PPTX 报告**，其中每项声明都带有其出处。所有这些都无需 key，全部都在你的磁盘上。
它还可以作为 MCP 服务器运行，因此 AI agent 可以查询相同的实时 feed，而不是根据其训练截止时间进行猜测——它返回的所有内容都被标记为自动化输出，而不是作为所谓的“AI 洞察”出售。
**[实时演示](https://projectvelocity.org)** · [快速开始](#quick-start) · [应用程序](#the-apps) · [功能导览](#take-the-tour) · [通过 AI agent 进行查询](#mcp-server-query-the-live-console-from-an-ai-agent)
[](./LICENSE)
[](https://github.com/AndrewCTF/velocity/releases/latest)
[](#tests)
[](#what-it-pulls-in)
。它会实时显示移动的飞机、船只、地震等所有内容，中间无需进行任何配置——并且位置历史记录已经同步录制到 Docker 卷中，因此下次运行 `docker compose up` 时它依然存在（在 `.env` 中设置 `ARCHIVE_MODE=1` 可启用无期限存档，而不是默认的滚动时间窗口；详情请参阅[范围与限制](#scope-and-limits)）。首次进入时，一个简短的导览会指出各功能的位置；你可以随时从 **⚙ Settings** 中重新调出导览。
底部的那个条带就是存档——这里显示的是 *recording since yesterday · 2.3 GB · 12.7 million fixes*。将其向后拖动一小时、一天，或者拖动到你的历史记录所及的任意位置，地球仪就会倒退回那个确切的时刻。
## 这些应用程序
Velocity 并不是一个庞大的单一仪表盘；它是一个由十二个应用程序组成的工作区，所有应用程序共享相同的选择和时间上下文，因此切换时绝不会丢失你已选择的对象。顶部栏对它们进行了分组：
| 组 | 应用程序 | 用途 |
| --- | --- | --- |
| **实时** | Map · Sim | Cesium 地球仪（始终挂载在其他所有内容之后）以及一个浏览器战争游戏覆盖层。 |
| **分析** | Explorer · Graph · Investigate · Targeting · Video · Country | 过滤实时对象存储，扩展链接分析图，运行数字 OSINT（域名/人物/钱包），一个概念性杀伤链板，FMV/地面侦察，以及各国的世界银行/联合国统计档案。 |
| **数据** | Foundry · Workflows | 通过受管控的 pipeline 引入你自己的数据；使用节点图编辑器自动化实时 feed。 |
| **产品** | Reports | 案件档案、值班军官简报、档案，以及案件→报告导出。 |
| **3D** | City 3D | 基于无 key 卫星 AOI 构建的高斯泼溅城市场景。 |
本 README 的其余部分将带你了解你日常最常使用的那些应用程序。以下所有内容均为当前版本 (v0.9.2) 的真实截图，而非模型预览。
## 功能导览
**1. 整个星球，尽在掌握。** 在一个 Cesium 地球仪上显示数以千计的飞机，以及船只、卫星、地震等。每架飞机和每艘船都呈现为其所属类别的图标，根据其航向着色并旋转；密集区域会聚合成数量徽章，你可以点击深入查看。
**2. 随意缩放，切换一切。** 拖动到某个区域，交通、标签和海岸线就会自动填充。左侧边栏是整合在一个树状结构中的完整情报堆栈——空中、海上、太空、地面危险、信号以及 14 个基础设施层——每一层都有实时计数。右侧的地图工具栏在地球仪之上添加了分析操作动词：**测量** 运行中的大圆距离，**框选** 一个区域并搜索其中的每个对象，使用放置的标记进行**标注**，或者**移动**标记——此外还有一键重置相机和缩放。
**3. 点击任意对象。** 选中一架飞机或一艘船，右侧面板就会填充其档案：身份、运动学、航班/航线、ACARS、生活模式基准、GPS 完整性和原始字段——同时一条洋红色的线会在地球仪上描绘出其最近的轨迹。一个 **AI 评估** 模块（带有标签，并基于观测到的轨迹）会总结档案字段所暗示的信息。点击空白区域，一切都会清空。
**4. 或者一次性查询整个存储库。** Explorer 应用程序将每个实时对象显示在一个可过滤、可排序的表格中——跨越船只、飞机和地震的数以万计的轨迹，每个轨迹都标记有其来源 feed 及其上次被发现的时间。对其进行分面筛选，保存搜索，将结果导出为 CSV。
**5. 咽喉要道和 AOI，持续监视。** 一个精心策划的全球海上咽喉要道库——霍尔木兹海峡、曼德海峡、马六甲海峡、台湾海峡、英吉利海峡、海底电缆走廊——每一个都有实时过境统计数据以及彰显其重要性的每日石油流量数据。后台会持续针对它们进行常态化探测。
**6. 空域、基地、港口和机场——作战背景，依然免 key。** 切换 TFR/空域图层，实时 FAA 临时飞行限制就会绘制成真实的多边形，并按原因及其高度带进行着色。除此之外：7,183 个军事基地（空军、海军和陆军，来自 Wikidata），带有雷区标记的 NGA NAVAREA 广播警告，来自 NGA 世界港口索引的 3,804 个港口（港口规模和类型、避风条件、维修、干船坞、码头和航道水深），以及经过丰富的机场数据（跑道：长度、表面、照明、来自 FAA NASR 的各端 ILS 类别），塔台/地面/ATIS 频率，带有飞行类别的实时 METAR，以及 LiveATC 链接。底图选择器可在八种无 key 地图样式之间切换（Esri 影像/地形/暗黑风格、OpenTopoMap、USGS、Sentinel-2 无云图等），每种样式在提供之前都会进行实时探测。
**7. 基于真实物理学的太空视图。** 来自 CelesTrak 的约 1.6 万颗卫星，在浏览器中使用真实的 SGP4 轨道力学进行轨道传播，并结合 SATCAT 进行了数据丰富，包含所有者、发射日期、雷达截面和轨道类别等信息。
**8. 值班军官处理收件箱。** 一个自主的值班军官将干扰、黑暗船只、军事空中活动和冲突事件融合为带有排名和引用来源的警报——GPS 欺骗、干扰蜂窝、黑暗船只候选目标——每个都附带一行 `[inferred]`（推断）推理依据，并支持一键 *slew to*（视角切至目标）。它会针对实时态势运行 `detect_deception` 和 `deep_analyze`，因此在一个全新的免 key 启动后，无需操作员进行任何设置，收件箱就会自动填充。
**9. ……并撰写简报。** 每隔几分钟，它会将这些趋同性事件——"船只在报告的活动附近关闭了应答器"、"欺骗轨迹与 AIS 信号缺口重合"——提升为带有引用来源的书面摘要和 *slew to* 按钮的、经过排序的事件卡片。可采取行动的事件会被自动提升到调查图谱中，从而实现本体图谱的自我扩展。
**10. 将其作为证据保留。** 任何值得保留的内容都会进入监管链**证据柜**：捕获 URL 快照、上传文件、截取屏幕截图，或者冻结当前的 feed 状态，每个工件都会被进行 SHA-256 哈希处理，写入 `./data/evidence`，并记录到本地本体存储中仅追加的监管链里。将其附加到某个态势中，随时重新验证哈希，或者将整个案件汇总成一个签名的哈希之哈希清单。完全无需 key。随后，**Reports** 会将案件（参见[导出](#export)）导出为 JSON 打包文件、带有逐项声明来源脚注的独立 HTML 报告，或者是 PPTX 简报——任何 AI 生成的叙述都会被限制在一个明确标记的区块中。
**11. 拆分工作区。** 任何右侧边栏面板都可以分离成地球仪上方的自由浮动、可拖拽、可调整大小的窗口——把档案放在一个屏幕上，图层树放在另一个屏幕上，保持地图清晰。其位置会在整个会话期间保持不变。
**12. 引入你自己的数据——Foundry 标签页。** 上传 CSV/JSON/NDJSON 文件，通过受管控的 pipeline（13 个转换步骤：过滤、派生、连接、聚合、联合、窗口、透视、去重、类型转换、排序等）对其进行塑造，通过数据健康检查（新鲜度 SLA、schema 偏移、唯一性等）对每个版本进行把关，并将其绑定到与实时 feed 相同的本体图谱中。数据血缘、带有回滚功能的不可变版本，以及用于存放转换失败行的死信队列，这些功能一应俱全；pipeline 图谱会准确标记出哪些输出已经过期。
**13. 实现自动化——Workflows 标签页。** 一个针对相同实时 feed 和本体的节点图编辑器：将数据源（飞机、船只、地震、警报、数据集、本体、国家）通过沙盒化的 Python/SQL/LLM 转换模块连接到接收器（警报、本体对象、数据集、持久化内存），然后按计划运行它。控制模块还可以向外扩展——向你的服务器发送 webhook，或者使用 MAVLink bridge 进行无人机任务下发，在没有飞行器的情况下以仅记录日志的方式进行演练。
## 范围与限制
其核心在于融合。许多网站已经能够很好地处理单一的 feed：Flightradar24 适合看飞机，MarineTraffic 适合看船只，[GPSJam](https://gpsjam.org) 适合查看干扰。
Velocity 则瞄准了它们之间的缝隙：AIS 加上雷达图像可以标记出关闭了应答器的船只；一群报告 GPS 完整性受损的飞机则成为一个干扰热点；当两个或更多此类现象在同一地点和时间对齐时，它们就会被提升为一个带有引用来源的书面摘要的单一事件。
有几件事需要提前了解，因为我宁愿你在这里看到它们，也不愿你之后感到烦恼：
- 它是为单一分析师设计的。一个可选的 API key，没有账户或角色。
- **哪些会保留，哪些会清除。** 磁盘上的持久化内容：位置历史存档（位于 `./data/history.db` 的 SQLite）、本地本体存储——本体对象、案件档案、态势 (`intel/ontology_local.py`)——以及证据柜（blobs 位于 `./data/evidence` 下，监管链位于本体存储中仅追加的 `assertions` 表中）。易失性数据，并在后端重启时会被清除：实时事件列表、瞬态 AOI 选择，以及生成的值班军官简报。Docker Compose 卷意味着持久化存储可以挺过 `docker compose down`，而不仅仅是进程重启。开发环境的 compose 开箱即用地设置了 `HISTORY_RETENTION_HOURS=48`（2 天）；设置 `ARCHIVE_MODE=1`（生产环境的 compose profile 就是这样做的，通过 `HISTORY_DISK_BUDGET_GB` 设置 5 GB 的初始预算）可以根据你的磁盘空间大小而不是固定的时间窗口来调整存档。
- AIS 以无 key 方式在全球范围内运行（约 3.3 万艘船只，通过 MMSI 在 ShipXplorer、MyShipTracking、Digitraffic 和 Kystverket 之间进行去重），但北欧和波罗的海的覆盖最密集，其他地方则较稀疏；AISStream key 可以填补这些空白。稀疏区域仍然依赖于雷达 (SAR) 图层。
- **两个 headless-Chrome sidecar 在 Docker 下处于降级状态，而非崩溃。** ADS-B（OpenSky + httpx tar1090 镜像 + ShipXplorer AIS）以及区域性 Kystverket/Digitraffic AIS feed 是直接的 HTTP 调用，可在容器中以全力运行。但是 tar1090 ADS-B sidecar 和 MyShipTracking（已启用的主要无 key *广域* AIS 源）通过 Node 驱动真实的 Chromium，而精简的 API 镜像并未提供该浏览器——它们会记录一条警告并保持空闲，而不会导致后端崩溃，因此你失去的只是它们额外的覆盖范围，而不是应用程序本身。请运行裸机 (`bash scripts/run-api.sh`) 以获得完整的 sidecar 覆盖。
- 一些**分析**类应用在设计上是概念性的——Targeting 杀伤链板和 Video/FMV 传感器 HUD 带有 "NOTIONAL // SIMULATED"（概念性 // 模拟）的横幅，并由 Sim overlay 驱动，而不是真实的武器或 ISR feed。
- 3D 卫星视图会消耗你的 VRAM。默认的 2D 暗色地图可以在笔记本电脑上运行；在切换到重度模式之前，请查看[系统要求](#system-requirements)。
启动时无需任何 API key。Key 只是为了扩展覆盖范围。
## 它引入了什么
以下是来自运行中的后端的粗略实时数据；这些数字在一天中会不断变动：
| Feed | 典型实时数量 | 来源 |
| --- | --- | --- |
| 飞机 (ADS-B) | 9,000–13,000 (通常约 11,000) | OpenSky + airplanes.live |
| 军用飞机 | ~140 | adsb.lol |
| 船只 (AIS) | ~33,000，全球范围 | ShipXplorer + MyShipTracking + Digitraffic + Kystverket |
| GPS 干扰 | ~200 个被标记的 1° 蜂窝 | ADS-B NACp/NIC，即 GPSJam 方法 |
| 黑暗船只 | 雷达变化检测 | Sentinel-1 SAR |
| 融合事件 | 相关性驱动 | 相关性引擎 |
| 卫星 | ~16,000，经 SATCAT 丰富 | CelesTrak |
| 空域 | 实时限制多边形 | FAA |
| 军事基地 | 7,183 (+1,330 MIRTA/Wikidata) | Wikidata + DIA MIRTA |
| 航海广播警告 | ~800 个绘制的点 | NGA NAVAREA |
| 港口 | 3,804，包含港口详情 | NGA World Port Index |
| 机场 | 跑道 + ILS + 频率 + 实时 METAR | FAA NASR, NOAA, LiveATC |
| 地震 | ~250/天 | USGS + EMSC |
| 新闻 + 事实核查 | ~370 篇文章 | 发布者 RSS |
| 互联网中断 | 国家级别 | IODA, Cloudflare |
| 海底电缆 | ~700 | TeleGeography |
| 冲突事件 | ~1,500 个实时事件 | GDELT, EONET, ACLED |
| 野火 | VIIRS 热点 | NASA FIRMS (需要 key) |
| 3D 战争破坏、影像、网络摄像头 | 不定 | Sentinel, GIBS, OSM |
| 各国工具包 | 53 个国家 | 开放数据 / 注册表 / 制裁链接 |
如果你想要更大的覆盖范围，可以使用可选 key：用于全球 AIS 的 AISStream，用于获取更大 ADS-B 预算的 OpenSky 登录账号，用于火灾的 `FIRMS_MAP_KEY`，用于冲突事件的 ACLED key，用于网络中断的 `CLOUDFLARE_TOKEN`。`GET /api/intel/sources` 会报告哪些数据源是实际处于活跃状态，哪些仍在等待 key 配置。
## MCP 服务器：从 AI agent 查询实时控制台
我认为真正具有创新性的一点是：该后端同时充当 **Model Context Protocol** 服务器，因此 AI agent 可以直接查询地球仪正在渲染的那些“热” feed，而不必抓取十几个网站或塞满自己的上下文。询问“现在哪里正在受到 GPS 干扰？”它就会根据实时 feed 给出答案。完整的架构以及 `/api/intel/*` HTTP 参考：[`docs/mcp-server.md`](./docs/mcp-server.md)。
它通过 `app.mcp_server` 暴露了 34 个工具（下面列出了具有代表性的部分；运行 `--list-tools` 查看完整列表）：
| 工具 | 返回内容 |
| --- | --- |
| `get_situation` | 全球摘要：按类别分类的飞机、GNSS 受损数量、紧急情况、最严重的干扰蜂窝、船只/警报数量。这是开销最小的首选调用。 |
| `focus_area(lat,lon,radius_nm)` | **将某个区域加载为 PRIMARY**（专门的全新 `/v2/point` 拉取 + 持续的优先级刷新，独立于全局速率限制），并返回完整的包：飞机 + 密度 + GPS 干扰 + 船只 + 融合异常。 |
| `aircraft_density` | 某区域内各蜂窝的网格（计数、按类别、GNSS 受损情况）。 |
| `gps_jamming` | GPSJam 方法的评估（ADS-B NACp<8 / NIC<7，1° 区间）：被标记的蜂窝、严重程度、受影响的飞机。支持全球或限定范围查询。 |
| `query_aircraft` | 过滤查询（bbox/中心点、类别、squawk、呼号、高度带、紧急情况 / gnss_degraded / on_ground）。 |
| `lookup_aircraft(ident)` | 按 ICAO24 或呼号查询单架飞机，并包含完整性/威胁评估。 |
| `query_vessels` | 某区域内已分类的 AIS 船只；使用 `dark_only` 查询黑暗船只候选目标。 |
| `anomalies` | 融合报告：紧急情况、干扰热点、黑暗船只、警报 + 分类威胁等级。 |
| `detect_deception` / `locate_emitter` | 标记被欺骗/位置重合的轨迹；根据完整性受损的飞机对干扰源进行三角定位。 |
| `whats_changed` / `incident_history` | 距某个时间戳的变化量（Delta）；某区域的事件时间线。 |
| `deep_analyze(question, lat?, lon?)` | 收集相关的情报 JSON，并让一个**推理模型**（如果配置了则使用 DeepSeek，否则使用本地 Ollama 模型）对其进行推理，这样繁重的分析工作就不会占用 agent 的上下文，而只返回最终的结论。 |
每个工具都会返回紧凑且有边界的 JSON（计数、网格、≤50 项的样本），因此 agent 只需消耗几百个 token 就可以扫描整个星球，而不必拉取 1.5 万个特征。繁重的工具还支持 **`detail='short'`**（默认的摘要——每个列表的前 N 项加上一个 `_total`）或 **`detail='long'`**（完整的包），因此 agent 可以先用 `short` 扫描，再用 `long` 深入挖掘。Area-primary 加载机制意味着，即使全球范围的“数据洪流”正在受到速率限制，agent 关注的区域也能保持最新和高密度；而世界的其他地区则继续从抓取的快照中输出数据。
同样的融合技术也为应用内的 **AI 选择简报** 提供了支持：点击一个实体，`POST /api/ai/selection/brief` 就会将其注册表中的丰富信息和生活模式档案融合进一个选择层级的模型 prompt 中，从而实现 Gotham 风格的推断——每一个论点都会标明其源自档案中的哪个字段，并且如果未配置模型，它会降级为仅使用原始属性。
### 作为 Claude Code 插件安装 (skill + commands + agent)
该仓库本身也是一个 Claude Code **插件市场**。一次安装即可接入 MCP 服务器，*外加* 一个分析师 skill (`osint-intel`)、斜杠命令 (`/osint-brief`、`/osint-watch`、`/osint-jamming`) 以及一个 `osint-watch-officer` agent。启动后端（`bash scripts/run-api.sh`），然后在 Claude Code 中执行：
```
/plugin marketplace add /path/to/OSINT
/plugin install osint-geoint@osint-velocity
```
出现提示时，请设置 **repo_dir** 和 **python**（该仓库的 venv 解释器）；该插件会直接运行该 Python 环境，因此可以在 Windows、macOS 和 Linux 上运行。安装程序会打印出适合你操作系统的准确命令：`bash plugin/osint-geoint/install.sh`（Linux/macOS，加上 `-y` 可注册 MCP 服务器）或 `plugin\osint-geoint\install.ps1`（Windows，加上 `-Run` 进行注册）。
### 托管版：将你的 agent 指向实时 endpoint
在托管平台上，MCP 服务器被挂载到后端的 `/mcp` 路径下（可流式传输的 HTTP），因此无需安装或运行任何东西。使用你的 Velocity 访问令牌将其注册到任何 MCP 客户端：
```
claude mcp add --transport http osint-geoint \
https://projectvelocity.org/mcp \
--header "Authorization: Bearer $VELOCITY_TOKEN"
```
`$VELOCITY_TOKEN` 是你登录后的 Velocity (Supabase) 访问令牌；网关 Worker 会对它进行验证，后端也会重新进行校验，因此该 endpoint 受限于你的会话。
### 自我托管 / 开发
```
# 1. backend 必须正在运行（提供 warm feeds）
uv run --project apps/api uvicorn app.main:app --port 8000
# 2a. 基于 stdio 的 MCP server（Claude Code / Desktop / Agent SDK），跨平台
uv run --project apps/api python -m app.mcp_server
# 2b. 或 streamable-HTTP
uv run --project apps/api python -m app.mcp_server --http --port 8765
# introspect（无需 backend）
uv run --project apps/api python -m app.mcp_server --list-tools
```
要使用 Claude Code 注册 stdio 服务器，请在仓库根目录下运行：
```
claude mcp add osint-geoint -- uv run --project apps/api python -m app.mcp_server
```
`uv run` 可以在 Linux、macOS 和 Windows 上解析出正确的解释器，而无需硬编码 venv 路径。没有 `uv`？直接将其指向 venv 的 Python：`apps/api/.venv/bin/python -m app.mcp_server`（Linux/macOS）或 `apps\api\.venv\Scripts\python.exe -m app.mcp_server` (Windows)，在 `apps/api` 目录下运行。
配置（环境变量或 `apps/api/.env`）：`API_BASE`、`API_KEY`、`OLLAMA_HOST`、`OLLAMA_MODEL`（留空会自动选择已安装的最小模型；如果 Ollama 不存在，`deep_analyze` 会降级为返回原始 JSON）。MCP 服务器绝不会因为工具调用而崩溃：后端宕机会返回结构化的 `backend_unreachable` 错误；Ollama 宕机则会回退到原始的情报 JSON。
## 导出
提供两种导出方式，适用于两种不同任务：
**实时态势。**
`GET /api/export?fmt=geojson|csv|kml&kinds=aircraft,vessels&bbox=min_lon,min_lat,max_lon,max_lat&limit=N`
将地球仪当前渲染的快照下载为 **GeoJSON**（适用于 QGIS / kepler.gl / Leaflet）、**CSV**（适用于电子表格）或 **KML**（适用于 Google Earth）。`bbox` 会将输出裁剪至特定视口；`kinds` 是以逗号分隔的列表（默认为 `aircraft`）；`limit` 限制特征数量；对船只的导出是尽力而为的。
**已完结的案件。**
`POST /api/situations/{id}/export?fmt=json|html|pptx` 会遍历某个态势的子项、其带有来源的断言以及每一条附加的证据，将它们汇总成一个可共享的工件：一个自描述的 **JSON** 打包文件、一个独立的 **HTML** 报告（每项声明都带有来源脚注），或者是一份 **PPTX** 简报。任何由 AI 生成的叙述都会被限制在一个带有明确标签的区块中——其余部分全是你附有引用来源的证据。
## 系统要求
负载繁重的组件是**客户端**，即一个基于 CesiumJS WebGL2 的地球仪。它严重依赖 GPU 和浏览器的主线程，而后端则比较轻量。要求支持 WebGL2（Chrome/Edge 110+，Firefox 110+）。在具备混合显卡的笔记本电脑上，请强制使用独立 GPU（`chrome://gpu`，寻找带有 "ACTIVE" 字样的适配器）。
**VRAM 的消耗很大程度上取决于你运行的模式：**
- **2D-暗色风格（默认底图）：** 轻量级。地球仪是一个代理的 2D 光栅底图，加上实体图层（飞机/船只）。可在集成显卡 / 约 2–4 GB VRAM 上运行，这最适合性能一般的硬件。
- **3D-卫星模式（卫星影像 + 全球地形 + OSM 3D 建筑，可选 Google Photorealistic 3D）：** **高 VRAM 消耗。** CesiumJS 会流式传输地形网格、高分辨率影像以及 3D-tile 建筑/摄影测量数据集，并将其缓存到所有可用的 VRAM 中，实测在一张 32 GB 显存的单卡上会消耗 **20+ GB**。Tilesets 现在都有了各自的缓存上限（Google 3D 约 1.5 GB，OSM 建筑约 0.5 GB）并且关闭了 MSAA（改用 FXAA），但是在加载地形 + 全球影像 + 高 DPI/4K 画布的情况下，其驻留集依然非常庞大。如果显卡的 VRAM 较小，Cesium 会更加频繁地清除和重新获取数据（导致 fps 降低、出现更多弹出效应），但依然能够运行。
| 等级 | GPU | RAM | 显示器 | 效果体验 |
|---|---|---|---|---|
| 最低配置 | 支持 WebGL2 的集成显卡 (Iris Xe / Vega / M1) | 8 GB | 1080p | 2D-暗色风格，区域缩放，约 30 fps。3D-卫星模式会比较卡顿。 |
| 推荐配置 | 独立显卡 ≥8 GB VRAM (RTX 3060 / RX 6700 / M-Pro) | 16 GB | 1080p–1440p | 2D-暗色风格流畅；3D-卫星模式在城市尺度下可用。 |
| 3D-卫星 / 4K | RTX 4070+ / 16 GB VRAM 或更高 | 32 GB | 最高支持 4K | 完整的 3D-卫星地形 + 建筑；高 fps。 |
这些等级是基于实际运行观察得出的结论。3D-卫星模式确实需要大量的 VRAM，而低 VRAM 的最低配置仅适用于 2D-暗色地图；一旦开启 3D-卫星模式，你就会希望有一张性能有余量的独立显卡。
**后端（服务器）：** Python 3.12，约 1 GB RAM，需要出站 HTTPS。可以在小型 VPS 或同一台机器上运行，它不是瓶颈所在。
## 技术栈
- **前端**: Vite + React 18 + TypeScript + CesiumJS + MapLibre GL JS v5.24 + Tailwind + Zustand
- **后端**: FastAPI (Python 3.12) + httpx + websockets。实时的*派生*状态存在于进程内（有界的观测存储 + 磁盘切片缓存）；持久化状态——位置轨迹回放存档、本体存储（对象 / 案件文件 / 态势）以及证据柜的监管链——被持久化到 SQLite 中，在 Compose 模式下存放在 Docker 卷中，默认使用滚动时间窗口，或通过 `ARCHIVE_MODE` 启用无限制的、受磁盘空间预算控制的存档
- **Agent 访问**: Model Context Protocol server (`app.mcp_server`，MCP SDK) + 可选的本地 Ollama 分析
- **数据（第二阶段，计划中）**: PostgreSQL 16 + PostGIS + TimescaleDB hypertables + Redis。SQLite 目前支持回放 + 本体存储；观测存储将根据计划 §locked-decisions #5 进行迁移
- **基础设施**: Docker Compose，nginx 反向代理
## 目录结构
```
osint/
├── apps/web/ # React + Cesium console (12-app workspace)
│ └── src/
│ ├── globe/ # Cesium globe, layers, map toolbar (measure/area/annotate)
│ ├── entity-panel/ # right-rail dossier / inspector
│ ├── evidence/ # chain-of-custody evidence locker UI
│ ├── foundry/ # FOUNDRY surface (datasets, pipeline DAG, builds, ontology)
│ └── shell/ # app switcher + detachable floating panels
├── apps/api/ # FastAPI backend
│ └── app/
│ ├── intel/ # agent-facing analytics, local ontology store, evidence, case export
│ ├── foundry/ # BYO-data layer: datasets, transforms, builds, checks, binding
│ ├── routes/intel.py # /api/intel/* deep-query JSON API
│ ├── routes/evidence.py# /api/evidence/* capture / verify / attach / manifest
│ ├── routes/foundry.py # /api/foundry/* datasets/pipelines/checks/bindings
│ └── mcp_server.py # Model Context Protocol server
├── packages/shared/ # Shared TS types (LayerDescriptor, Observation)
├── docs/ # design notes, decisions.md, foundry-plan.md
└── infra/ # Docker, nginx, db init
```
## 测试
```
# 从 repo ROOT 运行（从 apps/api 运行会导致 .env auth 解析失败 → 出现大量 401 错误）
OSINT_DISABLE_BACKGROUND=1 apps/api/.venv/bin/pytest apps/api -q # 1687 passed + 1 skipped
pnpm -r test # vitest (web, shared)
pnpm -r typecheck
bash scripts/verify.sh # typecheck + lint + web unit + api tests in one shot
# 手动 MCP integration drivers（需要 backend 在 :8000 运行）：
# apps/api/.venv/bin/python tests/mcp_client_check.py # stdio handshake
# apps/api/.venv/bin/python tests/mcp_full_check.py # tools end-to-end + Ollama
```
## 阶段状态
这是内部的构建日志，按交付顺序排列——而不是推介材料（那部分在上面）。图例：✅ 已交付 · 🚧 进行中
- ✅ **阶段 0** — 基础架构
- ✅ **阶段 1** — MVP：在地球仪上显示实时 ADS-B / AIS / 地震 / GPS 干扰图层
- ✅ **阶段 2** — 回放 + 深入分析。时间线滑动条和基于磁盘的历史存档以 SQLite 回放的形式交付（默认 48 小时滚动窗口，或通过 `ARCHIVE_MODE` 启用无限制的、受磁盘空间预算控制的存档）；现在就可以深入查看过去任一时刻的情况。一个用于支撑平台其余状态的、持久化的 Postgres + PostGIS + TimescaleDB 存储是一个推迟的扩展性升级，而不是阻塞项
- ✅ **阶段 3** — 融合引擎 + 警报（相关性规则）+ 2D 镜像
- 🚧 **阶段 4** — 高级传感器 + Agent 访问。MCP 服务器 + 情报 API（现配有 Claude Code 插件和 `detail=short|long` 工具变体），Sentinel-1 SAR 黑暗船只探测，一个能够自动撰写带引用事件简报并借此自动填充本体图谱的自主值班军官，一个无 key 的基础设施数字 OSINT 层，一个地点/空域图层（FAA TFR 多边形、军事基地、NGA 航海警告、World Port Index 港口详情、NASR/METAR 机场信息丰富、八选一的无 key 底图选择器），一个**监管链证据柜**和**案件→报告导出**（支持每项声明都带有来源的 JSON/HTML/PPTX），一个地球仪地图工具栏（测量/框选/标注）和可分离的浮动面板，一个照片地理定位 pipeline，一个 City 3D 高斯泼溅查看器，可选的本地 GPU (Ollama) 推理，以及首次运行的引导教程。更多传感器和更深入的分析正在持续开发中。
- 🚧 **阶段 5** — Foundry：一个无 key、本地化、单用户版本的 Palantir Foundry 数据集成闭环。上传 → 转换（受管控的 13 步 DSL 并带有血缘追踪）→ 构建（依赖 DAG、过期检测、循环拒绝）→ 数据健康检查 → 绑定到本地本体图谱。已包含：不可变版本 + 回滚、行级隔离/死信队列、新鲜度/schema 偏移 SLA、窗口/透视分析、实体解析。特意排除在范围之外（基于单用户身份）：多租户 MLS、分布式计算、流式 CDC、连接器目录。下一步：本体操作（经审计的写回）和数据集分支。
- 🚧 **阶段 6** — Workflows：建立在相同的实时 feed 和本体之上的节点图自动化层。包含 20 个区块——数据源（飞机、船只、地震、警报、数据集、本体、国家）、转换（`op.python`/`op.sql`/`op.llm` 沙盒子进程，`op.geo`、`op.http`、`op.steps`）、接收器（警报、本体、数据集、持久化内存），以及能够跨越平台向外扩展的**外部驱动控制块**：用于连接至任意服务器的 `control.webhook`，以及用于通过 JSON 信封指令无人机或硬件设备的 `control.drone`/`control.device`。一个一流的 **MAVLink bridge**（`app.mavlink_bridge`，支持 ArduPilot/PX4，在没有飞行器时仅记录日志以便于演练）已包含在仓库中。请参阅 [`docs/workflows-control-blocks.md`](./docs/workflows-control-blocks.md)。
请参阅 [`docs/`](./docs) 获取按功能分类的设计说明和 pipeline 详细说明。
## 许可证
[AGPL-3.0-or-later](./LICENSE) 涵盖了 Velocity 的**源代码**。上游的**数据受其各自的许可证约束**；有几个 feed 是非商业/学术性质的（例如 ACLED、adsb.fi、OpenSky）。请参阅 [`NOTICE`](./NOTICE) 获取按来源划分的归属和条款说明，并在进行任何商业或再分发使用之前，核实每个上游目前的最新条款。
本项不作任何保证，且对于你如何收集或使用数据不承担任何责任——请参阅 [`DISCLAIMER.md`](./DISCLAIMER.md)，该文件还涵盖了抓取行为、上游条款、个人数据以及禁止的用途。
不使用 Docker 进行本地开发
``` make install # pnpm install + api venv cd apps/api && .venv/bin/uvicorn app.main:app # backend on :8000 pnpm dev # vite on :5173, proxies /api to localhost:8000 ``` 如果后端不在 `http://localhost:8000` 上，请设置 `VITE_API_URL`。如果你在后端设置了 `API_KEY`，请使用匹配的 `VITE_API_KEY` 构建 Web 应用；它会在每次调用时作为 `X-API-Key` 随请求发送。标签：3D地球可视化, ESC4, HTTP/HTTPS抓包, MITM代理, OSINT, 态势感知, 数据关联, 数据溯源, 自托管, 请求拦截, 逆向工具, 黄金证书