使用 Docker 运行 Freqtrade

本页介绍如何使用 Docker 运行机器人。它并非开箱即用，你仍需阅读文档并了解如何正确配置。

安装 Docker¶

首先为你的平台下载安装 Docker / Docker Desktop：

• Mac
• Windows
• Linux

要检查 Docker 和 Docker Compose 是否已正确安装，可以根据不同操作系统执行相应命令。以下是各主流操作系统（Linux、macOS、Windows）中的方法：

✅ 通用命令（适用于所有系统）¶

# 检查 Docker 是否已安装及其版本
docker --version

# 检查 Docker 是否正在运行
docker info

# 检查 Docker Compose 是否已安装及其版本（新版本使用 docker compose 而不是 docker-compose）
docker compose version   # 推荐（适用于 Docker 20.10+）
# 或旧版（如果你安装的是旧版 Compose）
docker-compose version

which docker
systemctl status docker  # 检查是否运行中（Ubuntu/CentOS）

docker run hello-world

sudo usermod -aG docker $USER
newgrp docker  # 立即生效，或重启

which docker-compose

docker version
docker compose version

docker version
docker compose version

wsl -l -v

🚨 如果未安装或失败怎么办？¶

• Docker 官方安装指南：https://docs.docker.com/get-docker/
• Compose 安装：https://docs.docker.com/compose/install/

使用 docker 运行 Freqtrade¶

Freqtrade 在 Dockerhub 上提供了官方 Docker 镜像，并有一份docker compose 文件可直接使用。

Docker 快速入门¶

新建一个目录，并将 docker-compose 文件下载到该目录。

mkdir ft_userdata
cd ft_userdata/

# 从仓库下载 docker-compose 文件
curl https://raw.githubusercontent.com/freqtrade/freqtrade/stable/docker-compose.yml -o docker-compose.yml

# 拉取 freqtrade 镜像
docker compose pull

# 创建用户目录结构
docker compose run --rm freqtrade create-userdir --userdir user_data

# 创建配置文件 - 需要交互式回答问题
docker compose run --rm freqtrade new-config --config user_data/config.json

上述命令片段会创建一个名为 ft_userdata 的新目录，下载最新的 compose 文件并拉取 freqtrade 镜像。最后两步会创建带有 user_data 的目录，并根据你的选择（交互式）生成默认配置。

添加自定义策略¶

1. 现在配置文件已生成在 user_data/config.json
2. 将自定义策略复制到 user_data/strategies/ 目录下
3. 在 docker-compose.yml 文件中添加策略类名

默认会运行 SampleStrategy。

完成上述步骤后，你就可以启动机器人进入交易模式（Dry-run 或实盘，取决于你之前的选择）。

docker compose up -d

访问 UI¶

如果你在 new-config 步骤中选择启用了 FreqUI，则可通过 localhost:8080 端口访问 FreqUI。

你可以在浏览器中输入 http://localhost:8080 访问 UI。

监控机器人¶

你可以用 docker compose ps 查看正在运行的实例。

这会显示 freqtrade 服务为 running。如果不是，建议查看日志（见下文）。

Docker compose 日志¶

日志会写入：user_data/logs/freqtrade.log。

你也可以用 docker compose logs -f 查看最新日志。

数据库¶

数据库位于：user_data/tradesv3.sqlite

使用 docker 更新 freqtrade¶

使用 docker 更新 freqtrade 只需运行以下两条命令：

# 下载最新镜像
docker compose pull
# 重启镜像
docker compose up -d

这会先拉取最新镜像，然后用新镜像重启容器。

编辑 docker-compose 文件¶

高级用户可以进一步编辑 docker-compose 文件，包含所有可用选项或参数。

所有 freqtrade 参数都可通过 docker compose run --rm freqtrade <命令> <可选参数> 运行。

示例：用 docker 下载数据¶

从 Binance 下载 ETH/BTC 交易对 1 小时线的 5 天回测数据，数据将存储在主机的 user_data/data/ 目录下。

docker compose run --rm freqtrade download-data \
    --pairs ETH/BTC \
    --exchange binance \
    --days 5 \
    -t 1h

更多数据下载细节请参见数据下载文档。

示例：用 docker 回测¶

在 docker 容器中用 SampleStrategy 和指定历史数据区间(20190801-20191001)、做 5 分钟线的回测：

docker compose run --rm freqtrade backtesting \
    --config user_data/config.json \
    --strategy SampleStrategy \
    --timerange 20190801-20191001 \
    -i 5m

更多内容请参见回测文档。

在 docker 中增加的额外依赖(加入自己的 Python 依赖库)¶

如果你的策略依赖默认镜像未包含的依赖，则需在本地构建镜像。

为此，请创建一个包含额外依赖安装步骤的 Dockerfile（可参考 docker/Dockerfile.custom）。

你还需修改 docker-compose.yml 文件，取消 build 步骤的注释，并重命名镜像以避免命名冲突。

    image: freqtrade_custom
    build:
      context: .
      dockerfile: "./Dockerfile.<你自定义的扩展名>"

然后运行 docker compose build --pull 构建镜像，并用上述命令运行。

docker 下绘图¶

将 freqtrade plot-profit 和 freqtrade plot-dataframe（文档）命令的镜像在 docker-compose.yml 文件中改为 *_plot，即可使用这些命令：

docker compose run --rm freqtrade plot-dataframe \
    --strategy AwesomeStrategy \
    -p BTC/ETH \
    --timerange=20180801-20180805

输出会保存在 user_data/plot 目录下，可用任意现代浏览器打开。

用 docker compose 进行数据分析¶

Freqtrade 提供了一个 docker-compose 文件，可启动 jupyter lab 服务器。

你可以用以下命令启动该服务器：

docker compose -f docker/docker-compose-jupyter.yml up

这会创建一个运行 jupyter lab 的 docker 容器，可通过 https://127.0.0.1:8888/lab 访问。

请使用启动后控制台打印的链接简化登录。

由于该镜像部分在本地构建，建议不时重建镜像以保持 freqtrade（及依赖）为最新。

docker compose -f docker/docker-compose-jupyter.yml build --no-cache

故障排查¶

Windows 下的 Docker¶

• 错误："Timestamp for this request is outside of the recvWindow."

市场 API 请求需要同步时钟，但 docker 容器内的时间会逐渐偏移。

临时解决方法是运行 wsl --shutdown 并重启 docker（Windows 10 会弹窗提示）。

永久解决方案是将容器部署在 Linux 主机，或定期用计划任务重启 wsl。

taskkill /IM "Docker Desktop.exe" /F
wsl --shutdown
start "" "C:\Program Files\Docker\Docker\Docker Desktop.exe"

• 无法连接 API（Windows）

如果你在 Windows 上刚安装 Docker（Desktop），请务必重启系统。否则 Docker 可能会有网络连接问题。

当然也要确保你的设置正确。