MCP 生产部署与运维实践

# serverless.yml 示例
service: mcp-tools
provider:
  name: aws
  runtime: nodejs20.x

functions:
  filesystem:
    handler: dist/handlers/filesystem.handler
    timeout: 30
    memorySize: 512
    events:
      - http:
          path: /mcp/filesystem
          method: post

# mcp-server-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-filesystem-server
  labels:
    app: mcp-filesystem
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-filesystem
  template:
    metadata:
      labels:
        app: mcp-filesystem
    spec:
      containers:
        - name: server
          image: registry.example.com/mcp/filesystem:v1.2.3
          ports:
            - containerPort: 3000
              name: http
          env:
            - name: NODE_ENV
              value: "production"
            - name: ALLOWED_PATHS
              value: "/data/workspace"
            - name: LOG_LEVEL
              value: "info"
          resources:
            requests:
              memory: "128Mi"
              cpu: "100m"
            limits:
              memory: "512Mi"
              cpu: "500m"
          livenessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 10
            periodSeconds: 30
          readinessProbe:
            httpGet:
              path: /ready
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 5
          securityContext:
            runAsNonRoot: true
            runAsUser: 1001
            readOnlyRootFilesystem: true
            allowPrivilegeEscalation: false
          volumeMounts:
            - name: data-volume
              mountPath: /data
              readOnly: true
            - name: tmp-volume
              mountPath: /tmp
      volumes:
        - name: data-volume
          persistentVolumeClaim:
            claimName: workspace-data
        - name: tmp-volume
          emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
  name: mcp-filesystem-service
spec:
  selector:
    app: mcp-filesystem
  ports:
    - port: 80
      targetPort: 3000
  type: ClusterIP

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: mcp-filesystem-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: mcp-filesystem-server
  minReplicas: 2
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 60
      policies:
        - type: Pods
          value: 4
          periodSeconds: 60
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Pods
          value: 2
          periodSeconds: 120

// src/health.ts
import { Request, Response } from "express";

interface HealthStatus {
  status: "healthy" | "degraded" | "unhealthy";
  checks: Record<string, CheckResult>;
  timestamp: string;
}

interface CheckResult {
  status: "pass" | "fail" | "warn";
  responseTime: number;
  message?: string;
}

export async function healthCheck(req: Request, res: Response): Promise<void> {
  const start = Date.now();
  const checks: Record<string, CheckResult> = {};

  // 检查文件系统访问
  try {
    const fsStart = Date.now();
    await checkFilesystemAccess();
    checks.filesystem = {
      status: "pass",
      responseTime: Date.now() - fsStart,
    };
  } catch (error) {
    checks.filesystem = {
      status: "fail",
      responseTime: Date.now() - start,
      message: error instanceof Error ? error.message : String(error),
    };
  }

  // 检查内存使用
  const memUsage = process.memoryUsage();
  const memPercent = memUsage.heapUsed / memUsage.heapTotal;
  checks.memory = {
    status: memPercent > 0.9 ? "warn" : "pass",
    responseTime: 0,
    message: `Heap: ${(memUsage.heapUsed / 1024 / 1024).toFixed(1)}MB`,
  };

  const overallStatus = Object.values(checks).every((c) => c.status === "pass")
    ? "healthy"
    : Object.values(checks).some((c) => c.status === "fail")
    ? "unhealthy"
    : "degraded";

  const status: HealthStatus = {
    status: overallStatus,
    checks,
    timestamp: new Date().toISOString(),
  };

  res.status(overallStatus === "healthy" ? 200 : overallStatus === "degraded" ? 200 : 503).json(status);
}

export async function readinessCheck(req: Request, res: Response): Promise<void> {
  // 就绪检查：服务器是否准备好接收流量
  // 例如：是否已完成初始化、是否已连接到依赖服务
  res.status(200).json({ ready: true });
}

// src/shutdown.ts
import { Server } from "http";

class GracefulShutdown {
  private isShuttingDown = false;
  private activeConnections: Set<any> = new Set();

  constructor(private httpServer: Server, private timeoutMs: number = 30000) {}

  register(): void {
    process.on("SIGTERM", () => this.shutdown("SIGTERM"));
    process.on("SIGINT", () => this.shutdown("SIGINT"));

    // 追踪活跃连接
    this.httpServer.on("connection", (conn) => {
      this.activeConnections.add(conn);
      conn.on("close", () => {
        this.activeConnections.delete(conn);
      });
    });
  }

  private async shutdown(signal: string): Promise<void> {
    console.log(`收到 ${signal}，开始优雅关闭...`);
    this.isShuttingDown = true;

    // 停止接收新连接
    this.httpServer.close(() => {
      console.log("HTTP 服务器已停止接收新连接");
    });

    // 设置超时强制退出
    const forceExit = setTimeout(() => {
      console.error("关闭超时，强制退出");
      process.exit(1);
    }, this.timeoutMs);

    // 等待活跃连接处理完
    const waitForConnections = async () => {
      while (this.activeConnections.size > 0) {
        console.log(`等待 ${this.activeConnections.size} 个连接完成...`);
        await new Promise((r) => setTimeout(r, 1000));
      }
    };

    await waitForConnections();
    clearTimeout(forceExit);
    console.log("所有连接已关闭，正常退出");
    process.exit(0);
  }
}

// src/metrics.ts
import prometheus from "prom-client";

// 注册表
const register = new prometheus.Registry();

// 工具调用计数器
const toolCallsTotal = new prometheus.Counter({
  name: "mcp_tool_calls_total",
  help: "Total number of tool calls",
  labelNames: ["tool_name", "status"],
  registers: [register],
});

// 工具调用延迟直方图
const toolCallDuration = new prometheus.Histogram({
  name: "mcp_tool_call_duration_seconds",
  help: "Tool call duration in seconds",
  labelNames: ["tool_name"],
  buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
  registers: [register],
});

// 活跃连接数
const activeConnections = new prometheus.Gauge({
  name: "mcp_active_connections",
  help: "Number of active MCP connections",
  registers: [register],
});

// 资源使用
const resourceReadsTotal = new prometheus.Counter({
  name: "mcp_resource_reads_total",
  help: "Total number of resource reads",
  labelNames: ["uri"],
  registers: [register],
});

export function recordToolCall(toolName: string, durationSec: number, success: boolean): void {
  const status = success ? "success" : "failure";
  toolCallsTotal.inc({ tool_name: toolName, status });
  toolCallDuration.observe({ tool_name: toolName }, durationSec);
}

export function getMetrics(): Promise<string> {
  return register.metrics();
}

// src/logger.ts
import winston from "winston";

export const logger = winston.createLogger({
  level: process.env.LOG_LEVEL ?? "info",
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  defaultMeta: { service: "mcp-server" },
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: "logs/error.log", level: "error" }),
    new winston.transports.File({ filename: "logs/combined.log" }),
  ],
});

// 工具调用日志
export function logToolCall(params: {
  tool: string;
  args: Record<string, unknown>;
  result: "success" | "failure";
  durationMs: number;
  sessionId: string;
  error?: Error;
}): void {
  logger.info("tool_call", {
    tool: params.tool,
    args: sanitizeArgs(params.args),
    result: params.result,
    duration_ms: params.durationMs,
    session_id: params.sessionId,
    error: params.error?.message,
  });
}

function sanitizeArgs(args: Record<string, unknown>): Record<string, unknown> {
  const sensitive = new Set(["password", "token", "secret", "api_key", "key"]);
  const result: Record<string, unknown> = {};
  for (const [k, v] of Object.entries(args)) {
    result[k] = sensitive.has(k.toLowerCase()) ? "[REDACTED]" : v;
  }
  return result;
}

# alert-rules.yaml
groups:
  - name: mcp-alerts
    rules:
      - alert: MCPHighErrorRate
        expr: rate(mcp_tool_calls_total{status="failure"}[5m]) / rate(mcp_tool_calls_total[5m]) > 0.1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "MCP 服务器错误率过高"
          description: "{{ $labels.tool_name }} 的错误率超过 10%"

      - alert: MCPHighLatency
        expr: histogram_quantile(0.95, rate(mcp_tool_call_duration_seconds_bucket[5m])) > 2
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "MCP 工具调用延迟过高"
          description: "{{ $labels.tool_name }} 的 P95 延迟超过 2 秒"

      - alert: MCPPodCrashLooping
        expr: rate(kube_pod_container_status_restarts_total{container="mcp-server"}[15m]) > 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "MCP Pod 正在反复重启"

// src/config.ts
interface ServerConfig {
  port: number;
  logLevel: string;
  allowedPaths: string[];
  maxFileSize: number;
  rateLimit: {
    callsPerMinute: number;
    callsPerHour: number;
  };
  features: {
    tools: boolean;
    resources: boolean;
    prompts: boolean;
    subscriptions: boolean;
  };
}

function loadConfig(): ServerConfig {
  return {
    port: parseInt(process.env.PORT ?? "3000"),
    logLevel: process.env.LOG_LEVEL ?? "info",
    allowedPaths: (process.env.ALLOWED_PATHS ?? "/tmp").split(","),
    maxFileSize: parseInt(process.env.MAX_FILE_SIZE ?? "10485760"), // 10MB
    rateLimit: {
      callsPerMinute: parseInt(process.env.RATE_LIMIT_PER_MINUTE ?? "60"),
      callsPerHour: parseInt(process.env.RATE_LIMIT_PER_HOUR ?? "500"),
    },
    features: {
      tools: process.env.FEATURE_TOOLS !== "false",
      resources: process.env.FEATURE_RESOURCES !== "false",
      prompts: process.env.FEATURE_PROMPTS !== "false",
      subscriptions: process.env.FEATURE_SUBSCRIPTIONS === "true",
    },
  };
}

export const config = loadConfig();

apiVersion: v1
kind: ConfigMap
metadata:
  name: mcp-server-config
data:
  LOG_LEVEL: "info"
  ALLOWED_PATHS: "/data/workspace,/data/shared"
  MAX_FILE_SIZE: "10485760"
  RATE_LIMIT_PER_MINUTE: "120"
  FEATURE_SUBSCRIPTIONS: "true"
---
apiVersion: v1
kind: Secret
metadata:
  name: mcp-server-secrets
type: Opaque
stringData:
  DATABASE_URL: "postgresql://user:pass@db/mcp"
  API_KEY: "sk-production-key"

// 定期备份工具调用日志和配置
import { CronJob } from "cron";

const backupJob = new CronJob(
  "0 2 * * *", // 每天凌晨 2 点
  async () => {
    logger.info("开始备份 MCP 数据");
    try {
      // 备份审计日志
      await backupAuditLogs();
      // 备份配置文件
      await backupConfiguration();
      // 清理过期日志
      await cleanupOldLogs(30); // 保留 30 天
    } catch (error) {
      logger.error("备份失败", { error });
    }
  },
  null,
  true,
  "UTC"
);