Odoo MCP Server

# 多服务器架构改进文档 ## 架构变更概述 MCP服务器模块现在支持真正的多服务器架构，每个`mcp.server`记录都是一个独立的MCP服务器实例，运行在不同的端口上。 ## 主要改进 ### 1. 独立端口分配与唯一性保证 每个MCP服务器现在都有自己的唯一端口： ```python server_port = fields.Integer('服务器端口', default=lambda self: self._get_next_available_port()) # 数据库级别唯一性约束 _sql_constraints = [ ('server_port_unique', 'unique(server_port)', '服务器端口必须唯一！') ] ``` - **自动端口分配**：从10888开始自动分配可用端口 - **端口冲突检测**：自动检测并避免端口冲突 - **端口范围**：10888-11000（主要范围），20000-65000（备用范围） - **唯一性验证**：多层次的端口唯一性验证机制 - **端口可用性检查**：提供端口可用性检查功能 ### 2. 独立服务器实例与安全机制 每个服务器记录对应一个独立的FastMCP实例，并具有独立的安全设置： ```python self.mcp_servers = { server_id: { 'instance': mcp_server, # FastMCP实例 'port': port, # 监听端口 'thread': thread, # 服务器线程 'name': name, # 服务器名称 'security': { # 安全设置 'require_auth': True, # 是否需要授权 'api_key': '...', # API密钥 'allowed_ips': [], # 允许的IP地址 'log_requests': True # 是否记录请求 } } } ``` ### 3. 线程管理 每个服务器实例运行在独立的线程中： - **线程命名**：`FastMCP-Server-{server_id}-{port}` - **线程跟踪**：存储线程引用便于管理 - **守护线程**：自动随主进程退出 ## 数据模型变更 ### 新增字段 ```python class MCPServer(models.Model): # 端口字段 server_port = fields.Integer('服务器端口', default=lambda self: self._get_next_available_port()) # 安全设置字段 require_auth = fields.Boolean('需要授权', default=True) allowed_ips = fields.Text('允许的IP地址') log_requests = fields.Boolean('记录请求', default=True) max_requests_per_minute = fields.Integer('每分钟最大请求数', default=60) ``` ### 智能端口分配与验证逻辑 ```python def _get_next_available_port(self): """获取下一个可用的端口号""" # 1. 查找已使用的端口 # 2. 从10888开始顺序查找可用端口 # 3. 如果顺序查找失败，尝试随机高端口 # 4. 使用socket测试端口是否真的可用 # 5. 返回第一个可用端口 ``` ```python @api.constrains('server_port') def _check_server_port(self): """验证服务器端口唯一性""" # 1. 检查是否有其他记录使用相同的端口 # 2. 如果有，抛出ValidationError ``` ### URL自动生成 ```python @api.model def create(self, vals): # 自动生成服务器URL if 'server_port' in vals: vals['server_url'] = f'http://127.0.0.1:{vals["server_port"]}' ``` ## 默认配置 ### 预配置服务器 1. **默认MCP服务器** - 端口：10888 - 状态：活动（自动启动） - 功能：完整的Odoo数据访问 2. **演示服务器 1** - 端口：10889 - 状态：草稿 3. **演示服务器 2** - 端口：10890 - 状态：草稿 ## 服务器管理 ### 启动流程 1. **创建服务器记录**：自动分配端口和生成URL 2. **激活服务器**：启动独立的FastMCP实例 3. **端口绑定**：在指定端口上监听连接 4. **状态更新**：更新服务器状态为"活动" ### 停止流程 1. **停止请求**：调用stop_server方法 2. **线程清理**：清理服务器线程 3. **实例移除**：从服务器字典中移除 4. **状态更新**：更新服务器状态为"不活动" ## 用户界面改进 ### 表单视图 - 显示服务器端口字段（突出显示） - 端口字段可编辑（创建时） - URL字段自动生成（只读） - 添加"检查端口"按钮验证端口可用性 - 新增"安全设置"选项卡 - API密钥管理和生成功能 - IP白名单和请求限制配置 ### 列表视图 - 显示服务器端口列 - 按端口排序和筛选 - 状态颜色编码 ## 使用示例 ### 创建新服务器 ```python # 创建新的MCP服务器 server = env['mcp.server'].create({ 'name': '我的MCP服务器', # 端口会自动分配，比如10891 # URL会自动生成：http://127.0.0.1:10891 }) # 激活服务器 server.action_activate() ``` ### 多服务器场景 ```python # 同时运行多个服务器 servers = env['mcp.server'].search([('state', '=', 'active')]) for server in servers: print(f"服务器: {server.name}, 端口: {server.server_port}, URL: {server.server_url}") # 输出示例： # 服务器: 默认MCP服务器, 端口: 10888, URL: http://127.0.0.1:10888 # 服务器: 客户服务器, 端口: 10891, URL: http://127.0.0.1:10891 # 服务器: 产品服务器, 端口: 10892, URL: http://127.0.0.1:10892 ``` ## 网络配置 ### 端口范围 - **起始端口**：10888 - **结束端口**：11000 - **最大服务器数**：112个并发服务器 ### 防火墙配置 ```bash # 开放端口范围（如需外部访问） ufw allow 10888:11000/tcp # 或单独开放端口 ufw allow 10888/tcp ufw allow 10889/tcp ``` ## 监控和调试 ### 检查运行中的服务器 ```bash # 查看所有监听的MCP端口 netstat -tlnp | grep "1088[8-9]\|109[0-9][0-9]" # 检查特定端口 lsof -i :10888 lsof -i :10889 ``` ### 日志监控 ```python # 每个服务器的日志都包含端口信息 INFO: 开始异步启动MCP服务器: 默认MCP服务器 (端口: 10888) INFO: FastMCP服务器线程已启动，线程名: FastMCP-Server-1-10888 INFO: FastMCP服务器已在 0.0.0.0:10888 启动 ``` ## 性能考虑 ### 资源使用 - **内存**：每个服务器实例约占用10-20MB - **线程**：每个服务器一个守护线程 - **端口**：每个服务器占用一个TCP端口 ### 扩展性 - **理论上限**：受端口范围限制（112个服务器） - **实际建议**：根据服务器资源，建议不超过20-30个并发服务器 - **负载均衡**：可通过反向代理实现负载均衡 ## 迁移指南 ### 从单服务器架构迁移 1. **数据库更新**：运行模块升级添加端口字段 2. **端口分配**：现有服务器会自动分配端口 3. **URL更新**：服务器URL会自动更新 4. **重启服务**：重启Odoo以应用更改 ### 兼容性 - **向后兼容**：现有API调用保持兼容 - **配置保留**：现有服务器配置和资源保持不变 - **自动升级**：模块升级时自动处理数据迁移 ## 故障排除 ### 常见问题 1. **端口冲突** ``` 解决方案： - 使用"检查端口"按钮验证端口可用性 - 系统会自动阻止使用已被占用的端口 - 可以清除端口字段让系统自动分配新端口 ``` 2. **服务器启动失败** ``` 检查：端口是否可用，防火墙设置，日志错误信息 ``` 3. **多服务器管理混乱** ``` 建议：使用有意义的服务器名称，记录端口分配 ``` ## 最佳实践 1. **命名规范**：使用描述性的服务器名称 2. **端口管理**：记录端口分配，避免手动冲突 3. **资源规划**：根据需求合理规划服务器数量 4. **监控告警**：设置端口监控和服务器状态告警 ## 版本信息 - **架构版本**：2.0 - **更新日期**：2025-07-22 - **兼容性**：Odoo 17.0+, FastMCP 2.4.0+