OctoBot 项目研究站 · 安装与运行
OctoBot 安装与运行：四条官方路径怎么选
官方给了四条路：下载可执行文件（CI 自动构建 Windows/macOS/Linux/树莓派版本）、用一行 docker run 起容器、按官方指南从 Python 源码安装，或者直接在云端（DigitalOcean 一键部署 / octobot.cloud）跑。它们的前置条件差别很大：源码路线要求 Python 3.13 与 Pants 构建环境，Docker 路线则把依赖都封在镜像里。下面把每条路的前提、命令与自检方式列清。
- 一句话结论
- 四条官方安装路径：可执行文件省事，Docker 可控性更好，源码与云端各有前提。
- 适合谁
- 愿意按清单逐步部署、能看日志定位问题的人
- 不适合谁
- 希望一键装完后完全不用维护的人
- 最后核验
- 2026-10-12（官方仓库与文档口径）
- 对应版本
- 3.0.0-beta3（2026-10-08）／稳定线 2.1.1
- 实测状态
- 未在本机运行 OctoBot：本站没有运行环境与交易所凭据，内容为官方仓库与文档核对 + 作者分析，不含本站实测数据
OctoBot 的四种安装方式怎么选：横向对照
先按「你愿意付出多少运维成本」来选。
| 路径 | 适合谁 | 前置条件 | 更新方式 | 注意点 |
|---|---|---|---|---|
| 可执行文件 | 只想尽快跑起来、不打算改代码 | 操作系统在官方构建覆盖范围内（Windows/macOS/Linux/树莓派） | 重新下载 Releases 里的新版本 | README 称这是最容易的安装方式；打包配置在 bin/start.spec（PyInstaller） |
| Docker | 有服务器/群晖/NAS，想要可复现环境 | 已装 Docker；规划好端口与卷路径 | 拉新镜像；compose 可配 watchtower 自动更新 | 端口与卷必须按下面表格规划，否则数据会落在容器里 |
| Python 源码 | 要读代码、改策略、做二次开发 | Python 3.13、Pants 2.30.0、正确的 PYTHONPATH | 拉取代码后重装/重启 | README 指向官方 Python+Git 安装指南；解释器约束是 ==3.13.* |
| 云端 | 不想管机器、想长期在线上跑 | 云账号（如 DigitalOcean）或官方云服务订阅 | 由平台/镜像更新机制决定 | 官方云 octobot.cloud 与开源版本是两种形态，条款与数据归属不同 |
| 自建硬件下限 | 树莓派/低配 VPS 用户 | README 给出最低要求：CPU 1 核 1GHz、内存 250MB、磁盘 1GB | — | 这是「能不能启动」的下限，不代表跑多策略时够用 |
用 Docker 跑 OctoBot 要配哪些端口和卷
这一节是四条路里细节最多的，也是最容易配错的。
| 配置项 | Dockerfile / compose 中的值 | 用途 | 配错的后果 |
|---|---|---|---|
| 端口 8000 | EXPOSE 8000（注释：Node API / OctoBot node mode） | node 模式的接口端口 | 不映射则外部界面连不上 node |
| 端口 5001-5010 | EXPOSE 5001-5010（独立 Web 界面 + 最多 10 个子进程界面） | 手动实例的 Web 界面 | 多开的实例界面访问不到 |
| 卷 user | VOLUME /octobot/user | 用户配置与数据 | 不挂卷则重建容器会丢配置 |
| 卷 tentacles | VOLUME /octobot/tentacles | 已安装的插件 | 不挂卷则扩展需要重装 |
| 卷 logs | VOLUME /octobot/logs | 运行日志 | 排障时无处可查 |
| 卷 backtesting | VOLUME /octobot/backtesting | 回测数据与结果 | 回测数据随容器删除而消失 |
| 健康检查 | curl -sS http://127.0.0.1:5001，间隔 15s / 超时 10s / 重试 5 次 | 判断容器是否就绪 | 健康检查不过说明 Web 界面没起来 |
| 自动更新（可选） | compose 里可加 containrrr/watchtower（--cleanup --include-restarting） | 自动拉取新镜像并重启 | 自动更新意味着版本变化无人确认，实盘环境要谨慎 |
从源码安装 OctoBot 要对齐哪些前提：四个要点
这条路的坑都写在 CLAUDE.md 里，逐条对齐能省大量时间。
Python 版本必须是 3.13
setup.py的REQUIRES_PYTHON是>=3.13，分类器只列 3.13；pants.toml的解释器约束是==3.13.*。官方特别提醒：别写成==3.13，那只会匹配 3.13.0。预期：python3.13 -m venv .venv能正常创建虚拟环境。装 Pants（不随仓库附带）
用
scie-pants启动器安装一次，首次运行会引导下载pants.toml里指定的 2.30.0；pants --version打印 2.30.0 即完成。若内网取不到 pex，官方给出临时把pex-cli.url_template指向本地文件的临时方案（不要提交）。装依赖并理解「没有 lockfile」
Pants 配置里
enable_resolves = false，仓库不提交 lock 文件，每次直接按python_requirement解析。要本地调试可按官方示例创建 venv 并pip install -r requirements.txt -r full_requirements.txt。PYTHONPATH 必须写全且用绝对路径
官方给出的路径清单包含根目录与各 packages 子目录：不装 tentacles 时 15 项、装完后 16 项。原因是构建子进程会从 tentacle 子目录里运行，相对路径会解析失败。
setuptools 被钉在 79.0.1（官方注释：>=80 会破坏 easy_install），aiodns 钉在 3.1.1（官方注释：升到 3.2.0 不兼容且会导致 CI 失败）。改依赖前先读这两行注释。装完怎么确认它真的起来了
按你选的路径核对对应的几个信号。
| 现象 | 说明 | 处理方向 | 注意点 |
|---|---|---|---|
| Web 界面能打开（默认 5001） | 手动实例就绪 | 容器路线可用 docker ps 的 health 状态交叉确认 | Docker 健康检查就是 curl 这个端口 |
| node 模式能连上（8000） | 3.0 默认形态可用 | 确认端口映射与新界面访问方式 | beta 阶段功能可能不完整 |
| 界面里能看到策略模式 | tentacles 已加载 | 源码路线检查是否跑过 tentacles install | 见 Tentacles 页 |
| 日志有输出且无导入错误 | 依赖装全了 | 核对 requirements 与 PYTHONPATH | Docker 路线把 logs 卷挂出来才好查 |
| 数据目录出现文件 | user/ 等目录被写入 | 确认卷映射正确、有写权限 | 权限不足是容器部署的高频问题 |
| 能连上交易所（只读） | 凭据与网络可达 | 先用只读 Key 验证 | 本站未做任何连接实测 |
| 版本 / 资产 | 本项目采集时的官方状态 | 对安装的影响 | 核验方式 |
|---|---|---|---|
| 最新 Release | 3.0.0-beta3（2026-10-08），官方标注仍在开发中、可能存在缺陷或未完成功能 | 默认以 node 模式运行；beta 期间界面与配置字段可能变动 | 打开官方 Releases 页面确认最新 tag 与资产列表 |
| 稳定版 | 2.1.1（2026-03-30） | 经典 manual 流程与内置回测在此线可用；不包含 3.0 新界面 | 以 Releases 中非 beta 标记的版本为准 |
| Docker 镜像 | 官方镜像 drakkarsoftware/octobot，README 示例使用 :stable 标签构建参数指定 tentacles 版本 | 拉取新镜像才更新；配了 watchtower 会自动重启容器 | 用 docker images 与容器内日志确认实际版本 |
| 可执行文件资产 | CI 自动构建 Windows / macOS / Linux / Raspberry Pi 版本（README 表述） | 各平台资产随 tag 发布；某个平台缺失时只能选其他路径 | 在 Releases 的 Assets 列表核对平台与文件名 |
| Tentacles 版本 | 独立仓库按分支/tag 提供，Docker 构建用 TENTACLES_URL_TAG 指定 | 策略模式与交易所连接器的可用范围随该版本变化 | 源码路线跑 tentacles install 后检查运行时目录 |
| 更新时间 | 本表采集于 2026-09-15，官方后续发布未反映 | 不要按旧版本号下载资产 | 以 官方 Releases 与官方指南为准 |
setup.py、requirements.txt、Dockerfile、docker-compose.yml 与 CLAUDE.md，未做实测。实际版本请以官方为准。OctoBot 起不来或不动了：按现象定位的排查顺序
官方文档不会列出全部故障。下表按「现象 → 先查什么 → 再查什么 → 证据在哪」组织，是排查路径而非已复现结论。
| 现象 | 先查什么 | 再查什么 | 证据/日志位置 | 处理方向 | 可以公开提供的信息 |
|---|---|---|---|---|---|
| 程序启动即退出 | 看终端或容器日志的末段报错 | 核对 Python 版本与依赖是否满足要求 | 终端输出、容器日志 | 按报错补齐依赖，或改用 Docker 路线规避环境问题 | 报错类型与版本号（贴出前先删掉凭据） |
| 浏览器打不开界面 | 确认进程或容器是否还在运行 | 检查端口映射与主机防火墙 | 端口占用情况、容器端口映射 | 修正端口映射或放行本机访问 | 端口号与浏览器报错码 |
| 本机地址无响应 | 确认访问的是本机还是远程主机 | 远程访问改走隧道或反向代理 | 浏览器错误码 | 不要为了省事把端口直接开到公网 | 部署形态（本机 / 云主机） |
| Docker 容器反复重启 | 查看容器退出码与日志末段 | 检查卷权限与磁盘剩余空间 | 容器日志、卷挂载路径 | 修正卷权限或清理磁盘空间 | 退出码与卷配置（不含凭据文件） |
| node 显示 unreachable | 确认 node 服务是否在运行 | 核对 node 与界面的版本是否匹配 | node 侧日志 | 重启 node 并统一版本 | 版本号与报错文本 |
| 操作一直处于 queued | 确认任务队列是否积压、进程是否卡住 | 检查是否被交易所限频 | 任务队列与请求日志 | 降低并发与请求频率后重试 | 队列长度与操作类型 |
| 交易所 API 连接失败 | 核对 Key 权限与 IP 白名单 | 核对系统时间是否同步（签名对时间敏感） | 接口返回的错误码 | 按错误码修正权限、白名单或时间 | 错误码（不要贴 Key 或 secret） |
| 策略不下单 | 确认策略已启动、交易对在监控列表内 | 检查是否满足触发条件与最小下单额 | 策略日志、下单尝试记录 | 核对参数、资金与交易对门槛 | 参数与交易对名称 |
| 订单被交易所拒绝 | 看返回的错误码与文字 | 检查数量精度、余额、杠杆与仓位模式 | 订单请求与响应记录 | 按交易所规则修正下单参数 | 错误码与交易对 |
| 余额与界面不一致 | 区分可用、冻结与未结算金额 | 检查是否有在途订单 | 界面余额与交易所后台对照 | 以交易所后台为基准排查 | 差异类型（不公开具体金额） |
| 更新后配置或数据丢失 | 确认数据卷与备份是否存在 | 检查是否更换了卷或目录路径 | 卷配置与备份文件 | 先恢复备份，再把卷路径固定下来 | 卷配置（不含密钥文件） |
| 回测没有数据 | 确认是否在手动实例中运行 | 检查回测数据卷与数据来源 | 回测目录与相关日志 | 补齐历史数据后再运行 | 实例形态与数据区间 |
OctoBot 的备份、升级、降级与远程访问
安装完成只是开始：表格把长期运行最容易踩的维护动作集中列出。
| 维护需求 | 官方支持的方式 | 做法要点 | 适用场景 | 注意点 |
|---|---|---|---|---|
| 配置与数据备份 | 备份数据目录或 Docker 卷 | 升级前先备份数据目录与回测数据卷 | 升级、迁移 | 备份里含凭据文件，要加密保存 |
| 升级到新版本 | 拉取新镜像或安装新资产包 | 先读官方 Release 说明再升级 | 跟随官方修复与新功能 | beta 期间配置字段与界面可能变化 |
| 降级或回滚 | 切回旧版本镜像或旧资产包 | 回滚前保留当前数据目录副本 | 新版本出现问题时 | 数据格式可能不向后兼容，回滚不等于无损 |
| 开机自动启动 | 容器的重启策略或系统服务 | 容器加重启策略；源码部署用系统服务托管 | 云主机长期运行 | 自启动后要确认策略确实在跑，而不是只有进程在 |
| 远程访问 | 反向代理或隧道类工具 | 优先用隧道，不把端口直接暴露到公网 | 外出需要查看状态 | 公开端口会被持续扫描 |
| 国内网络连接 | 镜像加速源与备用 DNS | 拉取镜像慢时配置加速源 | 国内主机部署 | 加速源可用性会变化，失败时要能换回默认源 |
| 日志与磁盘管理 | 定期清理日志与历史数据 | 给日志设上限，监控磁盘占用 | 长期运行 | 磁盘占满会导致进程异常退出，症状常被误判为程序崩溃 |
安装与运行常见问题
能一键部署吗？
官方提供了 DigitalOcean Marketplace 的一键部署入口，Docker 命令也只有一行。但「一键」只覆盖启动这一步：端口、数据卷、交易所凭据、策略参数仍需自己配置，因此本站不使用「一键部署/开箱即用」的表述。
Windows 能安装 OctoBot 吗？如何确认安装成功？
README 说明 Releases 自动构建 Windows 可执行文件；建议从官方 OctoBot Releases 进入对应版本，按官方安装指南下载并运行，不从第三方网盘取包。首次启动后先确认进程与日志正常，再按实际运行形态访问相应界面：manual Web 默认 5001，node API 在 Dockerfile 暴露 8000；新界面连接方式以 beta getting-started 指南为准。本站没有 Windows 实机验证，出现 SmartScreen、权限或端口提示时先核对官方签名/发行说明，不要为了运行而关闭安全保护。
OctoBot 安装后界面打不开或启动失败，先查什么？
先从实例形态核对访问入口：manual Web 默认 5001，Dockerfile 暴露 node API 8000；不要把 API 端口误当浏览器界面。Docker 用户先查容器健康状态、端口映射和 logs 卷；源码用户优先查 Python 3.13、Pants 2.30.0、依赖安装和绝对路径 PYTHONPATH；可执行文件用户查看当前 Release 的平台资产及系统提示。若错误涉及 API Key，先撤销并重新创建最小权限 Key，不要把密钥贴到 issue。README 未提供完整错误码对照，仍无法启动时附脱敏日志并对照官方文档/仓库 Issue。
升级 OctoBot 前如何避免覆盖配置？
先备份 user/、tentacles/、logs/ 和 Docker 的 /octobot/backtesting 数据卷；记录当前 release 与镜像 tag，并按官方迁移说明升级。实盘实例慎用无人审核的 watchtower 自动更新。README 没有承诺所有跨主版本配置都能原样迁移，因此升级后先在隔离/模拟环境检查界面、策略和连接状态，再决定是否恢复运行。
如何卸载 OctoBot 并保留或删除配置？
先停止对应进程或容器，并确认是否要保留 user/、tentacles/、logs/ 与 backtesting 卷；这些目录可能包含配置、凭据或历史结果，删除前先备份并人工确认。可执行文件可按操作系统正常移除程序文件；Docker 只移除容器并不必然删除挂载卷。本站未验证各平台具体卸载器，按官方安装路径与当前容器管理命令操作。
没有服务器，能用自己的电脑吗？
可以。README 明确说可免费运行在你自己的电脑、服务器或树莓派上，并给出最低硬件要求：1 核 1GHz、250MB 内存、1GB 磁盘。但要让机器人持续运行，机器得长期开着。
Docker 版要自己装 tentacles 吗？
通常不用：镜像构建时会按 TENTACLES_URL_TAG 取指定版本的 tentacles，并把 /octobot/tentacles 挂为数据卷。源码路线才需要手动执行安装命令。
为什么源码路线这么麻烦？
因为它是为「要改代码/做贡献」的人准备的：需要 Python 3.13、Pants 2.30.0 构建系统、以及包含 15–16 个路径的 PYTHONPATH。只想用不想改的话，可执行文件或 Docker 更合适。
watchtower 自动更新能一直开着吗？
compose 示例里确实带了 watchtower，它会在有新镜像时自动更新并重启容器。但自动升级意味着版本切换没有人工确认环节——对跑实盘的实例，这本身就是一个风险选择，建议自行评估。
装完就能开始交易吗？
不能直接实盘。官方建议流程是先回测、再模拟盘（paper trading），确认行为符合预期后才考虑接入真实资金；同时 README 的免责声明明确要求自负盈亏。具体见回测与模拟盘页。