跳到主要内容

十二、插件系统

十二、插件系统​

12.1 插件系统概述​

OpenQuant提供了强大的插件系统，支持功能扩展和定制化需求。插件系统允许用户通过配置文件启用或禁用特定功能，实现模块化的系统架构。

11.1.1 插件配置​

⚠️ 重要说明：

  • 折扣币自动购买插件默认关闭，如需使用请手动在配置中设置 enabled = true
  • 该功能需要同时启用插件配置和交易所配置中的折扣币功能
  • 建议在测试环境验证配置无误后再在实盘环境使用

在 config.toml 中配置插件：

[[plugin.plugins]]
name = "插件名称"
enabled = true
priority = 100
auto_restart = false
restart_delay = 5
max_restarts = 3

[plugin.plugins.config]
# 插件特定配置

11.1.2 插件参数说明​

参数类型默认值说明
name字符串-插件名称，必须字段
enabled布尔值true是否启用插件
priority整数100插件优先级，数值越小优先级越高
auto_restart布尔值false插件异常时是否自动重启
restart_delay整数5重启延迟时间（秒）
max_restarts整数3最大重启次数

12.2 折扣币自动购买插件​

折扣币自动购买插件是一个智能化的交易费用优化工具，通过自动购买和管理交易所原生代币（如BNB等），为用户提供交易手续费折扣，降低交易成本。

11.2.1 功能特性​

  • 自动购买：根据配置的阈值自动购买折扣币
  • 智能管理：自动维持指定数量的折扣币余额
  • 多交易所支持：支持现货、合约等不同账户类型
  • 故障恢复：具备状态持久化和断点续传功能
  • 安全可靠：内置重试机制和完整的错误处理

11.2.2 配置说明​

插件基础配置

在 config.toml 中添加插件配置：

[[plugin.plugins]]
name = "DiscountCoin"
enabled = true
priority = 100
auto_restart = false
restart_delay = 5
max_restarts = 3

[plugin.plugins.config]
check_interval = 60  # 检查间隔（秒）

交易所折扣币配置

⚠️ 重要说明：

  • 折扣币自动购买功能默认关闭，如需使用请手动在配置中设置 enabled = true
  • 该功能需要插件系统支持，请确保已正确配置插件
  • 建议在测试环境验证配置无误后再在实盘环境使用

支持的交易所：

  • BinanceSwap: 支持BNB折扣币自动购买
  • BinanceSpot: 支持BNB折扣币自动购买
  • OkxSwap: 支持OKB折扣币自动购买
  • OkxSpot: 支持OKB折扣币自动购买
  • BybitSwap: 支持BIT折扣币自动购买
  • GateSwap: 支持GT折扣币自动购买
  • BitgetSwap: 支持BGB折扣币自动购买

在交易所配置中添加折扣币配置：

[[exchanges]]
exchange = "BinanceSwap"
key = "your_api_key"
secret = "your_secret_key"
# ... 其他交易所配置

[exchanges.discount_coin_config]
enabled = true                    # ⚠️ 重要：必须手动设置为true才能启用折扣币功能
unit = "Quote"                   # 计算单位：Quote(计价币价值) 或 Token(代币数量)
maintenance = 16.0               # 维持数量
buy_multiplier = 0.6            # 购买触发阈值倍数（可选，默认0.6）
quote_currency = "USDT"         # 计价货币（可选，默认USDT）
quote_back_threshold = 50.0     # 剩余资金回转阈值（可选，默认50.0）
spot_index = 0                  # 现货API索引（可选）

配置参数详解

参数类型默认值说明
enabled布尔值false是否启用折扣币自动购买功能 ⚠️ 重要：默认关闭，如需使用请手动设置为 true
unit枚举"Quote"计算维持数量的单位："Quote"（计价币价值）或 "Token"（代币数量）
maintenance浮点数200.0维持数量：当 unit = "Quote" 时为计价币价值，当 unit = "Token" 时为代币数量
buy_multiplier浮点数0.6购买触发阈值倍数：购买触发阈值 = maintenance × buy_multiplier
quote_currency字符串"USDT"用于购买折扣币的计价货币
quote_back_threshold浮点数50.0当现货账户剩余计价币低于此值时，自动转回合约账户
spot_index可选整数None指定现货API配置索引（当合约和现货使用不同API密钥时）
check_interval整数60检查间隔时间（秒）

11.2.3 内部流程​

初始化流程

主流程：现货账户

主流程：合约账户

详细步骤：

  1. 步骤1：转入资金到现货账户

    • 从合约账户转入购买所需的计价币
    • 转入金额 = 购买金额 × 1.02（增加2%滑点保护）
    • 支持重试机制，最多3次

  2. 步骤2：购买折扣币

    • 在现货账户创建市价买单
    • 等待订单完成并记录实际购买数量
    • 保存订单状态以便恢复

  3. 步骤3：转回折扣币

    • 将购买的折扣币转回合约账户
    • 转账数量取实际购买数量和现货余额的较小值
    • 处理可能的手续费扣除

  4. 步骤4：转回剩余资金

    • 检查现货账户剩余计价币
    • 如果余额低于 quote_back_threshold，转回合约账户
    • 保持现货账户资金最小化

11.2.4 故障恢复机制​

插件具备完善的故障恢复能力：

状态文件位置： data/discount_states/{exchange}.json

状态文件内容：

{
  "current_step": "TransferIn",
  "symbol": "BNBUSDT",
  "amount": 0.1,
  "need_quote": 30.5,
  "order_id": "123456789",
  "actual_amount": 0.1,
  "last_update": 1640995200
}

11.2.5 购买触发条件​

Quote 模式示例（默认）

配置：maintenance = 16, buy_multiplier = 0.6
触发条件：当前BNB价值 < 9.6 USDT (16 × 0.6)
购买数量：(16 - 当前价值) / BNB价格

Token 模式示例

配置：maintenance = 50, buy_multiplier = 0.6
触发条件：当前BNB余额 < 30 (50 × 0.6)
购买数量：50 - 当前余额

11.2.6 日志说明​

Info 级别日志 只有一条配置信息日志：

[DiscountCoin] BinanceSwap 折扣币配置: 币种=BNB, 计价币=USDT, 维持数量=16, 阈值=9.60, 回转阈值=50

Debug 级别日志 详细的操作流程：

  • 余额查询：[DiscountCoin] BinanceSwap 当前BNB余额: 0.123456
  • 购买计算：[DiscountCoin] BinanceSwap 准备购买: 数量=0.123456 BNB, 价格=1234.5678, 总金额=152.34
  • 订单创建：[DiscountCoin] BinanceSwap 创建市价买单: 交易所=Binance, 数量=0.123456 BNB, 交易对=BNBUSDT
  • 转账操作：[DiscountCoin] BinanceSwap 转入资金: 币种=USDT, 数量=152.34, 从=UsdtFuture 到=Spot
  • 步骤完成：[DiscountCoin] BinanceSwap 转入资金步骤完成

Warning 级别日志 异常情况：

  • 余额不足：[DiscountCoin] 当前USDT余额不足, 余额: 5.00, 需要: 152.34
  • 重试失败：[DiscountCoin] 转入资金到现货账户 在 3 次重试后仍然失败
  • 订单异常：[DiscountCoin] 订单未完成，状态: PartiallyFilled

11.2.7 配置示例​

币安合约账户配置

[[exchanges]]
exchange = "BinanceSwap"
key = "your_api_key"
secret = "your_secret_key"
use_ws_api = false
# 可选：配置代理
proxy = "http://127.0.0.1:7890"

[exchanges.discount_coin_config]
enabled = true
unit = "Quote"
maintenance = 16.0
buy_multiplier = 0.6
quote_currency = "USDT"
quote_back_threshold = 10.0

[[plugin.plugins]]
name = "DiscountCoin"
enabled = true
priority = 100

[plugin.plugins.config]
check_interval = 60

欧易合约账户配置

[[exchanges]]
exchange = "OkxSwap"
key = "your_api_key"
secret = "your_secret_key"
passphrase = "your_passphrase"

[exchanges.discount_coin_config]
enabled = true
unit = "Token"
maintenance = 50.0
buy_multiplier = 0.7
quote_currency = "USDT"
quote_back_threshold = 20.0
spot_index = 1  # 使用不同的现货API配置

11.2.8 最佳实践​

参数设置建议

保守设置（适合大额账户）：

maintenance = 100.0
buy_multiplier = 0.8
quote_back_threshold = 50.0
check_interval = 120

激进设置（适合小额账户）：

maintenance = 10.0
buy_multiplier = 0.5
quote_back_threshold = 5.0
check_interval = 30

交易所特定建议

币安（Binance）：

  • 推荐使用BNB，手续费折扣25%
  • maintenance建议设置为月交易量的0.01%
  • 使用Quote模式更精确控制成本

Bybit：

  • 推荐使用BIT，享受费率优惠
  • 合约和现货可使用统一账户

监控建议

  1. 定期检查余额：确保维持足够的计价币用于购买
  2. 监控日志：关注warning级别日志，及时处理异常
  3. 验证折扣：定期确认交易手续费确实享受了折扣
  4. 检查状态文件：确保没有卡住的流程

11.2.9 故障排除​

常见问题

  1. 插件未启动

    [DiscountCoin] 插件未启动或配置错误

    解决方案：

    • 检查插件配置中的 enabled = true
    • 检查交易所配置中的 discount_coin.enabled = true
    • 确认插件系统已正确加载

  2. 余额不足警告

    [DiscountCoin] 当前USDT余额不足, 余额: 5.00, 需要: 152.34

    解决方案：向账户转入足够的计价币

  3. 最小交易金额限制

    [DiscountCoin] BNB 需要购买 0.001 小于最小名义价值 5, 当前价值: 0.30

    解决方案：调整maintenance参数或增加购买金额

  4. API权限不足 解决方案：确保API密钥具有交易和转账权限

  5. 状态文件损坏 解决方案：删除 data/discount_states/ 目录下对应文件

  6. 插件未启动 解决方案：检查插件配置中的 enabled = true

调试步骤

  1. 启用Debug日志：设置日志级别为debug
  2. 检查配置：验证所有参数设置正确
  3. 测试连接：确保API连接正常
  4. 手动验证：手动执行购买操作验证权限
  5. 检查状态文件：查看是否有未完成的流程

11.2.10 安全注意事项​

  1. API安全：

    • 使用只读+交易权限，避免提现权限
    • 定期轮换API密钥
    • 使用IP白名单限制

  2. 资金安全：

    • 设置合理的maintenance数量
    • 避免过大的购买金额
    • 定期检查账户资金流向

  3. 监控安全：

    • 设置余额监控告警
    • 监控异常交易活动
    • 保持日志审计

11.2.11 性能优化​

  1. 检查间隔：根据交易频率调整check_interval
  2. 重试次数：根据网络状况调整重试策略
  3. 状态清理：定期清理过期的状态文件
  4. 日志级别：生产环境使用info级别，调试时使用debug级别