13. Dashboard部署与管理 - Hummingbot 速读教程

Hummingbot Dashboard 是框架生态中承上启下的关键组件。它把命令行工具的灵活性、API 的扩展性和图形界面的直观性揉在一起，让我们能在浏览器里完成从策略配置到多实例管理的全套操作。相比早期版本，v2.7.0 之后的 Dashboard 彻底重构在 Hummingbot API 之上，这意味着它不再是一个独立的工具，而是整个交易基础设施的可视化层。

Dashboard 安装与启动

安装 Dashboard 本质上是在部署一套微服务架构。核心服务包括 Dashboard 本身、Hummingbot API、PostgreSQL 数据库和 EMQX 消息代理。这套组合让策略配置、回测结果和实例状态都能持久化，同时保证与运行中机器人的实时通信。

Docker 方式部署

最省心的方案是用 Docker Compose 一键拉起。先确保系统装好了 Docker 和 Docker Compose，然后克隆仓库：

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

执行 setup 脚本，它会交互式地询问配置密码和 API 认证信息。这个密码用来加密交易所 API 密钥，务必牢记：

make setup

脚本执行完后，所有服务就配置好了。接着启动整个栈：

make deploy

这条命令会在后台启动四个容器：API 服务、数据库、消息代理和 Dashboard。启动过程可能需要几分钟，特别是第一次拉取镜像时。可以用 docker compose logs -f 查看实时日志，确认每个服务都正常初始化。

验证安装

打开浏览器访问 http://localhost:8000/docs，如果能看到 Swagger UI 界面，说明 API 服务已经就绪。Dashboard 默认运行在 http://localhost:8501，用 setup 脚本里设置的用户名和密码登录。

登录后首先看到的是 Overview 页面，这里汇总了所有连接交易所的总资产估值、活跃机器人数量和今日交易量。右上角的状态指示灯显示 API 连接状态，绿色表示正常，红色说明需要检查 EMQX 或数据库服务。

源码安装（开发者选项）

如果想二次开发 Dashboard，可以从源码启动。先安装 Python 3.10+ 和 Conda，然后：

git clone https://github.com/hummingbot/dashboard.git
cd dashboard
conda env create -f environment.yml
conda activate dashboard
streamlit run main.py

源码方式需要手动配置 API 地址，在 conf/config.yaml 里指定 hummingbot_api_url。这种方式的好处是能实时修改界面逻辑，比如添加自定义的绩效指标图表或调整仓位展示方式。

交易所凭证管理

凭证管理是 Dashboard 的基石功能。没有正确配置的 API 密钥，后续所有操作都是空中楼阁。Dashboard 把凭证按账户维度组织，支持为不同策略分配不同权限的密钥，实现风险隔离。

账户体系设计

Dashboard 采用"账户-凭证"两级结构。一个账户可以包含多个交易所的凭证，比如 master_account 下同时有 Binance 和 Hyperliquid 的密钥。这种设计让我们能按策略类型或风险等级划分资金，比如把高风险策略放在 aggressive_account，低风险策略放在 conservative_account。

创建账户很简单，在 Credentials 页面的"Manage Accounts"区域输入新账户名，点击 Create Account 即可。删除账户时要小心，这会连带删除该账户下所有凭证，且操作不可逆。

添加中心化交易所凭证

以 Binance 为例，演示添加凭证的完整流程。首先登录 Binance 官网，进入 API 管理页面创建新密钥。注意只给交易权限，不要开启提现权限，这是基本的安全原则。

在 Dashboard 的"Add Credentials"区域，按以下步骤操作：

选择目标账户（如 master_account）
选择连接器类型（binance 或 binance_perpetual）
粘贴 API Key 和 Secret Key
点击 Submit Credentials

提交后 Dashboard 会调用 API 测试连接，验证通过后会显示成功消息。如果提示权限不足，通常是 IP 白名单没配置。Binance 要求必须为 API 密钥添加服务器 IP，在 Binance 的 API 设置里找到"IP 访问限制"，填入服务器公网 IP。

凭证存储是加密的，Dashboard 把密钥传给 API 服务，API 服务用 CONFIG_PASSWORD 加密后存入 PostgreSQL。这意味着即使数据库泄露，没有密码也无法解密凭证。密码丢失的后果很严重——所有凭证都要重新添加，所以一定要用密码管理器妥善保管。

去中心化交易所凭证配置

DEX 凭证配置稍微复杂，因为涉及钱包私钥。以 Hyperliquid 为例，它支持两种模式：Arbitrum 钱包模式和 API Key 模式。

钱包模式需要 Arbitrum 地址和私钥。在 Dashboard 里添加 hyperliquid 连接器时，会提示输入这两个值。私钥输入框做了特殊处理，提交后立即从内存清除，不会在任何日志里留下痕迹。

API Key 模式更安全，适合生产环境。先在 Hyperliquid 网页端生成 API 密钥对，然后在 Dashboard 里选择 hyperliquid 连接器，填入 API Key 和 Secret。注意 Hyperliquid 的 API Secret 就是私钥，必须妥善保管。

有些 DEX 连接器（如 dYdX v4）需要 24 个助记词。Dashboard 的输入框支持空格分隔的助记词格式，粘贴后会自动验证词数。助记词同样采用内存安全处理，提交后立即清除。

凭证管理的最佳实践

生产环境建议遵循以下原则：

最小权限原则：只为密钥分配必要的交易权限，禁用提现
IP 白名单：所有 CEX 密钥必须绑定服务器 IP
账户隔离：不同策略用不同账户，避免密钥混用
定期轮换：每 90 天更换一次密钥，降低泄露风险
监控告警：在交易所设置异常交易告警，及时发现未授权操作

Dashboard 的凭证页面会显示每个密钥的最后使用时间和状态。如果某个密钥长时间未使用，考虑删除或禁用。对于团队管理场景，可以创建 team_account，把只读权限的密钥放在这里供分析师查看仓位，交易密钥放在 trading_account 供策略使用。

策略实例部署与配置

部署机器人是 Dashboard 的核心价值所在。它把复杂的 Docker 命令和配置文件管理封装成几个点击操作，让我们能专注于策略参数调优而非基础设施运维。

V2 策略框架的理解

Dashboard 只支持 V2 策略框架。V2 的核心思想是"控制器+执行器"的分离。控制器（Controller）负责决策，比如什么时候挂单、挂什么价格；执行器（Executor）负责执行，比如管理订单生命周期、处理部分成交。

这种分离让策略可以模块化组合。一个控制器可以调用多个执行器，比如同时用 Grid Executor 做市和用 Position Executor 做趋势跟踪。Dashboard 的配置界面就是围绕这种模块化设计的。

创建控制器配置

在 Config 页面选择策略类型，比如 pmm_simple。界面会动态加载该控制器的参数模板，每个参数都有类型验证和范围检查。

关键参数说明：

Connector：选择交易所，下拉列表只显示已添加凭证的交易所
Trading Pair：输入交易对，格式必须是 BASE-QUOTE，如 BTC-USDT
Total Amount：策略可用的总资金，以报价货币计。如果设为 1000 USDT，策略最多只会用 1000 USDT 做市
Order Levels：订单层级数，比如 3 表示在买价上方挂 3 层卖单，在卖价下方挂 3 层买单
Spread：每层订单与中间价的距离，可以设固定值或用 NATR 动态计算
Refresh Time：订单刷新间隔，单位秒。太短会增加费率成本，太长会跟不上市场变化

配置完成后点"Save Config"，文件会存入 conf/controllers 目录。文件名建议包含策略类型和交易对，如 pmm_simple_btc_usdt.yml，方便后续管理。

批量配置管理

对于多交易对策略，手动创建每个配置很繁琐。Dashboard 支持批量导入，准备一个 CSV 文件，列名对应参数名，然后在上传区域选择文件即可。

CSV 格式示例：

connector,trading_pair,total_amount,order_levels,buy_spreads,sell_spreads
binance,BTC-USDT,1000,2,0.01 0.02,0.01 0.02
binance,ETH-USDT,500,2,0.015 0.025,0.015 0.025
binance,SOL-USDT,300,1,0.02,0.02

上传后 Dashboard 会逐行验证，有错误的行会高亮显示。验证通过后批量生成配置文件，命名规则是 控制器名_交易对_序号.yml。

部署实例

切换到 Deploy V2 页面，这里列出了所有可用的控制器配置。勾选要部署的配置，填写实例名，选择 Docker 镜像版本，然后点击 Launch Bot。

实例名很重要，它决定了 Docker 容器的名称和数据存储路径。建议用 策略_交易对_序号 格式，如 pmm_btc_usdt_01。这样当实例数增多时，通过 docker ps 能快速识别每个容器的作用。

Docker 镜像版本选择：

latest：稳定版，适合生产环境
development：开发版，包含最新功能但可能不稳定
version-2.0.0：特定版本，适合需要固定功能的场景

点击 Launch 后，Dashboard 调用 API 创建容器。API 会做几件事：

生成容器配置，挂载 bots/instances/实例名 目录
把控制器配置复制到实例的 conf/controllers 目录
启动容器，自动执行 start --controller-config 配置文件
通过 MQTT 订阅实例状态，实时更新 Dashboard 界面

部署过程通常需要 10-30 秒，取决于镜像拉取速度。成功后实例会出现在 Instances 页面的"Active Controllers"列表中。

实例生命周期管理

部署后的实例有几种状态：

Starting：容器启动中，正在初始化连接器
Running：策略正常运行，有活跃的订单
Stopped：策略已停止，订单全部取消
Error：启动失败，通常是凭证或配置错误

在 Instances 页面可以查看每个实例的详细状态。如果显示 Error，点击实例名进入详情页，查看 Error Logs 了解具体原因。常见错误包括：

凭证无效：API 密钥权限不足或已过期
交易对不存在：交易所不支持该交易对
资金不足：账户余额低于 total_amount 设置
网络超时：交易所 API 响应慢，需调整超时参数

运行中实例监控与管理

监控是无人值守交易的生命线。Dashboard 提供了从宏观到微观的多层次监控能力，让我们既能总览所有实例的健康状况，又能深入单个订单的成交细节。

实例列表与核心指标

Instances 页面顶部显示所有运行中实例的卡片视图。每张卡片包含：

实例名：点击可进入详情页
运行时长：从启动到现在的累计时间
净盈亏：已实现盈亏 + 未实现盈亏，按报价货币计算
成交量：累计交易额，反映策略活跃度
CPU/内存占用：容器资源使用情况，过高可能需要优化策略

卡片按盈亏排序，亏损最多的显示在最上面，方便及时发现异常。如果某个实例的 CPU 持续超过 80%，说明策略计算量大，可能需要减少订单层级或延长刷新时间。

控制器级监控

点击实例名进入详情页，这里按控制器维度展示数据。一个实例可以运行多个控制器，比如同时做市 BTC 和 ETH。

控制器表格包含以下列：

ID：控制器唯一标识，格式是 控制器名_交易对_随机串
Connector：交易所名称
Trading Pair：交易对
Realized PnL：已平仓部分的盈亏，落袋为安
Unrealized PnL：持仓部分的浮动盈亏，随市场波动
Net PnL：总盈亏，是上面两项之和
Volume：该控制器产生的交易量
Position：当前仓位，只在做市策略中显示

表格支持按盈亏、成交量排序。点击列头即可切换排序方式。对于做市策略，重点关注 Volume 和 Net PnL 的比值，衡量单位成交量的盈利能力。

日志分析

详情页下方是日志区域，分为 Error Logs 和 General Logs 两类。

Error Logs 只显示 ERROR 级别以上的日志，包括：

订单提交失败：通常是价格或数量不符合交易所规则
网络异常：API 超时或连接重置
资金不足：下单时可用余额不足
策略异常：控制器逻辑错误，如除以零、索引越界

每条错误日志包含时间戳、错误类型和堆栈跟踪。点击日志可以展开完整信息。对于频繁出现的错误，需要修改策略参数或代码。比如"price too high"错误，说明卖单价格超出交易所允许范围，需要调小 spread。

General Logs 显示 INFO 级别日志，记录策略主要操作：

订单创建：价格、数量、方向
订单取消：原因（刷新、止损等）
订单成交：成交价格、手续费
仓位变化：开仓、平仓、部分成交

日志实时更新，通过 WebSocket 推送。如果日志停止更新，说明实例可能卡死或网络中断，需要重启。

实例控制操作

在实例详情页右上角有两个停止按钮：

STOP 按钮（推荐）：优雅停止，先取消所有订单，等待未成交订单处理完，再停止策略。这种方式保留实例数据，可以后续重启
Force Stop 图标：强制停止，直接杀死容器进程。未成交订单可能残留在交易所，需要手动清理

停止后的实例会移到"Stopped Controllers"区域。勾选已停止的实例，点击 START 按钮可以恢复运行。重启会重新加载配置文件，所以修改配置后无需重新部署，直接重启即可生效。

对于需要频繁启停的场景，比如只在高波动时段运行策略，可以用 Dashboard 的定时任务功能。在实例配置里添加 schedule 参数，格式是 cron 表达式：

schedule: "0 9-16 * * 1-5"  # 工作日 9:00-16:59 运行

投资组合分析与可视化

投资组合页面把分散在各个交易所的资产整合成统一视图，这是手动管理难以做到的。它自动聚合余额、计算估值、分析分布，让我们对整体资金状况一目了然。

多维度筛选

页面顶部是筛选器，支持按账户、交易所、代币三个维度过滤。

账户筛选：如果配置了多个账户（如 master_account、team_account），可以单独查看某个账户的资产，或勾选多个查看汇总。这在管理客户资金时特别有用，每个客户的资产独立核算。

交易所筛选：只显示特定交易所的资产。比如只想看 DEX 仓位，可以筛选出所有 Gateway 连接器（如 uniswap、jupiter）。这有助于分析不同市场的资金分配效率。

代币筛选：聚焦特定代币。比如持有大量 HBOT，可以只选 HBOT 查看其在各交易所的分布。这能发现套利机会，比如 HBOT 在 Gate.io 的价格比 KuCoin 高 1%，就可以考虑搬砖。

筛选器支持多选，组合使用能实现复杂分析。比如选 master_account + binance + BTC,ETH,SOL，就能快速查看主账户在 Binance 上的主流币持仓。

估值与分布可视化

筛选后的数据会更新三个核心区域：

总估值：显示所有选中资产的美元总价值。计算逻辑是 sum(代币数量 * 当前价格)，价格从 Rate Oracle 获取，优先用 Binance 价格，没有就用 CoinGecko。

分布饼图：用 sunburst 图表展示资产分布。从内到外依次是账户、交易所、代币。鼠标悬停显示占比和金额。这能直观发现配置失衡，比如 80% 资产集中在 Binance，需要考虑分散风险。

时序图：展示投资组合价值随时间的变化。数据来自 API 定期抓取的余额快照，默认保留 30 天历史。可以切换时间范围（1D、7D、30D），观察资产增长趋势。

表格明细

底部的表格列出每个代币的详细信息：

Exchange：交易所名称
Token：代币符号
Units：持有数量
Price：当前价格（美元）
Value：估值（美元）
Available：可用数量（未挂单部分）

表格支持导出 CSV，方便用 Excel 做进一步分析。点击列头可以排序，比如按 Value 排序能快速找到最大持仓。

高级分析技巧

盈亏归因分析：结合 Instances 页面的 PnL 数据，可以分析哪些策略对组合价值贡献最大。比如发现做市策略每天赚 0.1% 但持仓的 ETH 涨了 5%，说明收益主要来自币价上涨而非策略本身。

资金利用率：用 Value / Total Balance 计算每个交易所的资金利用率。如果某个交易所利用率长期低于 20%，考虑把资金转移到利用率高的交易所。

相关性分析：同时查看多个代币的时序图，能发现相关性。比如 BTC 和 ETH 的价格曲线高度重合，说明需要配置一些低相关性的代币（如平台币、DeFi 代币）来分散风险。

Dashboard 回测界面使用

回测是策略上线前的必经之路。Dashboard 的回测界面把历史数据获取、参数优化、绩效评估整合在一起，支持可视化分析，比命令行回测效率高得多。

回测配置

在任意控制器页面（如 PMM Simple）都能找到 Backtesting 区域。配置分三部分：

基础参数：

Start Date / End Date：回测时间范围，建议至少 30 天以覆盖不同市场状态
Backtesting Resolution：K 线周期，1m、5m、1h、1d 可选。做市策略用 1m 或 5m，趋势策略用 1h 或 1d
Trade Cost：手续费率，默认 0.1%，适合 Binance 等主流交易所。如果是 VIP 费率，需要手动调整

策略参数：自动加载控制器的配置界面，所有参数都可以调整。这是回测的核心价值——快速验证不同参数组合的效果。

数据源：默认用 Binance 的历史数据。如果回测其他交易所，需要确保该交易所有完整的历史数据。Dashboard 会自动检查数据可用性，缺失的数据会标红提示。

执行回测

参数设好后点击 Run Backtesting。后台会启动一个独立的回测进程，从数据服务拉取历史 K 线，按策略逻辑模拟交易。进度条显示当前处理到的日期。

回测速度取决于数据量和策略复杂度。简单的 PMM 策略处理 30 天 1m 数据约需 2-3 分钟，复杂的 D-Man Maker 可能需要 10 分钟以上。期间可以离开页面，回测完成后 Dashboard 会发送通知（如果浏览器允许推送）。

结果解读

回测完成后会显示详细报告，包含三类指标：

收益指标：

Net PnL：净盈亏，扣除手续费后的实际收益
Max Drawdown：最大回撤，从峰值到谷底的最大亏损幅度。这是最重要的风险指标，一般要求小于 10%
Sharpe Ratio：夏普比率，衡量单位风险收益。大于 1 说明策略有效，大于 2 说明优秀
Profit Factor：盈利因子，总盈利 / 总亏损。大于 1.5 说明策略稳健

交易统计：

Total Executors：执行器总数，反映交易频率
Global Accuracy：胜率，盈利交易占比
Long / Short：多空方向的交易次数和胜率
Close Types：订单关闭原因分布，如 TAKE_PROFIT、STOP_LOSS、TIME_LIMIT

可视化图表：

价格图：K 线图叠加买卖点位，直观展示策略操作
盈亏曲线：累计盈亏随时间变化，理想形态是平滑上升、回撤小
回撤图：展示每次回撤的深度和持续时间

参数优化

回测的真正价值在于迭代优化。Dashboard 支持参数扫描，在配置界面勾选"Optimize"模式，然后设置参数范围：

buy_spreads: [0.005, 0.01, 0.015]  # 测试三个值
sell_spreads: [0.005, 0.01, 0.015]
order_levels: [1, 2, 3]

点击 Run Optimization 后，Dashboard 会执行网格搜索，测试所有参数组合（3×3×3=27 组）。结果用热力图展示，横轴是一个参数，纵轴是另一个参数，颜色深浅代表盈亏高低。这能快速找到参数高原，避免局部最优。

优化时要注意过拟合问题。如果某个参数组合在回测期收益很高，但夏普比率低、最大回撤大，很可能是过拟合。建议把数据分成训练集和测试集，用训练集找参数，用测试集验证效果。

回测结果上传

满意的回测结果可以上传到后端，作为实盘配置的基础。在结果页面点击"Upload Config"，填写配置名和版本标签。版本标签建议用日期或迭代次数，如 v1.0、2024-01-15。

上传后配置会出现在 Deploy V2 页面的列表中，旁边会显示回测的关键指标（PnL、Sharpe、Max Drawdown）。这让我们在部署时能快速比较不同策略的优劣。

回测配置和实盘配置是分离的，上传后修改实盘配置不会影响回测结果。这保证了历史绩效的可追溯性，方便后续审计和分析。

Dashboard 把 Hummingbot 从一个命令行工具升级成了完整的交易管理系统。它降低了使用门槛，让不熟悉命令行的用户也能配置复杂策略；同时提升了管理效率，让专业交易者能同时监控几十个实例。随着 V2 策略框架的成熟，Dashboard 将成为 Hummingbot 生态的标准入口。

下一章将介绍如何通过 Hummingbot API 实现自动化部署和监控，把 Dashboard 的手动操作转化为可编程的接口调用，为大规模策略运营打下基础。