frankea/adsbtrack
GitHub: frankea/adsbtrack
一款离线聚合多源 ADS-B 历史数据并结构化航班记录的分析工具。
Stars: 5 | Forks: 0
# adsbtrack
从多个追踪网络获取历史 ADS-B 轨迹数据，并将其转换为结构化的飞行历史记录。给它一个 ICAO 十六进制码和日期范围，它将获取每一天的轨迹数据，提取单个航班，匹配起降坐标到机场，对每次降落按质量进行分类，并提供旅行模式统计信息。
专为 OSIST 和航空爱好者设计，旨在超越实时追踪，深入挖掘飞机在过去数月或数年中实际飞行过的区域——提供足够丰富的信号质量元数据以确保结果可信。
## 安装
需要 Python 3.12+。使用 [uv](https://github.com/astral-sh/uv)：
```
git clone https://github.com/frankea/adsbtrack.git
cd adsbtrack
uv sync
```
## 用法
### 获取追踪数据
```
uv run python -m adsbtrack.cli fetch --hex a66ad3 --start 2020-01-01
```
下载每日追踪数据并自动提取航班。选项：`--source`（adsbx、adsbfi、airplaneslive、adsblol、theairtraffic、opensky）、`--end`、`--rate`、`--db`、`--tail`（将 N 号转换为十六进制）。跳过已获取的日期。WAL 模式允许多个提取任务并行运行。
### 查看统计信息
```
uv run python -m adsbtrack.cli status --hex a66ad3
```
```
Status for a66ad3
Registration: N512WB
Type: Pilatus PC-XII 45
Date range: 2020-01-01 to 2026-04-10
Days w/ data: 392
Total flights: 628
Data quality:
Confirmed landings: 361 (54%)
Signal lost: 74 (11%)
Utilization:
Total hours: 1843.5
Avg flight: 166.4 min
Distinct airports: 47
```
展示数据质量分布、任务类型占比、利用情况汇总、夜间/紧急指示以及主要机场信息。
### 查看航班历史
```
uv run python -m adsbtrack.cli trips --hex a66ad3 --from 2026-03-27
```
```
Flights for a66ad3
Date | From | To | Duration | Callsign | Mission | Conf | Type
2026-03-27 | 67FL | KSPG | 10m | N512WB | XFER | 76% | OK
2026-03-27 | KSPG | KHKY | 1h 53m | N512WB | XFER | 89% | OK
2026-03-28 | KHKY | KVNC | 2h 41m | N512WB | XFER | 86% | OK
2026-03-29 | KSPG | ~KFXE | 12m | N512WB | | 0% | DROP
```
`Conf` 表示降落置信度（0-100%），`Type` 表示降落分类（OK/SIG LOST/DROP/UNCERT/ALT ERR）。选项：`--from`、`--to`、`--airport`。
### 重新提取航班
```
uv run python -m adsbtrack.cli extract --hex a66ad3 --reprocess
```
根据原始追踪数据重建航班表，适用于代码变更后重新处理。
## FAA 飞机注册信息
加载 FAA 批量注册文件（`ReleasableAircraft.zip`），使十六进制码能够解析为注册人姓名、地址、证书日期以及注销历史。使用 `faa` 额外依赖安装，以便绕过 Akamai TLS 指纹屏蔽：
```
uv sync --extra faa
uv run python -m adsbtrack.cli registry update
```
如果不安装 `curl_cffi`（即 `faa` 额外依赖），在线下载通常会返回 503。可改用浏览器下载 ZIP 文件，并将命令指向该文件：
```
uv run python -m adsbtrack.cli registry update --zip /path/to/ReleasableAircraft.zip
```
然后查询：
```
uv run python -m adsbtrack.cli registry lookup --hex a66ad3 # full record by hex
uv run python -m adsbtrack.cli registry lookup --tail N512WB # or by N-number
uv run python -m adsbtrack.cli registry owner --name "BANK OF UTAH" # LIKE match
uv run python -m adsbtrack.cli registry address --state MT --city BILLINGS
```
加载注册表后，`status` 命令会在行内显示 FAA 注册人、地址和证书信息，并标记仅出现在 `faa_deregistered` 中的飞机。
## ACARS 摄入
从 [airframes.io](https://app.airframes.io) 获取某架飞机的 ACARS / VDL2 / HFDL 消息，并将 OOOI 事件关联到其航班：
```
export AIRFRAMES_API_KEY=... # or put "airframesApiKey" in credentials.json
uv run python -m adsbtrack.cli acars --hex a66ad3 --start 2026-01-01
```
提取器会将十六进制码解析为 airframes.io 的数字机身 ID，遍历指定范围内的每个航班，并插入原始消息。当 OOOI 标签（14 / 44 / 4T / H1）位于航班时间窗口内时，解析器会填充 `acars_out`、`acars_off`、`acars_on`、`acars_in` 字段。
`trips` 会显示 ACARS 列及消息计数，并在存在 OOOI 信息时显示绿色 OOOI 标识；`status` 会为每架飞机显示 ACARS 汇总块。
## 十六进制码交叉引用增强
将 FAA + [Mictronics](https://github.com/Mictronics/readsb-protobuf/tree/dev/webapp/src/db) + [hexdb.io](https://hexdb.io) 合并到单个 `hex_crossref` 表中，使数据库中的每个十六进制码都能获得最佳匹配的识别信息，并标记已知军用分配区间的飞机。
```
uv run python -m adsbtrack.cli enrich all --download-mictronics # backfill everything
uv run python -m adsbtrack.cli enrich hex --hex a66ad3 # one at a time
uv run python -m adsbtrack.cli mil hex --hex ae1234 # check mil range
uv run python -m adsbtrack.cli mil scan # flag every mil hex
```
合并顺序为：FAA（优先）→ Mictronics → hexdb.io；增强器会标记冲突以便查看来源差异。25 个有充分文档记录的军用分配范围（如美国国防部、英国皇家空军、德国空军、日本航空自卫队、澳大利亚皇家空军、加拿大皇家空军、俄罗斯空天军等）在数据库初始化时自动加载；可通过向 `mil_hex_ranges` 表添加自定义行来扩展覆盖范围。
## 查找十六进制码
直接转换美国 N 号：
```
uv run python -m adsbtrack.cli lookup --tail N512WB
```
或对任意命令使用 `--tail` 替代 `--hex`：
```
uv run python -m adsbtrack.cli fetch --tail N512WB --start 2020-01-01
```
外部查询站点：[aircraftdata.org](https://aircraftdata.org)、[FAA Aircraft Registry](https://registry.faa.gov/aircraftinquiry)、[ADS-B Exchange](https://globe.adsbexchange.com/)
## 生成追踪 URL
```
uv run python -m adsbtrack.cli links --hex a66ad3
```
```
2026-03-27 67FL -> KSPG https://globe.adsbexchange.com/?icao=a66ad3&showTrace=2026-03-27
2026-03-27 KSPG -> KHKY https://globe.adsbexchange.com/?icao=a66ad3&showTrace=2026-03-27
```
使用 `--urls-only` 可输出每行一个原始 URL（无前缀或标记），便于用于 shell 循环管道。
## 多数据源
从不同网络获取数据以获得更好覆盖：
```
uv run python -m adsbtrack.cli fetch --hex a66ad3 --source adsbfi --start 2020-01-01
```
追踪数据在提取过程中会自动合并。
| 来源 | 标志 | 说明 |
|------|------|------|
| [ADS-B Exchange](https://globe.adsbexchange.com/) | `--source adsbx` | 默认 |
| [adsb.fi](https://globe.adsb.fi/) | `--source adsbfi` | |
| [airplanes.live](https://globe.airplanes.live/) | `--source airplaneslive` | |
| [adsb.lol](https://adsb.lol/) | `--source adsblol` | |
| [TheAirTraffic](https://globe.theairtraffic.com/) | `--source theairtraffic` | |
| [OpenSky Network](https://opensky-network.org/) | `--source opensky` | 需设置 `OPENSKY_CLIENT_ID` 与 `OPENSKY_CLIENT_SECRET` 环境变量 |
| 自定义 | `--url ` | 任何 readsb globe_history 实例 |
## 文档
面向贡献者和分析师的详细参考文档：
- **[数据库架构](docs/schema.md)** - 所有表（traces / flights / registry / stats / airports / helipads / FAA registry / ACARS / hex crossref / mil ranges）的完整列说明
- **[功能与评分](docs/features.md)** - 降落类型、置信度评分算法、每个派生列、任务分类规则、信号预算、ACARS OOOI、来源分布
- **[内部机制](docs/internals.md)** - 提取器如何工作：追踪合并、航班提取状态机、片段拼接、机场匹配、FAA 注册表解析、十六进制交叉引用合并
## 开发
```
uv sync --extra dev
uv run pytest
uv run ruff check .
uv run ruff format .
uv run mypy adsbtrack
```
CI 在推送和拉取请求时运行（Python 3.12 与 3.13）。
## 注意事项
- 数据可用性取决于 ADS-B 接收机覆盖范围。飞越海洋或偏远地区的航班会出现数据缺口，表现为 `signal_lost` 或 `dropped_on_approach`，而非缺失航班。
- 不同接收网络覆盖范围不同，因此从多个来源获取可获得最佳结果。
- 限流策略自适应：遇到 429 会增加延迟，连续成功会逐步恢复。
- `extract --reprocess` 会清除并从头重建所有航班表，数据库架构会自动迁移。
标签：ADS-B, DNS解析, ESC4, ICAO hex, OSINT, Python, Python 3.12+, SQLite, UV工具链, WAL模式, 信号质量元数据, 历史轨迹, 并行处理, 开源项目, 数据库, 数据提取, 数据质量分类, 旅行模式统计, 无后门, 机场匹配, 航班分类, 航班统计, 航空数据, 航空数据挖掘, 航空爱好者, 起降坐标, 起降机场识别, 逆向工具, 飞机监控, 飞行历史, 飞行追踪