LifeFrame
部署指南

MCP Server 部署指南

本指南介绍如何部署和配置 LifeFrame MCP Server。

📋 前置要求

  • Node.js 18+ 和 pnpm
  • PostgreSQL 数据库
  • Docker（可选，用于容器化部署）
  • 域名（可选，用于 HTTPS）

🚀 快速部署

1. 环境变量配置

在 .env 文件中添加以下配置：

# MCP Server 功能开关
MCP_SERVER_ENABLED=true

# MCP API 密钥前缀
MCP_API_KEY_PREFIX=lfmcp_

# MCP 速率限制配置
MCP_RATE_LIMIT_FREE=100
MCP_RATE_LIMIT_PRO=1000
MCP_RATE_LIMIT_ENTERPRISE=-1

# MCP Token 配额
MCP_TOKEN_QUOTA_FREE=10000
MCP_TOKEN_QUOTA_PRO=500000
MCP_TOKEN_QUOTA_ENTERPRISE=5000000

# MCP 日志级别
MCP_LOG_LEVEL=info

2. 数据库迁移

运行数据库迁移以创建 MCP 相关表：

# 开发环境
pnpm prisma migrate dev

# 生产环境
pnpm prisma migrate deploy

这将创建以下表：

  • MCPApiKey - 存储 API Key
  • MCPUsageLog - 记录使用日志

3. 启动服务

# 开发环境
pnpm dev

# 生产环境
pnpm build
pnpm start

MCP Server 将在 http://localhost:3000/api/mcp 启动。

🐳 Docker 部署

Docker Compose 配置

在 docker-compose.yml 中添加以下服务：

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - MCP_SERVER_ENABLED=true
      - MCP_API_KEY_PREFIX=lfmcp_
      - MCP_RATE_LIMIT_FREE=100
      - MCP_RATE_LIMIT_PRO=1000
    depends_on:
      - db
      - redis

  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=lifeframe
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

启动服务：

docker-compose up -d

🔒 安全配置

API Key 管理

创建 API Key 的三种方式：

方式 1：通过 Web UI（推荐）

  1. 登录 LifeFrame
  2. 进入「设置」→「API 密钥」
  3. 点击「创建新密钥」

方式 2：通过数据库

INSERT INTO "MCPApiKey" (
  "id",
  "userId",
  "name",
  "keyHash",
  "keyPrefix",
  "scopes",
  "rateLimitTier",
  "isActive",
  "createdAt",
  "updatedAt"
) VALUES (
  gen_random_uuid(),
  'user-id-here',
  'My API Key',
  SHA256('lfmcp_your_api_key_here'),
  'lfmcp_',
  '["photos:read","ai:review"]',
  'FREE',
  true,
  NOW(),
  NOW()
);

方式 3：通过 API（开发中）

curl -X POST https://your-domain.com/api/mcp/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Key",
    "scopes": ["photos:read", "ai:review"],
    "rateLimitTier": "PRO"
  }'

HTTPS 配置

使用 Nginx 配置 HTTPS：

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /api/mcp {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

📊 监控和日志

查看使用日志

-- 查询最近 100 条使用日志
SELECT
  "createdAt",
  "toolName",
  "statusCode",
  "responseTime",
  "tokensUsed",
  "costUsd"
FROM "MCPUsageLog"
ORDER BY "createdAt" DESC
LIMIT 100;

统计用户使用

-- 统计每个用户的总请求数和成本
SELECT
  u."email",
  COUNT(m."id") as total_requests,
  SUM(m."tokensUsed") as total_tokens,
  SUM(m."costUsd") as total_cost
FROM "MCPUsageLog" m
JOIN "User" u ON m."userId" = u."id"
WHERE m."createdAt" >= NOW() - INTERVAL '30 days'
GROUP BY u."id"
ORDER BY total_requests DESC;

🧪 测试 MCP Server

健康检查

curl http://localhost:3000/api/mcp

预期响应：

{
  "status": "ok",
  "service": "LifeFrame MCP Server",
  "version": "1.0.0",
  "timestamp": "2026-04-04T...",
  "endpoints": {
    "http": "/api/mcp",
    "tools": "/api/mcp/tools"
  }
}

测试工具调用

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lfmcp_your_api_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

测试实际工具调用

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lfmcp_your_api_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_photos",
      "arguments": {
        "limit": 5
      }
    }
  }'

🔧 性能优化

1. 启用 Redis 缓存（推荐）

# 安装 Redis
pnpm add ioredis

# 配置环境变量
REDIS_URL=redis://localhost:6379

2. 数据库索引优化

以下索引已自动创建：

  • MCPApiKey_keyHash_key - API Key 哈希索引
  • MCPApiKey_userId_idx - 用户 ID 索引
  • MCPUsageLog_apiKeyId_idx - API Key ID 索引
  • MCPUsageLog_createdAt_idx - 创建时间索引

3. 连接池配置

# Prisma 连接池配置
DATABASE_URL="postgresql://postgres:password@localhost:5432/lifeframe?connection_limit=10&pool_timeout=20"

🐛 故障排查

问题：工具未注册

症状：调用工具时返回 "Tool not found"

解决方案：

  1. 检查控制台是否有 "MCP tools registered" 日志
  2. 确认 /lib/mcp/tools/ 下的文件已正确导入
  3. 重启服务

问题：认证失败

症状：返回 "Unauthorized: Invalid API key"

解决方案：

  1. 检查 API Key 格式（lfmcp_...）
  2. 验证数据库中的 keyHash 是否正确
  3. 确认 API Key 的 isActive 字段为 true

问题：速率限制不生效

症状：请求超过限制但仍然被允许

解决方案：

  1. 检查环境变量 MCP_RATE_LIMIT_* 配置
  2. 确认 Redis 连接正常（如果使用缓存）
  3. 查看 MCPUsageLog 表中的记录

📈 生产环境建议

1. 使用进程管理器

# 使用 PM2
pm2 start npm --name "lifeframe" -- start
pm2 save
pm2 startup

2. 配置日志轮转

# /etc/logrotate.d/lifeframe
/home/user/lifeframe/logs/*.log {
  daily
  rotate 14
  compress
  delaycompress
  notifempty
  copytruncate
}

3. 监控告警

  • 集成 Sentry 进行错误监控
  • 配置 Prometheus + Grafana 进行性能监控
  • 设置日志告警（如错误率超过 1%）

🔄 更新和维护

更新 MCP Server

# 拉取最新代码
git pull origin main

# 安装依赖
pnpm install

# 运行数据库迁移
pnpm prisma migrate deploy

# 重启服务
pm2 restart lifeframe

备份数据

# 备份数据库
pg_dump -U postgres lifeframe > backup_$(date +%Y%m%d).sql

# 备份 MCP 相关表
pg_dump -U postgres -t "MCPApiKey" -t "MCPUsageLog" lifeframe > mcp_backup_$(date +%Y%m%d).sql

📚 相关文档

Docker 自托管部署指南

LifeFrame 个人版 Docker 自托管一键部署：网站 + PostgreSQL + MinIO，从国内容器仓库拉取镜像。

常见问题

LifeFrame 常见问题解答。

On this page

MCP Server 部署指南📋 前置要求🚀 快速部署1. 环境变量配置2. 数据库迁移3. 启动服务🐳 Docker 部署Docker Compose 配置🔒 安全配置API Key 管理方式 1：通过 Web UI（推荐）方式 2：通过数据库方式 3：通过 API（开发中）HTTPS 配置📊 监控和日志查看使用日志统计用户使用🧪 测试 MCP Server健康检查测试工具调用测试实际工具调用🔧 性能优化1. 启用 Redis 缓存（推荐）2. 数据库索引优化3. 连接池配置🐛 故障排查问题：工具未注册问题：认证失败问题：速率限制不生效📈 生产环境建议1. 使用进程管理器2. 配置日志轮转3. 监控告警🔄 更新和维护更新 MCP Server备份数据📚 相关文档