ops/docs/国产时序数据库选型验证.md

# OPS 国产/国内生态时序数据库选型验证

## 1. 文档目标

本文用于记录 P1 时序数据库选型验证和最终决策。OPS 第 1 阶段指标样本、探测样本、接口流量和采集健康度采用 TDengine 开源版作为时序数据存储底座。

本文不是商业采购建议。TDengine 开源版无时间使用限制，但采用 AGPL-3.0 许可证；最终部署版本、AGPL 合规、麒麟兼容性和是否需要企业版支持仍需在现场确认。

## 2. 选型约束

| 约束 | 要求 |
| --- | --- |
| 部署环境 | 必须支持 Linux/麒麟验收环境，优先支持 x86_64 和 ARM64。 |
| 后端语言 | 必须提供 Go 后端可用连接方式。 |
| 写入能力 | 支持批量写入高频指标样本。 |
| 查询能力 | 支持时间范围查询、聚合、降采样或等效能力。 |
| 保留策略 | 支持数据保留周期或 TTL。 |
| 运维 | 具备备份恢复、权限控制、日志和基础监控能力。 |
| 风险 | TDengine 开源版的 AGPL 合规、国产化适配、社区活跃度和长期维护风险可评估。 |

## 3. 官方资料依据

| 产品 | 官方资料 | 本文采用的信息 |
| --- | --- | --- |
| TDengine | https://docs.tdengine.com/tdengine-reference/supported-platforms/ | 官方平台矩阵列出 Linux、Windows、Galaxy Kirin V10、NeoKylin 等支持情况，并说明 Go 连接器平台支持。 |
| TDengine | https://docs.tdengine.com/tdengine-reference/client-libraries/go/ | Go 驱动实现 `database/sql`，WebSocket 连接为迁移方向，原生和 REST 连接计划在 2027-01-01 停用。 |
| Apache IoTDB | https://iotdb.apache.org/UserGuide/latest/API/Programming-Go-Native-API.html | Go Native API 支持 `Session` 和 `SessionPool`，并提供批量写入、范围查询、聚合查询等接口。 |
| openGemini | https://docs.opengemini.org/guide/quick_start/get_started.html | openGemini 支持 x86-64、ARM-64 和主流 Linux，单节点默认 HTTP 端口为 8086，并提供基础写入查询示例。 |

## 4. 候选产品验证

### 4.1 TDengine

| 项目 | 验证结论 |
| --- | --- |
| Linux/麒麟 | 官方平台矩阵覆盖 Galaxy Kirin V10、NeoKylin 等，但部分能力标注与企业版相关，需确认 OSS/企业版边界。 |
| CPU 架构 | 服务端和连接器支持 x64、ARM64；Go 连接器覆盖 Linux、Windows、macOS。 |
| Go 连接 | 官方 Go 驱动实现 `database/sql`；建议采用 WebSocket 连接路径。 |
| 批量写入 | 支持 SQL 和 schemaless 写入，适合指标样本。 |
| 查询 | 支持时间范围查询和聚合查询。 |
| 保留策略 | 支持 TTL 或库表级保留策略，需在样例库验证。 |
| 风险 | Go 原生连接和 REST 连接计划停用，首期必须避免新代码依赖将废弃路径。 |

### 4.2 Apache IoTDB

| 项目 | 验证结论 |
| --- | --- |
| Linux/麒麟 | Apache 项目，需在目标麒麟版本实测安装、服务管理和性能。 |
| CPU 架构 | 需按现场系统包和 JVM 环境确认。 |
| Go 连接 | Go Native API 提供 `SessionPool`，并建议多线程场景使用连接池。 |
| 批量写入 | 提供 `InsertTablet`、`InsertRecords`、`InsertTablets` 等批量写入接口。 |
| 查询 | 提供原始数据查询、聚合查询、SQL 查询等接口。 |
| 保留策略 | 支持 TTL 方向，需结合版本验证。 |
| 风险 | 设备树模型适合设备数据，但 OPS 的资源、指标、标签模型需要设计映射规则。 |

### 4.3 openGemini

| 项目 | 验证结论 |
| --- | --- |
| Linux/麒麟 | 官方文档列出主流 Linux、openEuler 等支持；麒麟需实测。 |
| CPU 架构 | 官方快速开始列出 x86-64 和 ARM-64 支持。 |
| Go 连接 | 内核使用 Go，生态接近 InfluxDB 协议；OPS 需验证 Go 客户端选型。 |
| 批量写入 | 支持 line protocol 风格写入，适合指标。 |
| 查询 | 支持类 InfluxQL 查询，适合时间范围和聚合。 |
| 保留策略 | 支持数据库、保留策略方向，需在版本中验证配置项。 |
| 风险 | 相比 TDengine 和 IoTDB，项目成熟度、企业支持和麒麟适配需要更谨慎验证。 |

## 5. 评分矩阵

分数为当前文档验证分，不替代现场压测。

| 维度 | 权重 | TDengine | Apache IoTDB | openGemini |
| --- | ---: | ---: | ---: | ---: |
| Linux/麒麟适配 | 20 | 18 | 14 | 14 |
| Go 接入成熟度 | 15 | 14 | 13 | 10 |
| 批量写入 | 15 | 14 | 13 | 12 |
| 范围查询与聚合 | 15 | 14 | 14 | 12 |
| 保留策略/降采样 | 10 | 8 | 8 | 8 |
| 运维和备份恢复 | 10 | 8 | 8 | 7 |
| 授权和交付风险 | 10 | 7 | 9 | 8 |
| 团队学习成本 | 5 | 4 | 3 | 4 |
| 总分 | 100 | 87 | 82 | 75 |

## 6. 选型结论

第 1 阶段已决策采用 TDengine 开源版。Apache IoTDB 和 openGemini 不作为首期实现目标，仅保留为后续替换或风险备选。

理由：

- TDengine 对 Linux、麒麟和多 CPU 架构的官方说明最贴近当前验收约束。
- TDengine Go 驱动与 `database/sql` 兼容，接入成本较低。
- Apache IoTDB 的设备树模型适合设备时序数据，但 OPS 需要额外设计资源和标签映射。
- openGemini 适合可观测性指标场景，但首期交付要降低成熟度和现场适配风险。

TDengine 开源版使用边界：

| 项目 | 结论 |
| --- | --- |
| 使用期限 | 开源版无固定到期时间；不是试用版授权。 |
| 许可证 | AGPL-3.0，需要进行开源合规确认。 |
| 商业支持 | 若院方要求原厂支持、国产系统认证或企业特性，需要另行评估企业版或商业支持。 |
| 技术路线 | 后端优先使用 TDengine Go WebSocket 连接路径，避免依赖官方已标记未来停用的原生或 REST 路径。 |
| 部署验证 | 必须在目标 Linux/麒麟版本上完成安装、写入、查询、保留策略、备份恢复和故障降级验证。 |

首期实现仍必须通过时序库适配层隔离 TDengine，避免业务逻辑直接依赖 TDengine SQL 方言，保留后续替换空间。

## 7. 适配层接口

后端建议定义最小接口：

| 方法 | 输入 | 输出 | 说明 |
| --- | --- | --- | --- |
| `WriteSamples` | 样本数组 | 写入结果 | 支持批量写入。 |
| `QueryRange` | 资源、指标、时间范围、标签 | 样本序列 | 用于资源详情趋势图。 |
| `QueryAggregate` | 资源、指标、时间范围、聚合窗口 | 聚合序列 | 用于报表和大屏。 |
| `CheckHealth` | 无 | 健康状态 | 用于部署烟测和自监控。 |
| `EnsureRetention` | 保留策略配置 | 执行结果 | 初始化或校验保留策略。 |

业务代码只依赖适配层，不直接拼接 TDengine 专有查询。

## 8. 验证计划

| 步骤 | 验证内容 | 通过标准 |
| --- | --- | --- |
| 1 | 在目标 Linux/麒麟环境安装 TDengine 开源版 | 服务可启动，端口和日志正常。 |
| 2 | 后端使用 Go 写入 10 万条样本 | 无明显错误，写入耗时可记录。 |
| 3 | 按 `resource_id + metric_code + 时间范围` 查询 | 返回正确序列，能映射回资源。 |
| 4 | 执行 1 分钟、5 分钟、1 小时聚合 | 聚合结果正确。 |
| 5 | 配置保留策略或 TTL | 过期策略可查询和验证。 |
| 6 | 执行备份恢复演练 | 恢复后样本可查。 |
| 7 | 权限验证 | 只读账号不能写入，写入账号不能管理系统配置。 |
| 8 | 故障验证 | 时序库不可用时，后端返回局部失败并记录 `traceId`。 |

## 9. 验收影响

| 功能 | 依赖时序库 | 降级策略 |
| --- | --- | --- |
| 资源详情趋势图 | 是 | 基本信息可见，趋势区显示局部错误。 |
| 首页资源健康 | 部分依赖 | 显示最近成功采集时间和数据过期提示。 |
| 告警阈值 | 是 | 采集失败转内部事件，不伪造阈值结果。 |
| 报表 | 是 | 异步失败可重试，保留失败原因。 |
| 大屏 | 是 | 单组件失败不影响整屏。 |

## 10. 未决项

| 未决项 | 当前处理 |
| --- | --- |
| AGPL 合规 | 需要项目、院方或法务确认开源版使用方式是否满足 AGPL-3.0 要求。 |
| 企业版需求 | 若验收要求原厂支持、认证或企业特性，需要商务和现场运维确认。 |
| 麒麟具体版本 | 验收环境确定后实测。 |
| 高可用部署 | 第 1 阶段可先单节点或小集群验证，正式上线前补 HA 方案。 |
| 压测指标 | `server/` 初始化后补写入吞吐、查询 p95/p99 和资源占用基线。 |