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

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。