Hummingbot logo Hummingbot
登录
2. 环境安装与部署

2.环境安装与部署

安装 Hummingbot 是开启算法交易的第一步。这个过程并不复杂，但涉及多个组件，每个组件都有特定的用途。我们会从最基础的系统要求开始，逐步讲解各种安装方式，直到把整个交易环境搭建起来。

系统要求与前置准备

在动手之前，先确认机器配置是否达标。Hummingbot 对硬件的要求相对亲民，一台普通云服务器就能胜任。

操作系统方面，Linux 是首选，Ubuntu 20.04 或 Debian 10 以上的版本都可以。macOS 也能完美支持。Windows 用户需要启用 WSL2，并在 Ubuntu 子系统中运行所有命令，千万不要在 PowerShell 或 CMD 里操作。

内存建议至少 4GB，每运行一个实例就需要这么多。如果计划同时部署多个机器人，要相应增加内存。存储空间每个实例预留 5GB 就够了，日志和交易数据不会占用太多地方。CPU 至少 1 个虚拟核心，多实例部署时建议 2 核以上。

接下来是软件依赖。Docker 安装方式最简单，只需要预先装好 Docker 和 Docker Compose。源码安装稍微复杂些，需要 Python 3.10+ 和 Conda 环境管理器。对于开发者来说，源码安装提供了最大的灵活性，可以修改代码、调试程序。

特别提醒，如果打算交易去中心化交易所（DEX），比如 Uniswap 或 Raydium，还需要准备 Node.js 18+ 和 pnpm 包管理器。这些是 Gateway 组件的依赖，后面会详细说明。

Docker 方式安装 Hummingbot 客户端

Docker 是最推荐的安装方式。它把 Hummingbot 和所有依赖打包在一起，避免了环境配置的麻烦。整个过程只需要几条命令。

首先克隆代码仓库：

git clone https://github.com/hummingbot/hummingbot.git
cd hummingbot

然后启动容器：

docker compose up -d

这条命令会自动下载最新的 Hummingbot 镜像，并在后台运行。第一次启动可能需要几分钟，取决于网络速度。

容器运行后，需要 attach 到 Hummingbot 的命令行界面：

docker attach hummingbot

如果一切正常，会看到 Hummingbot 的欢迎界面，提示设置密码。这个密码非常重要，它会加密存储所有交易所的 API 密钥和钱包私钥。一定要使用强密码，并且妥善保管。如果忘记密码，已保存的密钥将无法恢复。

常用 Docker 命令需要记一下：

# 查看运行中的容器
docker ps -a

# 停止 Hummingbot
docker compose down

# 查看日志
docker compose logs -f

# 更新到最新版本
docker compose down
docker pull hummingbot/hummingbot:latest
docker compose up -d

detach 容器也有技巧。按 Ctrl+P 然后 Ctrl+Q 可以退出 Hummingbot 界面，但保持容器在后台运行。下次再用 docker attach hummingbot 就能重新连接。如果直接按两次 Ctrl+C，Hummingbot 会彻底退出，所有未完成的订单也会被取消。

开发版本和特定版本的切换也很方便。编辑 docker-compose.yml 文件，修改 image 字段：

# 开发分支
image: hummingbot/hummingbot:development

# 特定版本
image: hummingbot/hummingbot:version-2.1.0

修改后重新启动即可：

docker compose down
docker compose up -d

源码方式安装与编译

源码安装适合需要修改代码的开发者。虽然步骤多些，但能完全掌控运行环境。

macOS 用户先安装 Xcode 命令行工具：

xcode-select --install

然后安装 Anaconda。建议安装完整版，而不是 Miniconda，可以避免很多依赖冲突。可以从官网下载图形安装包，或者用命令行安装：

# Intel 芯片
curl -O https://repo.anaconda.com/archive/Anaconda3-2024.10-1-MacOSX-x86_64.sh
bash Anaconda3-2024.10-1-MacOSX-x86_64.sh

# Apple Silicon 芯片
curl -O https://repo.anaconda.com/archive/Anaconda3-2024.10-1-MacOSX-arm64.sh
bash Anaconda3-2024.10-1-MacOSX-arm64.sh

Linux 用户先更新系统包：

sudo apt update && sudo apt upgrade -y && sudo apt install -y gcc build-essential

然后下载 Anaconda 安装脚本并执行。

Windows 用户需要先安装 WSL2 和 Ubuntu，之后在 Ubuntu 终端中按照 Linux 的步骤操作。

安装好依赖后，克隆仓库并安装：

git clone https://github.com/hummingbot/hummingbot.git
cd hummingbot
./install

./install 脚本会自动创建 Conda 环境并安装所有依赖。完成后激活环境：

conda activate hummingbot

接着编译代码：

./compile

编译过程可能需要几分钟，完成后就可以启动了：

./start

源码安装的优势在于可以轻松切换分支。要切换到开发分支：

git checkout development
git pull origin development

要切换到特定版本：

git tag                    # 查看所有可用版本
git checkout v2.1.0        # 切换到指定版本

切换后记得重新编译：

./compile

Hummingbot API 服务部署

Hummingbot API 是现代的多机器人管理方案。它提供了一个 RESTful API，可以通过 Telegram、AI 助手或自定义界面控制多个机器人实例。

API 部署需要 Docker。先克隆仓库：

git clone https://github.com/hummingbot/hummingbot-api.git
cd hummingbot-api

然后运行安装脚本：

chmod +x setup.sh
./setup.sh

脚本会提示输入配置密码和 API 认证信息。配置密码用于加密机器人凭证，API 用户名和密码用于访问接口。

安装完成后启动服务：

make deploy

这个命令会启动所有核心服务：

  • Hummingbot API（端口 8000）：REST API 后端
  • PostgreSQL：存储交易数据
  • EMQX：消息代理，用于实时通信

API 运行后，可以通过三种方式交互：

  1. Swagger UI：浏览器访问 http://localhost:8000/docs，可以查看所有接口文档并直接测试
  2. Condor：Telegram 机器人，适合移动端监控
  3. MCP：连接 AI 助手，用自然语言控制

对于开发者，还可以安装 Python 客户端：

pip install hummingbot-api-client

使用示例：

from hummingbot_api_client import HummingbotAPIClient

client = HummingbotAPIClient(
    base_url="http://localhost:8000",
    username="admin",
    password="admin"
)

# 获取投资组合数据
portfolio = await client.get_portfolio()

API 部署的优势在于可以管理多个机器人实例，每个实例都有独立的配置和数据。所有操作都通过标准化的接口完成，方便集成到现有系统中。

Gateway DEX 中间件安装

Gateway 是连接去中心化交易所的桥梁。它用 TypeScript 编写，提供标准化的 REST API，让 Hummingbot 能够与各种 DEX 交互。

Gateway 可以独立安装，也可以和 Hummingbot 一起通过 Docker Compose 部署。推荐后者，配置更简单。

编辑 docker-compose.yml 文件，取消 Gateway 相关行的注释：

gateway:
  restart: always
  container_name: gateway
  image: hummingbot/gateway:latest
  ports:
    - "15888:15888"
  volumes:
    - "./gateway-files/conf:/home/gateway/conf"
    - "./gateway-files/logs:/home/gateway/logs"
    - "./certs:/home/gateway/certs"
  environment:
    - GATEWAY_PASSPHRASE=admin
    - DEV=true

GATEWAY_PASSPHRASE 用于加密钱包私钥，建议改成复杂的密码。DEV=true 表示开发模式，使用 HTTP 协议，方便调试。生产环境可以设为 false 启用 HTTPS。

修改后重启服务：

docker compose up -d

会看到两个容器同时启动：

[+] Running 3/3
 ✔ Network hummingbot_default  Created
 ✔ Container hummingbot        Started
 ✔ Container gateway           Started

attach 到 Hummingbot 后，右上角应该显示 GATEWAY: 🟢 ONLINE，表示连接成功。如果显示 OFFLINE，检查 Gateway 容器是否正常运行，端口 15888 是否被占用。

Gateway 安装完成后，可以使用各种命令管理 DEX 交易：

# 测试连接
gateway ping

# 查看支持的链和连接器
gateway list

# 添加钱包
gateway connect

# 查询余额
gateway balance

# 执行兑换
gateway swap

# 管理流动性头寸
gateway lp

开发模式下，Swagger 文档在 http://localhost:15888/docs 可以访问，提供了所有接口的详细说明和测试功能。

目录结构与文件组织

安装完成后，了解目录结构很重要。这有助于定位配置文件、日志和策略脚本。

Hummingbot 的主要目录：

hummingbot/
├── conf/
│   ├── connectors/    # 交易所 API 密钥（加密）
│   ├── strategies/    # 策略配置文件
│   └── scripts/       # 脚本配置文件
├── logs/              # 日志文件
├── data/              # 交易数据库和 CSV 文件
└── scripts/           # 自定义策略脚本

conf/connectors 存储所有交易所的 API 密钥，用之前设置的密码加密。不要手动修改这些文件，通过 connect 命令管理。

conf/strategies 包含策略配置文件，用 create 命令创建。每个文件对应一个策略实例。

conf/scripts 是脚本策略的配置文件，用 create --script-config 创建。

logs 目录保存运行日志，按日期分割。调试问题时首先查看这里。

data 目录存储 SQLite 数据库和交易历史 CSV 文件，可用于绩效分析。

scripts 目录放自定义的 Python 策略脚本，可以从官方仓库复制示例文件到这里。

Gateway 的目录结构类似：

gateway-files/
├── conf/
│   ├── chains/        # 链和网络配置
│   ├── connectors/    # DEX 连接器配置
│   ├── tokens/        # 代币列表
│   └── pools/         # 流动性池信息
└── logs/              # Gateway 日志

版本更新与迁移指南

Hummingbot 每月发布新版本，包含新功能、连接器更新和 bug 修复。保持版本最新很重要，但升级过程需要注意一些细节。

标准升级流程适用于大多数情况，特别是配置文件格式没有变化时。

Docker 方式升级 Hummingbot Client：

docker compose down
docker pull hummingbot/hummingbot:latest
docker compose up -d

源码方式升级：

cd hummingbot
git pull origin master
./install
./compile
./start

Gateway 升级：

docker compose down
docker pull hummingbot/gateway:latest
docker compose up -d

有些版本会修改配置文件格式，这时需要先删除旧配置，否则会导致启动失败。升级前查看发布说明，确认是否有配置变更。

如果需要删除配置，先备份重要数据：

# 备份 Hummingbot 配置
cp conf/conf_client.yml conf/conf_client.yml.backup

# 备份 Gateway 配置
cp -r gateway-files gateway-files.backup

然后删除旧配置：

# 删除 Hummingbot 配置
rm conf/conf_client.yml

# 删除 Gateway 配置
rm -rf gateway-files

删除后重新启动，系统会自动生成新格式的配置文件。可以参考备份文件恢复自定义设置。

对于 Hummingbot API，升级方式类似：

docker compose down hummingbot-api
docker pull hummingbot/hummingbot-api:latest
docker compose up hummingbot-api -d

如果遇到数据库连接问题，可以运行修复脚本：

chmod +x fix-database.sh
./fix-database.sh

这个脚本会自动检查并修复 PostgreSQL 配置。

升级后建议测试基本功能，比如查询余额、创建策略等，确保一切正常。如果发现问题，可以回退到备份版本，并在社区寻求帮助。

安装和部署是 Hummingbot 之旅的起点。选择合适的安装方式，根据需求配置 Gateway 和 API，就能搭建起完整的交易环境。下一章将深入客户端的基本操作，学习如何连接交易所、管理配置和运行第一个策略。

上一章

框架和核心概念

 下一章

客户端基础操作