PyCryptoBot / 报错排查
PyCryptoBot 报错怎么查：按现象索引的排查对照表
官方仓库没有独立的排查文档——它的支持渠道是 GitHub Discussions 与 Telegram 群，而 README.md 本身只有约 2 KB，把安装与配置都外链到了作者的个人博客。这一页把「你会看到什么现象」和「去哪个文件、哪个开关、哪条开源记录里找原因」对上，按可核对的方式整理成表。
排查顺序建议固定为四步：先读日志定位是哪个阶段失败 → 再对照 config 排除配置问题 → 然后验证接口与权限 → 最后回看自己跑的是哪一版代码。这个顺序的价值在于：PyCryptoBot 的绝大多数「报错」其实不是程序写错了，而是环境、权限或版本对不上——本站把「版本」放在最后一步，是因为它最容易被忽略，也最容易解释「官方说修了但我还有」这类现象。
需要提前说明一条边界：本站没有实机运行过这个PyCryptoBot 机器人，所有条目都来自源码、配置样本、Dockerfile 与 CHANGELOG 的核对，因此每一条都标注了依据；凡是需要真实账户才能确认的行为，本站只写检查动作，不写结论。
- PyCryptoBot v8.2.4（main=1fa9aaef，2024-03-04）
- Python 3.11（官方 Dockerfile 基线）
- 交易所范围：Binance / Coinbase / KuCoin
- 验证日期 2026-09-21
- 本站未实机运行机器人
api.py 的错误处理点、429/recvWindow 处理与 CHANGELOG.md 的历史修复记录整理，非官方排查流程）。四格对应本页的四张表；顺序不建议调换——先定位阶段，再改配置。十四个常见现象，分别该查哪里
下表按「你会看到什么」组织，最后一列给出结论依据，便于你自己回到源码或 CHANGELOG 复核。本站不对任何一条做「这是官方 bug」的断言，只记录项目是否修复过同类问题。
| 现象 | 最可能原因 | 检查什么 | 处置方向 | 依据 |
|---|---|---|---|---|
日志出现 429、请求被拒 | 调用频率超过交易所限制 | 单周期内的请求次数、是否同时开了多个实例或 scanner | 降低频率、减少并行实例；不要指望库替你退避 | 某交易所 api.py 有显式 429 处理；其余三家的 retry 计数为 8/17/18，但四家的 backoff 计数均为 0——没有指数退避 |
| 时间戳不同步 / 签名校验失败 | 本机时钟漂移，或请求时间窗口过窄 | 系统时间与 NTP 同步状态；时间窗口参数是否被人为改小 | 同步系统时钟；不要随意改动时间窗口参数 | 某交易所 api.py 使用 recvWindow；四家均提供 get_time 类方法用于校准 |
| 提示密钥无效 / 未授权 | 密钥权限不足、密钥文件缺失或路径不对 | 密钥文件是否存在于配置里写明的路径；权限是否覆盖现货交易 | 按最小权限重建密钥；确认文件路径与配置一致 | CHANGELOG 记录过某交易所密钥缺失相关的修复（对应 PR #839） |
| 下单被拒：余额不足 | 计价币种余额不够，或资金在另一个账户 | 账户里计价币种的实际可用余额 | 补齐余额；开启「余额不足记录为警告」的开关以继续运行 | config 有 enableinsufficientfundslogging 开关，可把该异常降级为日志提醒 |
| 下单被拒：数量不合法 | 低于交易所最小下单量，或数量精度不符合步进 | 该币对的最小下单量与数量步进；程序算出的下单量 | 提高单笔规模或调整 buymaxsize；确认精度处理 | 仓库内有市场合法性校验与数量/价格增量处理；CHANGELOG 记录过最小下单函数抛异常与增量计算的修复 |
| 启动后报历史数据不足 | 请求的 K 线根数超过交易所单次返回上限 | 该交易所单次返回的最大根数；请求的周期与根数 | 让程序按起始时间分段取数，而不是一次取满 | CHANGELOG 记录过某交易所只返回 100 行的问题，修复方式是传入计算好的起始时间以取到 300 行 |
| 模拟/回测跑完，一笔都没成交 | 买入过滤条件未满足、周期写法不对，或点数阈值未达到 | disable* 系列取值的 0/1 方向；granularity 的写法；策略要求的点数阈值 | 先用最宽松的过滤组合验证链路能成交，再逐项加过滤 | 买入过滤共 8 个 disable* 键；默认自定义策略是点数制，pts_to_buy 默认 9，而部分趋势分支把该阈值抬到 100（等价于禁止买入） |
| 同一市场被重复买入 / 出现重复下单 | API 报错后重试、同一轮重复处理、或多实例并行 | 是否同时有多个实例在跑同一个币对；是否共用了同一个数据目录 | 一个币对只跑一个实例；多实例用不同数据目录隔离 | CHANGELOG 有多轮同类修复记录（涵盖 API 出错重复买入、同一轮重复处理、WebSocket 双重买入、只启动未运行实例） |
| 依赖装到一半编译失败 | 钉子依赖在 Python 3.11 上没有预编译轮子 | 报错里出现的是哪个包；本机是否有 C 编译器与头文件 | 用官方容器镜像（编译阶段已装编译工具），或在裸机上补齐编译环境 | 探测显示 matplotlib==3.3.3、pyyaml==5.3.1、websockets==9.1 均无 cp311 轮子；而 Dockerfile 的编译阶段确实安装了 build-essential |
| 启动即报配置缺失或解析失败 | 工作目录没有配置文件，或 JSON 格式错误 | 配置文件名是否已从样本改名；JSON 是否有多余逗号或中文标点 | 按样本改出正式配置并做一次 JSON 语法校验 | 仓库提供的是 config.json.sample 系列样本文件，需要自行改名为正式配置 |
| Web 面板空白 / 没有数据 | 控制数据未写入，或界面启动顺序不对 | 是否已开启控制开关；界面相对PyCryptoBot 机器人是早启动还是晚启动 | 先开控制开关并跑起PyCryptoBot 机器人，最后再启动界面；界面刷新有延迟 | 官方界面说明文件写明：界面通过读取控制数据目录工作，需在所有PyCryptoBot 机器人启动后再启动，首次加载约 6–7 秒、刷新间隔约 ±5 秒 |
| 进程重启后状态与实际持仓不符 | 本地状态文件与交易所侧真实持仓不同步 | 交易所侧的挂单与持仓；本地状态文件的更新时间 | 以交易所侧为真相核对一次，再决定是否继续运行 | PyCryptoBot用本地状态文件记录持仓与交易状态（CHANGELOG 多次提到状态文件与异常退出后的处理） |
| 容器起来就退出 | 缺少配置或首次运行前置条件未满足 | 容器日志的第一段报错；挂载的配置是否存在 | 先补配置再启动；注意按需选择退出即重启的策略 | 镜像入口固定为启动器脚本；编排样本里的重启策略是「失败时重启」，正常退出不会拉起 |
| 日志里偶发 HTML 或 JSON 解析错误 | 交易所返回了非预期内容（网关页、限流页等） | 该错误的出现频率与发生时段 | 记录频率；若伴随 429 则优先按限频处理 | CHANGELOG 记录过「偶发 HTML 错误无法在项目侧修复」与若干 JSON 解析相关的容错改动 |
日志里有什么、在哪里看
排错的第一步不是改配置，而是先把「失败发生在哪」这一件事确定下来。下面这张表列出可以看的对象与各自能回答的问题。
| 要看的对象 | 路径或命令 | 能看到什么 | 注意点 |
|---|---|---|---|
| PyCryptoBot 机器人日志文件 | 工作目录下的 pycryptobot.log（编排样本里作为卷挂载） | 每一轮的分析结果、买卖判断、接口调用与异常 | 先看最后一屏，再看异常第一次出现的位置，不要从文件头读 |
| 日志服务入口 | 仓库根目录的 logsvc.py | 与日志相关的服务入口，用于把日志分离出来查看 | 它是独立进程，需要单独启动；本站未实测其界面形态 |
| 日志开关 | 配置里的 disablelog | 开启后可关闭日志写入 | 排错期间不要关日志，否则会失去唯一的现场证据 |
| 日志级别 | 配置里 telegram 段的 logger_level | 控制通知与日志的详细程度 | 标准样本里默认是 DEBUG；降低级别有助于减少噪声 |
| 成交明细导出 | 工作目录下的 csv/ 目录与其中的交易明细文件 | 逐笔成交记录，可用于核对「到底下了几单」 | 怀疑重复下单时，先看这份明细而不是只看日志文本 |
| 你实际跑的是哪一版 | 在仓库目录执行 git log -1 --format="%h %ad %s" | 当前代码的 commit、日期与提交信息 | 这一步放在最前也不为过——它能直接排除一整类「版本差」问题 |
| 本地状态与交易所侧对账 | 交易所网页端或官方客户端 | 真实挂单、真实持仓与真实余额 | 本地状态文件不是真相来源，交易所侧才是 |
五步把配置逐项核对一遍
配置类问题的特点是「程序不报错、行为不符合预期」。下面五步按「最容易搞错」的顺序排列，每一步都给出可直接执行的检查动作与预期结果。
确认运行模式开关的值
检查动作：打开配置文件，找到交易所段里的
live。预期结果：值为0表示非实盘，1表示实盘。如果你「明明改了策略却什么都没发生」，先确认这个值——非实盘模式不会真实下单。确认周期（granularity）的写法
检查动作：看该交易所段的
granularity字段。预期结果：同一份官方样本里存在两种写法——有的交易所段写字符串"1hour"，有的写整数秒"3600"。周期只支持 7 档固定值（1m / 5m / 15m / 30m / 1h / 6h / 1d），写一个不在枚举里的值不会自动纠正。确认
disable*系列的方向检查动作：逐个看买入侧
disable开头的开关取值。预期结果：值为1表示「关闭该项过滤」，0表示「启用该项过滤」——方向与字面直觉相反。官方两份样本里各项的默认方向并不一致，所以「照抄默认值」不等于统一口径。若模拟跑完没有成交，先把过滤逐项放开验证链路。确认币对与计价币种
检查动作：核对基础币种、计价币种，以及账户里该计价币种的实际余额。预期结果：币对的写法要与交易所的命名一致；计价币种余额决定了PyCryptoBot 机器人是否有资金可下单。
确认密钥文件路径真的存在
检查动作：按配置里写的密钥文件名，在工作目录确认文件存在且可读。预期结果：文件存在、内容格式正确、权限不对外开放。这一步能排掉相当一部分「提示未授权」的误判。
哪七项接口与权限检查最容易误判？
「常见误判」这一列是这张表的价值所在——很多被当成程序 bug 的现象，实际是权限或账户设置问题，改代码永远改不好。
| 检查项 | 怎么做 | 期望结果 | 常见误判 |
|---|---|---|---|
| 密钥权限范围 | 在交易所后台查看该密钥已勾选的权限 | 覆盖现货交易所需的最小集合 | 把「只读权限」当成「可以下单」，于是把所有失败都归因于代码 |
| 是否误开提现权限 | 检查密钥是否勾选了提现 / 转账类权限 | 关闭提现权限 | 「权限越多越保险」——实际相反，多开的权限只增加风险，不提升成功率 |
| IP 白名单 | 若使用了白名单，确认运行机器的出口 IP 已在其中 | 请求来源 IP 与白名单一致 | 换网络、换 VPS 或启用代理后忘记同步白名单，表现为「昨天还能用」 |
| 交易所侧最小下单量 | 在交易所页面查该币对的最小下单量 | 程序算出的单笔规模高于该下限 | 把「下单被拒」当成代码错误，实际是资金规模不够一个最小单位 |
| 地区与端点可用性 | 确认当前网络能正常访问配置里写的接口地址 | 配置里的接口地址可访问 | 把网络层失败（超时、无法解析）当成密钥问题反复重配 |
| 沙箱与正式环境 | 确认密钥属于哪个环境、接口地址是否与之匹配 | 密钥环境与接口地址一致 | 用测试环境密钥打正式接口，或反之，表现为「密钥无效」 |
| 时间窗口与系统时钟 | 同步系统时钟；确认请求时间窗口未被改小 | 本机时间与标准时间偏差在秒级以内 | 忽略容器与宿主机的时区差异；容器里时间不滚动导致签名持续失败 |
| 接口调用的并发度 | 统计同一时间在跑几个实例、是否有额外脚本在调同一账户 | 同一账户的并发调用可控 | 多实例 + 扫描脚本同时打同一个账户，触发限频却以为是程序写错 |
「官方说修了但我这里还有」怎么办？
这是本站认为最值得单独成表的一类问题：它不属于你的配置错，也不属于代码错，而是你手上那份代码和别人讨论的那份不是同一版。
| 症状 | 可能原因 | 结论依据 | 怎么做 |
|---|---|---|---|
| 按 README 命令更新后，问题依旧 | README 教的更新方式拿到的是主干分支，而主干已有一段时间没有新提交 | 主干分支最后一次提交是 2024-03-04；最新发行版 8.2.4 也在同一天 | 不要假设「pull 过就是最新」；先看 commit 与日期，再判断问题是否可能已在新代码里被修 |
| 看到一个修复记录，但代码里找不到对应改动 | 该修复在另一条分支上，尚未合并进主干 | 仓库的领先分支上有一条 2025-05-26 的提交，比主干新约 14 个月 | 确认该修复位于哪条分支；若不在主干，说明按 README 更新拿不到它 |
| 依赖升级后行为变了 / 装不上 | 项目把多个依赖钉在 2020–2022 年的版本上，「升级依赖」会去装这些旧钉子 | 依赖清单里存在无对应 Python 版本轮子的旧包；仓库里存在一条未合并的依赖升级改动 | 升级前先看清要装的具体版本号；不要用「装最新的」这种模糊预期 |
| 找不到「最新版」的发布说明 | 变更日志的最后一条记录停在 8.2.0 | 发行版标签到 8.2.4，但变更日志末条是 8.2.0 | 把变更日志当补充材料，不要当完整发行说明；以标签与提交为准 |
| 想用 pip 升级却提示找不到包 | PyCryptoBot没有发布到包索引 | 四个常见候选包名在包索引上均不存在 | 升级只能走仓库拉取或容器镜像两条路；不要试图 pip 升级 |
| 换机器后表现不同 | 两台机器上装到的依赖版本不同 | 依赖清单里既有钉死版本的包，也有未钉版本的包 | 把装好的完整依赖清单一并留存，换机器时对照，而不是只装清单里那几行 |
| 不确定该用主干还是领先分支 | 两条分支各有取舍：主干稳但有已知未修问题，领先分支新但未经发行验证 | 两条分支的提交日期与发行标签状态 | 先明确你的目标（追新修还是求稳），再选分支；不要把两条分支的代码混用来排查 |
git log -1 --format="%h %ad %s"（看当前 commit 与日期）、git branch -a（看本地与远端有哪些分支）、git tag --sort=-v:refname | head -5（看最近的发行标签）。把三条的输出贴进求助帖，比任何文字描述都有效。关于报错排查的高频问题
回答依据源码、配置样本与仓库变更日志的核对结果；涉及运行期行为的结论以你的实际环境与官方仓库为准，本站未实机运行。
遇到 429 限频到底该怎么处理？
先降低请求频率，再排查并发来源。可核对的事实是：四个交易所实现里都有错误处理，其中三家写了重试逻辑（重试相关代码的出现次数分别为 8、17、18），另一家则对 429 有显式处理但重试计数为 0；四家都没有指数退避（退避关键词命中均为 0）。这意味着程序不会自己「越限越慢地退让」，所以真正的解法通常是减少同一时间在跑的实例、降低轮询频率、或确认是否有额外脚本在打同一个账户。
提示时间戳不对或签名失败，改代码有用吗？
通常没用，优先改环境。这类错误的根源一般是本机时钟漂移、容器与宿主机时区不一致，或者有人为了「更快」把请求时间窗口改得很小。仓库里提供了取交易所时间的方法用于校准，也有交易所使用了请求时间窗口参数。正确顺序是：先同步系统时钟并确认容器时间在滚动，再考虑是否动过时间窗口参数。
提示密钥无效或未授权，怎么快速判断是权限还是代码问题？
用「错误信息里有没有具体数值」来判断。如果错误只说未授权、拒绝、无效，优先查权限与环境：密钥勾选的权限范围、密钥属于哪个环境、配置里写的接口地址是否与之匹配、密钥文件路径是否真的存在。如果错误里带具体数值（数量、精度、余额、最小量），那就是规模与精度问题，改权限不会有帮助。
数量精度错误是怎么回事？
交易所对每个币对都有数量与价格的步进要求，程序算出的下单量必须落在合法格点上，且不低于最小下单量。可核对的是：仓库内有市场合法性校验以及数量/价格增量的处理代码，变更日志里也记录过最小下单相关函数抛异常、以及增量计算问题的修复。实务上先做两件事：到交易所页面确认该币对的最小下单量与精度，再看程序算出的单笔规模是否在其中。
模拟跑完了却一笔都没成交，最可能是哪里？
按三步排查。第一，看运行模式：非实盘模式下不会真实下单，判断「有没有成交」要看模拟输出而不是账户。第二，看过滤开关：disable 开头的开关值为 1 表示关闭该项过滤，方向与直觉相反，而官方两份样本里各开关的默认方向并不一致——照抄默认值不等于统一口径。第三，看策略阈值：默认自定义策略是点数制，买入选点数默认 9，而部分市场趋势分支会把该阈值抬到 100，相当于「本阶段不买入」。建议先用最宽松的过滤组合验证链路能成交，再逐项加回过滤。
依赖装不上，是不是我的环境有问题？
不完全是。可核对的探测结果是：依赖清单里钉死版本的包中，有三个在 Python 3.11 上没有预编译轮子（只发布到更早的 Python 版本），因此必须本地编译；而同清单里另有一个重量级包是有新版本轮子的。这也解释了为什么官方容器镜像能在同一 Python 版本上装成功——它的构建阶段安装了编译工具链。所以裸机装失败时，合理的做法是补齐编译环境，或者直接用官方容器路径。
Web 面板打开是空白的，是没数据还是启动错了？
两者都可能，但先查启动顺序。官方界面说明文件写明：界面通过读取控制数据目录工作，需要在控制开关打开、且所有PyCryptoBot 机器人启动之后再启动界面；首次加载约需 6–7 秒，之后刷新间隔约 ±5 秒。因此「刚打开就空白」未必是故障，「一直是空白」则先确认控制开关是否开启、界面是否早于机器人启动。本站未实测该界面的实际可操作项。