jetlog 介绍与选型指南

目标：说清楚 jetlog 是什么、能做什么、架构与功能边界如何，并与同类自托管飞行记录应用做量化对比，帮助读者判断「要不要用、适不适合自己」。本文为认知篇，全部信息来自官方仓库与官方文档的联网溯源（查询日期：2026-10-30），未混入任何本地实验结论。

一、环境信息

本文是一篇纯联网溯源的认知篇，先交代证据基础，便于读者复核时效性：

• 查询日期：2026-10-30（下述所有版本号、星数、发布时间均以该日查询结果为准）
• 信息来源：
  • GitHub 仓库：pbogre/jetlog（README、源码结构、LICENSE）
  • GitHub Releases 页：pbogre/jetlog/releases（版本清单与发布说明）
  • 官方 Installation Wiki：github.com/pbogre/jetlog/wiki/Installation（环境变量、路径前缀、镜像 tag 策略）
  • shields.io 徽章服务（GitHub 星数、Docker Hub 拉取量，取自仓库页与徽章接口返回值）
  • 同类项目官方页面：AirTrail 官网、FlightAirMap 仓库、OpenFlights 官网 FAQ
• 核验到的最新稳定版：v1.2（Releases 页最新条目「v1.2 - UI Overhaul 🎉」，发布于 2026-06-26；撰写本系列文档时该版本即最新稳定版）

💡 说明：jetlog 的官方发布形态只有 Docker 镜像与源码两种，官方 README 的 Getting Started 直接以 docker-compose.yml 起步；部署细节见本专栏《jetlog 1.2 Docker Compose 部署指南》。

二、软件概述

jetlog（下文按官方拼写 Jetlog/jetlog 混用，指同一项目）是一个可自托管的个人飞行记录追踪与查看器（官方原话：A self-hostable personal flight tracker and viewer）。它面向的人群是飞行爱好者与常旅客：把自己坐过的每一班飞机（日期、起降机场、时刻、舱位、座位、机型、航司、航班号、备注）记进一个属于自己的 Web 应用，然后获得世界地图航迹、统计面板和多格式导入导出能力。

关键身份信息（均查自 GitHub 仓库页与 Releases 页，2026-10-30）：

💡 技术拓展：自托管应用的镜像 tag 策略常见三种流派——「滚动 latest」（始终最新，省心但不可复现）、「双轨 latest+experimental」（jetlog 采用，兼顾尝鲜与稳定）、「纯版本 tag」（每个版本独立 tag，最可复现）。jetlog 三者兼备：生产环境建议锁定 x.x.x（如 1.2），本系列文档实测即采用 pbogre/jetlog:1.2。

从版本节奏看（Releases 页逐条核对）：v1.1.1（2025 年 2 月，自动抓取航班数据、航司字段）→ v1.1.2（2025 年 3 月，时区支持、HTTP 头认证、BASE_URL）→ v1.1.3（2025 年 5 月，Flighty CSV 导入、联程航班、到访国家统计）→ v1.1.5（2025 年 7 月，IPv6、航司统计）→ v1.1.6（2025 年 10 月，多用户管理增强、ENABLE_EXTERNAL_APIS 隐私开关）→ v1.1.7（2025 年 11 月，修复）→ v1.2（2026 年 6 月，UI 大改版）。平均一至两个月一个功能版本，个人项目里属于维护相当活跃的。

三、核心架构

以下架构信息来自官方 README 的 Stack 一节与仓库源码目录结构（2026-10-30 查证）：

• 后端：FastAPI（Python 异步 Web 框架），以 uvicorn 运行；API 自动生成 OpenAPI 文档（/docs 交互页面与 /openapi.json 规范文件）。
• 数据库：SQLite 单文件数据库。整个应用的数据就是一个 jetlog.db 文件（放在容器的 /data 目录），没有外部数据库依赖——这是它「轻」的根本原因。
• 前端：React + TailwindCSS 构建的单页应用（SPA），构建产物由 FastAPI 直接静态托管，不需要独立的 Node 服务或前端网关。
• 认证：JWT（HS256 签名，密钥来自环境变量 SECRET_KEY），密码哈希采用 argon2id；除 Web 登录外还支持通过环境变量 AUTH_HEADER 对接反代/S SO 场景的请求头认证（详见 Installation Wiki，官方同时警告「不了解就不要用」）。
• 内置参考数据：机场与航司库来自 OurAirports 数据集，应用初始化时自动导入，因此记录航班时起降机场可以直接按 IATA/ICAO 代码与城市名联想选择，机场的经纬度、时区也随之可用——距离与飞行时长能自动按大圆航线（Haversine 公式）与时区换算。
• 外部服务：adsbdb 公共 API，用于按航班号自动补全航司等信息；这是 jetlog 唯一的外部依赖，且提供了环境变量 ENABLE_EXTERNAL_APIS=false 的一键关闭开关（官方 README 的 Privacy Notice 明确说明：jetlog 本身不收集任何用户数据，介意隐私的用户可关闭外部 API）。

一句话总结架构特点：单进程 + 单文件 + 可选外部 API，部署面只有一个服务实例，备份面只有一个 SQLite 文件，这是它与需要 PostgreSQL/MySQL 的同类应用最本质的差异。

四、功能特性

按官方 README 的 Features 一节逐条核对，并结合 Releases 页各版本说明（2026-10-30）：

• 世界地图航迹视图：react-simple-maps + 世界 GeoJSON 绘制，可显示全部航线的飞行轨迹线与机场标记（含频次），支持只显示到访过的国家区域（v1.1.6 起「Allow restricting world map to visited region」）。
• 统计面板：总航班数、总飞行时长、总里程、到访机场数、到访国家数、日期跨度，以及最常到访机场 Top5、最常到访国家 Top5、座位偏好、舱位分布、最常乘坐航司 Top5（v1.1.1/1.1.3/1.1.5 逐步补齐）。
• 航班增删改查：手工录入过去飞过的航班；起降机场填 ICAO/IATA 代码即可，距离自动按大圆航线计算、时长自动按两地时区换算（v1.1.2 引入时区支持）；同一行程的联程航班可标记 connection 关联（v1.1.3），并支持在设置页一键批量计算历史航班的联程关系。
• 多用户支持：管理员（admin）可以创建/编辑/删除普通用户，普通用户只能看自己的航班；管理页可批量管理（v1.1.6/1.1.7 增强）。
• 导入：MyFlightRadar24 导出的 CSV、Flighty App 导出的 CSV（v1.1.3 起）、以及列名自选的自定义 CSV（按 jetlog 自己的字段名组织表头即可）。
• 导出：CSV（全字段）与 iCal 日历（每条航班一个 VEVENT，可订阅进日历应用）。
• 安全认证：argon2id 密码哈希 + JWT；默认仅创建一个 admin/admin 账号，官方明确要求首次登录后立即改密。
• 响应式设计：手机/桌面自适应；另有分翻牌式（SplitFlap）首页时钟等 v1.2 界面改版细节。
• 路径前缀部署：设置 JETLOG_BASE_URL 即可把 jetlog 挂在反向代理的子路径下（如 https://example.com/jetlog/），官方 Wiki 给了完整 nginx 配置示例。

五、快速开始（最小可用示例）

以下最小部署示例原样摘自官方 README 的 Getting Started（2026-10-30 查证），仅两行环境变量即可起服务：

services:
  jetlog:
    image: pbogre/jetlog:latest
    volumes:
      - /your/data/path:/data
    environment:
        JETLOG_PORT: 3000 # optional, default is 3000
        SECRET_KEY: yourLongAndRandomStringOfCharacters123!
    restart: unless-stopped
    ports:
      - 3000:3000

官方 README 同时给出三条关键提示，原样转述：

1. 服务起来后，默认管理员账号的用户名和密码都是 admin；
2. 首次登录后务必立即修改该默认密码；
3. 排障、环境变量、子路径部署等更多安装选项，见 Installation Wiki。

完整的从零部署流程（目录规划、端口选择、首次初始化实测回显、改密、备份、升级）见本专栏《jetlog 1.2 Docker Compose 部署指南》；全部环境变量的逐项实测见《jetlog 1.2 配置参数详解》；REST API 的逐接口实测见《jetlog 1.2 REST API 使用详解》。

六、适用场景与限制

适合的场景：

• 个人/家庭的自托管飞行日志：一台小主机或 NAS 即可长期运行，SQLite 单文件随手备份；
• 飞行爱好者 want 统计与地图可视化，且数据要握在自己手里（可关闭全部外部 API 调用）；
• 从 MyFlightRadar24 / Flighty 迁移历史的用户：官方导入器直接吃这两家的导出 CSV；
• 需要把航班同步进日历的用户：iCal 导出可订阅。

限制（源自身份与架构，选型前必须接受）：

• 单实例、单文件：SQLite 决定了它不适合多人高频并发写入的团队场景，也没有内置高可用；官方未提供集群形态。
• 无自动航班同步：除按航班号查询 adsbdb 补全航司信息外，不会自动导入航司 App 的行程，录入以手工和 CSV 导入为主。
• 认证体系较简单：账号密码 + JWT，没有内置 OAuth/LDAP；反代头认证（AUTH_HEADER）可用但官方自述有安全风险，需自行评估。
• HTTPS 不内置：需要自己上反向代理（官方 Wiki 提供 nginx 示例）。
• 个人项目节奏：无商业支持，issue/PR 响应取决于维护者个人；选型时应接受「锁版本 + 自行备份」的运维姿势。

七、同类选型对比

「记录自己坐过的航班」这个需求下，可自托管的开源同类项目主要有 AirTrail、FlightAirMap、OpenFlights，以及尚在早期的 TravStats。下表数据来源与查询日期：各项目官方仓库/官网 + shields.io 星数徽章（2026-10-30）。

关键差异与选型建议：

• 要记录「我坐过的航班」（个人行程日志）：在 jetlog 与 AirTrail 之间选。AirTrail 社区热度更高（1.7k 星）、导入源更丰富（TripIt/OpenFlights）、支持 OAuth 登录，但依赖较 jetlog 重；jetlog 胜在极轻（SQLite 单文件、单服务）、隐私开关明确（外部 API 可一键关停）、iCal 导出对日历订阅友好。追求「最小运维面 + 数据主权」选 jetlog，追求「导入生态 + OAuth」选 AirTrail。
• 要看「天上现在飞着的飞机」（实时 ADS-B 地图）：那是 FlightAirMap 的领域，与个人行程日志是两类需求，不要混选。
• 要轻量古董级、能自架的飞行日志 + 机场数据库：OpenFlights 功能完整但架构老旧，适合情怀与数据复用（它本身就是 AirTrail/jetlog 导入链路里的常见中转格式）。
• 若你的「记录型」需求不限于飞行——比如车辆维保与油耗记录，可参考本平台同类「个人记录型」自托管应用 《LubeLogger 介绍与选型指南》，其选型思路（轻量单服务、单用户家庭共享、导入导出闭环）与本文一致。

八、参考链接

• 官方 GitHub 仓库：https://github.com/pbogre/jetlog（README、LICENSE、源码）
• Releases 版本页：https://github.com/pbogre/jetlog/releases（v1.2 发布说明）
• Installation Wiki：https://github.com/pbogre/jetlog/wiki/Installation（环境变量表、路径前缀、镜像 tag 策略）
• Importing Wiki：https://github.com/pbogre/jetlog/wiki/Importing（导入格式说明）
• Docker Hub 镜像页：https://hub.docker.com/r/pbogre/jetlog
• adsbdb（外部航班号查询 API）：https://www.adsbdb.com/
• OurAirports（内置机场数据集）：https://ourairports.com/
• 同类项目：AirTrail https://airtrail.johan.ohly.dk/；FlightAirMap https://github.com/Ysurac/FlightAirMap；OpenFlights https://openflights.org/faq
• 本专栏相关篇目：《jetlog 1.2 Docker Compose 部署指南》（部署与改密实测）、《jetlog 1.2 配置参数详解》（环境变量逐项实测）、《jetlog 1.2 REST API 使用详解》（接口实测）

本文所有外部信息均标注了查询日期 2026-10-30；版本号、星数、拉取量随时间变化，读者复核时请以当日官方页面为准。