Files
pytdxdata/docs/internals/cache-pool.md
T
openbot-coder 7e830c7579 docs: 补齐测速缓存相关文档,并修掉 0.6.0 遗留的过时描述
上一提交只补了 getting-started / routing / llms.txt / SKILL.md 四处,本轮把其余
教程类页面与接口清单补齐,并顺手修正 v0.6.0 统一接口改造后遗留的过时说明。

补齐(当日测速缓存):

- README「已知限制」:说明当日首次启动会自动后台测速并缓存
- FAQ 新增「启动时会变慢吗?会不会在后台偷偷联网?」:无感保证 + 三个环境变量开关
- FAQ「连不上服务器怎么办」:加入"删当日测速缓存 / 环境变量指定主机"两条前置排查
- API_REFERENCE 四、辅助模块:config 补全当日测速相关函数与优先级链说明,
  新增 pytdxdata.pool.probe_cache 一节(ProbeCache / schedule_probe / get_probe_cache)
- internals/architecture.md 目录树:config.py、probe_cache.py 的职责注释更新
- internals/cache-pool.md「下一步」:补「服务器是怎么选出来的」交叉链接

修正(v0.6.0 遗留过时描述):

- FAQ / api/enums.md:删掉「所有接口的第一个参数都是 market」——统一接口已改为字符串标的
- FAQ / cookbook:`*_batch` 已并入 `get_bars`(多标的),不再作为批量入口
- FAQ / getting-started「自建服务器清单」:`standard_servers` 实际是 Sequence[str]
  而非 (host, port) 元组(端口由统一的 port= 指定);原示例照抄会取到错的主机名
  (已实测:字符串写法正确,元组写法不会被解析)

校验:check_docs.py exit 0;mkdocs build --strict 无告警;新增交叉链接
#当日自动测速无感 / #daily-probe 均正确渲染且目标锚点存在;全量 164 项通过;
src/pytdxdata/servers.json 跑测前后逐字节不变。
2026-09-21 18:26:37 +08:00

115 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 连接池与缓存
这个项目相比同类实现快 **约 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
同一时刻对**同一个缓存键**的并发请求会自动合并:第一个去回源,其余的等待并共享结果。
```python
# 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(指数加权移动平均)延迟让选路对「最近变慢」敏感,而不是被历史均值拖住。
### 为什么 MAC 池更小
MAC 通道可用服务器只有数台(见 [通道与数据源](routing.md#server-groups)),
所以 `mac_pool_cap` 默认只有 `4`——这是**对端限制**,不是本项目的选择。
逐笔 / 分时的并发能力天然弱于日线,原因就在这里。
## 并发分页
大请求会被拆成多页,每页带**显式 `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` 无用。
## 下一步
- [架构总览](architecture.md) — 这些模块在整体里的位置
- [通道与数据源](routing.md#daily-probe) — 服务器是怎么选出来的(当日测速缓存)
- [常见问题](../faq.md) — 缓存与超时的排查