企业官网建设流程全解析

• 金融科技
• 后端

本文围绕 Gekko 命令行模式下的tradebot（真实交易机器人）展开：讲解如何配置watch、tradingAdvisor、trader、performanceAnalyzer等核心插件，将实时行情监听、技术分析策略与真实交易所下单串联成一条自动化交易流水线。读完本文，你将掌握 tradebot 的完整配置方法、运行命令、API 密钥权限要求，以及其内部"建议 → 订单 → 成交 → 汇总"的源码级执行链路，并了解所有需要规避的风险点。

tradebot 是什么：一图看懂三要素

按照官方文档的定义，把 Gekko 设置为 tradebot 后，它会同时承担三项职责：

1. Watch a live market：实时监听一个真实交易市场（由config.watch指定交易所、币种与资产对）；
2. Run a strategy (in semi-realtime) over live market data：基于实时行情数据，以（半）实时方式运行技术分析策略，产出交易建议（advice）；
3. Automatically create buy/sell orders based on signals coming from the strategy：根据策略产出的买卖信号，自动在真实交易所创建买单与卖单。

这三点对应了 Gekko 流水线（pipeline）中的三个关键环节：行情市场（market）、策略顾问（tradingAdvisor）与执行者（trader）。在 core/pipeline.js 中，Gekko 会先加载所有启用的插件，再依据 subscriptions.js 中的事件订阅关系，把市场产生的candle事件分发给各插件，trader正是通过订阅tradingAdvisor广播的advice事件来完成自动下单的。

文档对 tradebot 给出了一个必须时刻牢记的免责声明：

As with everything in Gekko, the tradebot will make decisions based on the strategy selected/configured/createdby YOU. If you end up losing money, you have no one to blame but yourself.

即：tradebot 的一切决策都来自你选择、配置或编写的策略。它只是把你自己的交易策略自动化执行，并不提供任何投资建议；如果亏损，责任完全在策略本身。这一点在代码层面也有强制体现，详见下文"启动前的确认开关"一节。

前置准备：命令行模式与配置文件

tradebot 属于命令行运行模式，因此需要先按照命令行使用指南把 Gekko 配置为命令行用法：

• 每个命令行实例只运行一个 Gekko 实例，如需同时交易多个市场，需要分别运行多次；
• 复制sample-config.js为独立配置文件（例如config.js），所有插件开关与参数都在该文件中配置。

命令行模式下常用启动方式（详见命令行使用指南）：

# 实时模式（tradebot / 监视器 / paper trader 都属于此模式） node gekko --config config.js # 回测模式 node gekko --config config.js --backtest # 导入模式 node gekko --config config.js --import

运行 tradebot 使用的是不带--backtest/--import的实时模式。更完整的插件参数说明可参考插件配置文档。

需要配置的插件清单

根据官方文档，把 Gekko 变成 tradebot 需要配置以下插件：

同时文档明确要求：关闭paperTrader。原因是"一个实例中只能有一个交易类插件处于活动状态"（there can only be 1 trade plugin active per instance）。这在源码中有直接印证：在 core/pipeline.js 的插件订阅阶段，当paperTrader与trader同时启用并都试图广播advice相关事件时，pipeline 会检测到"多个插件广播同一事件"（Multiple plugins are broadcasting the event ... This is unsupported）并直接终止进程，因此二者必须二选一。

1.config.watch：监听哪个市场

指定要交易的市场，交易所名称、计价货币与交易资产三元组：

config.watch = { exchange: 'binance', // 交易所 slug，见 supported_exchanges 列表 currency: 'USDT', // 计价货币 asset: 'BTC', // 交易资产 }

交易所支持列表可参考 supported_exchanges.md。trader插件的资产/币种均取自config.watch（见下文 trader 源码剖析）。

2.candleWriter（可选）：行情落盘

如果需要把实时行情数据存储到本地（例如用于后续回测），启用 candleWriter。它在 sample-config.js 中的默认形态如下，其中adapter指向你配置的存储适配器（sqlite / postgresql / mongodb）：

config.candleWriter = { enabled: true, adapter: 'sqlite' }

对应的配置文件是 config/plugins/candleWriter.toml，存储适配器可在 sqlite、postgresql、mongodb 间切换，详见 config/adapters 下的 TOML 示例。

3.tradingAdvisor：策略与蜡烛属性

tradingAdvisor是策略运行器：它订阅市场的candle事件，按candleSize聚合蜡烛，并把蜡烛喂给所选策略计算买卖建议。核心配置：

config.tradingAdvisor = { enabled: true, method: 'MACD', // 使用的策略方法名 candleSize: 60, // 蜡烛周期（分钟），例如 60 表示 1 小时 K 线 historySize: 10, // 历史蜡烛数，用于策略预热（warmup） }

对应的 TOML 模板是 config/plugins/tradingAdvisor.toml。在源码 plugins/tradingAdvisor/tradingAdvisor.js 中：

• 插件用new CandleBatcher(config.tradingAdvisor.candleSize)按周期聚合实时蜡烛；
• this.strategyName = config.tradingAdvisor.method决定加载哪个策略文件（策略位于 strategies 目录）；
• 实时模式下，若非 leech 模式，会使用dataStitcher灌入历史数据作为策略预热期（warmup period），这正是historySize发挥作用的环节；
• 策略设置stratSettings直接取自config[this.strategyName]配置块（如config.MACD），所以每个策略的自有参数（如 MACD 的 short/long/signal/thresholds）需要在同名配置块下配置。

策略与蜡烛属性、各内置策略参数的完整说明可参考 sample-config.js 底部的 "OTHER STRATEGY SETTINGS" 部分与策略文档。

4.trader：对接交易所账户并真实下单

trader是 tradebot 的执行核心，它把策略的advice转成真实订单。启用前必须在交易所创建 API 密钥。文档（插件配置文档）特别强调，API 密钥需要具备的权限（各交易所命名不同）包括：get info、get balance/portfolio、get open orders、get fee、buy、sell、cancel order。所有交易所都需要 API key 与 API secret；Bitstamp 和 CEX.io 额外需要username（Bitstamp 中是一串数字）。

config.trader = { enabled: false, key: '', // 你的 API key secret: '', // 你的 API secret username: '', // 用户名，仅在 Bitstamp / CEX.io 等交易所需要 passphrase: '', // GDAX 等交易所需要 passphrase }

对应模板 config/plugins/trader.toml 中有醒目的安全提示：填写密钥后切勿与任何人分享该配置文件。同时，请务必确认你的交易所 wrapper 支持真实交易能力——plugins/trader/trader.js 在初始化 Broker 时会检查this.broker.capabilities.gekkoBroker，不支持时直接终止进程并提示This exchange is not yet supported。

5.performanceAnalyzer：绩效统计

启用 performanceAnalyzer 用于计算交易绩效指标（如夏普比率需要无风险收益率）：

config.performanceAnalyzer = { enabled: true, riskFreeReturn: 5 // 年化无风险收益率（%），用于计算夏普比率 }

对应模板 config/plugins/performanceAnalyzer.toml，注释说明riskFreeReturn是"每年 % 的无风险回报"，例如国债或银行存款利率。

完整可运行的 tradebot 配置示例

综合以上各插件，一份完整的 tradebot 配置文件（基于 sample-config.js 精简）如下。请把key/secret换成你自己的交易所 API 凭证：

var config = {}; config.debug = true; // 输出更多调试日志 // 1. 监听市场（binance 上的 BTC/USDT） config.watch = { exchange: 'binance', currency: 'USDT', asset: 'BTC', }; // 2.（可选）行情落盘 config.candleWriter = { enabled: true, adapter: 'sqlite' }; // 3. 策略配置 config.tradingAdvisor = { enabled: true, method: 'MACD', candleSize: 60, historySize: 10, }; // MACD 策略自身参数 config.MACD = { short: 10, long: 21, signal: 9, thresholds: { down: -0.025, up: 0.025, persistence: 1 } }; // 4. 真实交易插件（tradebot 的核心） config.trader = { enabled: true, key: 'your-api-key', secret: 'your-api-secret', username: '', passphrase: '', }; // 5. 绩效分析 config.performanceAnalyzer = { enabled: true, riskFreeReturn: 5 }; // 6. 必须关闭 paperTrader（同一实例只允许一个交易类插件） config.paperTrader = { enabled: false }; // 7. 确认你已经理解：Gekko 只是自动化"你自己的"交易策略 config['I understand that Gekko only automates MY OWN trading strategies'] = true; module.exports = config;

配置完成后运行：

node gekko --config your-config-file.js

启动前的确认开关：代码层面的安全闸门

入口文件 gekko.js 在启动实时流水线之前，会做一次强制检查：

if( config.trader && config.trader.enabled && !config['I understand that Gekko only automates MY OWN trading strategies'] ) util.die('Do you understand what Gekko will do with your money? Read this first: ...');

也就是说：只要启用了trader，却没有把config['I understand that Gekko only automates MY OWN trading strategies']设为true，Gekko 会直接拒绝启动。sample-config.js 中对这一开关的注释解释得很清楚：输出中的任何 advice 都不是 Gekko 在告诉你该开仓/平仓，而是你所配置指标自动运行的结果——Gekko 自动化的是你自己的交易策略，它自己不做任何建议。

源码级原理：trader 如何把 advice 变成真实订单

在 plugins/trader/trader.js 中可以完整看到真实下单的执行链路：

初始化与账户同步

• 构造函数把config.trader与config.watch合并为brokerConfig，并通过new Broker(brokerConfig)创建交易所 broker（exchange/gekkoBroker.js）；
• 启动时先sync()同步私有数据，输出当前 Portfolio（currency 与 asset 余额）、Balance（折合计价货币的总价值）与 Exposure（暴露仓位比例），之后每 10 分钟自动同步一次（setInterval(this.sync, 1000 * 60 * 10)）；
• setBalance()计算balance = currency + asset * price，exposure = asset * price / balance，当暴露比例超过 10% 时视为"已持仓"（this.exposed = this.exposure > 0.1）。

processAdvice：建议转下单方向

processAdvice(advice)把策略建议映射为下单方向：

• recommendation === 'long'→ 买入（buy）；
• recommendation === 'short'→ 卖出（sell）；
• 其他方向直接忽略并记录错误日志。

随后做持仓校验：

• 买入时若已暴露（this.exposed），放弃买入并广播tradeAborted（原因：Portfolio already in position）；
• 卖出时若未暴露，同样放弃卖出。

买入数量按amount = portfolio.currency / price * 0.95计算（即最多用 95% 的计价货币买入，保留约 5% 缓冲应对价格波动与手续费）；卖出数量为全部持仓资产。

createOrder：创建 sticky 订单

createOrder()使用type = 'sticky'创建订单：

• 先用broker.isValidOrder(amount, price)做下单前校验（用于捕捉交易所的 lot size、价格过滤等非标准错误），校验失败则放弃下单并广播tradeAborted；
• 成功则广播tradeInitiated事件，调用broker.createOrder('sticky', side, amount)；
• 订单生命周期中监听多个事件：fill（部分成交）、statusChange（状态变化）、error（出错后清空订单并广播tradeErrored）、completed（完成后生成订单汇总 summary）。

completed回调中会计算手续费成本与有效成交价（effectivePrice：买入 = price × (1 + fee%)，卖出 = price × (1 − fee%)），广播tradeCompleted事件，并重新同步账户。若交易所未提供费率信息，会给出警告并按零费率假设处理。

反向建议与挂单冲突处理

如果当前已有未完成订单，而收到相反方向的建议：

• 若方向与挂单一致，直接忽略（"already in the process to ..."）；
• 若方向相反且正在取消挂单，忽略新建议；
• 否则先cancelOrder()取消旧挂单，再重新执行processAdvice(advice)处理新建议。

trailingStop 追踪止损

值得注意的一个细节：当买入成交、且该条 advice 携带trigger.type === 'trailingStop'时，trader 会创建追踪止损触发器（broker.createTrigger({type: 'trailingStop', ...})）。此后一旦价格回撤触发止损，onStopTrigger会用一条recommendation: 'short'的 mock advice 重新调用processAdvice自动平仓，从而形成"买入 → 追踪止损保护 → 自动卖出"的完整闭环。相关触发器实现可参考 exchange/triggers/trailingStop.js 与粘性订单/触发器文档。

启动后的事件流

• 首个蜡烛到来时广播首次portfolioChange，之后每根蜡烛更新价格并视余额变化广播portfolioValueChange；
• 下单全过程的tradeInitiated/tradeCompleted/tradeAborted/tradeErrored/tradeCancelled等事件，可被 eventLogger、邮件、Telegram 等通知插件订阅，用于实时掌握机器人交易动态。

安全与运行建议

1. 先回测、再模拟盘、最后实盘：入口文件 gekko.js 的头部声明明确建议先以 paper trading 和回测验证策略，再考虑实盘。
2. API 密钥最小权限：仅授予交易所需权限（查询余额、下单、撤单），不要把提现权限暴露给机器人；key/secret/passphrase等凭证切勿分享。
3. 同一实例一个交易插件：paperTrader与trader必须二选一，同时启用会导致 pipeline 报错退出。
4. 确认开关必须置真：config['I understand that Gekko only automates MY OWN trading strategies'] = true是 trader 启动的必要条件。
5. 策略参数务必自查：tradebot 会严格执行你所配置的策略与参数，任何错误的指标配置都会直接影响真金白银，务必核对 sample-config.js 中各策略参数的语义后再上线。

• 金融科技
• 后端