docs: document local ingest deployment verification

2026-06-29 16:18:52 +08:00
parent d2bc4a0d0a
commit ef9ac327fe
6 changed files with 391 additions and 2 deletions
--- a/deploy/local/launchctl/README.md
+++ b/deploy/local/launchctl/README.md
@@ -0,0 +1,73 @@
+# macOS launchctl 本机部署模板
+
+本目录用于把本机 32960/JT808/history 三个服务的启动方式仓库化。模板面向当前生产验证链路：
+
+- `gb32960-ingest-app`: TCP `32960`，HTTP `20100`
+- `jt808-ingest-app`: TCP `808`，HTTP `20482`
+- `vehicle-history-app`: HTTP `20200`
+
+三个服务必须使用同一个 `SINK_ARCHIVE_PATH`。协议接入服务负责落原始 `.bin` 文件，Kafka raw envelope 只携带 `archive://...` 引用；history 服务按同一个 archive root 读取原始帧并提供查询。
+
+## 生成 plist
+
+在仓库根目录执行：
+
+```bash
+export PROJECT_ROOT="$(pwd)"
+export JAVA_BIN="$(/usr/libexec/java_home 2>/dev/null)/bin/java"
+export SHARED_ARCHIVE_PATH="$PROJECT_ROOT/data/archive-live"
+export EVENT_STORE_PATH="$PROJECT_ROOT/data/event-store-live"
+export TDENGINE_JDBC_URL='jdbc:TAOS-WS://<tdengine-host>:6041/vehicle_ts'
+export TDENGINE_USERNAME='root'
+export TDENGINE_PASSWORD='<tdengine-password>'
+
+mkdir -p "$HOME/Library/LaunchAgents" "$PROJECT_ROOT/data"
+mkdir -p /tmp/lingniu-gb32960-live /tmp/lingniu-jt808-live /tmp/lingniu-history-live
+
+for service in gb32960 jt808 vehicle-history; do
+  sed \
+    -e "s#__PROJECT_ROOT__#$PROJECT_ROOT#g" \
+    -e "s#__JAVA_BIN__#$JAVA_BIN#g" \
+    -e "s#__SHARED_ARCHIVE_PATH__#$SHARED_ARCHIVE_PATH#g" \
+    -e "s#__EVENT_STORE_PATH__#$EVENT_STORE_PATH#g" \
+    -e "s#__TDENGINE_JDBC_URL__#$TDENGINE_JDBC_URL#g" \
+    -e "s#__TDENGINE_USERNAME__#$TDENGINE_USERNAME#g" \
+    -e "s#__TDENGINE_PASSWORD__#$TDENGINE_PASSWORD#g" \
+    "deploy/local/launchctl/com.lingniu.${service}.plist.template" \
+    > "$HOME/Library/LaunchAgents/com.lingniu.${service}.plist"
+done
+```
+
+如果生产配置由 Nacos 下发，可以把模板里的 `NACOS_CONFIG_ENABLED` 改成 `true`，并补充 `NACOS_SERVER_ADDR`、`NACOS_NAMESPACE`、`NACOS_GROUP`、`NACOS_USERNAME`、`NACOS_PASSWORD`。端口、Kafka topic、archive root、TDengine 连接建议仍保留为启动环境变量，便于 Portainer、launchctl 和临时压测保持一致。
+
+## 启停
+
+```bash
+launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.lingniu.gb32960.plist"
+launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.lingniu.jt808.plist"
+launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.lingniu.vehicle-history.plist"
+
+launchctl list | rg 'com.lingniu.(gb32960|jt808|vehicle-history)'
+```
+
+替换 jar 前先停止服务，避免 KeepAlive 在 jar 拷贝中途拉起半包：
+
+```bash
+launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.lingniu.gb32960.plist" || true
+launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.lingniu.jt808.plist" || true
+launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.lingniu.vehicle-history.plist" || true
+```
+
+## 验证地址
+
+```bash
+curl -sS http://127.0.0.1:20100/actuator/health
+curl -sS http://127.0.0.1:20482/actuator/health
+curl -sS http://127.0.0.1:20200/actuator/health
+```
+
+Swagger：
+
+- GB32960 ingest: `http://127.0.0.1:20100/swagger-ui/index.html`
+- JT808 ingest: `http://127.0.0.1:20482/swagger-ui/index.html`
+- History query: `http://127.0.0.1:20200/swagger-ui/index.html`
--- a/deploy/local/launchctl/com.lingniu.gb32960.plist.template
+++ b/deploy/local/launchctl/com.lingniu.gb32960.plist.template
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.lingniu.gb32960</string>
+  <key>WorkingDirectory</key>
+  <string>__PROJECT_ROOT__</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>__JAVA_BIN__</string>
+    <string>-jar</string>
+    <string>__PROJECT_ROOT__/modules/apps/gb32960-ingest-app/target/gb32960-ingest-app.jar</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HTTP_PORT</key>
+    <string>20100</string>
+    <key>GB32960_PORT</key>
+    <string>32960</string>
+    <key>GB32960_AUTH_ENABLED</key>
+    <string>false</string>
+    <key>KAFKA_ENABLED</key>
+    <string>true</string>
+    <key>KAFKA_BROKERS</key>
+    <string>114.55.58.251:9092</string>
+    <key>KAFKA_NODE_ID</key>
+    <string>gb32960-live-32960</string>
+    <key>KAFKA_TOPIC_GB32960_EVENT</key>
+    <string>vehicle.event.gb32960.v1</string>
+    <key>KAFKA_TOPIC_GB32960_RAW</key>
+    <string>vehicle.raw.gb32960.v1</string>
+    <key>KAFKA_TOPIC_GB32960_DLQ</key>
+    <string>vehicle.dlq.gb32960.v1</string>
+    <key>SINK_ARCHIVE_PATH</key>
+    <string>__SHARED_ARCHIVE_PATH__</string>
+    <key>VEHICLE_IDENTITY_STORE</key>
+    <string>file</string>
+    <key>VEHICLE_IDENTITY_FILE</key>
+    <string>__PROJECT_ROOT__/data/vehicle-identity-gb32960.jsonl</string>
+    <key>NACOS_CONFIG_ENABLED</key>
+    <string>false</string>
+    <key>MANAGEMENT_HEALTH_REDIS_ENABLED</key>
+    <string>false</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>/tmp/lingniu-gb32960-live/launchctl-gb32960.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/lingniu-gb32960-live/launchctl-gb32960.err.log</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+</dict>
+</plist>
--- a/deploy/local/launchctl/com.lingniu.jt808.plist.template
+++ b/deploy/local/launchctl/com.lingniu.jt808.plist.template
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.lingniu.jt808</string>
+  <key>WorkingDirectory</key>
+  <string>__PROJECT_ROOT__</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>__JAVA_BIN__</string>
+    <string>-jar</string>
+    <string>__PROJECT_ROOT__/modules/apps/jt808-ingest-app/target/jt808-ingest-app.jar</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HTTP_PORT</key>
+    <string>20482</string>
+    <key>JT808_PORT</key>
+    <string>808</string>
+    <key>KAFKA_ENABLED</key>
+    <string>true</string>
+    <key>KAFKA_BROKERS</key>
+    <string>114.55.58.251:9092</string>
+    <key>KAFKA_NODE_ID</key>
+    <string>jt808-live-808</string>
+    <key>KAFKA_TOPIC_JT808_EVENT</key>
+    <string>vehicle.event.jt808.v1</string>
+    <key>KAFKA_TOPIC_JT808_RAW</key>
+    <string>vehicle.raw.jt808.v1</string>
+    <key>KAFKA_TOPIC_JT808_DLQ</key>
+    <string>vehicle.dlq.jt808.v1</string>
+    <key>SINK_ARCHIVE_PATH</key>
+    <string>__SHARED_ARCHIVE_PATH__</string>
+    <key>VEHICLE_IDENTITY_STORE</key>
+    <string>memory</string>
+    <key>NACOS_CONFIG_ENABLED</key>
+    <string>false</string>
+    <key>MANAGEMENT_HEALTH_REDIS_ENABLED</key>
+    <string>false</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>/tmp/lingniu-jt808-live/launchctl-jt808.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/lingniu-jt808-live/launchctl-jt808.err.log</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+</dict>
+</plist>
--- a/deploy/local/launchctl/com.lingniu.vehicle-history.plist.template
+++ b/deploy/local/launchctl/com.lingniu.vehicle-history.plist.template
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.lingniu.vehicle-history</string>
+  <key>WorkingDirectory</key>
+  <string>__PROJECT_ROOT__</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>__JAVA_BIN__</string>
+    <string>-jar</string>
+    <string>__PROJECT_ROOT__/modules/apps/vehicle-history-app/target/vehicle-history-app.jar</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HTTP_PORT</key>
+    <string>20200</string>
+    <key>KAFKA_ENABLED</key>
+    <string>true</string>
+    <key>KAFKA_CONSUMER_ENABLED</key>
+    <string>true</string>
+    <key>KAFKA_CONSUMER_AUTO_OFFSET_RESET</key>
+    <string>latest</string>
+    <key>KAFKA_CONSUMER_CLIENT_ID_PREFIX</key>
+    <string>vehicle-history-live</string>
+    <key>KAFKA_GROUP_HISTORY</key>
+    <string>vehicle-history-live</string>
+    <key>KAFKA_BROKERS</key>
+    <string>114.55.58.251:9092</string>
+    <key>KAFKA_TOPIC_GB32960_EVENT</key>
+    <string>vehicle.event.gb32960.v1</string>
+    <key>KAFKA_TOPIC_GB32960_RAW</key>
+    <string>vehicle.raw.gb32960.v1</string>
+    <key>KAFKA_TOPIC_JT808_EVENT</key>
+    <string>vehicle.event.jt808.v1</string>
+    <key>KAFKA_TOPIC_JT808_RAW</key>
+    <string>vehicle.raw.jt808.v1</string>
+    <key>EVENT_FILE_STORE_ENABLED</key>
+    <string>true</string>
+    <key>EVENT_FILE_STORE_PATH</key>
+    <string>__EVENT_STORE_PATH__</string>
+    <key>EVENT_FILE_STORE_ZONE_ID</key>
+    <string>Asia/Shanghai</string>
+    <key>SINK_ARCHIVE_PATH</key>
+    <string>__SHARED_ARCHIVE_PATH__</string>
+    <key>TDENGINE_HISTORY_ENABLED</key>
+    <string>true</string>
+    <key>TDENGINE_HISTORY_DATABASE</key>
+    <string>vehicle_ts</string>
+    <key>TDENGINE_JDBC_URL</key>
+    <string>__TDENGINE_JDBC_URL__</string>
+    <key>TDENGINE_DRIVER_CLASS_NAME</key>
+    <string>com.taosdata.jdbc.ws.WebSocketDriver</string>
+    <key>TDENGINE_USERNAME</key>
+    <string>__TDENGINE_USERNAME__</string>
+    <key>TDENGINE_PASSWORD</key>
+    <string>__TDENGINE_PASSWORD__</string>
+    <key>TDENGINE_MIN_IDLE</key>
+    <string>0</string>
+    <key>TDENGINE_MAX_POOL_SIZE</key>
+    <string>16</string>
+    <key>TDENGINE_INITIALIZE_SCHEMA</key>
+    <string>true</string>
+    <key>NACOS_CONFIG_ENABLED</key>
+    <string>false</string>
+    <key>MANAGEMENT_HEALTH_REDIS_ENABLED</key>
+    <string>false</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>/tmp/lingniu-history-live/vehicle-history.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/lingniu-history-live/vehicle-history.err.log</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+</dict>
+</plist>