fix(gateway): guard nats stream retention and writer timeouts

docs/architecture/production-data-plane-inventory.md

@@ -28,6 +28,7 @@ NATS 部署在 Kafka ECS 内网 `172.17.111.56:4222`。
 | Subjects | `vehicle.raw.go.gb32960.v1`、`vehicle.raw.go.jt808.v1`、`vehicle.raw.go.yutong-mqtt.v1` |
 | Durable consumer | `vehicle-kafka-bridge` |
 | 语义 | Gateway 先写 NATS raw subject；bridge 写 Kafka 成功后才 ACK NATS |
+| 保留策略 | `NATS_STREAM_MAX_BYTES=21474836480`，`NATS_STREAM_MAX_AGE_HOURS=24`，`NATS_STREAM_ENSURE_TIMEOUT_SECONDS=60`，NATS 仅做入口缓冲 |
 
 ### Kafka
 

docs/ops/100k-capacity-baseline.md

@@ -88,6 +88,19 @@ systemd gateway 已配置 `LimitNOFILE=1048576`，需要持续保持。
 | Realtime MySQL | async queue depth | 不持续增长 |
 | Stat writer | `vehicle_stat_write_duration_ms_histogram_bucket` | p99 不持续上升 |
 
+## Retention Guardrails
+
+10W 车辆接入时，中间件只承担解耦和短期缓冲职责，不能成为长期历史库。
+
+| Component | Guardrail |
+| --- | --- |
+| NATS JetStream `VEHICLE_INGEST` | `NATS_STREAM_MAX_BYTES=21474836480`，`NATS_STREAM_MAX_AGE_HOURS=24`，`NATS_STREAM_ENSURE_TIMEOUT_SECONDS=60` |
+| Kafka `vehicle.raw.go.*` / `vehicle.fields.go.*` | `retention.ms=21600000`、`segment.ms=600000`、`segment.bytes=268435456` |
+| Fast writer | `FAST_WRITER_OPERATION_TIMEOUT_MS=1000`，避免 TDengine 批量写尾延迟导致整批重投 |
+| Root disk | 使用率低于 `80%`，超过 `85%` 进入容量告警 |
+
+如果 NATS `consumer_pending` 下降但仍高，说明系统在追历史积压；如果 `ack_pending=0` 且 Kafka lag 为 `0`，不要重启服务，重点观察 NATS data size 和 pending 下降斜率。
+
 ## 分阶段压测
 
 压测入口：

docs/ops/vehicle-ingest-runbook.md

@@ -196,13 +196,30 @@ Kafka 是可回放日志。只要 Kafka 还保留消息，恢复 consumer 后 la
 1. 检查 bridge `/readyz` 和日志。
 2. 对比 `vehicle_bridge_kafka_writes_total` 和 `vehicle_bridge_nats_acks_total`。
 3. 如果 Kafka 写入失败，检查 ECS 到 Kafka broker 的网络。
-4. 如果 ack-pending 卡住且日志持续报错，只重启 bridge。
+4. 如果 `ack_pending > 0`，优先检查 Kafka 是否监听 `9092`、Kafka 盘是否打满，再看 bridge 日志。
+5. 如果 `ack_pending = 0` 但 `consumer_pending` 下降，说明 bridge 正在追历史积压；不要反复重启，持续观察下降速度即可。
+6. 如果 `consumer_pending` 不下降，才考虑扩容 bridge 或降低 batch/fetch 等配置。
 
 ```bash
 journalctl -u lingniu-go-nats-kafka-bridge.service --since '10 minutes ago' --no-pager
 systemctl restart lingniu-go-nats-kafka-bridge.service
 ```
 
+生产 stream 必须设置字节上限，避免 NATS JetStream 在 Kafka 或下游故障时吃满根盘：
+
+```bash
+grep NATS_STREAM_MAX_BYTES /opt/lingniu-go-native/env/nats-fast-writer.env
+grep NATS_STREAM_MAX_BYTES /opt/lingniu-go-native/env/nats-kafka-bridge.env
+grep NATS_STREAM_ENSURE_TIMEOUT_SECONDS /opt/lingniu-go-native/env/nats-fast-writer.env
+grep NATS_STREAM_ENSURE_TIMEOUT_SECONDS /opt/lingniu-go-native/env/nats-kafka-bridge.env
+du -sh /opt/lingniu-nats/data
+df -h /
+```
+
+当前建议值：`NATS_STREAM_MAX_BYTES=21474836480`，即 `20GiB`；`NATS_STREAM_ENSURE_TIMEOUT_SECONDS=60`，避免大 stream 元数据更新时被 NATS 客户端默认 5s 超时误杀。Kafka topic 只作为短期缓冲，当前建议保留 `6h`，不要把 Kafka 或 NATS 当长期历史存储；长期历史和 RAW 查询以 TDengine/MySQL 投影为准。
+
+fast-writer 的 `FAST_WRITER_OPERATION_TIMEOUT_MS` 建议为 `1000`。实时链路仍以 100ms 级为目标，但 TDengine 批量写存在尾延迟，过小的超时会造成 NATS 消息反复重投和重复写压力。
+
 ### Raw 有数据但实时查不到
 
 1. 查 realtime Kafka lag。