From 272ecef194789c2c541f12ca7bdb59dcea2fd266 Mon Sep 17 00:00:00 2001 From: lingniu Date: Mon, 29 Jun 2026 20:30:05 +0800 Subject: [PATCH] docs: record live ingest verification --- deploy/local/launchctl/README.md | 4 +-- .../com.lingniu.jt808.plist.template | 2 +- .../vehicle-ingest-tdengine-verification.md | 32 +++++++++++++------ 3 files changed, 26 insertions(+), 12 deletions(-) diff --git a/deploy/local/launchctl/README.md b/deploy/local/launchctl/README.md index 8dfec54f..b10abbca 100644 --- a/deploy/local/launchctl/README.md +++ b/deploy/local/launchctl/README.md @@ -11,7 +11,7 @@ `vehicle-history-app` 的生产高吞吐默认配置是 TDengine-only： - `EVENT_FILE_STORE_ENABLED=false`：避免 DuckDB/EventFileStore 进入实时消费热路径。 -- `TDENGINE_TELEMETRY_FIELDS_ENABLED=false`：默认只写 `raw_frames` 和 `vehicle_locations`，避免逐字段写放大。 +- `TDENGINE_TELEMETRY_FIELDS_ENABLED=false`：默认只写 `raw_frames` 和协议位置表，避免逐字段写放大。 - GB32960 snapshot/fields 接口默认通过 TDengine `raw_frames` 索引找到 `rawUri`，再回读共享 archive 中的原始 `.bin` 即时解析；后续解析器新增字段后可直接查询历史 raw。 - 如果需要兼容旧 `/api/event-history/records` 低层记录接口或逐字段趋势宽表，可以显式打开对应开关；开启后要重新压测 Kafka lag 和 TDengine 写入吞吐。 @@ -62,7 +62,7 @@ history 消费者会按协议和 raw/event 自动拆分 consumer group。设置 - `vehicle-history-live-jt808-event` - `vehicle-history-live-jt808-raw` -JT808 身份绑定默认使用内存或文件。需要把注册信息维护到 MySQL 时，将 `com.lingniu.jt808.plist.template` 里的 `VEHICLE_IDENTITY_STORE` 改为 `mysql`，并提供 `VEHICLE_IDENTITY_MYSQL_*` 连接参数。服务会自动创建 `vehicle_identity_binding` 和 `vehicle_identity_binding_registration` 两张表：前者保存已确认 VIN 的外部标识绑定，后者保存 0x0100 注册字段；外部系统可把真实 VIN 反写到 registration 表，服务按刷新周期加载后，后续 raw/event 会带真实 VIN。 +JT808 身份绑定本地模板默认使用 `file`，可以在没有 MySQL 时持久化人工绑定，避免重启后退回 `unknown`。需要把 0x0100 注册信息维护到 MySQL 并支持真实 VIN 反写时，将 `com.lingniu.jt808.plist.template` 里的 `VEHICLE_IDENTITY_STORE` 改为 `mysql`，并提供 `VEHICLE_IDENTITY_MYSQL_*` 连接参数。服务会自动创建 `vehicle_identity_binding` 和 `vehicle_identity_binding_registration` 两张表：前者保存已确认 VIN 的外部标识绑定，后者保存 0x0100 注册字段；外部系统可把真实 VIN 反写到 registration 表，服务按刷新周期加载后，后续 raw/event 会带真实 VIN。`memory` 仅适合一次性联调，不建议用于生产验证。 ## 启停 diff --git a/deploy/local/launchctl/com.lingniu.jt808.plist.template b/deploy/local/launchctl/com.lingniu.jt808.plist.template index 4773a3f3..cda5699f 100644 --- a/deploy/local/launchctl/com.lingniu.jt808.plist.template +++ b/deploy/local/launchctl/com.lingniu.jt808.plist.template @@ -33,7 +33,7 @@ SINK_ARCHIVE_PATH __SHARED_ARCHIVE_PATH__ VEHICLE_IDENTITY_STORE - memory + file VEHICLE_IDENTITY_MYSQL_TABLE vehicle_identity_binding VEHICLE_IDENTITY_MYSQL_JDBC_URL diff --git a/docs/operations/vehicle-ingest-tdengine-verification.md b/docs/operations/vehicle-ingest-tdengine-verification.md index 73e4d1aa..9effb60e 100644 --- a/docs/operations/vehicle-ingest-tdengine-verification.md +++ b/docs/operations/vehicle-ingest-tdengine-verification.md @@ -30,7 +30,7 @@ export TDENGINE_TELEMETRY_FIELDS_ENABLED=false `TDENGINE_MIN_IDLE=0` 用于减少冷启动时 TDengine 连接重试日志。TDengine 地址稳定后，再按生产并发调大连接池。 -高吞吐生产验收默认关闭 `EVENT_FILE_STORE_ENABLED` 和 `TDENGINE_TELEMETRY_FIELDS_ENABLED`，验证 `raw_frames`、`vehicle_locations`、raw archive 文件和分页查询闭环。GB32960 snapshot/fields 接口会通过 TDengine `raw_frames` 索引找到 `rawUri`，再回读共享 archive 的原始 `.bin` 即时解析；需要兼容旧 `/api/event-history/records` 低层记录接口或逐字段趋势宽表时，再显式开启对应开关，并单独压测写入放大。 +高吞吐生产验收默认关闭 `EVENT_FILE_STORE_ENABLED` 和 `TDENGINE_TELEMETRY_FIELDS_ENABLED`，验证 `raw_frames`、位置表、raw archive 文件和分页查询闭环。GB32960 snapshot/fields 接口会通过 TDengine `raw_frames` 索引找到 `rawUri`，再回读共享 archive 的原始 `.bin` 即时解析；需要兼容旧 `/api/event-history/records` 低层记录接口或逐字段趋势宽表时，再显式开启对应开关，并单独压测写入放大。 ## 构建 @@ -211,13 +211,14 @@ USE vehicle_ts; SHOW STABLES; SELECT COUNT(*) FROM raw_frames; SELECT COUNT(*) FROM vehicle_locations; +SELECT COUNT(*) FROM jt808_locations; -- 仅在 TDENGINE_TELEMETRY_FIELDS_ENABLED=true 时检查： SELECT COUNT(*) FROM telemetry_fields; ``` 预期： -- `raw_frames`、`vehicle_locations` 存在并持续增长。 +- `raw_frames`、`vehicle_locations`、`jt808_locations` 存在；有对应协议实时流量后，计数持续增长。 - `telemetry_fields` 表结构会创建；默认高吞吐模式不会持续增长，除非显式开启 `TDENGINE_TELEMETRY_FIELDS_ENABLED=true`。 - 有实时流量后，计数持续增加。 @@ -239,12 +240,14 @@ SELECT COUNT(*) FROM telemetry_fields; JT808 真实转发链路已验证： -- 本机 TCP `808` 有外部平台持续发送 JT808 报文。 +- 本机 TCP `808` 有外部平台 `222.66.200.68` 持续发送 JT808 报文。 - `vehicle.raw.jt808.v1` 和 `vehicle.event.jt808.v1` 被 history 消费。 -- `raw_frames` 中 `protocol='JT808'` 的真实行数已超过 `6000`。 -- `vehicle_locations` 中 `protocol='JT808'` 的位置行数已超过 `1900`。 +- `raw_frames` 中 `protocol='JT808'` 的真实行数已超过 `36000`。 +- 外部平台真实 0x0100 注册帧已超过 `347` 条，真实 0x0200 位置帧已超过 `12400` 条。 +- `jt808_locations` 中位置行数已超过 `8783`。 - 在旧的字段宽表开启模式下，`telemetry_fields` 中 `protocol='JT808'` 的字段行数曾超过 `15000`；当前高吞吐默认不要求该表持续增长。 -- 最新样例包含终端号 `13079963310`、消息 ID `512`、`archive://2026/06/29/JT808/...` 原始帧引用。 +- 分页 API 已用终端号 `13079963301` 验证第一页和 nextCursor 第二页，样例位置包含 `longitude=118.913846`、`latitude=31.927309`、`statusFlag=3` 和 `archive://2026/06/29/JT808/...` 原始帧引用。 +- 注册帧样例：终端号 `13079963320`、deviceId `9963320`、deviceType `SEG-9888G`、plate `沪A61559F`、maker `70112`、province `31`、city `113`、plateColor `2`。当前本机 live 进程仍使用早期生成的 `memory` 身份存储，正式行里 `vin` 仍为 `unknown`；模板已改为 `file`，生产 VIN 反写仍需要 MySQL identity store。 ## JT808 本机 smoke / 轻压测工具 @@ -275,7 +278,7 @@ python3 tools/jt808_e2e_smoke.py \ ```sql USE vehicle_ts; SELECT COUNT(*) FROM raw_frames WHERE protocol = 'JT808'; -SELECT COUNT(*) FROM vehicle_locations WHERE protocol = 'JT808'; +SELECT COUNT(*) FROM jt808_locations WHERE protocol = 'JT808'; -- 仅在 TDENGINE_TELEMETRY_FIELDS_ENABLED=true 时复查： SELECT COUNT(*) FROM telemetry_fields WHERE protocol = 'JT808'; SELECT event_time, vehicle_key, phone, message_id, raw_uri @@ -293,11 +296,14 @@ SELECT ts, frame_id, phone, message_id, metadata_json, raw_uri 复查 API： ```bash -curl -sS 'http://127.0.0.1:20200/api/event-history/jt808/locations?phone=13079963296&dateFrom=2026-06-29T00:00:00%2B08:00&dateTo=2026-06-29T23:59:59%2B08:00&limit=10' +curl -sS 'http://127.0.0.1:20200/api/event-history/jt808/locations?phone=13079963301&dateFrom=2026-06-29T00:00:00%2B08:00&dateTo=2026-06-29T23:59:59%2B08:00&order=DESC&limit=3' ``` -GB32960 链路已用合成实时帧验证： +GB32960 链路已用正式平台登录和合成实时帧验证： +- 正式平台 `115.29.187.205` 已连接 TCP `32960`，服务收到 `0x05 PLATFORM_LOGIN` 并返回 ACK；日志显示账号 `Hyundai`、策略 `ALLOW`。 +- 2026-06-29 正式平台登录 raw 已有 `3` 条，均落入 TDengine `raw_frames` 和共享 archive，可通过 `/api/event-history/gb32960/frame?rawArchiveUri=...` 回读解析为 `PLATFORM_LOGIN`。 +- 当前正式平台尚未发送车辆实时上报 `0x02`；非测试 VIN 的 `message_id=2` 计数为 `0`，因此不能把平台登录误判为车辆数据在线。 - TCP `32960` 返回 GB32960 `2323` ACK。 - `raw_frames` 中测试 VIN `LTEST202606290001` 已有 `2` 条 raw 记录。 - 在旧的字段宽表开启模式下，`telemetry_fields` 中测试 VIN `LTEST202606290001` 曾有 `34` 条字段记录；当前默认通过 GB32960 snapshot/fields 即时解析 raw，不要求该表增长。 @@ -318,6 +324,13 @@ SELECT event_time, vin, raw_uri, frame_id WHERE protocol = 'GB32960' AND vin = 'LTEST202606290001' ORDER BY event_time DESC LIMIT 5; +SELECT ts, vin, message_id, event_time, raw_uri, peer, metadata_json + FROM raw_frames + WHERE protocol = 'GB32960' AND peer LIKE '115.29.187.205:%' + ORDER BY ts DESC + LIMIT 5; +SELECT COUNT(*) FROM raw_frames + WHERE protocol = 'GB32960' AND message_id = 2 AND vin <> '' AND vin NOT LIKE 'LTEST%'; ``` 也可以直接运行仓库 smoke 工具验证 TCP `32960`、GB32960 snapshot/fields、TDengine `raw_frames` 和 raw archive： @@ -349,3 +362,4 @@ curl -sS 'http://127.0.0.1:20200/api/event-history/gb32960/snapshots/fields?vin= - `KAFKA_CONSUMER_AUTO_OFFSET_RESET=latest` 适合生产接入新流量；如果要回放历史 Kafka 数据，需要切换 consumer group 或重置 offset。 - `vehicle-history-app` raw 和 event 使用不同 consumer binding；raw consumer 必须开启，否则 `raw_frames` 不会持续增长。 - JT808 设备没有 VIN 映射时，`vehicle_key` 使用 `jt808:`；启用 MySQL identity store 后，registration 表中已反写 VIN 的 phone/deviceId/plate 会用于后续 raw/event 的 VIN 解析。 +- GB32960 正式对端目前只验证到平台登录；等待真实车辆 `0x02` 到达后，再用非测试 VIN 复查 `vehicle_locations`、snapshot/fields API 和导出能力。