Hummingbot API 安装¶

运行 Hummingbot 交易机器人的中心枢纽 — 现已通过 MCP（模型上下文协议）集成 AI 助手。

Hummingbot API 提供了一个完整的交易平台，支持三种交互方式：

🤖 MCP（AI 助手） - 使用自然语言通过 Claude、ChatGPT 或 Gemini 控制您的交易
📊 仪表板 - 用于机器人管理和监控的可视化网页界面
🔧 Swagger UI - 为开发者和高级用户提供完整的 REST API 访问

前提条件¶

已安装 Docker 和 Docker Compose
已安装 Git，用于克隆代码仓库
Python 3.10+ 和 Conda（仅适用于源码安装）
交易所 API 密钥（可在安装后添加）

快速开始（Docker - 推荐）¶

克隆仓库并运行设置脚本：

git clone https://github.com/hummingbot/hummingbot-api.git
cd hummingbot-api
chmod +x setup.sh
./setup.sh

安装流程¶

脚本将提示您输入以下信息：

凭据（必填）：
配置密码（用于加密机器人凭据）
API 用户名和密码
可选服务：
仪表板：用于基于网页的可视化界面
网关：DEX 交易的可选密码短语

安装内容说明¶

核心服务（始终安装）：

✅ Hummingbot API（端口 8000）- REST API 后端
✅ PostgreSQL - 用于存储交易数据的数据库
✅ EMQX - 实时通信的消息代理
✅ Swagger UI（端口 8000/docs）- API 文档

可选服务（在设置期间启用）：

📊 仪表盘（端口 8501）- 网页界面

设置完成后¶

1. 访问 Swagger UI（默认）

API 文档将立即可用：

URL: http://localhost:8000/docs
使用您配置的用户名/密码
直接测试所有 API 接口

2. 连接 AI 助手（可选）

设置完成后，您可以连接 AI 助手，通过自然语言控制 Hummingbot。

有关连接的完整说明，请参阅 MCP 安装指南：

Claude Code（推荐）—— 一行 CLI 命令完成设置
Gemini CLI —— Google 的 AI 终端代理
Codex CLI —— OpenAI 的编程助手
Claude Desktop —— 图形化桌面应用

3. 访问仪表板（如果已启用）

如果您在设置期间启用了仪表板：

URL: http://localhost:8501
使用设置时相同的用户名/密码

从源码安装（适用于开发者）¶

如果您正在开发或为 Hummingbot API 贡献代码，可以从源码安装。

1. 克隆并设置¶

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

2. 安装依赖项¶

make install

此操作将：

创建名为 hummingbot-api 的 conda 环境
激活环境
安装所有必需的依赖项
设置 pre-commit 钩子

3. 以开发模式启动 API¶

./run.sh --dev

此操作将启动 Broker 和 Postgres 数据库容器，并使用 uvicorn 运行 API，同时启用自动重载功能以支持开发。

API 将可通过 http://localhost:8000 访问。

安装 Python 客户端¶

Hummingbot API 客户端是一个 Python 库，提供与 Hummingbot API 交互的便捷接口。

通过 pip 安装¶

pip install hummingbot-api-client

基本用法¶

import asyncio
from hummingbot_api_client import HummingbotAPIClient

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

# Use the client
async def main():
    accounts = await client.list_accounts()
    print(accounts)

asyncio.run(main())

验证安装¶

安装完成后，您可以验证 API 是否正在运行：

检查 API 状态¶

curl http://localhost:8000/health

访问 API 文档¶

打开浏览器并访问：

交互式 API 文档：http://localhost:8000/docs
替代 API 文档：http://localhost:8000/redoc

配置¶

安装过程会创建一个包含您配置的 .env 文件。您可以修改以下设置：

API_USERNAME 和 API_PASSWORD：API 认证凭证
DATABASE_URL：PostgreSQL 连接字符串
MQTT_HOST、MQTT_PORT：EMQX 消息代理设置
HUMMINGBOT_IMAGE：用于机器人使用的 Docker 镜像

故障排除¶

数据库连接问题¶

如果您遇到 PostgreSQL 数据库连接错误（例如“角色 'hbot' 不存在”或“数据库 'hummingbot_api' 不存在”），请使用自动化修复脚本：

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

该脚本将执行以下操作：1. 检查 PostgreSQL 是否正在运行 2. 验证 hbot 用户和 hummingbot_api 数据库是否存在 3. 自动修复任何缺失的配置 4. 测试连接以确保一切正常

“角色 'postgres' 不存在”错误¶

如果在 PostgreSQL 日志中看到类似 FATAL: 角色 "postgres" 不存在 的错误：

原因：PostgreSQL 容器配置为仅创建 hbot 用户（通过 POSTGRES_USER=hbot），默认的 postgres 超级用户不会被创建。当某些程序尝试使用默认的 postgres 用户名连接时，就会出现此错误。

解决方案：

连接时务必指定正确的用户：

# Correct - use hbot user
docker exec -it hummingbot-postgres psql -U hbot -d hummingbot_api

# Incorrect - tries to use 'postgres' user (doesn't exist)
docker exec -it hummingbot-postgres psql

如果您确实需要 postgres 超级用户（不推荐），可以手动创建：

docker exec -it hummingbot-postgres psql -U hbot -d postgres -c "CREATE ROLE postgres WITH SUPERUSER LOGIN PASSWORD 'your-password';"

完全重置数据库（⚠️ 将删除所有数据）：
```
docker compose down -v
./setup.sh
```

手动数据库验证¶

如果您更倾向于手动检查：

# Check if containers are running
docker ps | grep -E "hummingbot-postgres|hummingbot-broker"

# Check PostgreSQL logs
docker logs hummingbot-postgres

# Verify database connection (use hbot user, not postgres)
docker exec -it hummingbot-postgres psql -U hbot -d hummingbot_api

# List all database users
docker exec -it hummingbot-postgres psql -U hbot -d postgres -c "\du"

设置过程中出现“数据库 'hbot' 不存在”错误¶

如果在运行 ./setup.sh 时看到此错误：

⚠️  Database initialization may be incomplete. Running manual initialization...
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL:  database "hbot" does not exist
❌ Failed to initialize database.

原因：设置脚本尝试连接名为 hbot（用户名）的数据库，而不是实际的数据库名称 hummingbot_api。这是旧版本 setup.sh 中的一个 bug。

解决方案：

更新 setup.sh：拉取包含修复的最新版本：
```
git pull origin main
```

或手动修复数据库：

# The database already exists, just verify it
docker exec hummingbot-postgres psql -U hbot -d postgres -c "\l"

# You should see 'hummingbot_api' in the list
# Test connection
docker exec hummingbot-postgres psql -U hbot -d hummingbot_api -c "SELECT version();"

如果数据库不存在，运行修复脚本：
```
chmod +x fix-database.sh
./fix-database.sh
```

预防措施：此问题已在 setup.sh 的最新版本中修复。脚本在执行手动初始化时现在会正确指定 -d postgres。

完整数据库重置¶

如果需要重新开始（⚠️ 这将删除所有数据）：

# Stop all containers and remove volumes
docker compose down -v

# Restart setup
./setup.sh

EMQX Broker 问题¶

如果机器人无法连接到 Broker：

# Check EMQX status
docker logs hummingbot-broker

# Restart EMQX
docker compose restart emqx

# Access EMQX dashboard (if needed)
# http://localhost:18083
# Default credentials: admin/public

端口冲突¶

如果您的系统上端口 8000 已被占用，您可以通过根据您的设置修改配置来更改端口：

Docker¶

在您的 docker-compose.yml 文件中更新 ports 映射，使用其他外部端口。例如，改用端口 8001：

services:
  hummingbot-api:
    ports:
      - "8001:8000"  # Maps local port 8001 to container's port 8000

从源码运行¶

编辑 ./run.sh 脚本，在 uvicorn 命令中添加 --port 标志。例如，要在端口 8001 上运行：

if [[ "$1" == "--dev" ]]; then
    echo "Running API from source..."
    # Start dependencies and launch API with uvicorn
    docker compose up emqx postgres -d
    source "$(conda info --base)/etc/profile.d/conda.sh"
    conda activate hummingbot-api
    uvicorn main:app --reload --port 8001
fi

请确保您选择的新端口未被占用。

常见问题¶

问题：API 无法启动 - “数据库连接失败” - 解决方案：运行 ./fix-database.sh 修复数据库配置

问题：机器人容器无法启动 - 解决方案：检查 Docker 守护进程是否正在运行，并确认您有足够的资源

问题：无法在 localhost:8000 访问 API - 解决方案：验证 API 容器是否正在运行：docker ps | grep hummingbot-api

问题：身份验证失败 - 解决方案：检查 .env 文件中的 USERNAME 和 PASSWORD

问题：旧的机器人数据导致冲突 - 解决方案：清理旧卷：docker compose down -v（⚠️ 删除数据）

开发问题¶

针对源码安装问题：

# Clean conda environment
make uninstall
make install

# Check logs
make run

支持与文档¶

API 文档：运行时可在 http://localhost:8000/docs 查看
详细示例：查看 CLAUDE.md 文件以获取全面的 API 使用示例
问题反馈：通过项目的问题跟踪器报告 Bug 和功能请求
数据库故障排除：使用 ./fix-database.sh 进行自动修复

下一步¶

安装完成后，请前往快速入门指南学习如何：

添加交易所凭证
查看您的投资组合
下达您的第一笔订单