<feat> 重构配置管理与安全检查机制，新增SQL解析器，优化数据库连接池管理

2025-12-08 17:52:28 +08:00 · 2025-05-09 11:36:30 +08:00
parent e0550a531d
commit 9cad3837a6
17 changed files with 1731 additions and 728 deletions
--- a/README.md
+++ b/README.md
@ -1,209 +1,206 @@
-# MySQL查询服务器
+# MySQL查询服务器 / MySQL Query Server

-这是一个基于MCP（Model-Controller-Provider）框架的MySQL查询服务器，提供了通过SSE（Server-Sent Events）进行MySQL数据库操作的功能。
+---

-## 功能特点
+## 1. 项目简介 / Project Introduction

- 基于FastMCP框架构建
- 支持SSE（Server-Sent Events）实时数据传输
- 提供MySQL数据库查询接口
- 完整的日志记录系统
- 自动事务管理（提交/回滚）
- 环境变量配置支持
- SQL安全检查机制
-  - 风险等级控制
-  - SQL注入防护
-  - 危险操作拦截
-  - WHERE子句强制检查
-  - 自动返回修改操作影响的行数
- 敏感信息保护机制
- 自动对元数据查询结果进行格式化和增强
+本项目是基于MCP框架的MySQL查询服务器，支持通过SSE协议进行实时数据库操作，具备完善的安全、日志、配置和敏感信息保护机制，适用于开发、测试和生产环境下的安全MySQL数据访问。

-## API接口功能
+This project is a MySQL query server based on the MCP framework, supporting real-time database operations via SSE protocol. It features comprehensive security, logging, configuration, and sensitive information protection mechanisms, suitable for secure MySQL data access in development, testing, and production environments.

-系统提供以下四大类工具：
+---

-### 基础查询工具
+## 2. 主要特性 / Key Features

- `mysql_query`: 执行任意SQL查询，支持参数化查询
+- 基于FastMCP框架，异步高性能
+- 支持高并发的数据库连接池，参数灵活可调
+- 支持SSE实时推送
+- 丰富的MySQL元数据与结构查询API
+- 自动事务管理与回滚
+- 多级SQL风险控制与注入防护
+- 敏感信息自动隐藏与自定义
+- 灵活的环境变量配置
+- 完善的日志与错误处理

-### 元数据查询工具
+- Built on FastMCP framework, high-performance async
+- Connection pool for high concurrency, with flexible parameter tuning
+- SSE real-time push support
+- Rich MySQL metadata & schema query APIs
+- Automatic transaction management & rollback
+- Multi-level SQL risk control & injection protection
+- Automatic and customizable sensitive info masking
+- Flexible environment variable configuration
+- Robust logging & error handling

- `mysql_show_tables`: 获取数据库中的表列表，支持模式匹配和限制结果数量
- `mysql_show_columns`: 获取表的列信息
- `mysql_describe_table`: 描述表结构
- `mysql_show_create_table`: 获取表的创建语句
+---

-### 数据库信息查询工具
+## 3. 快速开始 / Quick Start

- `mysql_show_databases`: 获取所有数据库列表，支持过滤系统数据库
- `mysql_show_variables`: 获取MySQL服务器变量
- `mysql_show_status`: 获取MySQL服务器状态信息
-
-### 表结构高级查询工具
-
- `mysql_show_indexes`: 获取表的索引信息
- `mysql_show_table_status`: 获取表状态信息
- `mysql_show_foreign_keys`: 获取表的外键约束信息
- `mysql_paginate_results`: 提供结果分页功能
-
-## 系统要求
-
- Python 3.6+
- MySQL服务器
- 依赖包：
-  - mysql-connector-python
-  - python-dotenv
-  - mcp (FastMCP框架)
-
-## 安装步骤
-
-1. 克隆项目到本地：
-```bash
-git clone [项目地址]
-cd mysql-query-server
-```
-
-2. 安装依赖包：
+### 安装依赖 / Install Dependencies
 ```bash
 pip install -r requirements.txt
 ```

-3. 配置环境变量：
-   - 复制`.env.example`文件并重命名为`.env`
-   - 根据实际情况修改`.env`文件中的配置
-
-## 环境变量配置
-
-在`.env`文件中配置以下参数：
-
-### 基本配置
- `HOST`: 服务器监听地址（默认：127.0.0.1）
- `PORT`: 服务器监听端口（默认：3000）
- `MYSQL_HOST`: MySQL服务器地址
- `MYSQL_PORT`: MySQL服务器端口
- `MYSQL_USER`: MySQL用户名
- `MYSQL_PASSWORD`: MySQL密码
- `MYSQL_DATABASE`: MySQL数据库名
-
-### SQL安全配置
- `ENV_TYPE`: 环境类型（development/production）
- `ALLOWED_RISK_LEVELS`: 允许的风险等级（LOW/MEDIUM/HIGH/CRITICAL）
- `BLOCKED_PATTERNS`: 禁止的SQL模式（正则表达式，用逗号分隔）
- `ENABLE_QUERY_CHECK`: 是否启用SQL安全检查（true/false）
- `ALLOW_SENSITIVE_INFO`: 是否允许查询敏感信息（true/false）
- `SENSITIVE_INFO_FIELDS`: 自定义敏感字段模式列表（逗号分隔）
-
-## 安全机制详解
-
-### 风险等级控制
- LOW: 查询操作（SELECT）和元数据操作（SHOW, DESCRIBE等）
- MEDIUM: 基本数据修改（INSERT，有WHERE的UPDATE/DELETE）
- HIGH: 结构变更（CREATE/ALTER）和无WHERE的UPDATE
- CRITICAL: 危险操作（DROP/TRUNCATE）和无WHERE的DELETE操作
-
-### 环境特性差异
- 开发环境：
-  - 允许较高风险的操作
-  - 不隐藏敏感信息
-  - 提供详细的错误信息
- 生产环境：
-  - 默认只允许LOW风险操作
-  - 严格限制数据修改
-  - 自动隐藏敏感信息
-  - 错误信息不暴露实现细节
-
-### 敏感信息保护
-系统会自动检测并隐藏包含以下关键词的变量/状态值：
- password、auth、credential、key、secret、private
- ssl、tls、cipher、certificate
- host、path、directory等系统路径信息
-
-### 事务管理
- 对于修改操作（INSERT/UPDATE/DELETE）会自动提交事务
- 执行错误时自动回滚事务
- 返回操作影响的行数
-
-## 启动服务器
-
-运行以下命令启动服务器：
+### 配置环境变量 / Configure Environment Variables
+复制`.env.example`为`.env`，并根据实际情况修改。
+Copy `.env.example` to `.env` and modify as needed.

+### 启动服务 / Start the Server
 ```bash
-python src/server.py
+python -m src.server
 ```
+默认监听：http://127.0.0.1:3000/sse
+Default endpoint: http://127.0.0.1:3000/sse

-服务器将在配置的地址和端口上启动，默认为 `http://127.0.0.1:3000/sse`
+---

-## 项目结构
+## 4. 目录结构 / Project Structure

 ```
 .
-├── src/                     # 源代码目录
-│   ├── server.py           # 主服务器文件
-│   ├── db/                 # 数据库相关代码
-│   │   └── mysql_operations.py # MySQL操作实现
-│   ├── security/           # SQL安全相关代码
-│   │   ├── interceptor.py   # SQL拦截器
-│   │   ├── query_limiter.py # SQL安全检查器
-│   │   └── sql_analyzer.py  # SQL分析器
-│   └── tools/              # 工具类代码
-│       ├── mysql_tool.py           # 基础查询工具
-│       ├── mysql_metadata_tool.py  # 元数据查询工具
-│       ├── mysql_info_tool.py      # 数据库信息查询工具
-│       ├── mysql_schema_tool.py    # 表结构高级查询工具
-│       └── metadata_base_tool.py   # 元数据工具基类
-├── tests/                  # 测试代码目录
-├── .env.example            # 环境变量示例文件
-└── requirements.txt        # 项目依赖文件
+├── src/
+│   ├── server.py           # 主服务器入口 / Main server entry
+│   ├── config.py           # 配置项定义 / Config definitions
+│   ├── validators.py       # 参数校验 / Parameter validation
+│   ├── db/
+│   │   └── mysql_operations.py # 数据库操作 / DB operations
+│   ├── security/
+│   │   ├── interceptor.py      # SQL拦截 / SQL interception
+│   │   ├── query_limiter.py    # 风险控制 / Risk control
+│   │   └── sql_analyzer.py     # SQL分析 / SQL analysis
+│   └── tools/
+│       ├── mysql_tool.py           # 基础查询 / Basic query
+│       ├── mysql_metadata_tool.py  # 元数据查询 / Metadata query
+│       ├── mysql_info_tool.py      # 信息查询 / Info query
+│       ├── mysql_schema_tool.py    # 结构查询 / Schema query
+│       └── metadata_base_tool.py   # 工具基类 / Tool base class
+├── tests/                  # 测试 / Tests
+├── .env.example            # 环境变量示例 / Env example
+└── requirements.txt        # 依赖 / Requirements
 ```

-## 常见问题解决
+---

-### DELETE操作未执行成功
- 检查DELETE操作是否包含WHERE条件
- 无WHERE条件的DELETE操作被标记为CRITICAL风险级别
- 确保环境变量ALLOWED_RISK_LEVELS中包含CRITICAL（如果需要执行该操作）
- 检查影响行数返回值，确认操作是否实际影响了数据库
+## 5. 环境变量与配置 / Environment Variables & Configuration

-### 环境变量未生效
- 确保在server.py中的load_dotenv()调用发生在导入其他模块之前
- 重启应用以确保环境变量被正确加载
- 检查日志中"从环境变量读取到的风险等级设置"的输出
+| 变量名 / Variable         | 说明 / Description                                   | 默认值 / Default |
+|--------------------------|------------------------------------------------------|------------------|
+| HOST                     | 服务器监听地址 / Server listen address                | 127.0.0.1        |
+| PORT                     | 服务器监听端口 / Server listen port                   | 3000             |
+| MYSQL_HOST               | MySQL服务器地址 / MySQL server host                   | localhost        |
+| MYSQL_PORT               | MySQL服务器端口 / MySQL server port                   | 3306             |
+| MYSQL_USER               | MySQL用户名 / MySQL username                          | root             |
+| MYSQL_PASSWORD           | MySQL密码 / MySQL password                            | (空/empty)       |
+| MYSQL_DATABASE           | 要连接的数据库名 / Database name                      | (空/empty)       |
+| DB_CONNECTION_TIMEOUT    | 连接超时时间(秒) / Connection timeout (seconds)       | 5                |
+| DB_AUTH_PLUGIN           | 认证插件类型 / Auth plugin type                       | mysql_native_password |
+| DB_POOL_ENABLED          | 是否启用连接池 / Enable connection pool (true/false)  | true             |
+| DB_POOL_MIN_SIZE         | 连接池最小连接数 / Pool min size                      | 5                |
+| DB_POOL_MAX_SIZE         | 连接池最大连接数 / Pool max size                      | 20               |
+| DB_POOL_RECYCLE          | 连接回收时间(秒) / Pool recycle time (seconds)        | 300              |
+| DB_POOL_MAX_LIFETIME     | 连接最大存活时间(秒, 0=不限制) / Max lifetime (sec)   | 0                |
+| DB_POOL_ACQUIRE_TIMEOUT  | 获取连接超时时间(秒) / Acquire timeout (seconds)      | 10.0             |
+| ENV_TYPE                 | 环境类型(development/production) / Env type           | development      |
+| ALLOWED_RISK_LEVELS      | 允许的风险等级(逗号分隔) / Allowed risk levels        | LOW,MEDIUM       |
+| ALLOW_SENSITIVE_INFO     | 允许查询敏感字段 / Allow sensitive info (true/false)  | false            |
+| SENSITIVE_INFO_FIELDS    | 自定义敏感字段模式(逗号分隔) / Custom sensitive fields | (空/empty)       |
+| MAX_SQL_LENGTH           | 最大SQL语句长度 / Max SQL length                      | 5000             |
+| BLOCKED_PATTERNS         | 阻止的SQL模式(逗号分隔) / Blocked SQL patterns        | (空/empty)       |
+| ENABLE_QUERY_CHECK       | 启用查询安全检查 / Enable query check (true/false)    | true             |
+| LOG_LEVEL                | 日志级别(DEBUG/INFO/...) / Log level                 | DEBUG            |

-### 操作被安全机制拒绝
- 检查操作的风险级别是否在允许的范围内
- 如果需要执行高风险操作，相应地调整ALLOWED_RISK_LEVELS
- 对于不带WHERE条件的UPDATE或DELETE，可以添加条件（即使是WHERE 1=1）降低风险级别
+> 注/Note: 部分云MySQL需指定`DB_AUTH_PLUGIN`为`mysql_native_password`。

-### 无法查看敏感信息
- 在开发环境中，设置ALLOW_SENSITIVE_INFO=true
- 在生产环境中，敏感信息默认会被隐藏，这是安全特性
+---

-## 日志系统
+## 6. 自动化与资源管理优化 / Automation & Resource Management Enhancements

-服务器包含完整的日志记录系统，可以在控制台和日志文件中查看运行状态和错误信息。日志级别可以在`server.py`中配置。
+### 自动化工具注册 / Automated Tool Registration
+- 所有MySQL相关API工具均采用自动注册机制：
+  - 无需手动在主入口维护注册代码，新增/删除工具只需在`src/tools/`目录下实现`register_xxx_tool(s)`函数即可。
+  - 系统启动时自动扫描并注册，极大提升可维护性和扩展性。
+- All MySQL-related API tools are registered automatically:
+  - No need to manually maintain registration code in the main entry. To add or remove a tool, simply implement a `register_xxx_tool(s)` function in the `src/tools/` directory.
+  - The system scans and registers tools automatically at startup, greatly improving maintainability and extensibility.

-## 错误处理
+### 连接池自动回收与资源管理 / Connection Pool Auto-Recycling & Resource Management
+- 连接池采用事件循环隔离与自动回收机制：
+  - 每个事件循环独立池，支持高并发与多环境。
+  - 定期（默认每5分钟）自动回收无效或失效的连接池，防止资源泄漏。
+  - 事件循环关闭时自动关闭对应连接池，确保资源彻底释放。
+  - 支持多数据库/多租户场景扩展。
+- 所有资源管理操作均有详细日志，便于追踪和排查。
+- The connection pool uses event loop isolation and auto-recycling:
+  - Each event loop has its own pool, supporting high concurrency and multi-environment deployment.
+  - Unused or invalid pools are automatically recycled every 5 minutes (by default), preventing resource leaks.
+  - When an event loop is closed, its pool is automatically closed to ensure complete resource release.
+  - Ready for multi-database/multi-tenant scenarios.
+- All resource management operations are logged in detail for easy tracking and troubleshooting.

-服务器包含完善的错误处理机制：
- MySQL连接器导入检查
- 数据库配置验证
- SQL安全检查
- 运行时错误捕获和记录
- 事务自动回滚
+---

-## 贡献指南
+## 7. 安全机制 / Security Mechanisms

-欢迎提交Issue和Pull Request来改进项目。
+- 多级SQL风险等级（LOW/MEDIUM/HIGH/CRITICAL）
+- SQL注入与危险操作拦截
+- WHERE子句强制检查
+- 敏感信息自动隐藏（支持自定义字段）
+- 生产环境默认只允许低风险操作

-## 许可证
+- Multi-level SQL risk levels (LOW/MEDIUM/HIGH/CRITICAL)
+- SQL injection & dangerous operation interception
+- Mandatory WHERE clause check
+- Automatic sensitive info masking (customizable fields)
+- Production allows only low-risk operations by default
+
+---
+
+## 8. 日志与错误处理 / Logging & Error Handling
+
+- 日志级别可配置（LOG_LEVEL）
+- 控制台与文件日志输出
+- 详细记录运行状态与错误
+- 完善的异常捕获与事务回滚
+
+- Configurable log level (LOG_LEVEL)
+- Console & file log output
+- Detailed running status & error logs
+- Robust exception capture & transaction rollback
+
+---
+
+## 9. 常见问题 / FAQ
+
+### Q: DELETE操作未执行成功？
+A: 检查是否有WHERE条件，无WHERE为高风险，需在ALLOWED_RISK_LEVELS中允许CRITICAL。
+
+Q: Why does DELETE not work?
+A: Check for WHERE clause. DELETE without WHERE is high risk (CRITICAL), must be allowed in ALLOWED_RISK_LEVELS.
+
+### Q: 如何自定义敏感字段？
+A: 设置SENSITIVE_INFO_FIELDS，如SENSITIVE_INFO_FIELDS=password,token
+
+Q: How to customize sensitive fields?
+A: Set SENSITIVE_INFO_FIELDS, e.g. SENSITIVE_INFO_FIELDS=password,token
+
+### Q: limit参数报错？
+A: limit必须为非负整数。
+
+Q: limit parameter error?
+A: limit must be a non-negative integer.
+
+---
+
+## 10. 贡献指南 / Contribution Guide
+
+欢迎通过Issue和Pull Request参与改进。
+Contributions via Issue and Pull Request are welcome.
+
+---
+
+## 11. 许可证 / License

 MIT License

-Copyright (c) 2024 MCP MySQL Query Server
-
-特此免费授予任何获得本软件副本和相关文档文件（"软件"）的人不受限制地处理本软件的权利，包括不受限制地使用、复制、修改、合并、发布、分发、再许可和/或出售本软件副本，以及允许本软件的使用者这样做，但须符合以下条件：
-
-上述版权声明和本许可声明应包含在本软件的所有副本或重要部分中。
-
-本软件按"原样"提供，不提供任何形式的明示或暗示的保证，包括但不限于对适销性、特定用途的适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权行为还是其他方面，产生于、源于或与本软件有关，或与本软件的使用或其他交易有关。
+本软件按"原样"提供，不提供任何形式的明示或暗示的保证，包括但不限于对适销性、特定用途的适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权行为还是其他方面，产生于、源于或与本软件有关，或与本软件的使用或其他交易有关。  
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.