Files
pytdxdata/docs/internals/cache-pool.md
T
openbotandopenbot-coder 1cd8f692a1 fix(pool): 服务器中途掉线不再拖垮整批任务 + 发布 0.7.2 (#16)
* fix(pool): 服务器中途掉线不再拖垮整批任务

三种调度细节会把「一台机器坏了」放大成「整批卡住」:

1. acquire() 在池锁内做 TCP 握手 + 探针 —— 一台主机握手卡满 timeout,
   所有并发协程的 acquire/release 一起被挡。改为锁内只预留槽位、
   握手在锁外做,失败时回滚计数。
2. 扩容失败分支 continue 且无截止检查 —— 全节点失联时无限重试,
   永远不抛 PoolTimeoutError。改为同一次 acquire 内每台主机只试一遍,
   试完立刻抛错;再加池级熔断(BLACKOUT_COOLDOWN=2s),期内直接失败,
   任一连接成功即解除。否则上层「按标的逐只重试」会把 16×6000 次握手
   放大成 60s+ 的空转。
3. 批量 K 线失败批次攒到 gather 结束再串行补 —— 每只重付一次 RTT。
   改为 extendleft 回队首由健康连接立刻接手(每只最多 2 次),
   尾部兜底也改成信号量并发。分页器同理:worker 退出时把剩余页放回
   共享 leftover,活着的 worker 接手,全部退出后仍有剩页则借新连接补完。

EX 池同步改为锁外建连,并给握手失败主机加 30s 拉黑。

实测(16 台替身节点、6000 只 × 240 根 1 分钟 K 线、0.9s 后变黑洞):
  无故障   1.79s → 1.80s
  2/16 死   2.28s → 1.91s
  6/16 死   2.97s → 2.30s
  16/16 死  >60s 未返回 → 2.37s

新增 tests/test_failover.py(7 项,含熔断期不再握手)与
scripts/bench_failover.py(对比压测)。

* chore(release): 0.7.2

- server_time 解码修正(0.7.1 及之前按「小时 + 百万分之一小时」解析是错的)
- 服务器中途掉线的四项隔离机制(锁外建连 / 本轮不重试 / 池级熔断 / 批次回队)
- 版本号四处对齐:pyproject.toml、__init__.py、uv.lock、CHANGELOG

---------

Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
2026-10-30 16:57:29 +08:00

5.5 KiB
Raw Blame History

连接池与缓存

这个项目相比同类实现快 约 2 倍,来源就是这两块。

缓存

两级结构

内存 LRU  ──miss──▶  磁盘 SQLite (WAL)  ──miss──▶  回源网络
   ↑                        ↑
  快,进程内              跨进程 / 跨重启持久
  • 内存层:进程内 LRU,命中就是字典查找
  • 磁盘层:单文件 SQLite,开 WAL 模式,可多进程共享
  • 未传 cache_dir 时只有内存层(进程退出即失效)

TTL 分级

不同数据的「新鲜度要求」差了几个数量级,所以 TTL 是分级的:

数据类型 TTL 理由
五档报价 5s 变化最快
分钟 K 线 60s 边界处才会新增一根
日 K 线 当天 当天数据在盘中会变
复权 K 线 1 天 复权因子一天最多变一次
历史逐笔 永久 已经成交的不会变
证券列表 1 天 只有新股上市才变

缓存的是「已解析记录」

缓存里存的是解析好的 dataclass 对象(codec/payload.py 做 pickle + zlib), 不是原始响应字节。所以缓存命中时是 0 网络 + 0 解析,只有一次反序列化。

这也是为什么重复请求能从 0.31s 降到 0.016s。

single-flight

同一时刻对同一个缓存键的并发请求会自动合并:第一个去回源,其余的等待并共享结果。

# 100 个协程同时请求同一只股票的同一段 K 线
# → 只发 1 次网络请求
results = await asyncio.gather(*[
    td.get_bars("sh600000", KlinePeriod.DAY, count=800)
    for _ in range(100)
])

上限由 max_inflight(默认 64)控制。

缓存键会做规范化——get_quotes 的键是排序去重后的股票集合, 所以 [A, B] 和 [B, A] 共享缓存。

连接池

动态扩缩容

参数 默认 含义
pool_min 3 保底连接数
pool_max 12 上限
mac_pool_cap 4 单台 MAC 服务器连接上限
timeout 3.0 连接超时(秒)

按等待队列长度与空闲时长动态扩缩容,不是启动时就拉满。

健康分与选路

每台服务器维护一个健康分,取连接时按健康分 + EWMA 延迟综合选路:

事件 健康分变化
请求失败 × 0.5
请求成功 + 0.2
连续失败 进入 120s 冷却,冷却期内不再被选中

失败会跨服务器故障转移——重试用的是另一台,而不是同一台重连。

EWMA(指数加权移动平均)延迟让选路对「最近变慢」敏感,而不是被历史均值拖住。

单台服务器中途掉线

「掉线」和「慢」是两回事:慢只是多等一会儿,掉线会把整批任务卡住。0.7.2 起有四道闸:

机制 作用
锁外建连 acquire 锁内只预留槽位,TCP 握手 + 探针在锁外做。否则一台主机握手卡满 timeout 期间,所有并发协程的 acquire / release 全被池锁挡住
本轮不重试同一台 一次 acquire 里握手失败的主机记进 avoid,不再重复试;每台都试完立刻抛 PoolTimeoutError
池级熔断 全主机失败后进入 BLACKOUT_COOLDOWN(2 秒)黑洞期,期内 acquire 直接失败、不再握手;任一连接成功即解除
批次回队 / 份额再分配 批量 K 线流水线失败的那一批立刻回队首由健康连接接手;分页器让活着的 worker 接手坏 worker 剩下的页

实测 16 台替身节点、6,000 只 × 240 根 1 分钟 K 线、跑起来 0.9 秒后集体黑洞:

场景 0.7.1 0.7.2
无节点故障 1.79 s 1.80 s
2/16 中途失联 2.28 s 1.91 s
6/16 中途失联 2.97 s 2.30 s
16/16 中途失联 > 60 s 未返回 2.37 s

全灭时的行为分两种:一开始就没有可用连接 → get_bars 抛 PoolTimeoutError(不再静默 返回空列表);跑到一半全灭 → 返回已经取到的部分(不抛错、不挂死)。熔断只在全部主机 都握手失败时触发,池子满了排队等待不受影响。

MAC 通道的单台连接上限

mac_pool_cap 默认 4,与标准池的 std_pool_cap 一致——这是对端单台连接限制, 不是本项目的选择。两个通道的可用台数见 通道与数据源: 实测可达台数会随服务器上下线变化,以当日测速缓存为准。

并发分页

大请求会被拆成多页,每页带显式 start 偏移——无状态,所以可以并行。 多连接并行拉取 → 按序拼接 → 某页失败就换连接重试该页。

count=2400  →  3 页  →  3 个连接并行  →  按序拼接

两种例外:

场景 策略 原因
KlinePeriod.MIN_1 单连接串行 各服务器历史深度不一致,并发会导致非确定性空洞
MAC 通道复权 K 线 单连接串行(_fetch_mac_kline_serial) 同上

!!! tip "调参建议" concurrency 超过 pool_max 之后只会排队。实践值 8~16。 MAC 类请求(逐笔 / 分时)并发能力受 mac_pool_cap 限制,调大 concurrency 无用。

下一步