mirror of
https://github.com/samanhappy/mcphub.git
synced 2025-12-24 02:39:19 -05:00
497 lines
9.4 KiB
Plaintext
497 lines
9.4 KiB
Plaintext
---
|
||
title: '服务器管理'
|
||
description: '通过热插拔配置集中管理多个 MCP 服务器'
|
||
---
|
||
|
||
## 概述
|
||
|
||
MCPHub 的服务器管理系统允许您从单个仪表板集中配置、监控和控制多个 MCP（模型上下文协议）服务器。所有更改都会实时应用，无需重启服务器。
|
||
|
||
## 添加 MCP 服务器
|
||
|
||
### 通过仪表板
|
||
|
||
1. **访问仪表板**: 导航到 `http://localhost:3000` 并登录
|
||
2. **点击"添加服务器"**: 位于服务器部分
|
||
3. **填写服务器详细信息**:
|
||
- **名称**: 服务器的唯一标识符
|
||
- **命令**: 可执行命令（例如 `npx`、`uvx`、`python`）
|
||
- **参数**: 命令参数数组
|
||
- **环境变量**: 环境设置的键值对
|
||
- **工作目录**: 命令的可选工作目录
|
||
|
||
### 通过配置文件
|
||
|
||
编辑您的 `mcp_settings.json` 文件：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"server-name": {
|
||
"command": "command-to-run",
|
||
"args": ["arg1", "arg2"],
|
||
"env": {
|
||
"API_KEY": "your-api-key",
|
||
"CONFIG_VALUE": "some-value"
|
||
},
|
||
"cwd": "/optional/working/directory"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 通过 API
|
||
|
||
使用 REST API 以编程方式添加服务器：
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/api/servers \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||
-d '{
|
||
"name": "my-server",
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
|
||
"env": {
|
||
"NODE_ENV": "production"
|
||
},
|
||
"cwd": "/app"
|
||
}'
|
||
```
|
||
|
||
## 服务器配置
|
||
|
||
### 通用配置选项
|
||
|
||
```json
|
||
{
|
||
"name": "filesystem-server",
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
|
||
"env": {
|
||
"NODE_ENV": "production",
|
||
"DEBUG": "mcp:*",
|
||
"MAX_FILES": "1000"
|
||
},
|
||
"cwd": "/app/workspace",
|
||
"timeout": 30000,
|
||
"retries": 3,
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
### Python 服务器示例
|
||
|
||
```json
|
||
{
|
||
"name": "python-server",
|
||
"command": "python",
|
||
"args": ["-m", "mcp_server", "--config", "config.json"],
|
||
"env": {
|
||
"PYTHONPATH": "/app/python",
|
||
"API_KEY": "${API_KEY}",
|
||
"LOG_LEVEL": "INFO"
|
||
},
|
||
"cwd": "/app/python-server"
|
||
}
|
||
```
|
||
|
||
### Node.js 服务器示例
|
||
|
||
```json
|
||
{
|
||
"name": "node-server",
|
||
"command": "node",
|
||
"args": ["server.js", "--port", "3001"],
|
||
"env": {
|
||
"NODE_ENV": "production",
|
||
"PORT": "3001",
|
||
"DATABASE_URL": "${DATABASE_URL}"
|
||
},
|
||
"cwd": "/app/node-server"
|
||
}
|
||
```
|
||
|
||
## 服务器生命周期管理
|
||
|
||
### 启动服务器
|
||
|
||
```bash
|
||
# 启动特定服务器
|
||
curl -X POST http://localhost:3000/api/servers/my-server/start \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
|
||
# 启动所有服务器
|
||
curl -X POST http://localhost:3000/api/servers/start-all \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
### 停止服务器
|
||
|
||
```bash
|
||
# 停止特定服务器
|
||
curl -X POST http://localhost:3000/api/servers/my-server/stop \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
|
||
# 优雅停止（等待当前请求完成）
|
||
curl -X POST http://localhost:3000/api/servers/my-server/stop \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-d '{"graceful": true, "timeout": 30000}'
|
||
```
|
||
|
||
### 重启服务器
|
||
|
||
```bash
|
||
# 重启服务器
|
||
curl -X POST http://localhost:3000/api/servers/my-server/restart \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
## 热配置重载
|
||
|
||
### 更新服务器配置
|
||
|
||
无需重启即可更新配置：
|
||
|
||
```bash
|
||
curl -X PUT http://localhost:3000/api/servers/my-server/config \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-d '{
|
||
"env": {
|
||
"DEBUG": "mcp:verbose",
|
||
"NEW_SETTING": "value"
|
||
},
|
||
"args": ["--verbose", "--new-flag"]
|
||
}'
|
||
```
|
||
|
||
### 批量配置更新
|
||
|
||
```bash
|
||
curl -X PUT http://localhost:3000/api/servers/bulk-update \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-d '{
|
||
"servers": ["server1", "server2"],
|
||
"config": {
|
||
"env": {
|
||
"LOG_LEVEL": "DEBUG"
|
||
}
|
||
}
|
||
}'
|
||
```
|
||
|
||
## 服务器状态监控
|
||
|
||
### 检查服务器状态
|
||
|
||
```bash
|
||
# 获取所有服务器状态
|
||
curl -X GET http://localhost:3000/api/servers/status \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
|
||
# 获取特定服务器状态
|
||
curl -X GET http://localhost:3000/api/servers/my-server/status \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"name": "my-server",
|
||
"status": "running",
|
||
"pid": 12345,
|
||
"uptime": 3600000,
|
||
"memory": {
|
||
"rss": 123456789,
|
||
"heapTotal": 98765432,
|
||
"heapUsed": 87654321
|
||
},
|
||
"cpu": {
|
||
"user": 1000000,
|
||
"system": 500000
|
||
},
|
||
"lastRestart": "2024-01-01T12:00:00.000Z"
|
||
}
|
||
```
|
||
|
||
### 健康检查
|
||
|
||
配置自动健康检查：
|
||
|
||
```json
|
||
{
|
||
"name": "my-server",
|
||
"command": "node",
|
||
"args": ["server.js"],
|
||
"healthCheck": {
|
||
"enabled": true,
|
||
"interval": 30000,
|
||
"timeout": 5000,
|
||
"retries": 3,
|
||
"endpoint": "/health",
|
||
"expectedStatus": 200
|
||
}
|
||
}
|
||
```
|
||
|
||
## 负载均衡
|
||
|
||
### 配置多实例
|
||
|
||
```json
|
||
{
|
||
"name": "load-balanced-server",
|
||
"instances": 3,
|
||
"command": "node",
|
||
"args": ["server.js"],
|
||
"loadBalancer": {
|
||
"strategy": "round-robin",
|
||
"healthCheck": true,
|
||
"stickySession": false
|
||
},
|
||
"env": {
|
||
"PORT": "${PORT}"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 负载均衡策略
|
||
|
||
- **round-robin**: 轮询分发请求
|
||
- **least-connections**: 分发到连接数最少的实例
|
||
- **weighted**: 基于权重分发
|
||
- **ip-hash**: 基于客户端 IP 的一致性哈希
|
||
|
||
## 资源限制
|
||
|
||
### 设置资源限制
|
||
|
||
```json
|
||
{
|
||
"name": "resource-limited-server",
|
||
"command": "python",
|
||
"args": ["server.py"],
|
||
"resources": {
|
||
"memory": {
|
||
"limit": "512MB",
|
||
"warning": "400MB"
|
||
},
|
||
"cpu": {
|
||
"limit": "50%",
|
||
"priority": "normal"
|
||
},
|
||
"processes": {
|
||
"max": 10
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 监控资源使用
|
||
|
||
```bash
|
||
# 获取资源使用统计
|
||
curl -X GET http://localhost:3000/api/servers/my-server/resources \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
## 日志管理
|
||
|
||
### 配置日志记录
|
||
|
||
```json
|
||
{
|
||
"name": "my-server",
|
||
"command": "node",
|
||
"args": ["server.js"],
|
||
"logging": {
|
||
"level": "info",
|
||
"file": "/var/log/mcphub/my-server.log",
|
||
"maxSize": "100MB",
|
||
"maxFiles": 5,
|
||
"rotate": true,
|
||
"format": "json"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
# 获取实时日志
|
||
curl -X GET http://localhost:3000/api/servers/my-server/logs \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
|
||
# 获取带过滤器的日志
|
||
curl -X GET "http://localhost:3000/api/servers/my-server/logs?level=error&limit=100" \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
## 环境变量管理
|
||
|
||
### 动态环境变量
|
||
|
||
```json
|
||
{
|
||
"name": "dynamic-server",
|
||
"command": "python",
|
||
"args": ["server.py"],
|
||
"env": {
|
||
"API_KEY": "${secrets:api_key}",
|
||
"DATABASE_URL": "${vault:db_url}",
|
||
"CURRENT_TIME": "${time:iso}",
|
||
"SERVER_ID": "${server:id}",
|
||
"HOSTNAME": "${system:hostname}"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 环境变量模板
|
||
|
||
支持的模板变量：
|
||
|
||
- `${secrets:key}`: 从密钥存储获取
|
||
- `${vault:path}`: 从 Vault 获取
|
||
- `${env:VAR}`: 从系统环境变量获取
|
||
- `${time:format}`: 当前时间戳
|
||
- `${server:property}`: 服务器属性
|
||
- `${system:property}`: 系统属性
|
||
|
||
## 服务发现
|
||
|
||
### 自动服务发现
|
||
|
||
```json
|
||
{
|
||
"serviceDiscovery": {
|
||
"enabled": true,
|
||
"provider": "consul",
|
||
"config": {
|
||
"host": "localhost",
|
||
"port": 8500,
|
||
"serviceName": "mcp-server",
|
||
"tags": ["mcp", "ai", "api"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 注册服务
|
||
|
||
```bash
|
||
# 手动注册服务
|
||
curl -X POST http://localhost:3000/api/servers/my-server/register \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-d '{
|
||
"service": {
|
||
"name": "my-mcp-service",
|
||
"tags": ["mcp", "production"],
|
||
"port": 3001,
|
||
"check": {
|
||
"http": "http://localhost:3001/health",
|
||
"interval": "30s"
|
||
}
|
||
}
|
||
}'
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **服务器启动失败**
|
||
|
||
```bash
|
||
# 检查服务器日志
|
||
curl -X GET http://localhost:3000/api/servers/my-server/logs?level=error \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
2. **配置无效**
|
||
|
||
```bash
|
||
# 验证配置
|
||
curl -X POST http://localhost:3000/api/servers/validate \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-d @server-config.json
|
||
```
|
||
|
||
3. **性能问题**
|
||
```bash
|
||
# 获取性能指标
|
||
curl -X GET http://localhost:3000/api/servers/my-server/metrics \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
### 调试模式
|
||
|
||
启用详细调试：
|
||
|
||
```json
|
||
{
|
||
"name": "debug-server",
|
||
"command": "node",
|
||
"args": ["--inspect=0.0.0.0:9229", "server.js"],
|
||
"env": {
|
||
"DEBUG": "*",
|
||
"LOG_LEVEL": "debug",
|
||
"NODE_ENV": "development"
|
||
},
|
||
"debugging": {
|
||
"enabled": true,
|
||
"port": 9229,
|
||
"breakOnStart": false
|
||
}
|
||
}
|
||
```
|
||
|
||
## 高级配置
|
||
|
||
### 自定义钩子
|
||
|
||
```json
|
||
{
|
||
"name": "hooked-server",
|
||
"command": "node",
|
||
"args": ["server.js"],
|
||
"hooks": {
|
||
"beforeStart": ["./scripts/setup.sh"],
|
||
"afterStart": ["./scripts/notify.sh"],
|
||
"beforeStop": ["./scripts/cleanup.sh"],
|
||
"onError": ["./scripts/alert.sh"]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 配置模板
|
||
|
||
```json
|
||
{
|
||
"templates": {
|
||
"python-server": {
|
||
"command": "python",
|
||
"args": ["-m", "mcp_server"],
|
||
"env": {
|
||
"PYTHONPATH": "/app/python",
|
||
"LOG_LEVEL": "INFO"
|
||
}
|
||
}
|
||
},
|
||
"servers": {
|
||
"my-python-server": {
|
||
"extends": "python-server",
|
||
"args": ["-m", "mcp_server", "--config", "custom.json"],
|
||
"env": {
|
||
"API_KEY": "custom-key"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
有关更多配置选项，请参阅 [MCP 设置配置](/zh/configuration/mcp-settings) 和 [环境变量](/zh/configuration/environment-variables) 文档。
|