PyCryptoBot / 安装与运行方式
PyCryptoBot 安装：没有 pip 包，只能 clone 或跑容器
大多数 Python 项目的安装章节从 pip install 开始。PyCryptoBot 不是这样：它在 PyPI 上没有包——本站探测的四个候选名（pycryptobot、pycryptobot-api、pycryptobotlib、py-crypto-bot）全部返回 404，仓库根目录也没有 setup.py 或 pyproject.toml 这类打包元数据。
所以你的起点只有两个：把仓库 clone 下来自己装依赖，或者直接用官方容器镜像。这两条路的前置条件完全不同，而且第二条路之所以更稳，原因写在 Dockerfile 里——它先用一个带 build-essential 的阶段把依赖编译好，再把产物复制进运行镜像。
这一页把四种运行方式、Dockerfile 里值得知道的细节、以及依赖钉子的编译风险逐项列出来。注意边界：本站没有实机跑完整安装，下面所有「需编译」「可直接装」的判断都来自 PyPI 上的轮子标签覆盖范围，不是本机安装日志。
- PyCryptoBot v8.2.4（main=1fa9aaef，2024-03-04）
- Python 3.11（官方 Dockerfile 基线）
- 交易所范围：Binance / Coinbase / KuCoin
- 验证日期 2026-09-21
- 本站未实机运行机器人
Dockerfile、docker-compose.yaml 与 chart/ 目录整理，非官方安装指南）。四种方式共享同一份 config.json 结构，差别在前置条件与运维成本上。为什么这个项目不能 pip install？
先把事实摆出来，因为「装不上」和「以为装上了但其实是别的包」是两件不同的事。下表是本站对 PyPI 的探测结果与仓库打包元数据的核查。
| 观测项 | 结果 | 依据 | 对你的影响 |
|---|---|---|---|
PyPI 包名 pycryptobot | 返回 404，不存在 | PyPI JSON API 探测 | pip install pycryptobot 会直接失败，不会装到任何东西 |
PyPI 包名 pycryptobot-api | 返回 404 | 同上 | —— |
PyPI 包名 pycryptobotlib | 返回 404 | 同上 | —— |
PyPI 包名 py-crypto-bot | 返回 404 | 同上 | —— |
| 仓库打包元数据 | 根目录没有 setup.py、没有 pyproject.toml、也没有 requires_python 声明 | 仓库文件清单 | 项目没有「可上传的发行物」，这不是遗漏安装说明，而是它本来就不走包管理器 |
| 官方实际分发形态 | 源码（git 标签 8.2.0–8.2.4）+ 容器镜像 | GitHub Tags API + docker-compose.yaml | 你的安装动作只能是 clone 或 pull 镜像 |
| 与「有 PyPI 包的项目」对比 | 那类项目一条命令装完；本项目要先取源码、再装依赖、再准备配置 | —— | 选型时要把这段额外成本算进去 |
四种落地方式的前置条件差在哪？
「能跑起来」和「能长期稳定地跑」是两件事。下表按前置条件与运维成本排序，最后两行是仓库里已提供说明文档的两条常驻路径。
| 方式 | 前置条件 | 适合谁 | 注意点 |
|---|---|---|---|
git clone + pip install -r requirements.txt | 本机有 Python 3.11 与可用的 C 编译工具链 | 想改源码、加自定义策略、做二次开发的人 | 三个钉子依赖没有 cp311 轮子，必须现场编译，见下方依赖表 |
官方容器镜像 ghcr.io/whittlem/pycryptobot/pycryptobot:latest | 装好 Docker 即可 | 只想尽快跑起来、不想碰依赖的人 | 镜像里依赖已编译好；注意 :latest 是浮动标签，版本需自己记录 |
docker-compose.yaml | Docker Compose | 单机跑一个到多个币对 | 挂载 config.json、pycryptobot.log、graphs/ 三个路径；重启策略是 condition: on-failure |
Helm chart（chart/ 目录） | 可用的 Kubernetes 集群与 Helm | 已经在用集群管理服务的团队 | 模板里含 deployment / secret / configmap / serviceaccount，说明作者考虑过把密钥放进 Secret 管理 |
| systemd 常驻服务 | Linux 主机与 systemd | 想用系统级进程守护、不引入容器的场景 | 仓库 docs/ 下有专门的 systemd 配置文档，按它的写法做比自制脚本稳 |
| 单独跑 Telegram 机器人进程 | 已有一份能运行的配置 | 需要手机端远程查看与控制 | compose 文件里这段是注释状态的示例块，entrypoint 改成 telegram_bot.py，需要自己取消注释 |
| 单独跑 Web Portal 进程 | 同上级，另需映射端口 | 想在浏览器里看状态 | 同样是注释块，映射端口 5000:5000；不要把它暴露到公网 |
为什么容器路线更省事
不是因为容器更先进，而是因为官方镜像已经把编译这一步做完了。你在本机 clone 之后要自己面对那份 2020–2023 年的依赖钉子；镜像里已经是一个构建成功的产物。代价是镜像标签浮动、你对内部依赖版本的控制力更弱。
为什么多币对要考虑目录隔离
compose 文件里给出的模板是「一个币对一个服务块」，每个块挂载自己的 config.json 与日志文件。如果你的计划是同一账户跑多个币对，先把这份目录结构定下来，否则排查时很难分清哪个进程写了哪条日志。
为什么别把控制面暴露到公网
Telegram 机器人与 Web Portal 都具备操作账户的能力（买入、卖出、启停）。它们的配置项里有授权用的用户 ID 与令牌，一旦端口开放到公网，等于把下单入口挂在互联网上。部署时优先考虑只在内网或经隧道访问。
Dockerfile 里有哪八个细节值得知道？
这一节不需要你改任何东西，但它解释了「为什么容器路线更稳」，也解释了「为什么裸机会卡住」。逐条对照你自己环境里的条件。
| 细节 | 具体做法 | 为什么重要 | 你要注意什么 |
|---|---|---|---|
| 两阶段构建 | 先用编译镜像装依赖，再把成品复制进运行镜像 | 编译器与构建缓存不会留在最终镜像里，体积更小 | 你自己做镜像时不要省掉这一步 |
| 基础镜像版本 | 两个阶段都用 python:3.11.4-slim-bullseye | 这是官方验证过的 Python 版本组合 | 用别的 Python 版本会改变依赖轮子是否可用的判断 |
| 编译工具链 | 编译阶段安装 build-essential | 那三个没有 cp311 轮子的依赖会在这里被现场编译 | 这就是裸机失败、容器成功的关键差异 |
| 运行期系统库 | 运行阶段装 libatlas3-base、libfreetype6、libjpeg62-turbo、libopenjp2-7、libtiff5、libxcb1 | 绘图与数值库在运行时需要这些共享库 | 自己精简镜像时删掉它们会导致出图或数值计算报错 |
| 额外索引源 | 构建时设置 extra-index-url 指向 piwheels | 在 ARM 设备上能拿到预编译包，明显减少编译时间 | 说明作者考虑过树莓派一类低功耗设备上的部署 |
| 非 root 运行 | 建立 UID/GID 都为 1000 的 pycryptobot 用户并 USER pycryptobot | 容器内进程不再拥有 root 权限 | 挂载宿主机目录时要确认该 UID 有读写权限，否则日志写不进去 |
| 绘图配置目录 | 设置 MPLCONFIGDIR=/app/.config/matplotlib 并预先建好目录 | 非 root 用户没有可写的 home，绘图库初始化会失败 | 这类报错看起来与交易无关，但会直接中断进程 |
| 启动命令 | ENTRYPOINT ["python3", "-u", "pycryptobot.py"] | -u 关闭输出缓冲，日志实时可见 | 你要跑别的入口脚本，需要覆盖 entrypoint 而不是追加参数 |
依赖钉子清单是什么？编译风险在哪
requirements.txt 里的版本横跨 2020 到 2023 年。判断「能不能装上」的关键不是版本新不新，而是这个版本有没有为你所用的 Python 版本预编译好的轮子。下表逐个核对了轮子覆盖范围。
| 依赖（钉子版本） | PyPI 上传日期 | 是否有 cp311 轮子 | 结论与注意点 |
|---|---|---|---|
pandas==1.5.1 | 2022-10-19 | 有（该版本共 26 个 wheel，含 cp311） | 可直接安装，是这份清单里少见的现代组合 |
matplotlib==3.3.3 | 2020-11-12 | 无（标签只到 cp39） | Python 3.11 下必须本地编译；这类老版本在较新的编译链上失败率较高 |
pyyaml==5.3.1 | 2020-11-19 | 无（标签只到 cp39） | 同样需要编译；YAML 解析是配置读取的必经路径，装不上就直接跑不起来 |
websockets==9.1 | 2021-05-27 | 无（标签只到 cp39） | 需要编译；只在启用 websocket 实时行情时才会真正用到 |
requests==2.31.0 | 2023-05-22 | 纯 Python 通用包 | 可直接安装，无编译环节 |
websocket-client==0.59.0 | 2021-05-05 | 纯 Python 通用包 | 可直接安装；版本较老，注意与上一个包并存时的行为差异 |
python-telegram-bot==13.7 | 2021-07-01 | 纯 Python 通用包 | 可直接安装；只在你使用 Telegram 控制面时才会加载 |
responses==0.13.3 / mock==4.0.3 | 2021-04-27 / 2020-12-10 | 纯 Python 通用包 | 测试用依赖，生产环境可以不放 |
| 另一类依赖 | 状态 | 影响 | 你要注意什么 |
|---|---|---|---|
pandas-ta、numpy、flask、tradingview-ta、bottleneck | 写在 requirements 里但未钉版本 | 每次安装解析到的版本可能不同，行为随时间漂移 | 要复现别人的结果，必须自己 pip freeze 存档 |
dash、dash-daq、dash-bootstrap-components | 未钉版本 | Web GUI 与 Dash 生态耦合紧密，大版本升级可能打断界面 | 只在用 Web GUI 时需要；不用可以不管 |
rich、regex、codespell | 未钉版本 | rich 承担终端彩色输出；codespell 是开发期拼写检查 | 开发期依赖，生产环境非必需 |
从零到能启动有哪六步？为什么第一步不要开 live
下面每一步都给出要执行的命令、它在做什么，以及你应该看到什么。任何一步的预期输出对不上，先停下核对，不要继续往下走——尤其是最后两步。
取到代码：clone 或用镜像
命令：
git clone https://github.com/whittlem/pycryptobot.git，或docker pull ghcr.io/whittlem/pycryptobot/pycryptobot:latest。
说明：这一步之后你就已经处在「2024-03 主线」这个版本上了，版本状态见版本与分支现状。
预期输出：目录里能看到pycryptobot.py、config.json.sample、requirements.txt、Dockerfile这几个文件。生成配置：从样本复制，不要手写
命令：复制
config.json.sample为config.json（进阶项再参考config.json.advanced.sample）。
说明：样本里已经包含各交易所的api_url与约 30 个开关，从它改起比从空文件写起少踩很多键名错误。
预期输出：config.json里能看到binance/coinbase/coinbasepro/kucoin四个区块与一个telegram区块。装依赖：容器路线跳过本步
命令：容器路线
docker build -t pycryptobot .；裸机路线python -m pip install -r requirements.txt。
说明：裸机路线会现场编译缺少轮子的那几个依赖，需要本机有 C 编译工具链。
预期输出：容器路线构建成功；裸机路线安装无报错。若在这一步失败，先怀疑编译工具链而不是代码。第一次运行：确认
live是 0命令：容器路线
docker run --rm -v "$PWD/config.json:/app/config.json" pycryptobot；裸机路线python3 pycryptobot.py。
说明：样本配置里live默认为0，也就是不下真实订单。这一步的目的是看它能连上行情、能算出指标，而不是看它赚钱。
预期输出：日志里出现当前价格、指标状态与「等待 / 买入 / 卖出」判断，且没有真实下单记录。观察若干周期，确认信号会变
命令：保持上一步运行，观察日志随周期推进的变化；也可临时开启
graphs生成图表辅助判断。
说明：如果连续多个周期指标都不变化，先查配置里的granularity是否符合你的预期，再查数据是否取到。
预期输出：日志中的指标值与判断随新 K 线出现而变化。接上通知，再决定是否上实盘
命令：按通知与控制面配置 Telegram 或 Web 界面，并单独一个进程启动它。
说明：先用只读监控的方式观察一段时间，再考虑开live。
预期输出：手机或浏览器能看到机器人状态；此时账户仍然没有被下单。
live=0。上线前要逐项核对的内容见实盘运维与安全。关于安装与运行方式的高频问题
回答依据仓库文件与 PyPI 元数据核查；涉及你本机环境的判断需要自行验证一次。
没有 PyPI 包，那我到底该怎么装？
两条路。第一条是 git clone 仓库后执行 python -m pip install -r requirements.txt，这条路的代价是要在本机编译三个没有 cp311 轮子的依赖（matplotlib==3.3.3、pyyaml==5.3.1、websockets==9.1）。第二条是直接用官方容器镜像，镜像里依赖已经编译好。如果你只是想把它跑起来，第二条路的前置条件更少。
我在 Windows 上，没有 C 编译器怎么办？
最直接的办法是走容器路线，绕开本机编译。如果必须在 Windows 上裸机跑，你需要自己准备能编译 C 扩展的工具链，并且要接受那份 2020–2023 年的依赖钉子在新工具链上可能编译失败。本站没有在 Windows 上实机验证过这条路，所以不给具体的安装步骤建议——请以你实际执行的结果为准。
官方镜像可以直接用于长期运行吗？
镜像本身是官方发布物，可以用。但要注意两件事：一是 docker-compose.yaml 里引用的标签是 :latest，属于浮动标签，版本会随上游变化，长期运行建议把用到的具体镜像摘要记录下来；二是镜像不能替你处理配置与密钥，config.json 和密钥文件都是你要自己挂载进去的。
依赖版本这么老，会不会有问题？
要分两类看。第一类是被钉死的版本（如 matplotlib==3.3.3），风险主要出现在安装阶段——缺少对应 Python 版本的预编译轮子时就要现场编译。第二类是没钉版本的包（如 pandas-ta、numpy、dash 系列），风险出现在运行阶段——不同时间安装会解析到不同版本，行为可能漂移。要复现结果就必须自己 pip freeze 存档。
需要装 talib 吗？
不需要，它是可选的。仓库的 CHANGELOG 里说明 talib 需要额外的系统级安装，因此没有放进任何 requirements 文件，属于完全可选项；如果你确实装好了，它会被自动加载。同一份记录里还提到另一个文件 requirements-advanced.txt 是给需要 pandas-ta 的场景用的。既然默认清单已经包含 pandas-ta，多数人不需要额外处理这一项。
为什么配置文件有两个样本？
config.json.sample 是基础样本，config.json.advanced.sample 在里面额外加入了一批进阶开关，例如动态追踪止损相关的一整组参数、preventloss 系列、以及启用自定义策略与 pandas-ta 的开关。建议的用法是先跑通基础样本，确认信号行为符合预期后，再逐一加入进阶项并记录每次改动。配置参考页把两组开关按功能分了类。
本站把这些结论验证到了什么程度？
只到「读源码与读元数据」这一层。具体来说：PyPI 的 404 与轮子覆盖是接口探测结果；Dockerfile、docker-compose.yaml、requirements.txt 的内容是文件原文；章节目录结构来自仓库文件清单。本站没有实机执行完整安装，也没有跑过机器人、没有连接过任何交易所账户、没有下过任何订单。请把这一页当作安装前的风险清单，而不是安装手册。