OctoBot Docker Compose 部署指南

目标：在一台 Ubuntu 22.04 服务器上，用 Docker Compose 把 OctoBot 2.1.1 完整跑起来：官方发行包拉取、Compose 编排、四目录持久化、启动验证（Web 界面 + API 真实回显）、日常运维与常见排障。本文全部命令与回显均在 Ubuntu 22.04.4 LTS + Docker 29.8.1 + Docker Compose v5.5.1 环境实测通过（2026-10-24）。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（内核 6.8.0-138-generic，x86_64）
• Docker：29.8.1（Docker Compose v5.5.1 独立插件版）
• OctoBot：2.1.1（官方稳定版，发行包 drakkarsoftware/octobot:2.1.1，压缩体积约 241 MB，实查 Docker Hub Registry API，查询日期 2026-10-24）
• OctoBot Web 界面端口：5001（发行包内固定监听端口，启动日志实测 Interface successfully initialized and accessible at ...:5001）
• 数据持久化目录：/opt/octobot/ 下的 user/、tentacles/、logs/、backtesting/（本文实测使用实验目录，读者可按同样结构落在自己的数据盘）
• Compose 项目名：octobot-211-stack（docker-compose.yml 中显式 name: 声明，防止多套环境相互覆盖）

⚠️ 注意：Docker 拉取官方发行包需要能访问 Docker Hub；国内网络不通时，为 Docker 守护进程配置镜像加速或 HTTP 代理后再执行 docker pull。

二、发行包选型说明

官方在 Docker Hub drakkarsoftware/octobot 维护多个标签（实查 2026-10-24，Docker Hub Registry API）：

关键解读：生产环境固定具体版本号 2.1.1（可升级、可回滚、行为可复现）；想跟随官方稳定线又懒得改版本号时用 stable；3.0.0-beta* 与 staging 只建议在测试环境评估 3.0 新特性（Agent 团队等）时使用。

三、前置条件

1. 服务器已安装 Docker（≥ 20.10）与 Docker Compose 插件，验证方式：

docker --version
docker compose version

实测回显：

Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1

2. 服务器可访问 Docker Hub（或已配置加速/代理）；
3. 规划好 Web 界面对外端口：发行包内固定监听 5001，宿主机侧可用任意空闲端口映射（本文用 5001 直映示例，端口被占时改为其他空闲端口即可）；
4. 磁盘预留：发行包约 250 MB，加上首次启动下载的 tentacles 与日志，建议预留 2 GB 以上；
5. 内存建议 2 GB 起（Python 进程 + 行情缓存；实测环境中单个 OctoBot 进程稳定运行内存占用为数百 MB 量级）。

四、部署步骤

4.1 建立部署目录与持久化子目录

本节要做的：为 OctoBot 建立独立部署目录，并创建四个必须持久化的子目录，避免服务升级后配置与数据丢失。

mkdir -p /opt/octobot/{user,tentacles,logs,backtesting}
cd /opt/octobot

四个子目录的用途：

• user/：全局配置 config.json、日志配置、全部 Profile 数据（核心数据，务必持久化）；
• tentacles/：策略/交易所/服务等插件模块的安装产物；
• logs/：运行日志（OctoBot 启动即写入 Saving logs in '/octobot/logs' folder）；
• backtesting/：回测数据文件。

4.2 编写 docker-compose.yml

本节要做的：在 /opt/octobot/ 下创建 Compose 编排文件，显式声明项目名、发行包版本、端口映射与四个持久化目录。

name: octobot-211-stack

services:
  octobot:
    image: drakkarsoftware/octobot:2.1.1
    container_name: octobot-211
    restart: unless-stopped
    ports:
      - "5001:5001"
    volumes:
      - ./user:/octobot/user
      - ./tentacles:/octobot/tentacles
      - ./logs:/octobot/logs
      - ./backtesting:/octobot/backtesting

逐项说明：

• name: octobot-211-stack：Compose 项目名，显式固定后 docker compose 系列命令都作用于本项目，不会误操作其他服务的栈；
• image：固定到具体稳定版本 2.1.1（选型依据见第二章）；
• restart: unless-stopped：服务器重启后自动拉起，人工 stop 后不自动重启；
• ports: "5001:5001"：宿主机 5001 → 发行包内 5001（Web 界面端口）；宿主机侧端口被占用时改左值即可（如 "8136:5001"）；
• volumes：四个目录逐条映射到发行包内对应路径，缺一则对应数据不落盘。

💡 说明：OctoBot 是单进程应用，无数据库、无外部中间件依赖，因此编排文件只有一个 service。多实例隔离部署时（例如模拟盘与实盘各跑一套），复制整个目录结构并把项目名、容器名、宿主机端口三处改开即可。

4.3 拉取发行包并启动

cd /opt/octobot
docker compose up -d

实测回显（首次启动会先创建网络与容器）：

 Network octobot-211-stack_octobot-net Creating
 Network octobot-211-stack_octobot-net Created
 Container octobot-211-compose Creating
 Container octobot-211-compose Created
 Container octobot-211-compose Starting
 Container octobot-211-compose Started

⚠️ 注意：若首次启动后立刻访问 Web 失败，通常是首次启动正在下载安装 tentacles（约 178 个模块，实测耗时约 30 秒）并同步官方 Profile，等待 1~2 分钟再验证即可，判断方法见下节日志。

4.4 查看启动日志确认关键里程碑

docker compose logs --tail 200 octobot

实测关键回显（节选）：

octobot-211-compose  |  2026-10-24 01:23:54,806 INFO     InstallWorker         *** All tentacles from 'https://tentacles.octobot.online/officials/packages/full/base/2.1.1/any_platform.zip' have been successfully processed ***
octobot-211-compose  |  2026-10-24 01:23:56,703 INFO     Configuration        Using Non-Trading profile.
octobot-211-compose  |  2026-10-24 01:23:56,712 INFO     OctoBot              Starting OctoBot with simulated trader on binance[spot] trading BTC/USDT with BlankTradingMode and using bot_id: 5586d237-d70a-4641-8563-a16402ba5ef3
octobot-211-compose  |  2026-10-24 01:23:57,988 INFO     WebService           Interface successfully initialized and accessible at: http://10.89.63.2:5001.

四行日志分别说明：tentacles 全量安装完成（来自官方分发源）、默认使用 Non-Trading Profile、以模拟交易器连接 binance 现货 BTC/USDT（无需任何 API Key）、Web 界面初始化完成。看到最后一行 Interface successfully initialized 即启动成功。

4.5 验证服务可用

本节要做的：从服务器本机与浏览器两个路径验证 OctoBot 已可访问。

命令行验证（API 层）：

curl -s http://127.0.0.1:5001/api/version
curl -s http://127.0.0.1:5001/api/ping
docker compose ps

实测回显：

"OctoBot 2.1.1"
"Running since 2026-10-24 01:23:56."
NAME                  IMAGE                           STATUS                    PORTS
octobot-211-compose   drakkarsoftware/octobot:2.1.1   Up 35 seconds (healthy)   0.0.0.0:5001->5001/tcp, [::]:5001->5001/tcp

浏览器验证：访问 http://<服务器IP>:5001，首次访问会跳转到 /terms 服务条款页，点击同意后进入 Home 仪表盘（实测首次访问 / 返回 302 重定向至 /terms，接受条款后 / 返回 200）。若浏览器无法访问而服务器本机 curl 正常，优先排查云服务器安全组/防火墙是否放行 5001 端口。

⚠️ 注意：Web 界面默认没有登录密码。公网服务器建议：① 用防火墙/安全组限制 5001 端口来源 IP；② 在 Web 界面 Accounts 或配置文件中启用访问密码（user/config.json 的 services.web.require-password 与 services.web.password，详见配置详解篇）；③ 或仅监听内网、通过 SSH 隧道访问。

五、数据持久化说明

OctoBot 的全部状态都在四个挂载目录内，容器的创建/销毁不影响数据：

备份建议：模拟盘/实盘运行期间定期备份 /opt/octobot/user（tar -czf octobot-user-$(date +%F).tar.gz user/ 即可）；升级大版本前必须先备份该目录。

六、环境变量表

官方发行包支持的环境变量（均经实查发行包入口脚本 /octobot/docker-entrypoint.sh、tunnel.sh 与程序源码验证，2026-10-24）：

⚠️ 注意：OCTOBOT_CONFIG 是"每次启动整体覆写 config.json"的语义（入口脚本使用 tee 覆盖写入），仅适合首次初始化场景；已有手工配置的存量环境不要在环境变量里再传它，否则会覆盖掉 Web 界面里做过的修改。

七、配置参数说明

部署完成后的参数体系分三层（字段级详解见配置详解篇）：

1. 全局配置 user/config.json：交易所接入、Web 服务开关、通知渠道、当前激活 Profile（"profile" 字段指向 Profile 目录名）、服务条款确认状态等；
2. Profile 配置 user/profiles/<名称>/profile.json：交易标的、参考市场、风险系数、模拟器初始资金与手续费、真实交易开关（trader.enabled / trader-simulator.enabled）；
3. Tentacle 激活表 user/profiles/<名称>/tentacles_config.json：该 Profile 下启用的指标评估器、策略、交易模式与交易所清单（布尔开关）。

常见调整举例（改完需重启生效，见第八章）：

• 切换策略 Profile：把 config.json 的 "profile" 从 "default" 改为 "daily_trading"（实测重启后日志输出 Using DailyTrading profile. 并以 DailyTradingMode 运行）；
• 开启 Web 访问密码：services.web.require-password: true 并设置 services.web.password；
• 修改模拟器初始资金：Profile 的 trader-simulator.starting-portfolio。

八、常用运维命令

以下命令均在 /opt/octobot 目录内执行（实测环境回显附后）：

docker compose ps                 # 状态与端口
docker compose logs -f octobot    # 实时日志
docker compose restart octobot    # 重启（改配置后生效）
docker compose stop               # 停止
docker compose down               # 停止并删除容器（四个挂载目录数据保留）
docker compose pull               # 拉取新版本发行包（配合修改 image 版本号升级）

升级流程（实测可行的标准路径）：备份 user/ → 修改 docker-compose.yml 中 image 版本号 → docker compose pull → docker compose up -d（Compose 会重建容器，挂载目录数据保留）→ curl http://127.0.0.1:5001/api/version 验证版本号。回滚则把 image 改回旧版本号重复后三步。

九、等价启动方式（不使用 Compose）

与上述 Compose 完全等价的原生启动命令（单行，供排查 Compose 层问题时对照）：

docker run -d --name octobot-211 \
  -p 5001:5001 \
  -v /opt/octobot/user:/octobot/user \
  -v /opt/octobot/tentacles:/octobot/tentacles \
  -v /opt/octobot/logs:/octobot/logs \
  -v /opt/octobot/backtesting:/octobot/backtesting \
  --restart unless-stopped \
  drakkarsoftware/octobot:2.1.1

参数与 Compose 文件一一对应；用此方式启动后，日志与验证命令同第四章（docker logs -f octobot-211）。日常管理更推荐 Compose 方式，升级与回滚只需改一行版本号。

十、常见问题（FAQ）

Q1：启动后访问 5001 无响应？ 按顺序排查：docker compose ps 看容器是否 healthy；docker compose logs --tail 50 octobot 找 Interface successfully initialized 是否出现（首启下载 tentacles 期间约需 1~2 分钟）；本机 curl -s http://127.0.0.1:5001/api/version 若正常而外网不通，则是安全组/防火墙未放行；实测中还遇到过宿主机侧端口被其他服务占用导致启动失败（报错 Bind for 0.0.0.0:8128 failed: port is already allocated），换一个空闲宿主机端口即可。

Q2：首次启动很慢，卡在下载？ 正常现象：首次启动要从 tentacles.octobot.online 下载官方插件包（约 178 个 tentacle）并同步 18 个官方 Profile，实测约 30 秒完成，日志里程碑见第四章；外网受限的服务器需保证容器能访问该域名，否则会反复重试。

Q3：改了 config.json 不生效？ OctoBot 只在启动时装载配置，改文件后必须 docker compose restart octobot。实测验证：把 "profile" 改为 "daily_trading" 并重启后，日志出现 Using DailyTrading profile.。若使用 OCTOBOT_CONFIG 环境变量，注意它每次启动都会覆写 user/config.json（第六章注意项）。

Q4：Web 界面是中文吗？有登录密码吗？ 界面默认英文（官方亦提供法语社区资料）；默认无密码，公网部署务必按第四章注意项加固，或启用 services.web.require-password + services.web.password。

Q5：怎么确认跑的是模拟盘而不是实盘？ 看两处：启动日志 Starting OctoBot with simulated trader on ...；Web 界面导航栏的 "Simulated trading" 标识。默认 Non-Trading Profile 下真实 trader 关闭、模拟器开启，只有显式修改 Profile 的 trader.enabled 并确认后才会产生真实订单。

Q6：升级后想回退版本？ 把 docker-compose.yml 的 image 改回旧版本号（如 2.1.1），docker compose up -d 即可；四个挂载目录的数据结构随版本向下兼容，但跨大版本回退前建议先用第五章方法备份 user/。

十一、参考链接

• 官方 Docker 使用文档：https://www.octobot.cloud/en/guides/octobot-installation/docker-installation
• 官方 GitHub 仓库（含源码入口脚本）：https://github.com/Drakkar-Software/OctoBot
• Docker Hub 发行页：https://hub.docker.com/r/drakkarsoftware/octobot
• 官方 tentacles 分发源：https://tentacles.octobot.online
• 本专栏相关篇目：《OctoBot 2.1.1 介绍与选型指南》、《OctoBot 2.1.1 配置参数详解》、《OctoBot 2.1.1 常用 CLI 命令与工具详解》