配置参考与运行手册

说明 config/config.yaml 及关联 .env 字段的含义、取值范围、默认值，以及热更新与运行流程。

1. 总览

配置分为以下章节：

env & 账户
策略模式与参数 (strategy_mode, grid, scalper)
风控 (risk)
对冲 (hedge)
监控与降级 (telemetry, adaptive_mode, liquidity, funding)

所有配置经过 zod 校验：缺失/类型不匹配会阻止启动。运行期可通过配置热更新，但需要遵循金丝雀流程（见下文）。

2. 基础配置

字段	类型 / 默认值	描述	热更新
`env`	`mainnet` \| `testnet`（默认 `testnet`）	影响 API base/WS endpoint	需重启
`api_base`	URL (`https://api.pacifica.fi/api/v1`)	REST 接口根路径	否
`ws_url`	URL (`wss://ws.pacifica.fi/ws`)	行情 WebSocket	否

.env 需提供：

PACIFICA_MAKER_ADDRESS=<address>
PACIFICA_MAKER_PRIVATE_KEY=<base58/base64 ed25519>
PACIFICA_HEDGER_ADDRESS=<address>
PACIFICA_HEDGER_PRIVATE_KEY=<private key>

3. 账户配置

accounts:
  maker:
    address: ${PACIFICA_MAKER_ADDRESS}
    private_key: ${PACIFICA_MAKER_PRIVATE_KEY}
    subaccount: maker-01
    role: maker
  hedger:
    address: ${PACIFICA_HEDGER_ADDRESS}
    private_key: ${PACIFICA_HEDGER_PRIVATE_KEY}
    subaccount: hedger-01
    role: hedger

role 标识账户用途（如 maker/hedger），Runner 会根据该字段分配策略与对冲。若未填写，则使用账户 ID。
address 是 Pacifica 账户地址（API key），用于 REST header X-Pacific-Key 以及下单 payload 中的 account 字段。
private_key 采用 base58 / base64 表示的 Ed25519 私钥。
如需兼容旧配置，可继续使用 api_key / secret 字段，Runner 会自动回退处理，但推荐尽快迁移到新命名。
热更新：❌（变更后必须重启以刷新签名上下文）。

4. 策略模式

strategy_mode: grid  # grid | scalper | both

模式	描述	热更新行为
`grid`	仅运行网格策略	支持，下一周期生效
`scalper`	仅运行剥头皮	支持
`both`	同时运行，Coordinator 协调	支持，需确保两策略配置完整

5. 网格策略 (`grid`)

grid:
  enabled: true
  symbol: BTC
  grid_step_bps: 30
  grid_range_bps: 300
  base_clip_usd: 80
  max_layers: 10
  hedge_threshold_base: 0.12
  tick_size: 1
  lot_size: 0.00001
  adaptive:
    enabled: true
    volatility_window_minutes: 30
    min_volatility_bps: 20
    max_volatility_bps: 200
    min_grid_step_bps: 10
    max_grid_step_bps: 100
    recenter_enabled: true
    recenter_threshold_bps: 150
    recenter_cooldown_ms: 300000
    min_step_change_ratio: 0.2
    tick_interval_ms: 60000
    hedge_pending_timeout_ms: 30000
    post_only_cushion_bps: 5
    min_layers: 8

字段	取值 / 默认	说明	热更新
字段	取值 / 默认	说明	热更新
------	--------------	------	--------
`grid_step_bps`	`10`–`300` (默认 `30`)	初始单层间距 (bps)，自适应启用时作为参考值	支持，立即重挂
`grid_range_bps`	`200`–`800`	覆盖范围	更新后触发 `reset()`
`base_clip_usd`	>0	单层挂单名义	支持
`base_clip_equity_pct`	0–1	按权益比例动态计算的最小 clip（取 `max(base_clip_usd, equity * pct * base_clip_leverage)`）	支持
`base_clip_leverage`	≥1	动态 clip 计算时的杠杆倍数	支持
`max_layers`	`2`–`16`	每侧层数上限	支持
`incremental_mode`	bool (默认 `false`)	启用增量更新模式（优先进行 `reconcileGrid`，减少全量撤挂）	支持
`tick_size`	`>0` (默认 `1`)	价格步长；下单时按此对报价做整形	支持
`lot_size`	`>0` (默认 `0.00001`)	数量步长；下单时向下取整到该步长	支持
`adaptive.enabled`	bool	启用波动率自适应与中心重置	支持
`adaptive.min/max_volatility_bps`	`>0`	映射区间：短期波动率 → 网格间距	支持
`adaptive.min/max_grid_step_bps`	`>0`	网格间距上下限	支持
`adaptive.min_step_change_ratio`	`0.1`–`0.5`	触发重布的最小相对变化	支持
`adaptive.recenter_threshold_bps`	`50`–`400`	中心偏离阈值 (bps)	支持
`adaptive.recenter_cooldown_ms`	≥60_000	单次重心重置后的冷却时间	支持
`adaptive.tick_interval_ms`	≥10_000	自适应检查间隔	支持
`adaptive.hedge_pending_timeout_ms`	10_000–120_000	对冲挂单超时阈值	支持
`adaptive.post_only_cushion_bps`	0–20	Post-only 保护缓冲，计算挂价时加到盘口价差上	支持
`adaptive.min_layers`	2–`max_layers`	目标最少层数，步长放大时自动限制以保持档位	支持
`adaptive.fill_starvation_threshold`	`{ ticks, compress_factor }`	连续无成交触发步长压缩/层数调整（M1.6）	支持

🎯 推荐起始配置：参考 config/grid.example.yaml，适用于测试网或小额实盘。根据账户规模调整 base_clip_usd 与 hedge_threshold_base，并保持 max_base_abs ≥ hedge_threshold_base × 1.5 以预留缓冲。

⚠️ 极限贴盘口模式（实验）：将 grid_step_bps / adaptive.min_grid_step_bps 压到 1–2 bps、post_only_cushion_bps 调至 0–1 bps 并配合 min_layers ≥ 10 可实现“微网格”密集挂单。此时务必：

同步降低 tick_interval_ms、min_step_change_ratio 并启用批次节流，避免一次 burst 触发交易所限频。

若采用多账户部署（如内圈账号专门贴盘口，外圈账号铺外围档位），请在配置中为每个实例分配独立 account_id 并在风控参数中放宽对应账户的 max_base_abs。

预先在测试环境验证 post-only 成功率与 RPC 延迟，再逐步推广至实盘。

6. 剥头皮策略 (`scalper`)

scalper:
  enabled: false
  trigger:
    spread_bps: 180
    obi_threshold: 0.6
    trade_imbalance: 0.55
    min_cooldown_ms: 300
  execution:
    passive_clip_usd: 400
    taker_clip_usd: 200
    tp_bps: 30
    sl_bps: 60

字段	说明	默认	范围	热更新
`spread_bps`	触发最小价差	180	120–400	支持
`obi_threshold`	订单簿不平衡阈值	0.6	0.3–0.8	支持
`trade_imbalance`	成交流偏置	0.55	0.4–0.8	支持
`min_cooldown_ms`	触发冷却	300	≥100	支持
`tp_bps`	止盈	30	10–80	支持
`sl_bps`	止损	60	20–120	支持

热更新后，Scalper 在下一次触发时使用新参数。

7. 风控 (`risk`)

risk:
  max_notional_abs: 100000
  max_base_abs: 0.8
  max_order_sz: 0.2
  kill_switch:
    drawdown_pct: 0.5     # 累计回撤 50bps 触发停机
    triggers:
      - type: delta_abs
        threshold: 1.6    # |Delta| > 1.6 BTC
      - type: hedge_failure_count
        threshold: 3      # 连续对冲失败 3 次
      - type: data_gap_sec
        threshold: 3      # 行情断流 3 秒
      - type: pnl_drawdown
        threshold: 1.0    # 单独的 PnL 触发（可选）

max_notional_abs：策略总名义，若超出 RiskEngine 拒单。
max_base_abs：库存上限；对网格策略尤为重要。
max_order_sz：单笔订单上限；适配拆单逻辑。
kill_switch 支持多触发器；可扩展 latency_p99, funding_correlation, stp_rate 等指标。
热更新：允许调整阈值；若需要更改 kill-switch 类型，应经评审后重启。

8. 对冲 (`hedge`)

hedge:
  kp: 0.6
  ki: 0.05
  qmax: 0.4
  min_interval_ms: 200
  latency_budget:
    target_p50_ms: 500
    target_p99_ms: 2000
    max_exposure_sec: 3
    retry_max: 2
    retry_slippage_increment_bps: 5

字段	说明	备注
`kp`, `ki`	PI 控制参数	需结合回测调节
`qmax`	单次对冲最大数量	通常 ≤ `max_base_abs`
`min_interval_ms`	对冲节流	防止秒内提交多笔
`max_exposure_sec`	超时强平阈值	超过时发起市价单
`retry_max`	IOC 重试次数	失败记录指标

热更新：支持参数变化，但若增大 qmax 超过风控则需同步调整 Risk 配置。

9. 执行 (`execution`)

execution:
  max_slippage_bps: 5
  min_order_interval_ms: 250
  ws_rate_limiter:
    burst: 6
    refill_per_sec: 5
    max_queue_depth: 60

market_data:
  poll_interval_ms: 1000

字段	说明	备注
`max_slippage_bps`	Router 允许的最大滑点阈值	超过后拒单，单位 bps
`min_order_interval_ms`	同账户连续下单的最小间隔	防止触发限频或竞态
`ws_rate_limiter.burst`	允许的瞬时并发请求数	建议 4–10，视交易所限额调整
`ws_rate_limiter.refill_per_sec`	每秒补充的令牌数	控制平均速率
`ws_rate_limiter.max_queue_depth`	排队上限	队列溢出会报错，提示降速

热更新：支持阈值调整，变更后下一次下单立即生效。

9. 监控与自适应

telemetry:
  push_interval_ms: 5000
  enabled_metrics:
    - maker_ratio
    - hedge_latency_p99

adaptive_mode:
  enabled: true
  rv_threshold_high: 0.5
  actions_on_high_vol:
    - disable: scalper
    - grid.max_layers: 2

liquidity:
  min_top10_depth_usd: 50000
  max_clip_ratio: 0.05
  slippage_alert_bps: 2

funding:
  min_correlation: 0.8
  max_same_sign_ratio: 0.2
  alert_net_cost_bps_per_8h: 1

adaptive_mode.actions_on_high_vol 支持指令：disable:<strategy>, grid.max_layers:<value>, hedge.qmax:<value>等。
liquidity 被监控模块用于触发降级或调参。
funding 指标用于 FundingRateMonitor 报警。

10. 热更新流程

修改 config.yaml → pnpm config:validate（调用 zod 校验）。
运行 pnpm backtest --smoke 验证核心指标。
curl POST /api/config/reload 触发 Runner 加载新配置：
- Runner 校验新旧差异，写入审计日志。
- 若 strategy_mode 变化 → Graceful 停止旧策略，启动新策略。
观测金丝雀 10 分钟：delta_abs, hedge_latency, hedge_success_rate。
达标后推广至生产；失败则 POST /api/config/rollback。

11. Runbook（常用操作）

11.1 启动

pnpm install
cp config/config.example.yaml config/config.yaml
pnpm run build
pnpm run live -- --config config/config.yaml

11.2 停止

curl -X POST http://localhost:4000/api/halt -d '{"reason":"maintenance"}'

11.3 查看当前配置

curl http://localhost:4000/api/config/current

11.4 金丝雀流程

pnpm run canary -- --config config/new.yaml --symbols BTC
# 观察 metrics: maker_ratio, delta_abs, hedge_latency_p95

12. 版本管理

配置文档更新需同步 bump configSchemaVersion。
Runner 在启动日志中打印当前 schema 版本与配置摘要。

CONFIG_REFERENCE.md 11 KB Historie Surový

配置参考与运行手册

1. 总览

2. 基础配置

3. 账户配置

4. 策略模式

5. 网格策略 (grid)

6. 剥头皮策略 (scalper)

7. 风控 (risk)

8. 对冲 (hedge)

9. 执行 (execution)

9. 监控与自适应

10. 热更新流程

11. Runbook（常用操作）

11.1 启动

11.2 停止

11.3 查看当前配置

11.4 金丝雀流程

12. 版本管理

CONFIG_REFERENCE.md 11 KB

Historie Surový

5. 网格策略 (`grid`)

6. 剥头皮策略 (`scalper`)

7. 风控 (`risk`)

8. 对冲 (`hedge`)

9. 执行 (`execution`)