Traccar 定位追踪-把家人和车辆的位置数据留在自己的盒子里 · 懒猫微服使用攻略

> 适用版本：懒猫商店「Traccar 定位追踪」1.0.21 及以上（包名 `f00700f.traccar`，基于上游 Traccar 6.16.0）。 > 文中 `<盒子名>` 请替换成你自己的微服名称，例如盒子叫 `landan`，应用地址就是 `https://traccar.landan.heiyu.space`。 > 文中截图来自同一镜像的测试实例，地图上的设备、轨迹、围栏都是**演示数据**（杭州），不是真实行程。 # 快速配置（5 步跑通） 1. **安装**：懒猫商店搜索「Traccar 定位追踪」并安装。 https://appstore.lazycat.cloud/#/shop/detail/f00700f.traccar 3. **登录**：打开 `https://traccar.<盒子名>.heiyu.space`，点「使用懒猫账号登录」，免密进入（微服管理员自动成为 Traccar 管理员）。 4. **添加设备**：设备列表点「+」，填名称和标识符（如 100004），保存。 5. **手机上报**：手机安装官方 Traccar Client，「设备标识符」填第 3 步的标识符，「服务器地址」填 `https://traccar.<盒子名>.heiyu.space/osmand/`，打开服务开关。这个地址要求手机安装并登录懒猫客户端；手机不装懒猫客户端时，用商店的 Cloudflared UI 把 `http://traccar-server.f00700f.traccar.lzcapp:5055` 映射成自己的域名，服务器地址改填该域名。 6. **看位置**：回到网页，设备变成「在线」，地图上出现位置；可再用「轨迹回放」「报表」查看历史。 设备照片可以从懒猫网盘选择上传，报表和轨迹导出可以直接保存到懒猫网盘，见「懒猫网盘」一节。 # 一、Traccar 是什么，适合谁 Traccar 是一款老牌开源 GPS 定位平台（Apache-2.0 协议）。装到懒猫微服上之后，它就是一台**只属于你家的定位服务器**： - **家人定位**：给爸妈、孩子的手机装上官方免费 App「Traccar Client」，随时在网页地图上看到位置； - **车辆记录**：放一台旧手机在车里，自动记录每天的行程、里程、停车点； - **外出轨迹**：徒步、骑行、出差时开着 App，回来按天回放完整轨迹； - **到家/离开提醒**：给「家」「公司」「学校」画地理围栏，进出时网页弹提醒、事件自动记账。 和各种商业定位 App 比，最大的区别是：**位置数据只上报到你自己的盒子**，不经过第三方云平台，也没有订阅费。 本商店版做了这些适配： | 项目 | 商店版的做法 | | -------- | ------------------------------------------------------------ | | 登录 | 接入懒猫账号（OIDC）免密登录；**微服管理员自动成为 Traccar 管理员**，普通成员是普通用户 | | 注册 | 关闭了 Traccar 自带的注册表单，账号统一来自懒猫 | | 手机上报 | 开放公开路径 `/osmand/`，装了懒猫客户端的手机上报时不用登录懒猫账号；没装客户端的手机访问不了 `heiyu.space`，要用 Cloudflared UI 映射的固定域名（见 4.4 节） | | 协议 | 只开启 OsmAnd 协议（官方 Traccar Client 用的就是它） | | 地图 | 默认高德地图，另可切换 OpenFreeMap、OpenStreetMap | | 单位 | 默认公里、公里/小时 | | 网盘 | 接入懒猫网盘文件选择器：设备照片、服务器文件、日历、围栏 GPX 可从网盘选；报表、轨迹导出可存到网盘 | | 数据 | 内置数据库、设备照片、上传的文件都存放在应用数据目录，重启和升级不丢 | # 二、安装与首次登录 1. 在懒猫商店搜索「Traccar 定位追踪」，点击安装。 2. 从启动台打开应用，或在浏览器访问 `https://traccar.<盒子名>.heiyu.space`。第一次打开时，懒猫会先弹出应用的「使用须知」，读完关闭即可。 3. 应用会跳转到懒猫账号授权。**第一次**可能会看到懒猫的授权页面，点一次 **Grant Access（允许访问）**，之后就是免密直进。 - 如果停在 Traccar 自己的登录页，点「使用懒猫账号登录」按钮即可，不需要输入任何账号密码。 4. 登录后就是主界面：左侧是设备列表，右侧是地图，底部有「地图 / 报表 / 设置 / 账户」四个入口。  > **权限说明**：微服**管理员**登录后自动是 Traccar 管理员，能看到「设置 › 服务器 / 用户」等管理项；家里其他懒猫成员第一次打开应用时会自动建一个**普通用户**，默认看不到任何设备，需要管理员把设备分配给他（见第九节）。 # 三、在网页里添加设备 每一部要被定位的手机（或其他设备）都要先在网页里「登记」，Traccar 只接收已登记标识符的上报。 1. 在主界面设备列表顶部点 **「+」**（或进入「设置 › 设备」，点右下角「+」）。 2. 填写两项必填内容： - **名称**：随便起，比如「奶奶的手机」「家用车」； - **标识符**：一串唯一的字符，比如 `100004`。**手机 App 里的「设备标识符」必须和这里一模一样**（区分大小写）。 3. 「附加」里可以选**类别**（人、汽车、自行车……，决定地图上的图标）、填电话、型号等，可不填。 4. 点「保存」。  > **小技巧**：Traccar Client 装好后会自带一个随机的「设备标识符」。你可以直接把那串数字抄到网页的「标识符」里；也可以反过来，在网页里定一个好记的（如 `100004`），再到 App 里把标识符改成它。两边一致即可。 添加完成后，在「设置 › 设备」能看到所有设备及其标识符：  # 四、手机安装 Traccar Client 并配置 ## 4.1 下载 App - **Android**：Google Play 搜索「Traccar Client」；没有 Google Play 的手机，可以从官网 <https://www.traccar.org/client/> 提供的 GitHub 链接下载 APK 安装（撰写本文时为 v10.2.1）。 - **iOS**：App Store 搜索「Traccar Client」（官网链接：<https://itunes.apple.com/us/app/traccar-client/id843156974>）。国区 App Store 能否搜到以实际为准，搜不到可换其他地区账号下载。 App 默认连的是官方演示服务器 demo.traccar.org，**一定要改成你自己的盒子地址**，否则位置会发到别人的服务器上。 ## 4.2 关键配置项 打开 App 的设置界面，按下表填写（括号里是英文界面的字段名，中文界面的叫法以 App 实际显示为准）： | 配置项 | 填什么 | 说明 | | ----------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------ | | 设备标识符（Device identifier） | 与网页「标识符」完全一致，如 `100004` | 不一致就会被服务器拒收 | | 服务器地址（Server URL） | `https://traccar.<盒子名>.heiyu.space/osmand/` | 必须带 `https://` 和末尾的 `/osmand/`；**不要加端口 `:5055`** | | 定位精度（Location accuracy） | 推荐「高（High）」；车载可选「最高（Highest）」 | 最高=GPS 常开，最准也最费电；中/低主要靠 Wi-Fi/基站 | | 距离（Distance） | 如 `50`～`100` 米 | 移动时每走 N 米上报一次，最主要的参数 | | 间隔（Interval） | 如 `60`～`300` 秒 | 距离设为 0（仅 Android）或精度为「最高」时按时间上报 | | 角度（Angle） | 如 `30` 度 | 精度为「最高」时，转弯超过该角度就补报一个点，轨迹更贴合道路 | | 静止心跳（Stationary heartbeat） | 如 `600`～`1800` 秒 | 静止时隔多久报一次「我还在这」，太长会让网页显示「xx 分钟前」 | | 离线缓存（Offline buffering） | 建议**打开** | 没网时先存在手机里，联网后补传，轨迹不断档 | | 唤醒锁（Wake lock，仅 Android） | 车载/重要场景打开 | 移动时阻止休眠，更可靠但更耗电 | | 停止检测（Stop detection） | 默认打开 | 自动区分移动/静止两种状态 | | 使用系统定位（Use system location，仅 Android） | 一般不用开 | 没有 Google 服务、定位异常的国产机可以试试打开 | | 密码（Password） | 可选 | 给 App 设置页加锁，防止家人误改 | 全部填好后，打开**服务开关（Service status / 开始）**，App 会开始在后台上报。回到网页，对应设备名下方会变成绿色的「在线」，地图上出现图标。 > 字段含义整理自官方配置说明：<https://www.traccar.org/client-configuration/>。 **为什么不用填 5055 端口？** 官方文档说默认端口是 5055，那是自建服务器直连的情况。商店版已经把 `https://…/osmand/` 这个路径转发到容器内的 5055 端口，手机走标准 HTTPS（443）即可。 **手机必须装懒猫客户端吗？** 用 `heiyu.space` 地址就必须装，并保持客户端在线。不想装的话，看 4.4 节，用自己的域名上报。 **这个公开地址安全吗？** `/osmand/` 只接受位置上报，不能浏览任何数据；没在网页里登记过的标识符会被直接拒收。网页的其余部分仍然需要懒猫账号登录。为了防止被人猜中，标识符可以用长一点的随机串，而不是 `123456`。 ## 4.3 后台权限与省电白名单（决定能不能持续定位） 手机系统为了省电会「杀后台」，这是定位断断续续最常见的原因。官方也明确建议给 App「不受限制的后台使用」。 **iOS：** 1. 「设置 › 隐私与安全性 › 定位服务 › Traccar Client」选 **始终**，并打开 **精确位置**； 2. 「设置 › 通用 › 后台 App 刷新」里允许 Traccar Client； 3. 不要从多任务界面上划关闭 App；低电量模式会影响后台定位。 **Android（各品牌菜单名称略有不同）：** 1. 位置权限选 **始终允许**（「仅使用期间允许」在锁屏后会停）； 2. 「电池 / 耗电管理」里把 Traccar Client 设为 **不限制 / 无限制**，关闭「智能省电」对它的限制； 3. 国产系统（小米、华为、OPPO、vivo 等）还要打开 **自启动**、在多任务界面把 App **加锁**； 4. 通知栏会常驻一个 Traccar 通知，这是正常的前台服务，别关掉通知权限。 不同品牌的具体路径可以查 <https://dontkillmyapp.com/>（官方推荐）。 ## 4.4 被追踪的手机不装懒猫客户端：用 Cloudflared UI 映射固定域名 上面的 `heiyu.space` 地址**只有装了懒猫微服客户端的手机才能访问**；没装客户端的手机连这个域名会直接报 SSL 错误，位置一条也传不上去。如果被追踪的人（老人、孩子、车载备用机）不方便装懒猫客户端，可以用商店里的 **Cloudflared UI**，把 Traccar 的上报服务映射成自己的固定域名，比如 `https://traccar.example.com`。手机只要能上网就能上报，**不需要装懒猫客户端，也不需要登录**。 Cloudflared UI 本身就运行在盒子里，能直接访问其他应用的内部服务地址，所以**不需要再用端口转发工具**。 > 为什么不用局域网地址？局域网地址只有手机连着家里 Wi-Fi 时才通，人一出门就断了。定位追踪本来就是为了知道人在外面的位置，只在家里能用的地址没有意义。 **准备：** - 一个托管在 Cloudflare 的域名（免费套餐即可）； - 在懒猫商店安装「Cloudflared UI」。 **第一步：在 Cloudflare 创建隧道** 1. 登录 Cloudflare 控制台，进入 **Zero Trust → 网络（Networks）→ 连接器 / 隧道（Tunnels）**； 2. 点「创建隧道」，类型选 **Cloudflared**，起个名字，例如 `lazycat`； 3. 在安装连接器的页面复制**隧道令牌（token）**。只复制 `--token` 后面那一长串，不要带前面的 `cloudflared tunnel run --token`。 **第二步：在 Cloudflared UI 里启动隧道** 打开懒猫上的 Cloudflared UI，粘贴隧道令牌，点「启动隧道」。回到 Cloudflare 页面，隧道状态变成「健康（Healthy）」就是连上了。 **第三步：添加已发布应用程序路由** 在这条隧道里点「添加已发布应用程序」，按下表填写： | 字段 | 填什么 | | -------- | --------------------------------------------------- | | 子域名 | `traccar`（随意） | | 域 | 选你托管在 Cloudflare 的域名 | | 路径 | 留空 | | 服务 URL | `http://traccar-server.f00700f.traccar.lzcapp:5055` |  服务 URL 的意思是「`traccar-server` 服务 · 包名 `f00700f.traccar` · 端口 5055」，这是 Traccar 在盒子内部的上报端口，复制粘贴即可，不用改。点「添加路由」后 Cloudflare 会自动加好 DNS 记录并签发证书。 **第四步：手机上填新的服务器地址** Traccar Client 里的「服务器地址」改成你的域名，例如： ``` https://traccar.example.com ``` - 必须是 `https://`，**不要**加 `:5055`； - 这个域名直接对接 5055 上报端口，**不用**加 `/osmand/`； - 设备标识符仍然要先在网页里登记，规则和前面一样。 想先测试的话，在手机浏览器打开 `https://traccar.example.com/?id=你的标识符&lat=30&lon=120`：空白页表示服务器收到了，400 表示标识符没登记（会在轨迹里留一个测试点）。 **安全提示：** - **只映射 5055 上报端口，不要把网页端口 8082 映射出去。** 隧道会绕过懒猫的登录网关；5055 只能写入已登记设备的位置，看不到任何数据，8082 映射出去等于把地图和轨迹交给公网； - 查看位置的人（家长、管理员）继续用懒猫客户端打开 `https://traccar.<盒子名>.heiyu.space`，用懒猫账号登录； - 标识符建议用长一点的随机串，防止被猜中后写入假位置。 # 五、查看实时位置与轨迹回放 ## 5.1 实时位置 在主界面点设备名，地图会定位到它，并弹出信息卡：定位时间、速度、总里程、电量等。卡片底部的按钮可以进入轨迹回放、编辑设备等。  设备状态的含义（测试实例中观察到的）： - **在线**（绿色）：最近一段时间内收到过上报； - **xx 分钟前**：有段时间没收到新位置了，显示的是最后一次上报距今多久； - **离线**（红色）：从未上报过，或连接已断开很久。 ## 5.2 切换地图（以及「位置偏了」怎么办） 点地图右上角的**图层按钮**，可以在「开放自由地图 / 开放街景地图 / 高德地图」之间切换，也可以开关地理围栏、精度圈、移动轨迹等图层。  > **关于位置偏移**：高德地图使用国内的 GCJ-02 坐标，而手机 GPS 上报的是国际通用的 WGS-84 坐标，两者在国内会差几百米。所以真实设备在高德底图上可能「偏到马路旁边」，这不是定位不准。需要精确对齐时，切换到「开放街景地图（OpenStreetMap）」即可。（本文截图是为了演示效果预先换算过坐标的模拟数据。） ## 5.3 轨迹回放 1. 在设备信息卡点「轨迹回放」，或进入「报表 › 轨迹回放」； 2. 选择**设备**和**时段**（用左右箭头按天切换，下拉还能选本周、上周、自定义）； 3. 点「查询」，地图上会画出整条轨迹，颜色代表速度（左上角显示速度范围）； 4. 用底部的播放条拖动或播放，逐点查看每个时刻的位置和时间。  # 六、地理围栏与通知 ## 6.1 画围栏 1. 进入「设置 › 地理围栏」，右侧是地图编辑器； 2. 用地图左上角的绘制工具在地图上圈出区域（多边形或折线），完成后给它起名，如「家」「公司」「学校」； 3. 点列表里的围栏名可在地图上定位，铅笔图标可改名和修改属性。  **关键一步：把围栏和设备关联。** 进入「设置 › 设备」，点设备那一行的「连接」（链条）图标，在「地理围栏」里勾选要生效的围栏。只有关联了的设备进出该区域才会产生事件。 ## 6.2 设置通知 1. 进入「设置 › 通知」，点右下角「+」； 2. **类型**：选「进入地理围栏」「离开地理围栏」「超速限制」「设备离线」等； 3. **通道**：选「网页」； 4. 勾选「所有设备」，或不勾、之后在设备的「连接」里单独关联； 5. 保存。   > 说明： > > - 通道列表里还有「电子邮件」和「命令」。邮件需要在服务器上配置 SMTP 发信，商店版目前没有提供这项配置入口，**请以「网页」通道为主**； > - 「网页」通知是在你打开 Traccar 网页时弹出的提醒，网页关着就看不到弹窗，但所有事件都会被记录，可以随时在「报表 › 事件」里查； > - 官方手机端「Traccar Manager」的推送依赖 Traccar 官方云推送，本商店版**未做验证**，不建议依赖它。 在测试实例中，车辆早上离开「家」、到达「公司」、晚上返回，事件都被准确记录： # 七、报表与导出  点底部「报表」进入，左侧是报表类型： | 报表 | 能看什么 | | ----------------------------- | ------------------------------------------- | | 组合 | 轨迹 + 事件的综合视图 | | 事件 | 进出围栏、移动/停止、超速、上下线等所有事件 | | 地理围栏 | 在各围栏内停留的时段 | | 行程 | 每一段行程的起止时间、里程、平均速度 | | 停留点 | 每次停车/停留的地点和时长 | | 总览 | 按天/按设备汇总里程、速度 | | 图表 | 速度、海拔等随时间变化的曲线 | | 轨迹回放 / 位置 | 回放轨迹 / 原始定位点列表 | | 日志 / 预定报表 / 统计 / 审计 | 偏管理用途 | 使用方法：选**设备**、**时段**（可选显示哪些列），点「查询」。在行程报表里，点某一行左侧的准星图标，上方地图就会画出这一段行程：  **导出 Excel**：点「查询」按钮右边的小箭头，菜单里有「导出 (XLSX)」「打印」「工作计划」（定时生成报表）。  商店版给网页加了懒猫的文件选择器适配，导出的报表可以直接保存到懒猫网盘。 # 八、懒猫网盘：从网盘上传、导出保存到网盘 商店版接入了懒猫网盘文件选择器。网页里凡是「选择文件」和「导出 / 下载」的地方，都会先弹出懒猫的窗口，顶部可切换「网盘文件 / 本地文件」。 ## 从网盘上传设备照片 1. 进入「设置 › 设备」，点设备那一行的编辑（铅笔）图标。设备照片栏只在已保存的设备上出现，新建设备时先保存一次再编辑； 2. 展开「设备照片」，点输入框，弹出懒猫窗口，在「网盘文件」里找到图片，选中后点「确定」；  3. 输入框里显示文件名后点「保存」。回到地图点该设备，信息卡顶部就会显示这张照片。   同样能从网盘选文件的还有：设置 › 服务器 › 文件（上传自定义文件，保存在应用数据目录）；设置 › 日历 › 类型选「自定义」（导入 .ics 日历文件，用于通知的生效时段）；地理围栏页左上角的上传图标（导入 .gpx 轨迹，直接生成一条折线围栏）。  ## 导出报表 / 轨迹保存到网盘 1. 在任意报表点「查询」，再点「查询」右边的小箭头，选「导出 (XLSX)」；位置报表还可以选 CSV / GPX / KML / KMZ； 2. 弹出「保存至懒猫」窗口，选目录（如 Downloads）、可改文件名，点「保存」； 3. 在懒猫网盘对应目录里就能看到导出的文件。想存到电脑上，切到顶部「本地文件」即可。  支持保存到网盘的导出：报表 › 总览 / 行程 / 停留点 / 事件 / 地理围栏（XLSX）；报表 › 位置（CSV、GPX、KML、KMZ）；轨迹回放页顶部的下载图标（KML）；设置 › 设备 › 「导出」（XLSX 设备列表）。 提示：如果点了没反应、仍然直接下载到浏览器，通常是浏览器还缓存着旧版页面，按 Ctrl+F5（Mac 上 Cmd+Shift+R）强制刷新一次即可。 # 九、多用户：让家人也能看 推荐做法是**每个家庭成员用自己的懒猫账号登录**，管理员再把设备分给他： 1. 在懒猫里给家人开好账号（家人需要能登录你的微服）； 2. 家人用自己的懒猫账号打开一次 Traccar，系统会自动为他创建一个普通用户； 3. 管理员进入「设置 › 用户」，找到这位家人，点那一行的「连接」（链条）图标； 4. 在「设备」里选上他可以看的设备（比如「妈妈的手机」「家用车」），也可以一起分配地理围栏、通知等； 5. 家人刷新页面后，就能在地图上看到这些设备，而看不到没分配给他的设备。   > 提示： > > - 每部被定位的手机仍然是在第三节里登记的「设备」，和谁能看它是两回事：一部设备可以同时分配给好几个用户； > - 用户编辑页里还能设置「只读」「设备数量上限」「失效日期」等，适合给临时需要看位置的人用； > - 应用强制使用懒猫账号登录，管理员在「用户」里手动新建的本地账号通常用不上，**以懒猫账号为准**。 # 十、常见问题 **1. 设备一直显示「离线」，地图上没有点** 按顺序检查： - App 的服务开关有没有打开； - 服务器地址是不是 `https://traccar.<盒子名>.heiyu.space/osmand/`：常见错误有少了 `/osmand/`、写成 `http://`、多加了 `:5055`、盒子名拼错； - App 日志里出现「SSL error」（iOS 报 -1200）：说明这台手机没装或没开懒猫客户端，访问不了 `heiyu.space`，改用 4.4 节的自定义域名； - App 里的设备标识符和网页里的标识符是否**完全一致**（多一个空格都不行）。服务器收到未登记的标识符会直接拒收； - 用的是 4.4 节的自定义域名时，检查 Cloudflare 隧道是否「健康」、服务 URL 末尾有没有 `:5055`； - 手机能不能正常上网。可以在手机浏览器里打开 `https://traccar.<盒子名>.heiyu.space/osmand/?id=你的标识符&lat=30&lon=120`，返回一片空白页说明服务器已接收；如果浏览器提示 400 错误，多半是这个标识符没在网页里登记。接收成功后再看网页里设备是否变成「在线」。注意这会在经纬度 (30, 120) 留下一个测试点，它会留在历史轨迹里。 **2. 一开始正常，过一会儿就不更新了 / 轨迹断断续续** 基本都是手机后台被系统限制了。回到 4.3 节：定位权限设为「始终」、电池设为「无限制」、国产手机开自启动并锁定后台。同时打开 App 的「离线缓存」，没网时的点联网后会补传。 **3. 显示的时间不对** - 商店版容器时区已设为北京时间（Asia/Shanghai）；网页显示时间还会受浏览器时区和「设置 › 首选项 / 账户」里的时区设置影响，检查一下是否被改成了其他时区； - 位置的「修正时间」来自手机自己的定位时间，手机系统时间不准也会导致时间错乱，打开手机「自动设置时间」。 **4. 地图空白或加载很慢** - 默认的高德底图需要能访问高德服务；某个图层加载不出来时，用右上角图层按钮换另一种底图试试； - 刚打开页面、或缩放到全球视图时瓦片加载需要几秒，放大到具体城市再看； - 位置和道路对不上：见 5.2 节「关于位置偏移」。 **5. 报表里的速度看起来不对** 行程报表的平均速度是按「总里程 ÷ 总时长」算的，等红灯、堵车都会被计入，所以通常比你感觉的车速低。如果你自己写脚本按 OsmAnd 协议上报，注意 `speed` 参数的单位是**节**（1 节 ≈ 1.852 公里/小时），官方 App 会自动处理，不用管。 **6. 能接 GPS 定位器硬件（GT06、途强等）吗？** 商店版只开放了 OsmAnd 这一种协议，且只通过 `/osmand/` 这个 HTTPS 路径接入。支持 OsmAnd 协议（HTTP 上报 `id`、`lat`、`lon`、`timestamp` 等参数）的 App 或设备都可以用同一个地址，或用 4.4 节映射出去的固定域名；走专有 TCP 协议的车载定位器目前接不进来。 **7. 数据存在哪？升级会丢吗？** 所有位置、设备、用户数据都存在应用自己的数据目录里（内置 H2 数据库），重启、升级应用都不会丢失。卸载应用前请先确认是否需要保留数据。 # 附：一分钟上手清单 1. 商店安装 → 打开 → 懒猫账号自动登录（首次点一次 Grant Access）； 2. 设备列表「+」→ 名称 + 标识符（如 `100004`）→ 保存； 3. 手机装 Traccar Client → 标识符填 `100004` → 服务器地址填 `https://traccar.<盒子名>.heiyu.space/osmand/` → 打开服务； 4. 手机给定位「始终允许」+ 电池「无限制」； 5. 网页看到设备「在线」，完成。之后再按需画围栏、建通知、看报表、给家人分配设备。 *本攻略基于 Traccar 6.16.0 商店版编写。上游项目：<https://github.com/traccar/traccar>（Apache-2.0）。*