# MCP 功能迁移后架构与交互流程

## 1. 概述

迁移完成后，**Execution Factory** 整合为单一的 **operator-integration** 服务，所有 MCP（Model Context Protocol）相关功能均在该服务内实现，包括：
- MCP Server 配置管理
- MCP Server 实例运行时管理
- MCP 协议端点服务
- 工具调用和执行

这种**单服务架构**消除了服务间通信开销，简化了部署和运维，提升了整体性能。

## 2. 整体架构

### 2.1 系统架构图

```mermaid
graph TB
    subgraph "外部调用方"
        Client[AI Agent/LLM Client]
        Admin[管理端]
        Studio[DIP Studio]
    end

    subgraph "operator-integration 服务"
        subgraph "API 层"
            API_Public[公开 API<br/>/v1/mcp/*]
            API_Private[内部 API<br/>/internal-v1/mcp/*]
        end

        subgraph "业务逻辑层"
            MCP_Service[MCP 配置服务]
            Instance_Service[实例服务]
            Tool_Service[工具服务]
        end

        subgraph "核心组件"
            Pool[实例池<br/>Instance Pool]
            Deployer[部署器<br/>Deployer]
            MCP_Instances[MCP Server<br/>运行实例]
        end

        subgraph "数据层"
            DB[(数据库)]
        end

        API_Public --> MCP_Service
        API_Public --> Instance_Service
        API_Private --> MCP_Service
        API_Private --> Instance_Service

        MCP_Service --> DB
        MCP_Service --> Instance_Service
        Instance_Service --> Pool
        Instance_Service --> DB
        Pool --> Deployer
        Deployer --> MCP_Instances
        Tool_Service --> DB
    end

    Admin -->|管理 MCP 配置| API_Public
    Client -->|调用 MCP 工具| API_Public
    Studio -->|内部调用| API_Private
    Client -->|MCP 协议交互| MCP_Instances

    style API_Public fill:#e1f5ff
    style Instance_Service fill:#ffe1f5
    style Pool fill:#e1ffe1
    style MCP_Instances fill:#fff4e1
```

### 2.2 与迁移前架构对比

| 对比项 | 迁移前 | 迁移后 |
|--------|--------|--------|
| **服务数量** | 2 个（operator-integration + operator-app） | 1 个（operator-integration） |
| **数据库** | 2 个独立数据库 | 1 个统一数据库 |
| **配置存储** | 分散在两个服务 | 统一在 mcp_server_config 表 |
| **实例管理** | operator-app 全局单例 | operator-integration 实例池 |
| **服务间通信** | HTTP 跨服务调用 | 本地方法调用 |
| **实例生命周期** | 永久保留，重启重建 | 懒加载 + LRU 淘汰 + TTL 过期 |
| **版本管理** | URL 中显式指定 | 自动使用最新发布版本 |
| **扩展性** | 受全局单例限制 | 实例池可配置大小和策略 |

## 3. 核心模块设计

### 3.1 模块层次结构

```mermaid
graph TB
    subgraph "应用层 (server/driveradapters)"
        H1[mcp_handler.go<br/>HTTP 路由分发]
        H2[mcp/handler.go<br/>MCP 协议处理]
    end

    subgraph "业务逻辑层 (server/logics)"
        subgraph "MCP 配置管理 (logics/mcp)"
            L1[manage.go<br/>配置 CRUD]
            L2[execute.go<br/>工具执行]
            L3[mcp_release.go<br/>版本管理]
            L4[mcp_tool.go<br/>工具管理]
        end

        subgraph "MCP 实例管理 (logics/mcpinstance)"
            I1[service.go<br/>实例服务]
            I2[instance_manager.go<br/>实例管理器]
            I3[pool.go<br/>实例池]
            I4[tool_manager.go<br/>工具管理]

            subgraph "部署器 (deployer)"
                D1[http_deployer.go]
                D2[sse_deployer.go]
                D3[provider.go]
            end
        end
    end

    subgraph "接口定义层 (server/interfaces)"
        IF1[logics_mcp.go<br/>MCP 服务接口]
        IF2[mcp_instance.go<br/>实例服务接口]
    end

    subgraph "数据访问层 (server/dbaccess)"
        DB1[mcp_server_config.go]
        DB2[mcp_server_release.go]
        DB3[mcp_tool.go]
    end

    H1 --> L1
    H2 --> I1
    L1 --> I1
    L2 --> I1
    I1 --> I2
    I2 --> I3
    I3 --> D1
    I3 --> D2
    I3 --> D3
    L1 --> DB1
    L3 --> DB2
    L4 --> DB3
    I1 --> DB2

    L1 -.实现.-> IF1
    I1 -.实现.-> IF2
```

### 3.2 目录结构

```
operator-integration/
├── server/
│   ├── driveradapters/          # HTTP 适配层
│   │   ├── mcp_handler.go       # MCP 路由注册
│   │   └── mcp/                 # MCP 协议处理
│   │       ├── handler.go       # 基础处理器
│   │       ├── stream_handler.go # Stream 端点
│   │       └── sse_handler.go   # SSE 端点
│   ├── logics/                  # 业务逻辑层
│   │   ├── mcp/                 # MCP 配置管理
│   │   │   ├── index.go
│   │   │   ├── manage.go        # 配置 CRUD
│   │   │   ├── execute.go       # 工具执行
│   │   │   ├── connection.go    # 连接管理
│   │   │   ├── mcp_release.go   # 版本管理
│   │   │   ├── mcp_tool.go      # 工具管理
│   │   │   └── ...
│   │   └── mcpinstance/         # MCP 实例管理（新增）
│   │       ├── service.go       # 实例服务实现
│   │       ├── instance_manager.go # 实例管理器
│   │       ├── pool.go          # 实例池
│   │       ├── tool_manager.go  # 工具管理器
│   │       └── deployer/        # 部署器
│   │           ├── http_deployer.go
│   │           ├── sse_deployer.go
│   │           └── provider.go
│   ├── interfaces/              # 接口定义层
│   │   ├── logics_mcp.go       # MCP 服务接口
│   │   ├── mcp_instance.go     # 实例服务接口（新增）
│   │   └── ...
│   ├── dbaccess/                # 数据库访问层
│   │   ├── mcp_server_config.go
│   │   ├── mcp_server_release.go
│   │   ├── mcp_tool.go
│   │   └── ...
│   ├── infra/                   # 基础设施
│   │   ├── config/              # 配置管理
│   │   └── ...
│   └── main.go                  # 服务入口
├── docs/                        # 文档
│   ├── migration/               # 迁移文档
│   └── ...
└── ...
```

## 4. 核心组件详解

### 4.1 实例池 (Instance Pool)

实例池是迁移后的核心改进，负责 MCP Server 实例的生命周期管理。

#### 4.1.1 设计原理

```mermaid
graph LR
    subgraph "实例池核心机制"
        A[懒加载<br/>Lazy Loading]
        B[LRU 淘汰<br/>Least Recently Used]
        C[TTL 过期<br/>Time To Live]
        D[活跃保护<br/>Active Protection]
    end

    A -->|首次访问时创建| Pool
    Pool -->|池满时触发| B
    Pool -->|定期检查| C
    D -->|阻止淘汰| Pool

    style Pool fill:#e1ffe1
```

#### 4.1.2 数据结构

```go
type InstancePool struct {
    maxSize      int                              // 最大实例数
    ttl          time.Duration                    // 实例存活时间
    instances    map[string]*poolItem             // 实例映射
    lruList      *list.List                       // 双向链表，维护 LRU
    mu           sync.RWMutex                     // 读写锁
    cleanupStop  chan struct{}                    // 清理协程停止信号
}

type poolItem struct {
    key       string                  // mcpID:version
    instance  *MCPServerInstance      // MCP 实例
    element   *list.Element           // LRU 链表节点
    lastUsed  time.Time              // 最后使用时间
}
```

#### 4.1.3 核心方法

```go
// GetOrCreate 获取或创建实例（懒加载）
func (p *InstancePool) GetOrCreate(ctx context.Context, mcpID string, version int) (*MCPServerInstance, error)

// Evict 淘汰最少使用的实例
func (p *InstancePool) Evict() error

// Cleanup 清理过期实例
func (p *InstancePool) Cleanup() int

// StartBackgroundCleanup 启动后台清理协程
func (p *InstancePool) StartBackgroundCleanup()
```

#### 4.1.4 工作流程

```mermaid
sequenceDiagram
    participant Req as 请求
    participant Pool as Instance Pool
    participant Deployer as Deployer
    participant MCP as MCP Server

    Req->>Pool: GetOrCreate(mcpID, version)
    activate Pool

    alt 实例已存在
        Pool->>Pool: 更新 lastUsed
        Pool->>Pool: 移动到 LRU 头部
        Pool-->>Req: 返回现有实例
    else 实例不存在
        alt 池未满
            Pool->>Deployer: Deploy(config)
            activate Deployer
            Deployer->>MCP: 创建实例
            activate MCP
            MCP-->>Deployer: 实例
            deactivate MCP
            Deployer-->>Pool: 部署完成
            deactivate Deployer
            Pool->>Pool: 添加到池
            Pool->>Pool: 插入 LRU 头部
            Pool-->>Req: 返回新实例
        else 池已满
            Pool->>Pool: Evict() 淘汰 LRU 尾部
            Pool->>Deployer: Deploy(config)
            Deployer->>MCP: 创建实例
            MCP-->>Deployer: 实例
            Deployer-->>Pool: 部署完成
            Pool->>Pool: 添加到池
            Pool->>Pool: 插入 LRU 头部
            Pool-->>Req: 返回新实例
        end
    end

    deactivate Pool
```

#### 4.1.5 实例保护机制

**活跃连接保护：**

```go
// 在 Handler 中增加活跃连接计数
func (h *mcpHandler) HandleStreamingHttp(c *gin.Context) {
    instance, _ := h.Pool.GetOrCreate(ctx, mcpID, version)

    // 增加活跃连接数
    atomic.AddInt64(&instance.ActiveStreamConn, 1)
    defer atomic.AddInt64(&instance.ActiveStreamConn, -1)

    // 代理请求
    instance.StreamServer.ServeHTTP(c.Writer, c.Request)
}

// 在淘汰时检查
func (p *InstancePool) Evict() error {
    // 从 LRU 尾部开始查找可淘汰的实例
    for e := p.lruList.Back(); e != nil; e = e.Prev() {
        item := e.Value.(*poolItem)

        // 跳过有活跃连接的实例
        if atomic.LoadInt64(&item.instance.ActiveStreamConn) > 0 ||
           atomic.LoadInt64(&item.instance.ActiveSSEConn) > 0 {
            continue
        }

        // 淘汰该实例
        // ...
    }
}
```

### 4.2 部署器 (Deployer)

部署器负责根据不同的 MCP 模式创建和启动 MCP Server 实例。

#### 4.2.1 部署器类型

```mermaid
graph LR
    subgraph "部署器类型"
        A[Deployer Interface]
        B[HTTP Deployer<br/>Stream 模式]
        C[SSE Deployer<br/>SSE 模式]
    end

    A -->|实现| B
    A -->|实现| C

    B -->|创建| D[StreamableHTTPServer]
    C -->|创建| E[SSEServer]
```

#### 4.2.2 部署流程

```mermaid
sequenceDiagram
    participant Pool as Instance Pool
    participant Prov as Deployer Provider
    participant Dep as Deployer
    participant Server as MCP Server
    participant Router as Router

    Pool->>Prov: GetDeployer(mode)
    Prov-->>Pool: 返回 Deployer

    Pool->>Dep: Deploy(config)
    activate Dep

    Dep->>Server: 创建 MCPServer
    activate Server
    Dep->>Server: 注册工具

    alt Stream 模式
        Dep->>Server: 创建 StreamableHTTPServer
        Dep->>Router: 注册 Stream 路由
    else SSE 模式
        Dep->>Server: 创建 SSEServer
        Dep->>Router: 注册 SSE 路由
    end

    Server-->>Dep: 返回配置好的实例
    deactivate Server
    Dep-->>Pool: 返回部署好的实例
    deactivate Dep
```

### 4.3 版本管理

迁移后使用自动版本解析机制，简化 API 调用。

#### 4.3.1 版本解析流程

```mermaid
graph TB
    Start[客户端请求<br/>/v1/mcp/app/:mcp_id/mcp] --> Query[查询最新发布版本]
    Query --> DB[(mcp_server_release)]
    DB --> Check{版本状态?}
    Check -->|published| Use[使用该版本]
    Check -->|unpublished| Error[返回错误]
    Use --> GetInst[获取或创建实例]
    GetInst --> Pool[实例池]
    Pool --> Return[返回实例]

    style Start fill:#e1f5ff
    style Use fill:#e1ffe1
    style Error fill:#ffe1e1
```

#### 4.3.2 版本状态机

```mermaid
stateDiagram-v2
    [*] --> draft: 创建配置
    draft --> published: 发布
    published --> unpublished: 下线
    unpublished --> published: 重新发布
    unpublished --> [*]: 删除

    note right of published
        只有 published 状态
        的版本才能被访问
    end note
```

## 5. 数据模型

### 5.1 数据库表结构

```mermaid
erDiagram
    MCP_SERVER_CONFIG ||--o{ MCP_SERVER_RELEASE : has
    MCP_SERVER_CONFIG ||--o{ MCP_TOOL : contains
    MCP_SERVER_RELEASE ||--o{ MCP_SERVER_RELEASE_HISTORY : records

    MCP_SERVER_CONFIG {
        string mcp_id PK
        string business_domain_id
        string name
        string description
        string mode
        string url
        string command
        json args
        json headers
        json env
        string status
        string category
        timestamp created_at
        timestamp updated_at
    }

    MCP_SERVER_RELEASE {
        string mcp_id PK,FK
        int version PK
        string status
        timestamp created_at
        timestamp updated_at
    }

    MCP_TOOL {
        string tool_id PK
        string mcp_id FK
        string name
        string description
        json input_schema
        timestamp created_at
    }

    MCP_SERVER_RELEASE_HISTORY {
        int id PK
        string mcp_id FK
        int version FK
        string operation
        string operator
        timestamp operated_at
    }
```

### 5.2 实例池内存结构

```mermaid
graph TB
    subgraph "Instance Pool"
        Map[Map: mcpID:version -> poolItem]
        LRU[LRU List: 双向链表]
    end

    subgraph "poolItem 1"
        Key1[key: mcp1:1]
        Inst1[instance: MCPServerInstance]
        Last1[lastUsed: 2026-01-28 16:00]
    end

    subgraph "poolItem 2"
        Key2[key: mcp2:2]
        Inst2[instance: MCPServerInstance]
        Last2[lastUsed: 2026-01-28 15:50]
    end

    Map -->|指向| Key1
    Map -->|指向| Key2
    LRU -->|头部<br/>最近使用| Key1
    LRU -->|尾部<br/>最久未用| Key2

    style LRU fill:#ffe1f5
```

## 6. 交互流程

### 6.1 MCP Server 创建流程

```mermaid
sequenceDiagram
    participant Admin as 管理端
    participant API as REST API
    participant MCP as MCP Service
    participant DB as 数据库
    participant Pool as Instance Pool

    Admin->>API: POST /v1/mcp
    activate API
    API->>MCP: AddMCPServer(req)
    activate MCP

    Note over MCP,DB: 步骤 1: 保存配置
    MCP->>DB: INSERT mcp_server_config
    DB-->>MCP: 配置 ID

    Note over MCP,DB: 步骤 2: 创建版本
    MCP->>DB: INSERT mcp_server_release (version=1, status=published)
    DB-->>MCP: 版本创建成功

    Note over MCP,DB: 步骤 3: 保存工具
    loop 遍历工具列表
        MCP->>DB: INSERT mcp_tool
    end

    Note over MCP,Pool: 步骤 4: 实例预创建（可选）
    MCP->>Pool: Warm up (可选预热)

    MCP-->>API: 返回 MCP ID
    deactivate MCP
    API-->>Admin: 返回创建结果
    deactivate API
```

**关键改进：**
- 无需调用外部服务
- 配置保存和实例创建解耦
- 支持实例懒加载

### 6.2 MCP 工具调用流程（Stream 模式）

```mermaid
sequenceDiagram
    participant Client as AI Agent
    participant API as REST API
    participant Handler as MCP Handler
    participant Service as MCP Service
    participant Pool as Instance Pool
    participant Inst as MCP Server Instance
    participant DB as 数据库

    Client->>API: ANY /v1/mcp/app/:mcp_id/mcp
    activate API
    API->>Handler: HandleStreamingHttp
    activate Handler

    Note over Handler,Service: 步骤 1: 查询版本
    Handler->>Service: GetLatestRelease(mcpID)
    activate Service
    Service->>DB: SELECT FROM mcp_server_release WHERE status='published'
    DB-->>Service: version=2
    Service-->>Handler: version=2
    deactivate Service

    Note over Handler,Pool: 步骤 2: 获取实例
    Handler->>Pool: GetOrCreate(mcpID, version)
    activate Pool

    alt 实例已存在
        Pool->>Pool: 更新 LRU
        Pool-->>Handler: 返回缓存实例
    else 实例不存在
        Pool->>DB: 查询配置和工具
        DB-->>Pool: 配置信息
        Pool->>Pool: Deploy 实例
        Pool->>Pool: 添加到池
        Pool-->>Handler: 返回新实例
    end
    deactivate Pool

    Note over Handler,Inst: 步骤 3: 执行调用
    Handler->>Handler: atomic.Add(ActiveStreamConn, 1)
    Handler->>Inst: StreamServer.ServeHTTP(w, r)
    activate Inst
    Inst-->>Handler: 工具执行结果
    deactivate Inst
    Handler->>Handler: atomic.Add(ActiveStreamConn, -1)

    Handler-->>API: 返回结果
    deactivate Handler
    API-->>Client: HTTP Response
    deactivate API
```

**性能优势：**
- 实例缓存，避免重复创建
- 自动版本解析，简化调用
- 活跃连接保护，避免实例被误淘汰

### 6.3 MCP Server 更新流程

```mermaid
sequenceDiagram
    participant Admin as 管理端
    participant API as REST API
    participant MCP as MCP Service
    participant DB as 数据库
    participant Pool as Instance Pool

    Admin->>API: PUT /v1/mcp/:mcp_id
    activate API
    API->>MCP: UpdateMCPServer(mcpID, req)
    activate MCP

    Note over MCP,DB: 步骤 1: 更新配置
    MCP->>DB: UPDATE mcp_server_config
    DB-->>MCP: 更新成功

    Note over MCP,DB: 步骤 2: 创建新版本
    MCP->>DB: SELECT MAX(version) FROM mcp_server_release
    DB-->>MCP: 最大版本 = 2
    MCP->>DB: INSERT mcp_server_release (version=3, status=published)
    DB-->>MCP: 版本创建成功

    Note over MCP,DB: 步骤 3: 下线旧版本
    MCP->>DB: UPDATE mcp_server_release SET status='unpublished' WHERE version < 3
    DB-->>MCP: 更新成功

    Note over MCP,DB: 步骤 4: 更新工具
    MCP->>DB: DELETE FROM mcp_tool WHERE mcp_id=?
    MCP->>DB: INSERT mcp_tool (工具列表)

    Note over MCP,Pool: 步骤 5: 实例自动更新
    Note right of Pool: 旧版本实例在 TTL 后自动清理<br/>新版本实例在首次访问时创建

    MCP-->>API: 返回更新成功
    deactivate MCP
    API-->>Admin: 返回结果
    deactivate API
```

**懒更新策略：**
- 配置和版本立即更新
- 旧实例逐步过期清理
- 新实例按需创建

### 6.4 实例池清理流程

```mermaid
sequenceDiagram
    participant Timer as 后台定时器
    participant Pool as Instance Pool
    participant Inst as MCP Server Instance

    Timer->>Pool: 定时触发 Cleanup()
    activate Pool

    loop 遍历所有实例
        Pool->>Pool: 计算空闲时间

        alt 超过 TTL 且无活跃连接
            Pool->>Inst: Shutdown()
            activate Inst
            Inst-->>Pool: 关闭成功
            deactivate Inst
            Pool->>Pool: 从池中移除
            Pool->>Pool: 从 LRU 链表移除
        else 未超时或有活跃连接
            Pool->>Pool: 跳过
        end
    end

    Pool-->>Timer: 返回清理数量
    deactivate Pool
```

**清理策略：**
- 每 5 分钟执行一次
- 清理空闲超过 TTL 的实例
- 保护有活跃连接的实例

## 7. API 接口

### 7.1 公开 API 列表

| 路径 | 方法 | 功能 | 变化 |
|------|------|------|------|
| `/v1/mcp` | POST | 添加 MCP Server | 无变化 |
| `/v1/mcp/{mcp_id}` | GET | 查询详情 | 无变化 |
| `/v1/mcp/{mcp_id}` | PUT | 更新配置 | 无变化 |
| `/v1/mcp/{mcp_id}` | DELETE | 删除 | 无变化 |
| `/v1/mcp/list` | GET | 查询列表 | 无变化 |
| `/v1/mcp/{mcp_id}/status` | POST | 更新状态 | 无变化 |
| `/v1/mcp/proxy/{mcp_id}/tools` | GET | 获取工具列表 | 无变化 |
| `/v1/mcp/proxy/{mcp_id}/tool/call` | POST | 调用工具 | 无变化 |
| `/v1/mcp/parse/sse` | POST | 解析 SSE MCP | 无变化 |
| `/v1/mcp/market/list` | GET | 市场列表 | 无变化 |
| **`/v1/mcp/app/:mcp_id/mcp`** | **ANY** | **Stream 端点** | **新增** |
| **`/v1/mcp/app/:mcp_id/sse`** | **GET** | **SSE 端点** | **新增** |
| **`/v1/mcp/app/:mcp_id/message`** | **POST** | **Message 端点** | **新增** |

### 7.2 内部 API 列表

| 路径 | 方法 | 功能 | 变化 |
|------|------|------|------|
| `/internal-v1/mcp/proxy/{mcp_id}/tools` | GET | 获取工具列表 | 保留 |
| `/internal-v1/mcp/proxy/{mcp_id}/tool/call` | POST | 调用工具 | 保留 |
| `/internal-v1/mcp/intcomp/register` | POST | 注册内置 MCP | 保留 |
| `/internal-v1/mcp/intcomp/unregister/:mcp_id` | POST | 注销内置 MCP | 保留 |
| ~~`/internal-v1/mcp/instance/*`~~ | ~~*~~ | ~~实例管理~~ | **废弃** |
| ~~`/internal-v1/mcp/app/*`~~ | ~~*~~ | ~~MCP 端点~~ | **废弃** |

**说明：**
- 原 operator-app 的实例管理接口已废弃（内部方法调用）
- 原 operator-app 的 MCP 端点迁移到公开 API

### 7.3 URL 路径对比

| 功能 | 迁移前 (operator-app) | 迁移后 (operator-integration) |
|------|----------------------|------------------------------|
| Stream 端点 | `/internal-v1/mcp/app/:mcp_id/:version/stream` | `/v1/mcp/app/:mcp_id/mcp` |
| SSE 端点 | `/internal-v1/mcp/app/:mcp_id/:version/sse` | `/v1/mcp/app/:mcp_id/sse` |
| Message 端点 | `/internal-v1/mcp/app/:mcp_id/:version/message` | `/v1/mcp/app/:mcp_id/message` |

**关键变化：**
- 从 internal API 变为 public API
- URL 中不再包含 version 参数（自动使用最新版本）
- Stream 路径从 `/stream` 改为 `/mcp`（符合 MCP 协议规范）

## 8. 系统启动流程

```mermaid
sequenceDiagram
    participant Main as main()
    participant Config as Config Loader
    participant Pool as Instance Pool
    participant Router as Router
    participant Server as HTTP Server

    Main->>Config: 加载配置
    Config-->>Main: 配置对象

    Main->>Pool: 创建实例池
    activate Pool
    Pool->>Pool: 初始化 LRU 链表
    Pool->>Pool: 启动后台清理协程
    Pool-->>Main: 实例池
    deactivate Pool

    Main->>Router: 注册路由
    activate Router
    Router->>Router: 注册健康检查
    Router->>Router: 注册公开 API
    Router->>Router: 注册内部 API
    Router-->>Main: 路由器
    deactivate Router

    Main->>Server: 启动 HTTP 服务
    activate Server
    Note right of Server: 监听端口<br/>接受请求

    Note over Main,Server: 系统就绪，等待请求
```

**启动特点：**
- 无需预加载所有实例
- 轻量级启动，快速就绪
- 实例按需创建

## 9. 监控与可观测性

### 9.1 关键指标

| 指标名称 | 类型 | 说明 |
|---------|------|------|
| `mcp_pool_size` | Gauge | 当前实例池大小 |
| `mcp_pool_max_size` | Gauge | 实例池最大容量 |
| `mcp_pool_hit_rate` | Gauge | 缓存命中率 |
| `mcp_pool_eviction_total` | Counter | 累计淘汰次数 |
| `mcp_pool_cleanup_total` | Counter | 累计清理次数 |
| `mcp_instance_create_total` | Counter | 实例创建总数 |
| `mcp_instance_create_duration` | Histogram | 实例创建耗时 |
| `mcp_active_connections` | Gauge | 活跃连接数 |
| `mcp_tool_call_total` | Counter | 工具调用总数 |
| `mcp_tool_call_duration` | Histogram | 工具调用耗时 |

### 9.2 日志规范

```go
// 实例创建日志
logger.Info("create mcp instance",
    "mcp_id", mcpID,
    "version", version,
    "mode", mode,
    "duration_ms", duration.Milliseconds())

// 实例淘汰日志
logger.Info("evict mcp instance",
    "mcp_id", mcpID,
    "version", version,
    "idle_duration_s", idleDuration.Seconds(),
    "reason", "lru")

// 工具调用日志
logger.Info("call mcp tool",
    "mcp_id", mcpID,
    "tool_name", toolName,
    "status", "success",
    "duration_ms", duration.Milliseconds())
```

### 9.3 调用链追踪

使用 OpenTelemetry 实现分布式追踪：

```mermaid
graph LR
    A[HTTP Request] --> B[HandleStreamingHttp]
    B --> C[GetLatestRelease]
    B --> D[GetOrCreate]
    D --> E[Deploy]
    E --> F[CreateMCPServer]
    E --> G[RegisterTools]
    B --> H[ServeHTTP]

    style A fill:#e1f5ff
    style H fill:#e1ffe1
```

## 10. 性能优化

### 10.1 优化点对比

| 优化项 | 迁移前 | 迁移后 | 提升 |
|--------|--------|--------|------|
| **服务间调用** | HTTP 跨服务 | 本地方法调用 | **延迟降低 ~10ms** |
| **实例管理** | 全局单例，永久保留 | 实例池，LRU + TTL | **内存可控** |
| **实例创建** | 启动时全部加载 | 懒加载 | **启动速度↑** |
| **版本解析** | URL 显式指定 | 自动查询最新版本 | **API 简化** |
| **并发处理** | 全局锁 | 读写锁 + 细粒度锁 | **并发性能↑** |

### 10.2 预期性能提升

| 场景 | 迁移前 | 迁移后 | 提升 |
|------|--------|--------|------|
| 工具调用 P50 | 50ms | **40ms** | **20%** |
| 工具调用 P99 | 200ms | **150ms** | **25%** |
| 实例创建 | 5s | **5s** | 无变化 |
| 系统启动 | 20s（加载所有实例） | **2s** | **90%** |
| 内存占用 | 不可控（持续增长） | **可控（配置上限）** | - |

## 11. 容错与高可用

### 11.1 故障场景与处理

| 故障场景 | 影响 | 处理策略 |
|---------|------|----------|
| 实例创建失败 | 该实例不可用 | 返回错误，客户端重试 |
| 实例池满 | 新实例无法创建 | LRU 淘汰，为新实例腾出空间 |
| 数据库连接失败 | 配置查询失败 | 返回错误，降级处理 |
| MCP Server 崩溃 | 工具调用失败 | 自动重建实例 |

### 11.2 熔断与降级

```mermaid
stateDiagram-v2
    [*] --> Healthy: 初始状态
    Healthy --> Degraded: 错误率超过 10%
    Degraded --> Healthy: 恢复正常
    Degraded --> CircuitOpen: 错误率超过 50%
    CircuitOpen --> Degraded: 半开测试

    note right of Degraded
        降级策略：
        - 禁用实例池淘汰
        - 增加超时时间
    end note

    note right of CircuitOpen
        熔断策略：
        - 拒绝新请求
        - 返回缓存结果
    end note
```

## 12. 总结

### 12.1 架构改进

1. **单服务架构**：合并两个服务为一个，简化部署和运维
2. **实例池管理**：引入 LRU + TTL 机制，优化内存使用
3. **懒加载策略**：实例按需创建，提升启动速度
4. **自动版本解析**：API 更简洁，易于使用
5. **性能提升**：消除服务间调用开销，降低延迟

### 12.2 功能完整性

迁移后保留了所有 MCP 相关功能：
- ✅ MCP Server 配置管理（CRUD）
- ✅ MCP Server 版本管理
- ✅ MCP 工具管理
- ✅ MCP 实例运行时管理
- ✅ MCP 协议端点服务（Stream、SSE、Message）
- ✅ 工具调用和执行
- ✅ 市场列表查询

### 12.3 技术亮点

1. **实例池设计**：支持 LRU 淘汰、TTL 过期、活跃保护
2. **懒加载机制**：减少资源占用，提升系统响应
3. **并发优化**：读写锁、原子操作，提升并发性能
4. **自动化管理**：版本自动解析、实例自动清理
5. **可观测性**：完善的监控指标、日志、调用链

### 12.4 运维优势

| 优势 | 说明 |
|------|------|
| **部署简化** | 只需部署一个服务 |
| **配置统一** | 所有配置在一个地方管理 |
| **监控集中** | 单一服务的监控更简单 |
| **故障排查** | 减少跨服务问题，易于定位 |
| **资源节约** | 减少服务实例数量 |

迁移后的架构更加简洁、高效、易维护，为未来的功能扩展和性能优化打下了坚实的基础。
