企业官网建设流程全解析

• 金融科技
• CLI

导读：本文以 hummingbot/cli/README.md 为主体，系统讲解 Hummingbot 新一代命令行工具hbot——一个完全非交互、可脚本化的单实例机器人控制接口。读完本文，你将掌握三类配置的心智模型、全部命令的语义与退出码契约、create → config → start的实战链路、deploy一键式部署、密钥安全管理，以及 Docker 环境下的两种运行形态（hbot 宿主模式与单容器单 bot），并能在 Agent/LLM 自动化场景中稳定依赖其 Markdown/JSON 输出与退出码。

一、hbot是什么：为自动化而生的 CLI

hbot是 Hummingbot 的命令行接口，负责运行、控制、监控一次安装中的一个 Hummingbot 机器人。与交互式客户端不同，它完全非交互、可脚本化：每条命令都会输出紧凑的Markdown（列表用表格、单条记录用键值对，人类与 Agent 都能直接阅读），并返回稳定的退出码；运行/观测类命令还支持--json输出机器可读结构。整个过程不需要 MQTT broker，也不需要交互式提示符。

hbot --help # 顶层命令 hbot --version hbot <command> -h # 单个命令的完整帮助（细节都在这里，而不是菜单里）

从源码看，hbot由 hummingbot/cli/main.py 基于 Typer 构建，注册了connect、balance、create、import、config、deploy、start、stop、status、logs、history、update、doctor共 13 条命令，且使用SortedCommandsGroup（见 hummingbot/cli/output.py）让--help菜单按字母序排列；入口脚本 bin/hbot 将仓库根目录加入sys.path后调用hummingbot.cli.main.main()。

一个安装一个 bot。要跑多个机器人，请使用多份安装或多个容器。在同一安装内启动第二个 bot 会失败，除非传入--replace。

二、心智模型：三种配置类型与“当前加载的策略”

三种配置类型

CLI 将配置分为三类（文档中称之为types），每种对应一个源目录：

配置文件名在三个目录间全局唯一，因此裸文件名即可无歧义定位，绝大多数场景不需要输入类型标志。import/start/config都会从文件所在目录自动检测类型；只有当某个历史遗留名称在多个目录下同时存在时，才需要--v1-strategy/--v2-script/--controller标志消歧。

当前加载的策略

与交互式客户端一样，hbot会维护一个currently loaded配置：

• create <strategy>与import <file>都会加载一个配置（但不会启动它）；
• start <file>加载并运行；
• 加载之后，hbot config可以查看/编辑它，hbot start（不带参数）直接运行它。

该指针存放在data/bot/loaded.json；正在运行的 bot 自身配置永远优先。这一机制在 hummingbot/cli/bot.py 中实现为read_loaded()/write_loaded()，记录{"file", "type"}两字段。

config——一条命令，两个作用域

hbot config展示全局客户端设置（汇率源、日志级别、超时等，存放在未加密的conf/conf_client.yml），当已加载策略时，同时展示该策略的配置。config <key> <value>则编辑键所属的那个作用域（全局键优先）。这是 v1 CLI 的唯一配置入口——没有单独的settings命令。

值得一提的是 hummingbot/cli/main.py 为config设置了ignore_unknown_options=True：因为配置值可能合法地以-开头（如负 spread/百分比），不这样做的话hbot config <key> -1会在解析阶段死于No such option: -1。

控制器不能独立运行

controller无法单独运行，因此start会自动为它生成一个极小的 V2 loader 脚本；该 loader 的名称会同时成为 bot 的交易数据库（trades-DB）与日志名称。你不需要管理 loader——直接start控制器配置即可。这一逻辑在 hummingbot/cli/commands/start.py 中通过validate_controller+wrap_controller_as_v2完成。

三、命令本体论：v1 命令全景

v1 的命令面镜像交互式 Hummingbot 客户端的命令（去掉了gateway套件）。无子命令、扁平结构，每个菜单都按字母序排列：

hbot │ ├─ ── 设置（连接器与资金）── │ ├─ connect [connector] 展示连接，或添加某连接器的 API 密钥 │ └─ balance [connector] 余额 + 美元估值（永续合约：仓位 + 净价值） │ ├─ ── 创建、加载与配置 ── │ ├─ create <strategy> 创建策略配置（--set k=v，或 --with-defaults 生成脚手架） │ ├─ import <config> 加载现有配置作为当前策略 │ └─ config [key] [value] 全局客户端设置 + 已加载策略的配置 │ ├─ ── 运行与控制 ── │ ├─ deploy <target> 一键式：创建/加载配置并启动（--set k=v） │ ├─ start [config] 启动 bot（默认用已导入的配置）；--replace 可切换 │ └─ stop 优雅停止（撤销订单）；--force 强制终止 │ └─ ── 观测与维护（[name] = 过往/已停止的 bot）── ├─ status 运行状态、实时状态、近期错误 ├─ logs [name] 追踪日志（-f 跟随） ├─ history [name] 每个市场的 PnL、手续费、成交量 ├─ doctor 健康检查：密钥库、时钟偏差、磁盘、陈旧状态（exit 0 = 健康） └─ update 将 hbot 自身更新到该分支的最新版（--check 预览）

doctor：把零散的运行时错误前置为一次体检

doctor执行那些原本会以一条条令人困惑的运行时错误逐个浮现的检查：安装/扩展健全性、密钥库可解锁（当设置了HBOT_PASSWORD时）、时钟偏差（与互联网时间对比——签名交易所请求会拒绝漂移的时钟）、交易数据库与日志的可用磁盘空间、陈旧的bot.pid、以及悬空的已加载配置指针。任何fail行都会以退出码 1 结束；warn只是建议，退出码仍为 0。

源码 hummingbot/cli/commands/doctor.py 将检查实现为一张表驱动的CHECKS列表，每个检查返回一行{check, status, detail}：

• 时钟偏差阈值（doctor.py）：偏差 ≤ 2 秒为ok；≤ 10 秒为warn（签名请求可能开始失败，建议同步 NTP）；超过 10 秒为fail（签名请求必然失败）。网络超时设为 5 秒，时间源优先api.kraken.com，失败时回退到cloudflare.com的Date响应头，并对 RTT 做补偿。
• 磁盘阈值：剩余 < 100 MiB 直接fail，< 1 GiB 为warn。
• bot 状态检查：通过 hummingbot/cli/bot.py 的is_engine_pid()判断 pid 是否既存活且确实是 hummingbot 引擎进程——避免kill -9或容器重启后残留的bot.pid指向已死或被复用的 pid，从而把死 bot 误报为运行中。

每个检查被 try/except 包裹，任何意外异常只会变成该检查的一行fail，而不会让整条命令崩溃。

update：按安装类型更新软件本体

update更新软件本身，行为取决于安装类型：

• 源码安装：快进当前分支，并且仅在编译源文件发生变化时才重建 Cython 扩展；
• Docker 安装：快速失败并给出宿主侧命令（docker compose pull && docker compose up -d）——容器无法替换自己的镜像。

它拒绝在 bot 运行期间执行更新，也拒绝在分支发生分叉（diverged）时自作主张。

四、实战走查：从连接器到运行中的 bot

以下是一段完整的端到端流程（摘自原文档并补充注释）：

# 1. 连接一个连接器（密钥用你的 keystore 密码加密） hbot connect hyperliquid_perpetual --fields # 它需要哪些密钥字段？ hbot connect hyperliquid_perpetual # 填入密钥 hbot balance # 确认资金 # 2. 创建策略配置（Agent 场景：一步填齐所有必填字段） hbot create pmm_simple --name conf_eth.yml \ --set connector_name=hyperliquid_perpetual --set trading_pair=ETH-USD # ...或者先生成脚手架，稍后再填字段： hbot create pmm_simple --name conf_eth.yml --with-defaults # 默认值 + 空必填字段，并加载它 hbot config # 查看全局 + 该策略的字段 hbot config total_amount_quote 250 # 启动前填/调一个字段 # （已有 .yml？跳过 create 直接加载：hbot import conf_eth.yml） # 3. 运行 hbot start # 运行已加载的配置（或：hbot start conf_eth.yml） hbot status # 是否健康？ hbot logs -f # 实时查看（Ctrl-C 停止） # 4. 调参、观测、停止 hbot config buy_spreads 0.001 # 控制器实时热调（约 10 秒生效） hbot history # PnL、手续费、成交量 hbot stop # 优雅停止，撤销订单 # 5. 事后按名称回顾已停止的 bot hbot history conf_eth

create → config → start。create从策略生成配置并加载它；config查看并填充字段；start运行已加载的配置。创建时有两种填充方式：用--set key=value或--values-stdin提供全部必填字段，得到一个开箱即用的配置（适合 Agent）；或用--with-defaults写出一个脚手架（默认值 + 空白必填字段），再用config补齐（适合人类）。执行create <strategy>时若缺少必填字段，会精确列出缺失项——这本身也充当“字段发现”机制。如果已有.yml（来自 dashboard、API、示例），直接用import即可。

create 的源码级细节

hummingbot/cli/commands/create.py 揭示了create的完整决策链：

• 类型消歧（_resolve_strategy_type）：先看显式标志，否则按名称匹配类型；若一个名称同时命中多个类型则报错并提示用--controller等标志消歧；若完全未命中则列出当前全部可用策略（名称发现）。
• 值合并（_collect_values）：--values-stdin读入的 JSON 对象与--set键值对合并，--set优先。
• 命名规则：配置名跨类型唯一。显式--name撞名是硬错误（并给出建议名）；默认名会自动顺延到下一个空闲的conf_<strategy>_N.yml。
• 严格默认：缺必填字段且未传--with-defaults时，返回CONFIG_ERROR（退出码 4），并列出缺失项。
• 创建后自动加载：成功后调用bot.write_loaded(out_name, stype)，于是hbot config立即能显示它、hbot start不带参数即可运行它。

deploy——一键式命令

deploy把整个“配置 → 运行中 bot”的流程打包成一条命令，面向不需要中间步骤的 Agent 与脚本：

# 已有配置文件 →（可选 --set 修改）→ 运行中的 bot hbot deploy conf_eth.yml hbot deploy conf_eth.yml --set total_amount_quote=500 # 策略/控制器/脚本名称 → 创建开箱即用配置 → 运行中的 bot hbot deploy pmm_simple --set connector_name=hyperliquid_perpetual --set trading_pair=ETH-USD

目标解析优先按配置文件（配置名跨类型唯一）；其余情况必须是可创建的策略名，且全部必填字段都要通过--set/--values-stdin提供——因为deploy的契约是一个运行中的 bot，所以不存在--with-defaults。--replace、--foreground、--password-stdin、--timeout、--json的行为与start完全一致（两者共享 start.py 中的launch()核心）。

五、运行与观测的细节

• 一安装一 bot：start在已有 bot 运行时直接失败；传--replace会先优雅停止旧 bot 再启动新的。配置类型从所在目录自动检测。
• config key value写运行中 bot 的配置文件：控制器可实时更新的字段约10 秒内生效；其他字段（以及 v1/v2 脚本）在下次启动时生效——回复会明确告知是哪种。
• status报告运行状态、策略实时状态与近期错误计数：一个 bot 可以“活着且在报错”——务必检查。stop是优雅的，会撤销未平订单。
• logs/history接受 bot 名称（即此前一次start的配置 stem），用于检视过往/已停止的 bot。history还会拉取实时余额，所以是最慢的一条。
• logs -f跟随输出直到中断——写脚本时请给它加个时限（如 timeout）；不带-f的logs立即返回。

从运行机制上看，hbot start会派生一个分离的引擎子进程（python -m hummingbot.cli.engine --name <name>，见 hummingbot/cli/engine.py），并把新 pid 写入data/bot/bot.pid。引擎与交互式客户端的run_headless()不同——后者强制依赖 MQTT broker，而引擎用自己的事件循环保活进程。状态按需计算：引擎只在收到SIGUSR1（由hbot status触发）时、启动时以及关闭时各写一次新鲜的status.json，没有轮询间隔，查询频率完全由 Agent 决定；收到SIGTERM/SIGINT则优雅停策（撤销未平订单）后退出。hbot start则轮询该快照直到engine.strategy_running为真（默认超时 120 秒，可用--timeout调整），超时返回TIMEOUT（退出码 5），启动中退出则附带近期日志。

六、Roadmap：v1 刻意推迟的命令与未来 UX

v1 是交互式 Hummingbot 客户端命令的忠实子集——目标是让现有源码/Docker 用户以非交互方式用上他们熟悉的命令。上一代 CLI 的某些命令被刻意推迟，以保持 v1 贴近客户端命令面，将在后续版本回归：

移除这些并非引擎能力损失——只是 CLI 命令面的损失——每项都登记在案，待核心客户端对齐稳固后回归。

未来 UX（提案，超越客户端对齐）

面向首次运行体验与可运维性的新命令提案：

七、输出格式与退出码契约

默认情况下每条命令都在 stdout 输出紧凑的Markdown：记录列表用表格，单条记录用- key: value键值块。错误输出到 stderr，格式为Error: <message> (code N)。运行/观测命令（deploy、start、stop、status、logs、config、balance）额外支持--json，输出带原始值的机器可读对象（例如hbot status --json→{"running": true, "pid": …, "errors": {…}, …}）。

无论哪种输出形式，结果判定的机器契约都是退出码——按退出码分支，而不是按文本：

这个枚举在 hummingbot/cli/output.py 中定义为ExitCode(IntEnum)；fail()统一把错误打到 stderr 并携带码退出。输出层另有render_table()（对齐的 Markdown 表格，末列不填充以省 token）与render_kv()（键值块），以及emit()——--json时输出携带原始值（数字保持数字，Decimal 等非 JSON 类型经str序列化）的 payload，Agent 无需反向解析人类可读的渲染结果。

八、密码与密钥安全

keystore 密码用于解锁你加密的密钥。提供密码时不要放在命令行参数（argv）里——argv 对ps、/proc、shell 历史与 Agent 工具日志可见。两种安全方式：

# 方式一：环境变量 export HBOT_PASSWORD='...' hbot start conf_eth.yml # 方式二：通过 stdin 管道（绝不落 argv） printf '%s' "$PW" | hbot start conf_eth.yml --password-stdin

密码缺失或错误会以退出码 4 快速失败——命令永远不会挂起等待输入。这在 hummingbot/cli/password.py 中实现为三级解析顺序：--password-stdin（自动化、docker-login 风格）→$HBOT_PASSWORD/$CONFIG_PASSWORD环境变量 → 仅在 stdin 是 TTY 时的隐藏交互提示；三者都不可用时直接fail(... , CONFIG_ERROR)。

在全新安装上还没有 keystore——你第一次提供的密码（首次运行hbot connect/balance/start时）会成为你的 keystore 密码，与交互式客户端的首次启动行为一致；之后每条命令都必须使用同一密码。unlock_keystore()会在首启时自动写入密码校验文件（store_password_verification），密码错误则返回退出码 4。

还有一个容易被忽略的安全细节：hbot start会把密码通过环境变量传给引擎子进程，而 hummingbot/cli/engine.py 在引擎启动后会立即把HBOT_PASSWORD/CONFIG_PASSWORD从进程环境中抹除——这样引擎（或连接器）后续派生的任何子进程都不会继承 keystore 密码。密码只应存在于这一个变量里，而非可继承的 env 中。

九、在 Docker 中运行

自动化/Agent 驱动场景推荐 Docker。镜像预装了 conda 环境与编译好的 Cython 扩展，没有 Miniconda 下载、conda env create、ToS 提示或数分钟的扩展编译——只要make deploy && make link-cli。仅当你需要构建或修改代码时才使用源码安装。

hbot在 Docker 中与源码安装完全一致——同样的命令、同样的流程。默认情况下make deploy拉起运行经典交互式客户端的hummingbot容器（docker attach hummingbot使用它）。要让容器专用于hbot，请启用idle "hbot host"模式——容器只是保持运行，每条hbot命令都 exec 进容器执行——只需在docker-compose.yml中取消注释一行：

# docker-compose.yml，在 hummingbot 服务下，取消注释： # command: tail -f /dev/null make deploy # 启动容器（一个空闲的 hbot host） make link-cli # 安装宿主侧的 `hbot` 命令（-> docker exec 进容器） hbot connect binance # 与源码安装完全相同的命令 hbot import conf_my_bot.yml # 加载你放进 conf/ 的配置 hbot start conf_my_bot.yml hbot status ; hbot logs -f ; hbot stop

宿主侧包装器（bin/hbot-host）自动探测运行位置，bin/hbot 则是进入 conda 环境/容器内真正 CLI 的启动器。make link-cli将包装器符号链接到 PATH 上，于是hbot <command>无论安装方式如何都能工作：

1. 站在一个正在运行的 compose 项目内→docker exec进其hummingbot容器（容器内的conf/data/logs是宿主用户拥有的 bind mount，宿主侧 CLI 本来也写不进去）；
2. 有hummingbotconda 环境→ 直接在环境内运行（注意包装器直接 exec 环境的 python，而非conda run——后者会在每个非零退出码上打一行噪音ERROR conda.cli.main_run...，把健康的 CLI 弄得像坏了）；
3. 有运行中的hummingbot容器→docker exec进它。

HBOT_PREFER=docker可以在两种安装都存在的机器上强制走容器。包装器还会显式把宿主侧的HBOT_PASSWORD/CONFIG_PASSWORD通过-e VAR转发进容器（docker exec默认使用容器的 env，宿主侧密码不会自己传过去），并仅在当前 shell 有 TTY 时附加-t，保证管道输入（如--password-stdin）依然可用。不用包装器的话，docker exec -it hummingbot hbot <command>做的是同一件事。

idle-host 容器必须跑一个真正的 init（compose 文件设置了init: true），这样 bot 进程——在启动它的docker exec返回后 reparent 到 PID 1——退出时才能被回收。裸tail作为 PID 1 不会回收僵尸进程，会让hbot stop等满整个超时。如果你自己docker runidle host，请传--init。

单容器单 bot（编排场景）

做编排（一容器 = 一 bot、重启策略）时，用hbot start --foreground让 bot 成为容器的主进程——之后docker stop发送 SIGTERM，bot 优雅关机（撤销订单）：

services: bot: image: hummingbot/hummingbot environment: [HBOT_PASSWORD] volumes: - ./conf:/home/hummingbot/conf - ./data:/home/hummingbot/data - ./logs:/home/hummingbot/logs command: hbot start conf_my_bot.yml --foreground # bot 就是容器的 PID 1

（没有--foreground时，hbot start是分离式启动并立即返回——在宿主上没问题，但作为容器命令会立刻退出并停掉容器。）--foreground的实现是os.execve直接替换当前进程（start.py），保持同一 PID，因此记录的 pid 就是引擎的 pid，stdout/stderr 仍附着在终端/容器上（可用docker logs查看）。无论哪种方式，都不要在同一个容器里同时跑hbot与交互式客户端——那会让两个 bot 争抢同一套conf/data/logs。

十、文件与状态布局

conf/strategies/ conf/scripts/ conf/controllers/ # 你的配置文件（.yml），按类型分 conf/conf_client.yml # 全局设置（hbot config 管理） data/bot/ # 当前 bot：meta.json, bot.pid, status.json, bot.log, loaded.json data/<name>.sqlite # 某个 bot 的交易数据库（name = 配置 stem） logs/logs_<name>.log # 某个 bot 的结构化日志

各命令的数据来源一目了然：

• status读data/bot/status.json（运行中的 bot 每几秒写入的快照，实际由引擎在收到 SIGUSR1 时按需刷新，见 hummingbot/cli/engine.py）；
• history读 SQLite 库；logs追踪logs/logs_<name>.log；
• import/start把已加载配置记录到data/bot/loaded.json。

由于数据库和日志都以配置 stem 命名，已停止 bot 的日志/历史可以永久按名查看（db_path_for()/structured_log_for()还会尝试点号展平的变体名，见 hummingbot/cli/bot.py）。

陈旧状态永远不会伪装成实时状态：

• 快照（市场/订单/余额）只在 bot 运行期间渲染；
• 记录的 pid 只有确实是 hummingbot 引擎进程时才被信任（is_engine_pid()检查进程 cmdline 是否含hummingbot.cli.engine）——被kill -9或容器重启打断的 bot 可能留下指向已死或被复用 pid 的bot.pid；
• 上次运行之后新导入的配置会在status中取代已停止 bot 的记录（显示为imported, not started，并把上一次运行标记为last_run）。

doctor的_bot_row/_loaded_row检查正是这些陈旧状态的体检项：陈旧 pid 只是warn（下一次 start/stop 会自动清除），而悬空的已加载配置指针同样以warn提示重新import。

结语

hbot把 Hummingbot 的交互式命令面以非交互、可脚本化、机器可读的方式完整重建了一遍：三类配置的自动类型检测、create → config → start的生产链路、deploy一键式部署、稳定的 Markdown/JSON 双轨输出与五级退出码契约、不落 argv 的密钥安全模型，以及源码/Docker 两套安装下完全一致的使用体验。对 Agent、LLM 与运维脚本而言，hbot的价值在于把“判断命令成败”从解析文本降级为读取退出码——这正是其设计文档所强调的：branch on it, not on the text。

• 金融科技
• CLI