从“能工作”到“可扩展、可靠、高性能”的系统演进

flowchart TB
  subgraph APP["应用与接入层"]
    direction LR
    A1["LLM / Inference Service"]
    A2["Python Binding / Client SDK"]
    A3["Mooncake Store Client API
Put / Get / Remove / BatchGet"]
    A1 --> A2 --> A3
  end

  subgraph CACHE["客户端缓存与访问路径"]
    direction LR
    HC["HotCache"]
    DC["DummyClient / RealClient"]
    WU["Warmup Manager"]
    A3 --> HC
    A3 --> DC
    DC --> WU
  end

  subgraph CTRL["控制面 / 元数据面"]
    direction TB
    MC["MasterClient"]
    WS["WrappedMasterService / MasterService"]
    META["Object Metadata / Replica Metadata"]
    ALLOC["Allocation Strategy
SSD_FREE_RATIO_FIRST"]
    RPC["ListWarmupTargets / Remove / FetchRemoveTasks / AckRemoveTasks"]
    PLUGIN["Metadata Store Plugin
etcd / P2P Handshake"]
    MC --> WS
    WS --> META
    WS --> ALLOC
    WS --> RPC
    WS --> PLUGIN
  end

  subgraph TE["数据搬运层"]
    direction LR
    FAC["TransferEngine Facade"]
    subgraph OLDTE["Classic Transfer Engine"]
      direction TB
      MT["MultiTransport"]
      RDMA0["RdmaTransport"]
      TCP0["TcpTransport"]
      UB0["UbTransport"]
      META0["TransferMetadata / Handshake"]
      MT --> RDMA0
      MT --> TCP0
      MT --> UB0
      UB0 --> META0
    end

    subgraph TENT["TENT Runtime"]
      direction TB
      TI["tent::TransferEngineImpl"]
      TS["TransportSelector"]
      TL["TransportLoader"]
      SM["SegmentManager"]
      PFM["Platform / Topology"]
      TUB["UB Transport
Non-native / Native"]
      TRDMA["RdmaTransport"]
      TTCP["TcpTransport"]
      TI --> TS
      TI --> TL
      TI --> SM
      TI --> PFM
      TL --> TUB
      TL --> TRDMA
      TL --> TTCP
    end

    FAC --> OLDTE
    FAC --> TENT
  end

  subgraph STORAGE["存储与后台任务"]
    direction LR
    MEM["Memory Segment / KV Buffer"]
    FILE["FileStorage"]
    BUCKET["BucketStorageBackend"]
    GC["Bucket GC Worker"]
    DFS["DFS / Remote Storage"]
    FILE --> BUCKET --> GC
  end

  subgraph HW["网络与硬件"]
    direction LR
    RDMAH["RDMA NIC / verbs"]
    UBH["UB NIC / URMA / liburma"]
    TCPH["TCP Socket"]
    SSD["LOCAL_DISK / SSD"]
    DRAM["Host DRAM"]
  end

  HC --> FAC
  DC --> MC
  DC --> FAC
  WU --> MC
  WU --> FAC

  META --> FAC
  ALLOC --> FILE
  RPC --> FILE

  FAC --> MEM
  FAC --> FILE
  FAC --> DFS

  RDMA0 --> RDMAH
  TCP0 --> TCPH
  UB0 --> UBH

  TRDMA --> RDMAH
  TTCP --> TCPH
  TUB --> UBH

  MEM --> DRAM
  FILE --> SSD
  BUCKET --> SSD

  classDef core fill:#dfecff,stroke:#3973c6,stroke-width:2px,color:#123;
  classDef mine fill:#ddf5e3,stroke:#32a852,stroke-width:3px,color:#132;
  classDef key fill:#fff0cc,stroke:#e39a20,stroke-width:3px,color:#321;
  classDef prob fill:#ffe1e1,stroke:#d64545,stroke-width:2px,color:#311;

  class A1,A2,A3,MC,WS,META,PLUGIN,FAC,MT,RDMA0,TCP0,UB0,META0,TI,TS,TL,SM,PFM,TRDMA,TTCP,MEM,FILE,DFS,RDMAH,UBH,TCPH,SSD,DRAM core;
  class HC,WU,ALLOC,RPC,TUB,BUCKET,GC mine;
  class DC key;
  class FILE,HC,RPC,ALLOC prob;
        

flowchart LR
  REQ["应用发起 Put / Get / Remove"]
    --> API["Store Client API"]
    --> PATH{"操作类型"}

  PATH -->|"Get / BatchGet"| HOT["HotCache / Metadata Lookup"]
  PATH -->|"Put / Write"| PUT["Store metadata + allocate replica"]
  PATH -->|"Remove"| DEL["Master Remove / Delete Task"]

  HOT --> TE1["TransferEngine / TENT"]
  PUT --> TE1
  DEL --> CTRL1["Master / Holder / GC 协议"]

  TE1 --> XPORT{"传输后端"}
  XPORT --> RD["RDMA"]
  XPORT --> UB["UB / URMA"]
  XPORT --> TCP["TCP"]

  RD --> DATA["远端 Memory / SSD / DFS 数据"]
  UB --> DATA
  TCP --> DATA

  CTRL1 --> FILE1["LOCAL_DISK Holder / BucketStorageBackend"]
  FILE1 --> GC1["GC 回收"]

  classDef core fill:#dfecff,stroke:#3973c6,stroke-width:2px,color:#123;
  classDef mine fill:#ddf5e3,stroke:#32a852,stroke-width:3px,color:#132;
  classDef key fill:#fff0cc,stroke:#e39a20,stroke-width:3px,color:#321;

  class REQ,API,PATH,TE1,XPORT,RD,UB,TCP,DATA core;
  class HOT,DEL,CTRL1,FILE1,GC1,PUT mine;
  class PUT,HOT key;
        

flowchart TB
  APP["Application / Mooncake Store"]

  subgraph TENT["TENT Layer"]
    direction LR
    RT["TENT Runtime"] --> SEL["Transport Selector"] -->|"选择 UB"| UBT["UbTentTransport"] --> BR["Request / Metadata Bridge"]
  end

  subgraph CLASSIC["Classic TE UB Data Plane"]
    direction LR
    OLD["Classic UbTransport"] --> CTX["UbContext / UbEndpoint"] --> W["UB Worker"]
    OLD --> TOPO["Legacy Topology"]
  end

  subgraph URMA["URMA / UMDK"]
    direction LR
    UC["UrmaContext / UrmaEndpoint"] --> LIB["liburma"] --> HW["UB NIC"]
  end

  APP --> RT
  BR -->|"TENT Request → TransferRequest"| OLD
  W --> UC

  classDef new fill:#ddf5e3,stroke:#32a852,stroke-width:3px,color:#132;
  classDef bad fill:#ffe1e1,stroke:#d64545,stroke-width:3px,color:#311;
  classDef core fill:#dfecff,stroke:#3973c6,stroke-width:2px,color:#123;
  classDef key fill:#fff0cc,stroke:#e39a20,stroke-width:3px,color:#321;
  class UBT new;
  class BR key;
  class OLD,TOPO bad;
  class RT,SEL,CTX,W,UC,LIB,HW core;
        

classDiagram
  direction LR

  class Transport {
    <<interface>>
    +install()
    +uninstall()
    +allocateSubBatch()
    +freeSubBatch()
    +submitTransferTasks()
    +getTransferStatus()
    +addMemoryBuffer()
    +removeMemoryBuffer()
    +getEstimatedBandwidth()
    +cancelTransferTask()
  }

  class UbTentTransport {
    <<TENT adapter>>
    -legacyUbTransport
    -metadataBridge
    +install()
    +addMemoryBuffer()
    +allocateSubBatch()
    +submitTransferTasks()
    +getTransferStatus()
    +cancelTransferTask()
  }

  class UbTentMetadataBridge {
    <<metadata adapter>>
    +getSegmentDescByName()
    +getSegmentDescByID()
    +translateHandshake()
  }

  class TransferMetadata {
    <<Classic TE interface>>
    +SegmentDesc
    +HandShakeDesc
  }

  class SegmentManager {
    +BufferDesc
    +SegmentDesc
    +lookupSegment()
  }

  class ControlService {
    +BootstrapUb()
  }

  class UbTransport {
    <<Classic TE UbTransport>>
    +install()
    +registerLocalMemory()
    +allocateBatchID()
    +submitTransfer()
    +getTransferStatus()
  }

  class BatchID {
    <<Classic TE task handle>>
  }

  class TransferRequest {
    +opcode
    +source
    +target
    +length
  }

  class TransferTask {
    +status
    +transferredBytes
  }

  Transport <|-- UbTentTransport
  UbTentTransport --> UbTransport : delegates data path
  UbTentTransport --> UbTentMetadataBridge : metadata / handshake
  UbTentMetadataBridge ..|> TransferMetadata
  UbTentMetadataBridge --> SegmentManager : TENT segment → legacy view
  UbTentMetadataBridge --> ControlService : BootstrapUb
  UbTransport --> TransferMetadata
  UbTransport --> BatchID
  UbTransport --> TransferRequest
  UbTransport --> TransferTask
        

flowchart TB
  APP["Application / Store"]

  subgraph TENT["TENT Runtime"]
    direction LR
    RT["TENT Runtime"] --> SEL["Transport Selector"] --> UB["Native UB Transport"]
  end

  subgraph EXEC["TENT-native UB Execution"]
    direction LR
    TASK["UbTask"] --> SL["UbSlice[]"] --> W["UbWorkers"] --> PATH["Path / Rail Selection"]
  end

  subgraph DATA["UB Data Plane"]
    direction LR
    CTX["UbContext"] --> EP["UbEndpoint"] --> UA["UrmaAdapter"]
  end

  subgraph UMDK["URMA / UMDK"]
    direction LR
    LIB["liburma"] --> HW["UB NIC"] --> JFC["UbJfc / Completion"]
  end

  APP --> RT
  UB --> TASK
  PATH --> CTX
  UA --> LIB
  JFC --> W
  W --> TASK

  classDef new fill:#ddf5e3,stroke:#32a852,stroke-width:3px,color:#132;
  classDef key fill:#fff0cc,stroke:#e39a20,stroke-width:3px,color:#321;
  classDef core fill:#dfecff,stroke:#3973c6,stroke-width:2px,color:#123;
  class UB,TASK,SL,W new;
  class PATH key;
  class RT,SEL,CTX,EP,UA,LIB,HW,JFC core;
        

classDiagram
  direction TB

  class Transport {
    <<TENT transport contract>>
    +install()
    +uninstall()
    +allocateSubBatch()
    +freeSubBatch()
    +submitTransferTasks()
    +getTransferStatus()
    +addMemoryBuffer()
    +removeMemoryBuffer()
    +getEstimatedBandwidth()
    +supportsCancellation()
    +cancelTransferTask()
  }

  class UbTransport {
    <<TENT-native UB>>
    +allocateSubBatch()
    +submitTransferTasks()
    +getTransferStatus()
    +addMemoryBuffer()
    +getEstimatedBandwidth()
    +cancelTransferTask()
  }

  class RdmaTransport {
    <<TENT RDMA>>
    +allocateSubBatch()
    +submitTransferTasks()
    +getTransferStatus()
    +addMemoryBuffer()
    +getEstimatedBandwidth()
    +cancelTransferTask()
  }

  class TransportSelector {
    +selectTransport()
  }

  class SegmentManager {
    +registerBuffer()
    +lookupSegment()
  }

  class Platform {
    <<shared runtime abstraction>>
    +probe()
    +memory / topology info
  }

  class UbTask {
    +status
    +totalBytes
    +transferredBytes
    +cancelRequested
  }

  class UbSlice {
    +offset
    +length
    +retryCount
    +endpointGeneration
  }

  class UbWorkers {
    +submitBatch()
    +selectPath()
    +post()
    +poll()
  }

  class UbContext
  class UbEndpoint
  class UbJfc
  class UrmaAdapter

  Transport <|-- UbTransport
  Transport <|-- RdmaTransport
  TransportSelector --> Transport : only depends on common API
  SegmentManager --> UbTransport
  SegmentManager --> RdmaTransport
  Platform --> UbTransport
  Platform --> RdmaTransport

  UbTransport --> UbTask
  UbTask --> UbSlice
  UbSlice --> UbWorkers
  UbWorkers --> UbContext
  UbWorkers --> UbEndpoint
  UbWorkers --> UbJfc
  UbEndpoint --> UrmaAdapter
        

flowchart LR
  subgraph CTRL["控制面"]
    direction TB
    S["Store Client 初始化"] --> W["Warmup Manager"]
    W --> L["ListWarmupTargets"]
    L --> M["Master"]
    M -->|"有界 targets"| W
  end

  subgraph INIT["连接初始化"]
    direction TB
    O["openSegment()"] --> META["Remote Metadata"] --> HS["Socket Handshake"] --> EP["RDMA / UB / TCP Endpoint"]
  end

  subgraph PROBE["Warmup Probe"]
    direction TB
    P["Small READ-only Probe"] --> EP2["复用已建立 Endpoint"]
    P --> C["Cleanup Worker"]
  end

  W --> O
  W --> P
  EP --> EP2
  B["后续真实 GET / WRITE"] -->|"直接复用"| EP2

  classDef new fill:#ddf5e3,stroke:#32a852,stroke-width:3px,color:#132;
  classDef key fill:#fff0cc,stroke:#e39a20,stroke-width:3px,color:#321;
  classDef core fill:#dfecff,stroke:#3973c6,stroke-width:2px,color:#123;
  class W,L,P,C new;
  class HS,EP key;
  class M,O,META core;
        

classDiagram
  direction LR

  class Client {
    +setup()
    +warmup()
  }

  class MasterClient {
    +ListWarmupTargets()
  }

  class WrappedMasterService {
    +ListWarmupTargets(clientId, maxTargets, preferredProtocols)
  }

  class WarmupTarget {
    +segmentName
    +segmentId
    +clientId
    +protocol
    +isLocal
    +allowWarmup
    +priority
  }

  class TransferEngine {
    +openSegment()
    +submitTransfer(READ)
    +getTransferStatus()
    +freeBatchID()
  }

  class ProbeResource {
    +buffer
    +batchId
    +status
  }

  class CleanupWorker {
    +poll()
    +requeueOnStatusError()
    +releaseOnTerminal()
  }

  Client --> MasterClient : query targets
  MasterClient --> WrappedMasterService
  WrappedMasterService --> WarmupTarget : returns bounded list
  Client --> TransferEngine : open + READ probe
  Client --> ProbeResource : create
  CleanupWorker --> ProbeResource
  CleanupWorker --> TransferEngine : query/release
        

flowchart LR
  subgraph MASTER["Master"]
    direction TB
    U["RealClient
Remove / BatchRemove"] --> M["Object Metadata"]
    M --> G["生成 Holder-specific Tasks"]
    G --> Q["Bounded Remove Queue"]
    G -->|"全部成功入队后"| DEL["删除 Object Metadata"]
  end

  subgraph HOLDER["LOCAL_DISK Holder"]
    direction TB
    H["Heartbeat"] --> F["FetchRemoveTasks"]
    F --> MR["BucketStorageBackend::MarkRemoved"]
    MR --> CK["校验 tenant / key / incarnation"]
    CK --> D["tmp → fsync → rename → fsync(parent)"]
    D --> A["AckRemoveTasks"]
  end

  subgraph GCBOX["Background GC"]
    direction TB
    GC["GC Worker"] --> CP["Bucket Compaction"] --> R["回收 SSD 物理空间"]
  end

  Q --> F
  A --> Q
  D --> GC

  classDef new fill:#ddf5e3,stroke:#32a852,stroke-width:3px,color:#132;
  classDef key fill:#fff0cc,stroke:#e39a20,stroke-width:3px,color:#321;
  classDef core fill:#dfecff,stroke:#3973c6,stroke-width:2px,color:#123;
  class G,Q,F,MR,A,GC new;
  class CK,D key;
  class U,M,H,CP,R,DEL core;
        

classDiagram
  direction LR

  class MasterService {
    +Remove()
    +BatchRemove()
    +FetchRemoveTasks()
    +AckRemoveTasks()
  }

  class RemoveTaskQueue {
    +enqueue()
    +fetchWithoutDelete()
    +ackAndErase()
    +capacity
  }

  class RemoveTask {
    +taskId
    +clientId
    +tenantId
    +key
    +objectIncarnation
    +replicaIdentity
  }

  class FileStorage {
    +heartbeat()
    +fetchRemoveTasks()
    +ackRemoveTasks()
  }

  class BucketStorageBackend {
    +MarkRemoved()
    +persistMetadata()
    +compactBucket()
  }

  class BucketGcWorker {
    +start()
    +scanCandidates()
    +compact()
    +stopAndJoin()
  }

  MasterService --> RemoveTaskQueue
  RemoveTaskQueue o-- RemoveTask
  FileStorage --> MasterService : heartbeat RPC
  FileStorage --> BucketStorageBackend : execute task
  BucketStorageBackend --> RemoveTask : validate incarnation
  BucketGcWorker --> BucketStorageBackend : background GC
        

flowchart LR
  subgraph OLD["原方案 · RDMA READ Pull"]
    R1["Requester"] -->|"① Read RPC"| T1["Target"]
    SSD1["SSD"] -->|"② pread"| ST1["Target Staging"]
    T1 -->|"③ staging addr/rkey"| R1
    R1 -->|"④ RDMA READ"| ST1
    R1 -->|"⑤ release"| T1
  end

  subgraph NEW["优化 · RDMA WRITE Push"]
    R2["Requester Destination"] -->|"① RPC + dst addr/rkey"| T2["Target"]
    SSD2["SSD"] -->|"② pread"| ST2["Target Staging"]
    ST2 -->|"🟢 ③ RDMA WRITE"| R2
    T2 -->|"④ complete"| R2
  end

  classDef bad fill:#ffe1e1,stroke:#d64545,stroke-width:3px,color:#311;
  classDef good fill:#ddf5e3,stroke:#32a852,stroke-width:3px,color:#132;
  class R1,T1,ST1 bad;
  class R2,T2,ST2 good;
        

flowchart LR
  subgraph MASTER["Master Allocation"]
    direction TB
    R["Object Offload Request"] --> A["Allocation Strategy"]
    A --> S["SSD Usage Statistics"]
    S --> C["计算 free_ratio"]
    C --> P["SSD_FREE_RATIO_FIRST"]
  end

  subgraph HOLDERS["LOCAL_DISK Holders"]
    direction TB
    H1["Holder A · Used 80%"]
    H2["Holder B · Used 45%"]
    H3["Holder C · Used 20%"]
  end

  H1 -->|"usage"| S
  H2 -->|"usage"| S
  H3 -->|"usage"| S
  P -. "skip" .-> H1
  P -. "skip" .-> H2
  P -->|"🟢 prefer"| H3
  H3 -->|"allocation 后更新 used_bytes"| S

  classDef good fill:#ddf5e3,stroke:#32a852,stroke-width:3px,color:#132;
  classDef bad fill:#ffe1e1,stroke:#d64545,stroke-width:3px,color:#311;
  classDef key fill:#fff0cc,stroke:#e39a20,stroke-width:3px,color:#321;
  class H3,P good;
  class H1 bad;
  class S,C key;
        

flowchart LR
  AL["Allocate LOCAL_DISK"] -->|"+"| U["ssd_used_bytes"]
  U --> F["free_ratio"]
  F --> S["Next Allocation"]
  D["Remove / GC"] -->|"🟢 -"| U

  classDef good fill:#ddf5e3,stroke:#32a852,stroke-width:3px,color:#132;
  classDef key fill:#fff0cc,stroke:#e39a20,stroke-width:3px,color:#321;
  class D good;
  class U,F key;
        

flowchart LR
  A["查已有 Issue / PR"] --> B{"已有同类工作?"}
  B -->|"有"| C["加入讨论 / 补充方案
避免重复实现"]
  B -->|"没有"| D["创建 Issue / RFC"]
  D --> E["基于 upstream/main
建立功能分支"]
  E --> F["实现 + 回归测试"]
  F --> G["format / pre-commit
本地测试"]
  G --> H["同步 upstream/main
处理冲突"]
  H --> I["提交 PR
Fixes / Closes #Issue"]
  I --> J["GitHub CI"]
  J --> K["Bot Review"]
  K --> L["Maintainer / CODEOWNER Review"]
  L --> M["修复问题 + 回复原因
Resolve threads"]
  M --> N{"Required checks
+ approvals 完成?"}
  N -->|"否"| F
  N -->|"是"| O["Merge"]

  classDef good fill:#ddf5e3,stroke:#32a852,stroke-width:3px,color:#132;
  classDef key fill:#fff0cc,stroke:#e39a20,stroke-width:3px,color:#321;
  classDef bad fill:#ffe1e1,stroke:#d64545,stroke-width:2px,color:#311;
  class D,I,O good;
  class J,L,N key;
  class B,M bad;
        

flowchart LR
  U["upstream/main
kvcache-ai/Mooncake"] -->|"fetch"| L["本地仓库"]
  L -->|"checkout -b feature"| B["功能分支"]
  B -->|"实现 / 测试 / commit"| B
  U -->|"rebase / merge latest main"| B
  B -->|"push"| F["个人 / 公司 Fork"]
  F -->|"Pull Request"| U

  classDef good fill:#ddf5e3,stroke:#32a852,stroke-width:3px,color:#132;
  classDef core fill:#dfecff,stroke:#3973c6,stroke-width:2px,color:#123;
  class B,F good;
  class U,L core;
        

flowchart LR
  A["Bot / Maintainer Comment"] --> B{"问题类型"}
  B -->|"正确性 / 生命周期"| C["先验证代码路径
补 regression test"]
  B -->|"架构 / scope"| D["重新确认模块边界
必要时拆 PR"]
  B -->|"风格 / 文档"| E["直接修复并跑 format"]
  B -->|"判断不成立"| F["用代码事实 + 测试结果解释"]
  C --> G["提交修复"]
  D --> G
  E --> G
  F --> H["回复 rationale"]
  G --> H
  H --> I["Resolve conversation"]
  I --> J["等待 re-review / approval"]