From 8f3b337fd677ec022c8480e20f8ba8085bcec312 Mon Sep 17 00:00:00 2001 From: lingniu Date: Thu, 2 Jul 2026 00:02:21 +0800 Subject: [PATCH] docs: add native go deployment runbook --- deploy/systemd/README.md | 66 +++++++++++++++ deploy/systemd/lingniu-go-gateway.service | 18 ++++ .../systemd/lingniu-go-history-writer.service | 18 ++++ .../systemd/lingniu-go-realtime-api.service | 18 ++++ deploy/systemd/lingniu-go-stat-writer.service | 18 ++++ ...-gateway-verification-result-2026-07-01.md | 84 +++++++++++++++++++ 6 files changed, 222 insertions(+) create mode 100644 deploy/systemd/README.md create mode 100644 deploy/systemd/lingniu-go-gateway.service create mode 100644 deploy/systemd/lingniu-go-history-writer.service create mode 100644 deploy/systemd/lingniu-go-realtime-api.service create mode 100644 deploy/systemd/lingniu-go-stat-writer.service diff --git a/deploy/systemd/README.md b/deploy/systemd/README.md new file mode 100644 index 00000000..3a6f16b2 --- /dev/null +++ b/deploy/systemd/README.md @@ -0,0 +1,66 @@ +# Go Vehicle Gateway Native Deployment + +本目录用于 ECS 原生部署。当前 goal 后续不再使用 Docker/Portainer 作为 Go 接入链路的部署方式。 + +## Runtime Layout + +```text +/opt/lingniu-go-native/ + current -> /opt/lingniu-go-native/releases/ + releases// + gateway + history-writer + stat-writer + realtime-api + env/ + gateway.env + history-writer.env + stat-writer.env + realtime-api.env + spool/gateway/ +``` + +## Services + +| systemd unit | Binary | Purpose | +|---|---|---| +| `lingniu-go-gateway.service` | `gateway` | GB32960 TCP `32960`、JT808 TCP `808`、宇通 MQTT 接入，写 Kafka RAW/unified | +| `lingniu-go-history-writer.service` | `history-writer` | 消费 RAW topic，写 TDengine `raw_frames` 和核心时序表 | +| `lingniu-go-stat-writer.service` | `stat-writer` | 消费 RAW topic，写 MySQL `vehicle_daily_metric` | +| `lingniu-go-realtime-api.service` | `realtime-api` | 消费 unified topic，写 Redis，并提供 realtime/raw/stat 查询 API | + +## Build + +在开发机或 CI 上构建 Linux amd64 二进制： + +```bash +cd go/vehicle-gateway +CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o /tmp/lingniu-go-native/gateway ./cmd/gateway +CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o /tmp/lingniu-go-native/history-writer ./cmd/history-writer +CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o /tmp/lingniu-go-native/stat-writer ./cmd/stat-writer +CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o /tmp/lingniu-go-native/realtime-api ./cmd/realtime-api +``` + +## Cutover Notes + +1. 先上传二进制到新 release 目录并更新 `current` symlink。 +2. 从现有生产 env 生成四个 systemd 专用 env 文件；不要把密钥写入仓库。 +3. 停止旧 Docker Go 容器或 Java 容器，释放 `808`、`32960`、`20210`。 +4. 执行： + +```bash +systemctl daemon-reload +systemctl enable lingniu-go-gateway lingniu-go-history-writer lingniu-go-stat-writer lingniu-go-realtime-api +systemctl restart lingniu-go-gateway lingniu-go-history-writer lingniu-go-stat-writer lingniu-go-realtime-api +``` + +## Verification + +```bash +systemctl is-active lingniu-go-gateway lingniu-go-history-writer lingniu-go-stat-writer lingniu-go-realtime-api +ss -lntp | egrep ':(808|32960|20210)\b' +journalctl -u lingniu-go-gateway --since '5 minutes ago' --no-pager +curl -sS 'http://127.0.0.1:20210/api/history/raw-frames?protocol=JT808&limit=1' +curl -sS 'http://127.0.0.1:20210/api/history/raw-frames?protocol=GB32960&limit=1' +curl -sS 'http://127.0.0.1:20210/api/history/raw-frames?protocol=YUTONG_MQTT&limit=1' +``` diff --git a/deploy/systemd/lingniu-go-gateway.service b/deploy/systemd/lingniu-go-gateway.service new file mode 100644 index 00000000..40ef12f2 --- /dev/null +++ b/deploy/systemd/lingniu-go-gateway.service @@ -0,0 +1,18 @@ +[Unit] +Description=Lingniu Go Vehicle Gateway +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +WorkingDirectory=/opt/lingniu-go-native/current +EnvironmentFile=/opt/lingniu-go-native/env/gateway.env +ExecStart=/opt/lingniu-go-native/current/gateway +Restart=always +RestartSec=3 +LimitNOFILE=1048576 +KillSignal=SIGTERM +TimeoutStopSec=30 + +[Install] +WantedBy=multi-user.target diff --git a/deploy/systemd/lingniu-go-history-writer.service b/deploy/systemd/lingniu-go-history-writer.service new file mode 100644 index 00000000..b08bed08 --- /dev/null +++ b/deploy/systemd/lingniu-go-history-writer.service @@ -0,0 +1,18 @@ +[Unit] +Description=Lingniu Go History Writer +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +WorkingDirectory=/opt/lingniu-go-native/current +EnvironmentFile=/opt/lingniu-go-native/env/history-writer.env +ExecStart=/opt/lingniu-go-native/current/history-writer +Restart=always +RestartSec=3 +LimitNOFILE=1048576 +KillSignal=SIGTERM +TimeoutStopSec=30 + +[Install] +WantedBy=multi-user.target diff --git a/deploy/systemd/lingniu-go-realtime-api.service b/deploy/systemd/lingniu-go-realtime-api.service new file mode 100644 index 00000000..6ef81160 --- /dev/null +++ b/deploy/systemd/lingniu-go-realtime-api.service @@ -0,0 +1,18 @@ +[Unit] +Description=Lingniu Go Realtime API +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +WorkingDirectory=/opt/lingniu-go-native/current +EnvironmentFile=/opt/lingniu-go-native/env/realtime-api.env +ExecStart=/opt/lingniu-go-native/current/realtime-api +Restart=always +RestartSec=3 +LimitNOFILE=1048576 +KillSignal=SIGTERM +TimeoutStopSec=30 + +[Install] +WantedBy=multi-user.target diff --git a/deploy/systemd/lingniu-go-stat-writer.service b/deploy/systemd/lingniu-go-stat-writer.service new file mode 100644 index 00000000..6b46c108 --- /dev/null +++ b/deploy/systemd/lingniu-go-stat-writer.service @@ -0,0 +1,18 @@ +[Unit] +Description=Lingniu Go Stat Writer +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +WorkingDirectory=/opt/lingniu-go-native/current +EnvironmentFile=/opt/lingniu-go-native/env/stat-writer.env +ExecStart=/opt/lingniu-go-native/current/stat-writer +Restart=always +RestartSec=3 +LimitNOFILE=1048576 +KillSignal=SIGTERM +TimeoutStopSec=30 + +[Install] +WantedBy=multi-user.target diff --git a/docs/operations/go-vehicle-gateway-verification-result-2026-07-01.md b/docs/operations/go-vehicle-gateway-verification-result-2026-07-01.md index 89ae45d4..7c1d58aa 100644 --- a/docs/operations/go-vehicle-gateway-verification-result-2026-07-01.md +++ b/docs/operations/go-vehicle-gateway-verification-result-2026-07-01.md @@ -748,3 +748,87 @@ calculation_method=TOTAL_MILEAGE_DIFF - RAW 查询已返回 `raw_hex`、`parsed_json`、`fields_json`，可以用于查看完整解析结果。 - 日统计和实时查询在生产端口接管后仍可用。 + +## 2026-07-02 00:00 原生 systemd 部署与宇通 MQTT 复验 + +根据本次 goal 的新要求，Go 接入链路后续不再使用 Docker 部署。本轮已中断 Docker 镜像构建路径，改为 ECS 原生 Linux 二进制 + systemd。 + +部署版本： + +- Git commit：`594ab2d` +- 部署目录：`/opt/lingniu-go-native` +- 当前 release：`/opt/lingniu-go-native/releases/594ab2d` +- 当前指针：`/opt/lingniu-go-native/current -> /opt/lingniu-go-native/releases/594ab2d` + +systemd 服务： + +```text +lingniu-go-gateway.service active +lingniu-go-history-writer.service active +lingniu-go-stat-writer.service active +lingniu-go-realtime-api.service active +``` + +端口确认： + +```text +[::]:32960 gateway +[::]:808 gateway +[::]:20210 realtime-api +``` + +Go Docker 容器已停止： + +```text +go-vehicle-gateway Exited +go-history-writer Exited +go-stat-writer Exited +go-realtime-api Exited +``` + +宇通 MQTT： + +```text +yutong mqtt client started +mqtt subscribed broker=ssl://cpxlm.axxc.cn:38883 topic=/ytforward/shln/+ qos=1 +``` + +说明：MQTT broker 存在短连接 `EOF` 后自动重连现象，但订阅后已收到真实数据并落 RAW。 + +RAW 查询复验： + +```text +GET /api/history/raw-frames?protocol=YUTONG_MQTT&limit=3 + +total=3 +protocol=YUTONG_MQTT +vin=LMRKH9AC1R1004131 +vehicle_key=LMRKH9AC1R1004131 +parse_status=OK +parsed_json_len=1104 +fields_json_len=116 +``` + +同轮回归： + +```text +GET /api/history/raw-frames?protocol=JT808&vin=LKLG7C4E3NA774736&messageId=0x0200&limit=1 +total=1 +parse_status=OK + +GET /api/history/raw-frames?protocol=GB32960&vin=LB9A32A21R0LS1707&limit=1 +total=1 +parse_status=OK + +GET /api/realtime/vehicles/LKLG7C4E3NA774736/online +online=true +protocols=["JT808"] +``` + +本轮落地文件： + +- `deploy/systemd/README.md` +- `deploy/systemd/lingniu-go-gateway.service` +- `deploy/systemd/lingniu-go-history-writer.service` +- `deploy/systemd/lingniu-go-stat-writer.service` +- `deploy/systemd/lingniu-go-realtime-api.service`