Commit Graph
7 Commits
Author SHA1 Message Date
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
openbot-coder b78d0fabf5 docs: 修正 servers.json 清理后遗留的过时描述(含一处事实反转)
servers.json 复测后三池台数已变(standard 9 / mac 22 / ex 4),但 README 与部分文档
仍停留在旧口径,且有一处因果结论被实测推翻:

- README.md
  - 测试用例数 127 → 164(并补「当日测速缓存」到用例分组说明)
  - 「已知限制」补测速缓存详情的文档站链接
- docs/internals/routing.md
  - 三池台数:标准池「数十台」→ 9 台、MAC 池「数台」→ 22 台(EX 池 4 台不变),
    并标注为 2026-09-21 离线探针实测可达数、实际以当日测速缓存为准
  - **事实反转修正**:原文「MAC 池远小于标准池,这解释了逐笔/分时并发弱于日线」
    与实测不符(mac 22 > standard 9)→ 已改为陈述实测台数,
    并指出两通道单台连接上限默认相同(均 4)
- docs/internals/cache-pool.md
  - 「为什么 MAC 池更小」小节前提已不成立 → 改为「MAC 通道的单台连接上限」,
    保留 mac_pool_cap=4 的可用信息,删除错误因果
- docs/refactor-audit.md
  - 历史快照的 127 passed 标注「审查当时」,避免误读为当前基线

验证:scripts/check_docs.py exit 0;mkdocs build --strict exit 0(无告警)
2026-09-21 19:42:06 +08:00
openbot-coder d422385877 chore(servers): 离线探针复测重写 servers.json,并给探针工具补 --discover
servers.json(真数据复测 2026-09-21,两轮零漂移)
- 剔除历史脏记录 s1;刷新 status/latency/checked_at/checked_date/fast_pool
- 可达 25/33:standard 9 台、mac 22 台、ex 4 台(旧文件 mac 只标了 10 台)
- 关键发现:14 台服务器 0x010C 标准 K 线已成空响应(回 2 字节空壳),
  但同端口同主机的 0x122E MAC 帧正常 → 据实测把 protocols 由 standard/mac 收窄为 mac
- 8 台不可达:华林 4 台(218.106.92.182/183, 220.178.55.71/86)、159.75.55.232、
  117.34.114.13/14/30 → status=fail
- 117.34.114.17 实测 standard+mac 均通(此前只申报 standard)

server_probe.py
- 新增 --discover:三种协议全测并据实修正 protocols(顺带剔除 ip 非法记录)
- 失败重试一次再判定不支持(单次抖动会误删协议,且收窄后不会自动恢复)
- EX 握手模式申报错时换另一种再试(login <=> setup)
- 补写 checked_date / fast_pool / 顶层 version·note,入池规则与运行时缓存一致

验证:164 passed;servers.json 跑测前后 sha 不变;check_docs.py + mkdocs --strict 通过
2026-09-21 19:05:32 +08:00
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
openbot-coder 18d9e9a006 fix(pool): 重写当日测速缓存:全量候选 + 用户级缓存 + 真实数据探针
原实现在 v0.5.0 已随包发布,但有三处会"静默失效"的缺陷,等于没真正生效:

- 候选集自指:连接池把自己已过滤后的成员当探针输入,实测只重测了 9 台,
  另外 20+ 台候选(含快节点)永远测不到。改为由 probe_cache 自行枚举
  全量候选(包内清单 ∪ 代码常量 ∪ env),不再接受调用方传入的"当前池成员"。
- 写回安装目录:结果写回 src/pytdxdata/servers.json,容器/系统级安装下只读会
  静默失败、多用户共用一个安装会互相覆盖,且污染随包分发的数据。改为写入
  用户级缓存目录(Win %LOCALAPPDATA% / macOS ~/Library/Caches / Linux $XDG_CACHE_HOME),
  运行时绝不再改写包内清单。
- 探测太弱:只做握手,测不出「握手正常但 K 线空响应」的坏节点。改为发真实业务
  命令并要求返回非空(标准 GetSecurityBarsCmd / MAC MacKlineCmd / EX GetExInstrumentBarsCmd),
  EX 池(4 台,7727)也一并纳入。

无感保证:后台 task 不阻塞 start()、日志全 debug 级、绝不抛异常(取消除外)、
原子写 tmp + os.replace、进程内单例 + asyncio.Lock 单飞;全不可达时不写缓存
(否则"今天全挂"会被缓存一整天)。close() 会取消并 await 后台探针,
避免解释器退出时报 "Task was destroyed but it is pending"。

新增环境变量 PYPYTDX_DATA_CACHE_DIR(覆盖缓存目录)、
PYPYTDX_DATA_DISABLE_PROBE=1(关闭测速)。新增 tests/test_probe_cache.py(37 项)。
2026-09-21 17:54:29 +08:00
openbot-coder 3e0beb27a6 release: v0.6.0(统一对外接口重构)
按「数据类型」合并同类查询接口:一个数据类型 = 一个方法,跨市场自动选路。

- 28 个统一接口(get_universe/get_quotes/get_bars/get_indicators/get_ticks/
  get_minutes/get_f10/get_file/get_boards/get_board_of/get_snapshot 等),
  标的统一字符串写法(sz000001 / hk00700 / usAAPL / cffex:IFL0);
  同名旧方法不再兼容 (market, code) 元组。
- 旧 51 个按通道/市场分裂的接口:33 个保留为 deprecated 别名(1.0 移除),
  18 个同名升级为统一接口。公开方法共 63 个。
- 新增库层标的解析 pytdxdata.symbols;数据模型追加 symbol/name/fields 兜底字段。
- 修复:分页器连接泄漏、日期区间 K线返回 0 条(偏移方向探测)、池子全冷却死等。
- 文档/README/SKILL/llms.txt 全量同步;新增 docs/refactor-audit.md 审查报告。
- 测试 127 个用例全绿(含 tests/test_all_interfaces.py 全 63 方法回归)。
2026-09-17 11:34:52 +08:00
openbot-coder c4dd61665b docs: 建立 MkDocs 文档站与 AI 层文档
- 新增 MkDocs + Material 文档站(19 页):入门、CLI、场景示例、FAQ、
  Contributing、Changelog、API 参考(mkdocstrings 自动渲染)、内部原理
  (架构 / 协议 / 三池路由 / 缓存)
- 新增 docs/llms.txt:面向 LLM 的结构化摘要(枚举取值、方法速查、常见陷阱)
- 新增 scripts/check_docs.py:校验文档与 api.py 公开方法清单是否漂移
- 新增根 CHANGELOG.md 作为版本记录唯一来源,docs/changelog.md 用 snippet 引入
- 新增 .github/workflows/docs.yml:push main 自动构建并部署 GitHub Pages
- 修正文档口径:TdxData 公开方法 53 个(51 数据方法 + start/close);
  API_REFERENCE 版本号 v0.3.2 -> v0.4.0
- pyproject.toml 新增 docs 依赖组;.gitignore 忽略 site/
2026-09-15 13:57:31 +08:00