MCP 指南deprecated

MCP 历史安全设计（未公开）

保留的 MCP 安全架构草案，不代表 RailWise 已对外发布认证、权限或数据接口。

复核 2026-07-20入门不进入公开索引RailWise 技术团队

MCP 指南

RailWise MCP Server 安全与认证

1. 安全架构概述

RailWise MCP Server 采用多层安全架构，确保工程测量与安全监测数据的机密性、完整性和可用性。

┌─────────────────────────────────────────────────────────┐
│                    安全架构层次                          │
├─────────────────────────────────────────────────────────┤
│  Layer 4: 应用安全层                                      │
│  - 输入验证、输出编码、防注入攻击                          │
├─────────────────────────────────────────────────────────┤
│  Layer 3: 权限控制层                                      │
│  - API Key 认证、RBAC 权限模型、资源访问控制               │
├─────────────────────────────────────────────────────────┤
│  Layer 2: 传输安全层                                      │
│  - TLS 1.3 加密、证书校验、防中间人攻击                     │
├─────────────────────────────────────────────────────────┤
│  Layer 1: 环境安全层                                      │
│  - 本地配置保护、环境变量隔离、日志脱敏                     │
└─────────────────────────────────────────────────────────┘

2. 认证机制

2.1 API Key 认证

RailWise MCP Server 使用 API Key 作为主要的认证方式。API Key 在每次请求时通过 HTTP Header 传递给 RailWise API 服务。

认证流程：

AI 客户端 → MCP Server → RailWise API
                ↓              ↓
           读取 API Key    Authorization: Bearer {api_key}
                ↓              ↓
           环境变量/配置    TLS 加密传输

API Key 格式：

环境	前缀	示例
生产环境	`rw_live_`	`rw_live_a1b2c3d4e5f6g7h8`
测试环境	`rw_test_`	`rw_test_a1b2c3d4e5f6g7h8`
开发环境	`rw_dev_`	`rw_dev_a1b2c3d4e5f6g7h8`

2.2 获取 API Key

登录 RailWise 开发者平台
进入 API 管理 → 密钥管理
点击 创建新密钥
填写密钥信息：
- 密钥名称：便于识别的名称（如 “Claude Desktop 集成”）
- 权限范围：选择所需的最小权限集合
- 有效期：设置密钥过期时间（建议 90 天内轮换）
- IP 白名单（可选）：限制允许访问的 IP 地址
复制并安全保存生成的 API Key

⚠️ 安全警告：API Key 仅在创建时显示一次，请务必立即复制保存。如果丢失，需要重新创建新密钥。

2.3 API Key 权限范围

创建 API Key 时可选择以下权限：

权限	标识	说明	风险等级
数据读取	`data_read`	查询监测数据、历史记录	低
数据写入	`data_write`	修改、删除监测数据	高
项目读取	`project_read`	查询项目信息、测点配置	低
项目写入	`project_write`	创建、修改项目配置	高
设备读取	`device_read`	查询设备状态、信息	低
设备控制	`device_control`	远程控制设备操作	高
计算服务	`compute`	使用坐标转换、平差计算等	中
管理权限	`admin`	系统管理、用户管理	极高

最小权限原则建议：

使用场景	推荐权限组合
日常数据查询	`data_read` + `project_read` + `device_read`
数据分析报告	`data_read` + `project_read` + `compute`
项目管理	`project_read` + `project_write` + `data_read`
设备运维	`device_read` + `device_control` + `data_read`
系统管理	`admin`（仅限管理员）

2.4 API Key 轮换

建议定期轮换 API Key 以降低泄露风险：

# 1. 在开发者平台创建新密钥
# 2. 更新本地配置
export RAILWISE_API_KEY="rw_live_new_key_here"

# 3. 重启 MCP Server（或等待 AI 客户端自动重连）
# 4. 验证新密钥工作正常
npx @railwise/mcp-server --check-config

# 5. 在开发者平台删除旧密钥

3. 权限控制

3.1 RBAC 权限模型

RailWise 采用基于角色的访问控制（RBAC）模型：

角色	权限范围	适用对象
观测员	`data_read`, `project_read`	现场观测人员
分析员	`data_read`, `project_read`, `compute`	数据分析人员
工程师	`data_read`, `project_read`, `project_write`, `compute`	项目工程师
设备管理员	`device_read`, `device_control`	设备维护人员
项目经理	全部读取权限 + 项目写入	项目管理人员
系统管理员	全部权限	系统管理员

3.2 项目级权限控制

API Key 可以限制可访问的项目范围：

{
  "api_key_id": "KEY-xxxxxxxx",
  "accessible_projects": ["PRJ-A1B2C3D4", "PRJ-E5F6G7H8"],
  "permissions": {
    "data_read": true,
    "project_read": true
  }
}

3.3 查询当前权限

通过 MCP 工具查询当前 API Key 的权限：

用户：查看我当前的权限。

AI：[调用 railwise_query_user_permissions]

AI：您当前的权限如下：

数据读取：✅ 允许

数据写入：❌ 禁止

项目读取：✅ 允许

项目写入：❌ 禁止

设备读取：✅ 允许

设备控制：❌ 禁止

计算服务：✅ 允许

管理权限：❌ 禁止

可访问项目：PRJ-A1B2C3D4, PRJ-E5F6G7H8

4. 传输安全

4.1 TLS 加密

所有与 RailWise API 的通信均通过 TLS 1.3 加密：

配置项	要求	说明
协议版本	TLS 1.2+	推荐使用 TLS 1.3
证书校验	强制	验证服务器证书链
证书透明度	启用	防止伪造证书
加密套件	仅前向安全	禁用 RSA 密钥交换

4.2 API 端点安全

环境	端点	协议
生产环境	`https://api.railwise.cn/v1`	HTTPS 强制
测试环境	`https://api-staging.railwise.cn/v1`	HTTPS 强制
开发环境	`https://api-dev.railwise.cn/v1`	HTTPS 强制

注意：HTTP 非加密端点已被禁用，所有请求必须通过 HTTPS。

5. 数据安全

5.1 数据分类

RailWise 处理的数据按敏感度分类：

级别	数据类型	保护措施
公开	技术规范、标准文档	无需特殊保护
内部	项目基本信息、设备信息	需要认证访问
敏感	监测数据、变形分析结果	加密传输 + 访问控制
机密	客户信息、合同数据	加密存储 + 严格权限控制

5.2 日志安全

MCP Server 日志处理遵循以下安全原则：

措施	说明
API Key 脱敏	日志中自动掩码 API Key，显示为 `rw_live_****`
敏感数据过滤	监测数据值在调试日志中部分脱敏
日志分级	`error` 级别仅记录错误信息，不包含敏感数据
本地存储	日志默认输出到 stderr，不写入本地文件（除非配置）

日志配置建议：

{
  "env": {
    "RAILWISE_MCP_LOG_LEVEL": "warn",
    "RAILWISE_MCP_LOG_FILE": "/var/log/railwise-mcp.log"
  }
}

5.3 数据留存

数据类型	留存期限	说明
API 访问日志	90 天	用于安全审计
MCP 通信日志	7 天	调试用途，定期清理
监测数据	按项目配置	由 RAILWISE-TSM 平台管理

6. 环境安全

6.1 配置文件保护

AI 客户端的配置文件包含敏感信息，需要妥善保护：

macOS/Linux：

# 设置配置文件权限
chmod 600 ~/.cursor/mcp.json
chmod 600 ~/.windsurf/mcp_config.json
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 验证权限
ls -la ~/.cursor/mcp.json
# -rw-------  1 user  group  234 Jan 15 10:00 mcp.json

Windows：

# 设置配置文件权限
$path = "$env:USERPROFILE\.cursor\mcp.json"
$acl = Get-Acl $path

# 移除所有权限
$acl.SetAccessRuleProtection($true, $false)

# 添加当前用户权限
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
    $env:USERNAME, "Read", "Allow"
)
$acl.SetAccessRule($rule)
Set-Acl $path $acl

6.2 环境变量管理

避免在以下位置暴露 API Key：

❌ 不安全	✅ 安全替代方案
命令行历史	使用配置文件或密钥管理工具
脚本文件	使用环境变量注入或密钥管理服务
代码仓库	使用 `.env` 文件并加入 `.gitignore`
共享文档	使用 RailWise 开发者平台的密钥管理

6.3 使用密钥管理服务

对于企业用户，建议使用密钥管理服务：

macOS Keychain：

# 存储 API Key
security add-generic-password -s "railwise-api-key" -a "user" -w "rw_live_xxxxxxxx"

# 读取 API Key（在启动脚本中使用）
export RAILWISE_API_KEY=$(security find-generic-password -s "railwise-api-key" -w)

Windows Credential Manager：

# 存储 API Key
cmdkey /generic:railwise-api-key /user:user /pass:rw_live_xxxxxxxx

# 读取 API Key（需要额外脚本处理）

7. 安全最佳实践

7.1 配置检查清单

部署 RailWise MCP Server 前，请确认以下安全事项：

API Key 使用最小权限原则配置
配置文件权限设置为仅所有者可读写（600）
使用 HTTPS 端点（非 HTTP）
日志级别设置为 warn 或更高（生产环境）
定期轮换 API Key（建议 90 天）
启用 IP 白名单（如适用）
配置 API Key 过期时间
不在代码仓库中提交配置文件

7.2 安全事件响应

事件	响应措施
API Key 泄露	立即在开发者平台撤销密钥，创建新密钥并更新配置
异常访问	检查访问日志，确认是否为授权操作，必要时撤销密钥
配置错误	检查配置文件权限，确保未暴露敏感信息
数据泄露	立即联系 RailWise 安全团队（security@railwise.cn）

8. 合规性

8.1 数据保护合规

RailWise MCP Server 遵循以下数据保护标准：

标准	说明
网络安全等级保护 2.0	符合三级等保要求
ISO 27001	信息安全管理体系认证
GDPR	欧盟通用数据保护条例（涉及欧盟项目时）

8.2 审计与日志

所有 API 访问均记录审计日志：

{
  "timestamp": "2025-01-15T14:30:00Z",
  "api_key_id": "KEY-xxxxxxxx",
  "action": "railwise_query_monitoring_data",
  "project_id": "PRJ-A1B2C3D4",
  "ip_address": "192.168.1.100",
  "user_agent": "railwise-mcp-server/1.2.0",
  "status": "success",
  "response_time_ms": 120
}

9. 相关文档

MCP Server 概述 — 功能介绍和适用场景
MCP Server 安装配置 — 详细的安装步骤
MCP Server 工具列表 — 完整的工具清单和参数说明
MCP Server 集成示例 — 与主流 AI 平台的集成教程
MCP Server 故障排查 — 常见问题排查和解决方案

本文档由 RailWise 技术文档团队维护，最后更新于 2025-01-15。

安全联系：security@railwise.cn