第 10 章 · 03 插件系统

第 10 章 · 03 插件系统

本节摘要:freqtrade 的插件系统分两大类:pairlist(交易对过滤器)决定 bot 交易哪些币，protection(保护机制)在异常行情下自动暂停交易。pairlist 是链式的——多个处理器按顺序串联，前一个的输出是后一个的输入，从 StaticPairList/VolumePairList 生成候选，再用 AgeFilter、PriceFilter、SpreadFilter、VolatilityFilter 等层层筛选。protection 则在策略里以 protections 属性声明，含 StoplossGuard(连亏暂停)、MaxDrawdown(最大回撤保护)、CooldownPeriod(平仓冷却)、LowProfitPairs(低盈币锁定)。本节讲清这两类插件的配置与组合，帮你打造稳健的交易对池与风控墙。

内容来源:原项目文档 docs/plugins.md、docs/includes/pairlists.md、docs/includes/protections.md，汉化并套用体系化模板。

⚠️ 风险提示:不是所有 pairlist/protection 适配所有策略，参数要按自己的策略调优。多数动态 pairlist(如 VolumePairList)不支持回测，调试配置建议用 FreqUI 的 webserver 模式或 test-pairlist 命令。

学习目标

阅读完本节，你应当能够:

1. 理解 pairlist 的链式处理机制。
2. 配置 StaticPairList 与 VolumePairList 及其高级模式。
3. 用 AgeFilter/PriceFilter/SpreadFilter/VolatilityFilter 等过滤器筛选。
4. 在策略里声明 protections 属性。
5. 组合 StoplossGuard/MaxDrawdown/CooldownPeriod/LowProfitPairs。

一、pairlist 链式处理:候选生成 + 层层过滤

pairlist 处理器在配置的 pairlists 数组里声明，按顺序串联执行:

第一位必须是候选生成器(StaticPairList、VolumePairList、ProducerPairList、RemotePairList、MarketCapPairList、PercentChangePairList、CrossMarketPairList 之一)，后面跟零到多个过滤器(AgeFilter、PriceFilter、SpreadFilter、VolatilityFilter、RangeStabilityFilter、ShuffleFilter、PerformanceFilter、PrecisionFilter 等)。

黑名单(exchange.pair_blacklist)在最后总会被移除，支持正则通配符(如 BNB/.* 排除所有 BNB 对)。

💡 测试技巧:pairlist 配置很容易出错。用 FreqUI 的 webserver 模式或 freqtrade test-pairlist 命令快速验证，不用真跑交易。

二、候选生成器

StaticPairList(默认):用配置里的 exchange.pair_whitelist 静态定义:

"exchange": {
    "pair_whitelist": ["BTC/USDT", "ETH/USDT"],
    "pair_blacklist": ["BNB/USDT"]
},
"pairlists": [{"method": "StaticPairList"}]
​

VolumePairList:按 24h 成交额(quoteVolume)排序选 top N。第一位使用时，pair_whitelist 被忽略，直接从交易所所有匹配计价币的市场里选:

"pairlists": [
    {
        "method": "VolumePairList",
        "number_assets": 20,
        "sort_key": "quoteVolume",
        "min_value": 0,
        "max_value": 8000000,
        "refresh_period": 1800
    }
]
​

高级模式用历史 K 线算滚动成交量(更平滑):

"pairlists": [
    {
        "method": "VolumePairList",
        "number_assets": 20,
        "sort_key": "quoteVolume",
        "refresh_period": 86400,
        "lookback_days": 7
    }
]
​

⚠️ VolumePairList 不支持回测。它也不支持与 FreqAI 联用(动态增删币对会导致数据来不及准备)。但 ShufflePairList 或保持总数不变的 VolumePairList 可以。

其他生成器:

三、过滤器:层层把关

AgeFilter:排除上市不足 min_days_listed 天(默认 10)或超过 max_days_listed 天的币。新币价格波动剧烈，等它稳定再交易。

PriceFilter:按价格过滤，含 min_price、max_price、max_value、low_price_ratio。low_price_ratio 排除「一个价格步就涨很多」的低流动性币(如价格 0.00000011，下一步 0.00000012 涨 9%)。

SpreadFilter:排除买卖价差比超过 max_spread_ratio(默认 0.005)的币。价差大说明流动性差，滑点会吃掉利润。

"pairlists": [
    {"method": "VolumePairList", "number_assets": 30, "sort_key": "quoteVolume"},
    {"method": "AgeFilter", "min_days_listed": 10},
    {"method": "PriceFilter", "low_price_ratio": 0.01},
    {"method": "SpreadFilter", "max_spread_ratio": 0.005}
]
​

RangeStabilityFilter:排除 lookback_days 内波动幅度太小(如稳定币对)或太大的币。设 min_rate_of_change 和 max_rate_of_change。

VolatilityFilter:按对数日收益的标准差(波动率)过滤，排除波动率过低或过高的币。

ShuffleFilter:随机打乱顺序，避免 bot 总优先交易排前面的币。设 seed 可复现(回测用)。

PerformanceFilter:按历史交易表现排序——盈利的排前、无交易的居中、亏损的排后。需 bot 有几百笔交易后才稳。

⚠️ PrecisionFilter、PerformanceFilter、ShuffleFilter 等多个过滤器不支持多策略回测或回测模式，详见文档。生产用没问题。

四、完整 pairlist 示例

一个稳健的 pairlist 链:

"exchange": {
    "pair_whitelist": [],
    "pair_blacklist": ["BNB/BTC"]
},
"pairlists": [
    {"method": "VolumePairList", "number_assets": 20, "sort_key": "quoteVolume"},
    {"method": "DelistFilter", "max_days_from_now": 0},
    {"method": "AgeFilter", "min_days_listed": 10},
    {"method": "PrecisionFilter"},
    {"method": "PriceFilter", "low_price_ratio": 0.01},
    {"method": "SpreadFilter", "max_spread_ratio": 0.005},
    {
        "method": "RangeStabilityFilter",
        "lookback_days": 10, "min_rate_of_change": 0.01,
        "refresh_period": 86400
    },
    {
        "method": "VolatilityFilter",
        "lookback_days": 10, "min_volatility": 0.05, "max_volatility": 0.50,
        "refresh_period": 86400
    },
    {"method": "ShuffleFilter", "seed": 42}
]
​

逻辑:选 top 20 成交量 → 排除即将下架 → 排除上市不到 10 天 → 排除精度问题币 → 排除低价低流动性 → 排除高价差 → 排除波动太小/太大 → 随机打乱。

五、protection:异常行情自动熔断

protection 在策略里以 protections 属性声明，在异常情况下临时锁定某些交易对或全部交易。所有 protection 的结束时间向上取整到下一根 K 线，避免 K 线内突然重开。

回测时需加 --enable-protections 才生效。

StoplossGuard:一段时间内止损次数达标就暂停:

@property
def protections(self):
    return [
        {
            "method": "StoplossGuard",
            "lookback_period_candles": 24,   # 看最近 24 根 K 线
            "trade_limit": 4,                # 达 4 次止损
            "stop_duration_candles": 4,      # 暂停 4 根 K 线
            "required_profit": 0.0,          # 只算亏损的止损
            "only_per_pair": False,          # False=全局，True=单币
            "only_per_side": False           # 合约可按多/空分
        }
    ]
​

MaxDrawdown:回撤超阈值就暂停。支持两种计算:calculation_mode: "equity"(基于权益曲线，推荐新项目)和 "ratios"(基于累计盈亏比，兼容旧逻辑):

{
    "method": "MaxDrawdown",
    "calculation_mode": "equity",
    "lookback_period_candles": 48,
    "trade_limit": 20,
    "stop_duration_candles": 12,
    "max_allowed_drawdown": 0.2   # 20%
}
​

CooldownPeriod:平仓后冷却一段时间不再开该币，给其他币机会:

{"method": "CooldownPeriod", "stop_duration_candles": 2}
​

LowProfitPairs:某币近期交易总盈亏低于阈值就锁它:

{
    "method": "LowProfitPairs",
    "lookback_period_candles": 6,
    "trade_limit": 2,
    "stop_duration": 60,
    "required_profit": 0.02
}
​

💡 通用参数:所有 protection 都可用 stop_duration(分钟)或 stop_duration_candles(K 线数)定锁定时长，用 lookback_period(分钟)或 lookback_period_candles 定回看窗口。两者不能混用，推荐用 K 线数(切换时间周期更灵活)。

六、组合 protection 筑墙

protection 可多次声明、层层加码。下面这个例子(1h 时间周期)筑了五道墙:

@property
def protections(self):
    return [
        # 1. 平仓后冷却 5 根 K 线
        {"method": "CooldownPeriod", "stop_duration_candles": 5},
        # 2. 最近 48h(48 根)交易达 20 笔且回撤>20%，暂停 4 根 K 线(4h)
        {
            "method": "MaxDrawdown",
            "calculation_mode": "equity",
            "lookback_period_candles": 48,
            "trade_limit": 20,
            "stop_duration_candles": 4,
            "max_allowed_drawdown": 0.2
        },
        # 3. 最近 24h 全局止损达 4 次，暂停 2 根 K 线
        {
            "method": "StoplossGuard",
            "lookback_period_candles": 24,
            "trade_limit": 4,
            "stop_duration_candles": 2,
            "only_per_pair": False
        },
        # 4. 最近 6h 某币 2 笔交易总盈利<2%，锁 60 分钟
        {
            "method": "LowProfitPairs",
            "lookback_period_candles": 6,
            "trade_limit": 2,
            "stop_duration": 60,
            "required_profit": 0.02
        },
        # 5. 最近 24h 某币 4 笔交易总盈利<1%，锁 2 根 K 线
        {
            "method": "LowProfitPairs",
            "lookback_period_candles": 24,
            "trade_limit": 4,
            "stop_duration_candles": 2,
            "required_profit": 0.01
        }
    ]
​

按声明顺序评估，形成对表现差的交易对的「递增封锁」——越差锁越久。

⚠️ protection 参数必须按你的策略调优。StoplossGuard 的 trade_limit 和 lookback_period 设得太严会频繁误锁，太松又起不到保护作用。先用回测(--enable-protections)验证再上实盘。

本节要点回顾

1. 链式 pairlist:第一位是候选生成器(Static/Volume/MarketCap 等)，后面跟过滤器(Age/Price/Spread/Volatility 等)，按序串联，黑名单最后移除；用 test-pairlist 验证。
2. 生成器:StaticPairList(静态)、VolumePairList(成交量，支持 lookback 滚动，不支持回测/FreqAI)、MarketCap(市值)、Producer/Remote(跨 bot)。
3. 过滤器:Age(上市天数)、Price(价格/流动性)、Spread(价差)、RangeStability(波动幅度)、Volatility(波动率)、Shuffle(随机)、Performance(按历史表现)。
4. protection 声明:策略 protections 属性，回测需 --enable-protections；锁定时长用 K 线数或分钟，回看窗口同理。
5. 四种 protection:StoplossGuard(连亏)、MaxDrawdown(equity/ratios 两种计算)、CooldownPeriod(平仓冷却)、LowProfitPairs(低盈锁币)。
6. 组合筑墙:可多次声明同种 protection，按序评估，对差币递增封锁；参数要按策略调优。

下一节，我们看 SQL 查询速查——直接查 freqtrade 的 SQLite 数据库，做盈亏统计与故障修复。