Skip to content

Latest commit

 

History

History
276 lines (218 loc) · 9.17 KB

security.md

File metadata and controls

276 lines (218 loc) · 9.17 KB

安全架构

English | 中文 | Français | Español | العربية | Русский

通信模式与安全架构

MCP数据库工具服务实现了一套安全的通信模式，旨在每一步都保护您的数据安全。下图展示了数据在各组件之间的流动方式，同时保持安全性：

flowchart LR
    subgraph User["用户环境"]
        Client["AI客户端<br>(Claude/Cursor)"]
        ConfigFile["配置文件<br>(YAML)"]
    end

    subgraph MCP["MCP数据库工具"]
        MCPService["MCP服务"]
        ConnectionManager["连接管理器"]
        QueryProcessor["查询处理器<br>(只读)"]
    end

    subgraph Databases["数据库层"]
        DB1["数据库1"]
        DB2["数据库2"]
        DBn["数据库n"]
    end

    %% 通信流程
    Client-- "步骤1:<br>数据请求<br>(自然语言)" -->MCPService
    ConfigFile-. "启动时加载<br>(连接详情)" .->MCPService
    MCPService-- "步骤2:<br>处理请求" -->ConnectionManager
    ConnectionManager-- "步骤3:<br>打开连接<br>(按需)" -->Databases
    ConnectionManager-- "步骤4:<br>发送查询<br>(仅SELECT)" -->QueryProcessor
    QueryProcessor-- "步骤5:<br>执行查询" -->Databases
    Databases-- "步骤6:<br>返回结果" -->QueryProcessor
    QueryProcessor-- "步骤7:<br>格式化结果" -->MCPService
    MCPService-- "步骤8:<br>传递结果" -->Client
    ConnectionManager-- "步骤9:<br>关闭连接<br>(完成后)" -->Databases

    %% 样式
    classDef user fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#01579b
    classDef mcp fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#2e7d32
    classDef db fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#e65100

    class User user
    class MCP mcp
    class Databases db

    %% 添加安全说明
    style ConnectionManager stroke-dasharray: 5 5
    style QueryProcessor stroke-dasharray: 5 5
Loading

核心安全特性

  1. 隔离访问流程:

    • 您的AI客户端永远不会直接访问您的数据库
    • 所有请求都通过受控的MCP服务环境传递

  2. 临时连接:

    • 仅在需要时才建立数据库连接
    • 查询执行后立即关闭连接
    • 没有可被利用的持久连接

  3. 只读操作:

    • 查询处理器强制执行严格的仅SELECT操作
    • 不可能修改数据（无INSERT、UPDATE、DELETE）

  4. 配置分离:

    • 连接详情隔离在单独的配置文件中
    • 凭据永远不会暴露给AI模型

  5. 多数据库支持:

    • 每个数据库连接单独管理
    • 数据库通过连接管理器相互隔离

  6. 自动超时机制:

    • 查询超时防止长时间运行的查询消耗资源
    • 连接超时确保数据库连接得到适当管理
    • 空闲超时自动关闭不活动的连接
    • 全局超时限制会话的总持续时间

这种架构确保即使您将该工具用于多个数据库或用途，每个连接仍然保持安全和隔离，最大限度地减少数据暴露。

故障排除指南

在使用MCP数据库工具时，您可能会遇到以下常见问题。以下是排查和解决这些问题的指南。

连接问题

  1. 无法连接到数据库

    • 确认您的配置文件中的连接信息是否正确
    • 验证您的数据库服务器是否运行并可访问
    • 检查网络防火墙是否允许连接
    • 对于远程数据库，确认主机名/IP地址和端口是否正确

  2. 配置文件错误

    • 检查YAML语法是否正确（缩进、冒号等）
    • 确认所有必需的字段都已提供
    • 验证文件路径是否正确（特别是SQLite数据库文件）

  3. 权限问题

    • 确保提供的数据库用户具有SELECT权限
    • 检查用户是否可以访问所需的表和视图
    • 对于SQLite，验证文件系统权限是允许读取的

工具和查询问题

  1. 查询执行失败

    • 检查SQL语法错误
    • 确认表名和列名拼写正确
    • 验证您的查询仅包含SELECT操作
    • 对于复杂查询，尝试拆分成更简单的部分

  2. 性能问题

    • 避免没有WHERE条件的大表查询
    • 使用LIMIT子句限制结果集大小
    • 对于复杂的JOIN操作，考虑简化查询
    • 使用dbutils-explain-query工具分析查询性能

  3. MCP客户端集成问题

    • 确认MCP配置正确（命令和参数）
    • 检查路径是绝对路径而非相对路径
    • 验证uvx或docker能在命令行直接运行

  4. 超时问题

    • 运行时间过长的查询可能会被超时设置终止
    • 在连接设置中配置适当的超时值
    • 对于长时间运行的分析查询，请增加查询超时值

日志和诊断

对于高级故障排除，您可以启用详细日志记录：

命令行启用调试

# 启用详细日志
MCP_DEBUG=1 uvx mcp-dbutils --config your_config.yaml

MCP客户端配置中启用调试

在MCP配置中添加环境变量：

JSON配置示例：

{
  "dbutils": {
    "command": "uvx",
    "args": [
      "mcp-dbutils",
      "--config",
      "/path/to/your/config.yaml"
    ],
    "env": {
      "MCP_DEBUG": "1"
    }
  }
}

Cursor MCP配置： 在Cursor设置 → MCP → 编辑服务器配置中添加环境变量。

查看日志

MCP客户端会处理服务生成的日志。不同的MCP客户端可能在不同位置存储日志：

  • 对于Claude Desktop：请查看Claude Desktop的应用日志
  • 对于Cursor：请查看Cursor的MCP日志部分
  • 对于其他客户端：请参考各自客户端的文档了解如何访问MCP服务日志

安全最佳实践

为确保使用MCP数据库工具时的最高安全级别：

  1. 使用只读账户：

    -- PostgreSQL示例
CREATE ROLE readonly_user WITH LOGIN PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE analytics TO readonly_user;
GRANT USAGE ON SCHEMA public TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;

  2. 启用SSL/TLS：

    connections:
  secure-db:
    # ...
    ssl:
      mode: verify-full
      # ...

  3. 限制表访问：

    connections:
  limited-access:
    # ...
    allowed_tables:
      - public.products
      - public.categories
      - analytics.sales

  4. 配置适当的超时：

    MCP数据库工具提供了三种可配置的超时参数，以确保数据库连接的安全性和资源的有效利用：

    查询超时 (query_timeout)：

    • 作用：限制单个SQL查询执行的最大时间。如果查询执行时间超过此值，查询将被自动终止。
    • 单位：秒
    • 默认值：60秒
    • 适用场景：防止复杂查询或大表查询消耗过多资源
    • 配置建议：
      • 常规查询：30-60秒
      • 数据分析查询：300-600秒
      • 报表生成：最高1800秒

    连接超时 (connection_timeout)：

    • 作用：限制建立数据库连接的最大等待时间。如果在此时间内无法建立连接，将返回连接错误。
    • 单位：秒
    • 默认值：10秒
    • 适用场景：网络不稳定或数据库负载高的环境
    • 配置建议：
      • 本地数据库：5-10秒
      • 远程数据库：15-30秒
      • 高负载环境：最高60秒

    空闲超时 (idle_timeout)：

    • 作用：定义连接在空闲多长时间后自动关闭。这有助于释放未使用的连接资源。
    • 单位：秒
    • 默认值：300秒（5分钟）
    • 适用场景：管理连接池中的空闲连接
    • 配置建议：
      • 高频使用：600-1200秒
      • 一般使用：300-600秒
      • 低频使用：60-180秒

    参数关系：

    • 通常 idle_timeout > query_timeout > connection_timeout
    • 如果您的查询需要长时间运行，请确保 query_timeout 足够长
    • 如果 idle_timeout 太短，可能会导致频繁的连接创建和销毁，影响性能

    配置示例：

    connections:
  analytics-db:
    type: postgres
    host: analytics.example.com
    port: 5432
    dbname: analytics
    user: analyst
    password: secure_password
    # 超时配置（所有值均为秒）
    query_timeout: 300     # 允许长时间运行的分析查询
    connection_timeout: 15  # 远程数据库连接等待时间
    idle_timeout: 600      # 保持连接活跃以便频繁查询

    注意事项：

    • 设置过短的超时可能导致合法查询被中断
    • 设置过长的超时可能导致资源浪费和潜在的安全风险
    • 根据您的具体使用场景和数据库性能调整这些值

获取帮助

如果您在使用过程中遇到问题，以下资源可能会有所帮助：

  1. 项目文档：首先查看最新的项目文档以获取使用指南和已知问题

  2. GitHub Issues：搜索或提交新issue报告错误或请求帮助

  3. GitHub Discussions：参与讨论区获取社区支持或分享使用经验