企业官网建设流程全解析

如何在三维地图上看DIY AirTag的永久轨迹？NinjiaTag Web前端完整使用指南（轨迹点/热图/GPX导出）

【免费下载链接】NinjiaTag-backend项目地址: https://gitcode.com/gh_mirrors/ni/NinjiaTag-backend

NinjiaTag 是一个开源的 DIY AirTag 项目：无需 Mac、也无需一直开着 iPhone，自建服务器即可从 FindMy 网络后台永久抓取并保存你 DIY 定位标签的位置数据。本指南带你一步步完成 NinjiaTag Web 前端的全部操作——配置服务器地址、导入物品密钥、在三维地图上查询轨迹点与热图，并导出 GPX 轨迹文件，把 DIY AirTag 的永久轨迹真正"看"在手里。

30秒速览：NinjiaTag 的三维轨迹能做什么

和"只能看最新位置"的方案不同，NinjiaTag 的核心卖点是轨迹永久记录：

• ✅ 后端定期从 FindMy 网络拉取位置，存入本地 SQLite 数据库，存储时长不限（主流同类产品一般只保留 7 天）
• ✅ 基于开源 Mapbox-GL 三维地图引擎，支持三维地形显示，渲染美观
• ✅ 支持任意时间段、单/多物品查询：轨迹点、热图、最新位置三种模式
• ✅ 支持导出 GPX（GPS eXchange Format）轨迹文件，可导入其他地图工具
• ✅ Web 前端内置密钥管理，导入 JSON 密钥文件即可绑定物品

硬件门槛很低：一颗烧录好固件的蓝牙模块（nRF5x 或 ST17H66）+ 一枚纽扣电池，就能成为兼容 FindMy 网络的 DIY AirTag。成品开箱教程见usr_guide/2032_TAG.md（2032 圆形 Tag）与usr_guide/Mini_TAG.md（迷你版接线），刷写模块参考flash_guide/目录下的两份烧录教程。

第一步：打开 Web 前端并配置服务器地址

1. 用浏览器打开 NinjiaTag Web 前端页面（NinjiaTagPage，基于 Vue3 + Mapbox-GL 开发），建议收藏或添加到桌面，手机、电脑都能访问。
2. 点击页面右上角的"配置服务器"按钮，填入你部署的数据查询服务地址，格式为http://服务器ip:3000/query，注意加上/query后缀，保存即可。
3. 后端服务由项目根目录的server.mjs提供：默认监听 3000 端口，通过/query接口从本地 SQLite 数据库（reports.db）中查询位置数据。

💡 提示：如果你把前端页面部署在 HTTPS 域名下，由于浏览器安全限制，后端服务也必须部署为 HTTPS（需要 SSL 证书），否则无法访问。

第二步：添加 DIY AirTag 物品，两种方式任选

方式一：粘贴序列号添加（购买成品推荐）

用微信扫描包装盒上的序列号二维码，得到一串序列号：

点击页面左下角"物品管理"按钮，在"粘贴序列号或 JSON 密钥添加"输入框中粘贴序列号，点击右侧的 ＋ 号按钮即可添加：

方式二：导入 JSON 密钥文件（自建服务器推荐）

自行烧录固件时，先在keygen/目录执行python3 generate_keys.py生成密钥（该脚本支持-n参数批量生成多密钥滚动标签，滚动密钥能让位置上报更频繁，但功耗略增）。然后把生成的.json密钥文件通过"物品管理 → 解析 JSON 密钥文件"上传，解析后选择"确认使用数据"保存密钥即可。

添加完成后，在"物品管理"对话框中点击刷新按钮：能看到最新更新日期，说明已成功从后端获取到位置数据。

第三步：三维地图查询轨迹——轨迹点、热图、最新位置三种模式

点击主页面右下角的"数据选择"按钮，在对话框中选择物品和时间段，即可切换三种查询模式：

• 轨迹点：把历史轨迹以点阵形式渲染在三维地图上，鼠标悬停或点击任意轨迹点，即可显示该点的经纬度和时间点，支持随意缩放回溯任意历史时刻的位置。
• 热图（Hotspot）：类似 GIS 系统的人流密度显示——Tag 经常待的地方颜色更深，偶尔去或从不去的地方颜色浅，一眼看穿它"跑过"哪些地方。
• 最新位置：以图标形式显示物品当前最新上报的位置。

底图引擎为 Mapbox-GL，支持三维地形渲染，页面左上角可自由切换卫星、浅色、深色、街道、户外及高德地图等底图样式。

第四步：GPX 导出——把永久轨迹带进专业工具

前端支持对单个或多个物品、任意时间段的轨迹导出 GPX（GPS eXchange Format）文件。操作步骤：

1. 在"数据选择"对话框中勾选目标物品；
2. 设定起止时间范围；
3. 执行 GPX 导出，下载生成的文件。

下载的 GPX 文件可以导入 Google Earth、各类运动户外导航软件等第三方工具，用更专业的视角回放你的 DIY AirTag 出行轨迹，也能方便地与自己的历史行程做对比分析。

常见问题：为什么看不到位置数据？

• 刚添加物品 / 数据为空：DIY AirTag 的位置来自 FindMy 网络中"路过"的苹果设备，带上 Tag 到地铁、商场等人流密集处走一圈，等待后台抓取入库即可。
• 后台抓取有间隔：request_reports.mjs定时任务默认每 5 分钟向 FindMy 服务器请求一次位置并写入数据库（cron 间隔可自行修改），刚更新的位置请稍等片刻再刷新。
• 刷新太快被限流：后端/query接口对每个 IP 做了限流（5 分钟内最多 100 次请求），短时间内频繁刷新会被临时拒绝。
• 浏览器自动跳转 https：直接访问 http 地址时可能被自动重定向，把地址栏改回http再回车即可。

项目核心文件速查

⚠️ 免责声明：NinjiaTag 仅用于研究与物品防丢场景，请遵守当地法律法规，严禁将本项目用于非法追踪用途。

配置好服务器地址、导入密钥、选一个时间段点一下"轨迹点"——你的 DIY AirTag 从此不再只有一张"最新位置"截图，而是一条可以在三维地图上无限回看、随时导出 GPX 的永久轨迹。

【免费下载链接】NinjiaTag-backend项目地址: https://gitcode.com/gh_mirrors/ni/NinjiaTag-backend