安装与环境准备

官方强烈建议使用 Docker 安装 Freqtrade，因为 Docker 镜像已预配置好所有依赖（包括 Python、TA-Lib、系统库和环境），无需手动处理复杂的编译和依赖冲突问题，极大简化了安装流程，尤其适合 Windows、ARM64（如 M1 Mac）和 Raspberry Pi 等平台。Docker 提供了环境隔离，确保你的系统不会被 Freqtrade 的依赖污染，同时便于升级、备份和迁移。此外，Docker 容器可轻松部署在云服务器或本地机器上，支持一键启动，是生产环境和评估阶段的首选方式。对于初学者，使用 Docker 可以快速验证 Freqtrade 是否符合需求，而无需耗费大量时间调试安装问题。

要运行 Freqtrade 的 Docker 版本，首先需要为您的操作系统安装 Docker 或 Docker Desktop。官方提供了针对不同平台的安装指南：

• 对于 macOS，请访问 Docker for Mac 安装页面。
• 对于 Windows，请访问 Docker for Windows 安装页面。
• 对于 Linux，请访问 Docker 安装页面。

安装完成后，请确保 Docker 服务已启动，并且当前用户有权限执行 docker 命令。特别注意，如果您在 Windows 上刚安装 Docker，建议重启系统以避免网络连接问题。此外，Freqtrade 文档默认使用 Docker Desktop 或 docker-compose 插件，如果使用的是独立的 docker-compose，需将所有命令中的 docker compose 替换为 docker-compose（例如 docker-compose up -d）。

Freqtrade 提供了官方的 Docker 镜像，托管在 Docker Hub 上，镜像地址为 freqtradeorg/freqtrade。同时，官方还提供了一个预配置的 docker-compose.yml 文件，您可以在 GitHub 仓库的稳定分支中获取：https://github.com/freqtrade/freqtrade/blob/stable/docker-compose.yml。

该文件定义了运行 Freqtrade 所需的服务配置，包括容器映射、卷挂载和命令参数，是启动和管理 Freqtrade 的推荐方式。您应将此文件下载到本地工作目录中，后续所有操作都将在该目录下执行。

要使用 Docker 快速启动 Freqtrade，请按以下步骤操作：

1. 创建一个新目录，例如 ft_userdata，并进入该目录：

   mkdir ft_userdata
   cd ft_userdata/
   

2. 下载官方的 docker-compose.yml 文件：

   curl https://raw.githubusercontent.com/freqtrade/freqtrade/stable/docker-compose.yml -o docker-compose.yml
   

3. 拉取最新的 Freqtrade Docker 镜像：

   docker compose pull
   

4. 创建用户数据目录结构：

   docker compose run --rm freqtrade create-userdir --userdir user_data
   

5. 交互式生成配置文件 user_data/config.json：

   docker compose run --rm freqtrade new-config --config user_data/config.json
   

完成以上步骤后，您将拥有一个完整的用户数据目录和配置文件，可在此基础上启动交易机器人。注意：--rm 参数会在命令执行后自动删除临时容器，避免残留。

安装 Freqtrade 前，系统必须满足以下基本要求：首先，必须安装 Python 3.10 或更高版本，以及对应的 pip 包管理工具；其次，需要安装 git 用于克隆代码仓库；此外，必须安装 Python 开发头文件（如 python3-dev 或 python3-devel），这些文件是编译某些依赖库（如 TA-Lib）所必需的。同时，系统时钟必须保持准确，并定期与 NTP 服务器同步，以避免与交易所通信时出现时间偏差问题。对于 ARM64 架构的设备（如 Apple M1 芯片的 Mac 或 Oracle VM），官方不推荐原生安装，建议使用 Docker 镜像。

TA-Lib 是 Freqtrade 用于技术分析的核心依赖库，安装方式有两种：一是使用 Freqtrade 提供的脚本自动安装，运行命令 sudo ./build_helpers/install_ta-lib.sh，该脚本会使用仓库内附带的 ta-lib-0.4.0-src.tar.gz 源码包进行编译安装；二是手动安装，需先下载源码包 wget http://prdownloads.sourceforge.net/ta-lib/ta-lib-0.4.0-src.tar.gz，解压后进入目录，修改 src/ta_func/ta_utility.h 文件中的浮点精度常量以避免编译错误，然后依次执行 ./configure --prefix=/usr/local、make 和 sudo make install。在 Debian/Ubuntu 系统上，安装完成后建议运行 sudo ldconfig 更新动态链接库缓存。安装完成后，TA-Lib 将被系统识别，供 Python 包调用。

虚拟环境（virtualenv）是一个独立的 Python 环境，它允许你在同一台机器上为不同项目创建隔离的依赖包集合，避免不同项目之间的库版本冲突。安装 Freqtrade 时推荐使用虚拟环境，是因为它会安装大量第三方 Python 包（如 pandas、numpy、ccxt 等），如果直接安装在系统全局环境中，可能会影响其他 Python 应用。创建虚拟环境的命令是 python3 -m venv .venv，激活后使用 source .venv/bin/activate，此时所有 pip 安装的包都会被限制在这个环境中，确保 Freqtrade 的依赖不会干扰系统其他部分。

./setup.sh 是 Freqtrade 提供的自动化安装脚本，适用于 Linux 和 macOS 系统。使用前需先克隆 Freqtrade 仓库并进入目录。运行 ./setup.sh -i（或 --install）会自动完成以下任务：安装系统依赖（如 python3-pip、python3-venv、git、curl 等）、安装 TA-Lib、创建名为 .venv 的虚拟环境、激活环境并安装所有 Python 依赖（requirements.txt 和 -e .）。安装完成后，你只需每次打开新终端时运行 source ./.venv/bin/activate 激活环境，即可直接使用 freqtrade 命令。该脚本还支持其他选项：-u 用于更新代码和依赖，-r 用于重置当前分支并重建虚拟环境。

每次打开新的终端窗口时，必须手动激活 Freqtrade 的虚拟环境，否则系统无法识别 freqtrade 命令。激活命令为 source ./.venv/bin/activate（Linux/macOS）。激活后，终端提示符前会显示 (.venv)，表示当前处于虚拟环境中。在此环境下，所有 freqtrade 命令（如 freqtrade trade）才能正常运行。若未激活就运行命令，会出现 freqtrade: command not found 错误。因此，建议将激活命令添加到 shell 配置文件（如 ~/.bashrc 或 ~/.zshrc）中，实现自动激活，或使用 tmux/screen 保持会话持久化。

Freqtrade 要求 Python 版本为 3.10 或更高。安装脚本会自动检查当前 Python 版本，若低于要求会中止安装并提示升级。若系统默认 Python 为 3.9 或更低，需确保已安装 Python 3.10+（如通过 apt、brew 或源码编译），并在执行安装命令时显式使用 python3.10 或 python3.11 等版本号，例如创建虚拟环境时使用 python3.10 -m venv .venv。在 Conda 环境中，创建环境时需指定 python=3.12。若系统有多个 Python 版本，建议使用 pyenv 管理版本，或直接使用 Docker 镜像避免版本冲突。切勿在系统全局环境中降级 Python，以免破坏系统工具。

虽然可以从 PyPI 使用 pip install freqtrade 直接安装 Freqtrade，但官方不推荐此方法。原因是该方式要求用户必须预先正确安装 TA-Lib 库，而 TA-Lib 的编译和配置过程在不同系统上复杂且容易出错，容易导致安装失败。相比之下，使用 GitHub 克隆 + ./setup.sh 或 Docker 的方式会自动处理 TA-Lib 安装，大大降低出错概率。因此，除非你已经熟练掌握 TA-Lib 的跨平台安装，否则应优先选择脚本安装或 Docker 方式，以确保安装流程顺畅可靠。

验证 Freqtrade 是否安装成功，需完成以下步骤：首先，确保已激活虚拟环境（运行 source ./.venv/bin/activate）；其次，运行 freqtrade --help，如果显示帮助信息（包含子命令列表如 trade、new-config、create-userdir 等），说明安装成功；接着，运行 freqtrade create-userdir --userdir user_data 和 freqtrade new-config --config user_data/config.json 创建配置目录和文件；最后，尝试运行 freqtrade trade --config user_data/config.json --strategy SampleStrategy，若输出开始初始化日志但未报错，说明环境配置正确。注意：首次运行建议开启 dry_run: true 模式，避免真实交易。