M1.6 Workstream 4: Multi-Instance Orchestration Design

版本: v1.0.0
日期: 2025-10-09
负责人: Strategy Platform Team
依赖文档: IMPLEMENTATION_PLAN.md, ARCHITECTURE_DESIGN.md, M16_INCREMENTAL_GRID_DESIGN.md, M16_PLACEMENT_THROTTLING_DESIGN.md

1. 背景与目标

支持同一 Runner 进程内运行多个 Grid 实例（多账户、多标的、内外圈策略）。
解决当前单实例架构无法分层挂单、无法差异化限流的问题。
为后续多 venue / 多策略协同奠定基础。

2. 核心组件

组件	说明
`GridFleetManager`	负责实例生命周期管理（启动/停止/热更新）、调度、监控。
`GridInstance`	包含 `GridMaker`、`ShadowBook`、`timers`、`metrics` 等封装。
`FleetConfig`	`grid.instances[]` schema（参见 §3），支持 per-instance 参数。
`InstanceRegistry`	映射 `(accountId, symbol)` → `GridInstance`，提供迭代、查找。
`GlobalOrderCoordinator` 扩展	跨实例 STP、冲突检测、节流。
`FleetController`	CLI/REST 控制接口（list/scale/degrade）。

3. 配置 Schema

grid:
  enabled: true
  instances:
    - id: btc-inner
      account_id: maker-inner
      symbol: BTC
      grid_step_bps: 2
      grid_range_bps: 120
      base_clip_usd: 80
      max_layers: 14
      adaptive:
        enabled: true
        min_grid_step_bps: 1.5
        max_grid_step_bps: 20
        post_only_cushion_bps: 0.5
        min_layers: 12
        tick_interval_ms: 30000
        fill_starvation_threshold: { ticks: 4, compress_factor: 0.5 }
    - id: btc-outer
      account_id: maker-outer
      symbol: BTC
      grid_step_bps: 8
      grid_range_bps: 200
      base_clip_usd: 100
      max_layers: 10
      adaptive:
        enabled: true
        min_grid_step_bps: 6
        max_grid_step_bps: 60
        post_only_cushion_bps: 2
        min_layers: 8

3.1 Schema 说明

id：唯一实例 ID，用于日志/指标/运维命令。
account_id：会在 AdapterRegistry 中查找对应账户；必须配对成功。
symbol：允许多个实例操作同一 symbol（需 STP 控制）。
其余字段与现有 grid 配置一致，adaptive 支持新增字段：
- fill_starvation_threshold.ticks: 连续无成交的 tick 数。
- compress_factor: 步长压缩比例（例如 0.5 → 减半）。
如果 grid.instances 缺失，则回退到旧的单实例配置（兼容性）。

4. GridFleetManager 设计

4.1 数据结构

interface GridInstanceContext {
  id: string;
  symbol: string;
  accountId: string;
  maker: GridMaker;
  shadowBook: ShadowBook;
  timers: {
    tick: NodeJS.Timeout;
    status: NodeJS.Timeout;
  };
  metrics: GridInstanceMetrics;
  state: "initializing" | "running" | "paused" | "degraded" | "stopped";
  lastConfigHash: string;
}

4.2 生命周期

create
- 构建 ShadowBook、GridMaker、Hedge/Fills handler。
- 注册到 InstanceRegistry 并启动 timers。
- 记录 metrics：grid_instance_state{id="...", state="initializing"}。
start
- 调用 GridMaker.initialize()；成功后状态切换为 running。
pause
- 停止 timers，调用 GridMaker.shutdown()，保留配置。
resume
- 重新启动 timers，视需要重新初始化。
degrade
- 进入“保守模式”——例如仅留 4 层、步长放大、停止自适应。
destroy
- 停止 timers、注销 handlers、释放资源。

4.3 热更新

新配置进来后，计算 hash(instanceConfig)：
- 若 hash 未变化→忽略。
- 若变化→调用 instance.update(newConfig)：
- 暂停当前实例；
- 应用新配置（重建 GridMaker/ShadowBook）；
- 重新启动。
更新过程中需确保全局 STP/节流不会误判（详见 §5）。

5. GlobalOrderCoordinator 扩展

5.1 目标

同一 symbol、不同实例之间禁止互相吃单（STP）。
对共享账户的实例合并限流（如 maker-inner / maker-outer 使用同一 API 限额）。
实例级别的订单统计用于填充 metrics。

5.2 实现

OrderId 索引改为 (accountId, symbol, clientId) 复合键。
在 registerOrder 时追加实例 ID，检测 conflicts 时排除相同实例 / 允许不同 symbol。
提供接口 coordinator.getAccountLoad(accountId)，供节流模块查询。
新增指标：
- stp_conflicts_total{instance}
- account_order_load{accountId}
STP 冲突触发时，使用 fleet.degrade(instanceId, reason="stp_conflict") 或回退自适应。

6. 监控与指标

指标	说明
`grid_instance_state{instance}`	`initializing/running/paused/degraded/stopped`
`grid_active_orders{instance}`	当前活跃订单数
`grid_pending_levels{instance}`	reconcile 后未补足的层数
`grid_fill_interval_seconds{instance}`	平均成交间隔
`grid_step_bps{instance}`	当前步长指标（Expose via Gauge）
`order_gateway_queue_depth{accountId}`	WS 队列深度（Placement Throttling 依赖）

告警建议：

grid_instance_state != running 持续 > 60s。
grid_pending_levels > 2 持续 > 2 tick。
order_gateway_queue_depth > 40 持续 > 5s。
stp_conflicts_total 突然增加。

7. 运维接口（FleetController）

命令	描述
`GET /api/fleet/instances`	列出所有实例状态、当前配置 hash、活跃订单数
`POST /api/fleet/instances/{id}/pause`	暂停实例（保留订单）
`POST /api/fleet/instances/{id}/resume`	恢复实例
`POST /api/fleet/instances/{id}/degrade`	进入保守模式（参数：步长放大倍数、保留层数）
`POST /api/fleet/instances/{id}/shutdown`	停止并撤销所有订单
`POST /api/fleet/reload`	重新加载配置（wrapper of config reload）

接口需经过认证（与 Kill-switch 相同机制），并写入审计日志。

8. 与 M16 其他 Workstream 的关系

与 Workstream 1（增量网格）共享 reconcileGrid、实例级 metrics。
与 Workstream 2（节流 2.0）共享 rate limiter（按 account/instance 聚合）。
与 Workstream 3（成交驱动压缩）需要同步 fill_starvation_threshold 配置。
在极限贴盘口实验中，可通过多实例策略（内圈 vs 外圈）开展分层测试。

9. 风险与缓解

风险	描述	缓解策略
STP/限流复杂度上升	多实例同时下单造成冲突或超限	统一通过 coordinator + rate limiter，必要时设置硬阈值
热更新中断	更新流程出现异常导致实例停滞	引入事务化流程：先创建新实例，成功后替换旧实例
指标压力	多实例指标数倍增	聚合指标支持 `cluster` 标签，Grafana 通过 regex 过滤

10. 实施步骤

扩展配置解析（zod schema + 文档更新）。
实现 GridFleetManager 与 GridInstance。
修改 Runner (apps/runner/src/index.ts) 以实例化 Fleet。
升级 GlobalOrderCoordinator。
与 Placement Throttling 集成（共享 rate limiter）。
补充指标/运维接口/测试。
回归单实例模式确保兼容。
金丝雀：1 内圈 + 1 外圈实例，观测 24 小时后推广。

11. 测试计划

单元测试：实例创建/更新/销毁、STP 冲突检测、rate limiter 分配。
集成测试：Mock 2 个实例，验证填充订单、增量补单、节流逻辑。
压测：模拟 10+ 实例并发下单，评估指标采集和限流表现。
金丝雀指标：grid_instance_state, grid_pending_levels, order_gateway_queue_depth, placement_latency_p95.

M16_MULTI_INSTANCE_ORCHESTRATION_DESIGN.md 7.7 KB Historie Surový