1. 概览Lightweight. Replicated. Real-time.Vortex TSDB是面向实时指标的分布式时序数据库用 HTTP 写入数值读回分钟级聚合、瞬时值以及滚动 / 滑动窗口。每个节点在内存里持有全量数据。版本镜像amd64 · arm64源码License1.0.0fredfeng033/vortex-tsdb·ghcr.io/paganini2008/vortex-tsdbGitHubApache 2.02. 它解决什么问题设备在线数、接口 QPS、订单量、温度这类实时指标需要多客户端并发写入时计数精确、按分钟和任意窗口聚合、节点挂了服务不停。通用 TSDB 能做到但要带上磁盘引擎、查询语言和多组件运维Vortex 只做这一层全部在内存里接口只有 HTTP。痛点Vortex组件多、部署运维重一个服务 可选 Redisdocker compose up -d并发写入计数不准写入在 leader 上串行执行再复制精确、无锁窗口聚合要建表或写查询语言range·step·window·z读时折叠单点故障每个节点全量副本约 5 秒选出新 leader内存随序列增长每节点 key 上限超出部分溢出到 Redis3. 快速开始镜像已上架 Docker Hub 和 GHCR免费拉取·linux/amd64linux/arm64· 无需 JDK、Node无需构建curl-fsSLOhttps://raw.githubusercontent.com/paganini2008/vortex/main/deploy/docker-compose.ymldockercompose up-d# 3 个节点 Web 控制台 网关curl-XPOSThttp://localhost:9080/tsd/push?tlongccardspeedv44curlhttp://localhost:9080/tsd/last?tlongccardspeed{code:1,data:{value:44,timestamp:1791182928819},elapsed:1,msg:ok,requestPath:/tsd/last}打开地址Web 控制台http://localhost:9080/Swagger UIhttp://localhost:9080/swagger-ui.html其他方式命令只拉镜像docker pull fredfeng033/vortex-tsdb:latest·docker pull fredfeng033/vortex-tsdb-web:latest从 GHCRdocker pull ghcr.io/paganini2008/vortex-tsdb:latest·VORTEX_REGISTRYghcr.io/paganini2008 docker compose up -d接自己的 RedisVORTEX_REDIS_HOSThost.docker.internal VORTEX_REDIS_PASSWORDsecret docker compose up -d从源码git clone https://github.com/paganini2008/vortex.git cd vortex ./run-docker.sh节点启动约需 20–30 秒docker compose ps显示(healthy)即就绪。4. 环境要求用途需要运行镜像Docker compose v2Docker Desktop、Rancher Desktop、OrbStack、Engine 23溢出存储可选Redis已测试 7.4 和 8.6从源码构建JDK 17、Maven 3.9、Node.js 20技术栈Spring Boot 4.1 · openspreader · Next.js 16 · React 19 · Tailwind 4 · Traefik v35. 工作原理数据Key结构分钟桶tsd:type:category:dimension:minutemax · min · sum · count保留期即 TTL最新值tsd:last:categoryHash一次读出整个 category序列目录tsd:catalog按最后采样时间排序的 ZSet集群健康tsd:healthHash每节点每 5 秒写一次6. 代码示例示例 1 —— 写入并读回输入for v in 44 67 112; do curl -X POST localhost:9080/tsd/push?tlongccardspeedv$v; done再curl localhost:9080/tsd/retrieve?tlongccardspeedzAsia/Shanghai执行3 个样本落进同一个分钟桶retrieve按时区z返回最近 60 个桶输出09:29:00: {count: 3, highestValue: 112, lowestValue: 44, totalValue: 223, averageValue: 74.3333}示例 2 —— 滑动窗口输入curl localhost:9080/tsd/query?tlongccardspeedrange6hstep5window15执行72 个点每个点折叠它之前的 15 个分钟桶window step即滚动窗口输出{step: 5, window: 15, last: {value: 61}, summary: {count: 21540, …}, points: [{from: …, to: …, count: 900, averageValue: 69.8}, …]}示例 3 —— 整个集群输入curl localhost:9080/tsd/categories·curl localhost:9080/tsd/health执行任意节点都从本机的复制内存中作答输出按繁忙程度排序的 category每个节点的 QPS、错误率、缓存、复制延迟、JVMCategories放大浅色主题7. 配置变量默认值说明VORTEX_RETENTION24h数据保留期VORTEX_SPAN_MINUTES1桶宽分钟需整除 60VORTEX_TIME_ZONEUTC请求未带z时的时区VORTEX_CACHE_MAX_KEYS10000每节点内存 key 上限VORTEX_REDIS_HOST空溢出 Redis为空则超限 key 被删除VORTEX_SNAPSHOT_INTERVAL5m快照间隔VORTEX_GATEWAY_PORT9080宿主机端口全部配置见 docs/configuration.md。8. 性能与对比环境Docker Desktop4 CPU / 8 GB3 个节点k6 经网关压测。场景结果阶梯加压 826,781 次写入0 失败各节点计数完全一致持续吞吐约 1,000 samples/s峰值1,400–1,500 samples/sleader 约 2.3 个 CPU堆 ≤ 310 MB600/s 写入时kill -9leader4.7 秒选出新 leader0.28% 请求失败优雅停机 leader立即交接0 失败VortexPrometheusInfluxDBTimescaleDB写入HTTP pushpullHTTP pushSQL查询HTTP 参数PromQLInfluxQL / SQLSQL存储内存 快照磁盘磁盘PostgreSQL高可用内置需额外方案视版本依赖 PG 方案适合实时指标、天级保留监控告警通用时序长期分析9. 限制与取舍限制后果所有写入经一个 leader约 1,000–1,500 samples/s不随节点数增长数据在内存所有节点同时被杀 → 回到最近快照≤ 5 分钟异步复制leader 崩溃时进行中的写入会失败其中少数可能已写入Redis 溢出读取已溢出的 key 需要一次网络往返无查询语言、告警、鉴权部署在内网不适合一条都不能丢的账务数据 · 月 / 年级保留 · 每秒数万次以上写入。10. 总结一条命令——docker compose up -d镜像支持 amd64 与 arm64。只有 HTTP—— 写入用t/c/d/v查询用range/step/window/z。计数精确—— leader 串行执行写入无漂移、无锁。本机读取—— 每个节点都是全量副本。窗口免费—— 滚动与滑动窗口都由分钟桶折叠而来。自动恢复—— 约 5 秒选出新 leader优雅停机无感知。足够持久—— 停机时及每 5 分钟写快照。内存可控—— 每节点 key 上限可选 Redis 溢出。可观测——/tsd/health与 Web 控制台开箱即用。定位清晰—— 面向天级保留的实时指标。GitHubhttps://github.com/paganini2008/vortex ·官网https://paganini2008.github.io/vortex/