连不上 influxdb 2.x 首先核对 token、org、url 三要素：token 需在 ui 创建并绑定 bucket 权限，org 填名称非 id，url 必带协议和端口；写入时间戳必须用 time.time 类型显式传入；gin 中应全局复用 writeapi 而非每次新建；query 需循环 result.next() 并检查 result.err()。
连不上 InfluxDB 2.x？先核对 token、org、URL 三要素
绝大多数连接失败不是网络不通，而是配置项写错或权限没开。InfluxDB 2.x 强制要求 token 绑定 org，并显式授予 bucket 的读写权限。
token 必须从 UI 的 Load Data → Tokens 页面创建，勾选目标 bucket 的 Write 和/或 Read 权限；org 填的是组织名称（不是 ID），可在右上角头像 → Organizations 里确认；URL 必须带协议和端口，例如 http://localhost:8086，启用 TLS 时必须用 https 且证书有效。
初始化 client 的最小可行代码：
client := influxdb2.NewClient("http://localhost:8086", "your-token-here")
写入时时间戳总被忽略？必须用 time.Time 显式传入
InfluxDB 默认用本地时间打点，但设备上报时间、日志生成时间等业务时间必须自己控制。不能传字符串、数字或 Unix 时间戳整数——SetTime() 只接受 time.Time 类型。
- 正确：
point.SetTime(time.Now().UTC()) - 正确（从字符串解析）：
t, _ := time.Parse(time.RFC3339, "2026-06-12T14:30:00Z"); point.SetTime(t) - 错误：
point.SetTime(time.Now().UnixMilli())—— 精度丢失，纳秒级写入可能冲突，后写覆盖前写
tag 值里禁止逗号、等号、空格；字段类型要严格对齐：int64 写整数，别用 int（32 位平台易溢出）。
Gin 路由里怎么安全复用 WriteAPI？别在 handler 里 new
每次请求都新建 WriteAPI 会快速耗尽连接、触发 429 Too Many Requests，而且无法利用缓冲机制。
应该在 Gin 启动时初始化一次，并注入到 gin.Context 或全局变量中：
writeAPI := client.WriteAPI("my-org", "my-bucket")
defer writeAPI.Close() // 程序退出前必须调用
在 handler 中直接使用：
func postMetric(c *gin.Context) {
p := influxdb2.NewPoint("cpu",
map[string]string{"host": "server-01"},
map[string]interface{}{"usage": 85.2},
time.Now().UTC(),
)
writeAPI.WritePoint(p)
c.Status(http.StatusOK)
}
注意：writeAPI 是线程安全的，可并发调用；但程序退出前务必调 writeAPI.Flush() 并检查 error，否则 buffer 中未刷出的数据直接丢失。
Query 返回空？你大概率忘了遍历 result.Next()
queryAPI.Query() 返回的是迭代器，不是数据数组。不手动循环，永远拿不到结果。
标准用法必须是：
for result.Next() {
record := result.Record()
log.Printf("time: %v, value: %v", record.Time(), record.Value())
}
if err := result.Err(); err != nil {
log.Fatal(err)
}
漏掉 result.Err() 检查，查询中途失败也不会报错；漏掉 result.Next() 循环，则整个结果集被静默丢弃。
真正容易被忽略的点是：InfluxDB 的时间精度是纳秒，而 Go 的 time.Now() 在某些系统上默认只到微秒，批量写入时若没显式用 .UTC() 或指定时区，可能导致多点时间戳“撞车”，后写覆盖前写——这问题在压测时才暴露，日常开发几乎不会发现。
