Webship 工程

安全地将 AI 代理连接到 Webship 的 MCP 服务器

使用 TLS 1.3、强大的承载令牌、回环绑定、SSH 隧道、配置验证和实用的事件响应清单，设置 Webship 的隔离 MCP 控制平面。

发表于 2026年9月10日

# 将 AI 代理安全连接到 Webship 的 MCP 服务器

与网络服务器的 MCP 连接不是聊天窗口小部件。它是一个操作界面，可以检查生产状态、改变路由和安全策略、重新加载证书、激活静态版本、协调集群更改，并安装签名的 Webship 更新。

请相应地处理它：作为一个特权的管理 API。最安全的 Webship 设置是将 MCP 监听器保持在公共数据平面之外，将其绑定到回环接口，用 TLS 1.3 和强大的承载令牌保护它，并通过经过身份验证的 SSH 隧道访问它。

本指南构建了该设置，解释了每个边界存在的原因，并为你提供了一个清单，用于在不将便利变为暴露的情况下操作它。

从信任边界开始

Webship 的公共流量和 MCP 流量使用独立的监听器。MCP 控制平面默认被禁用，并且从不与普通 HTTP、HTTP/2、HTTP/3 或 WebTransport 监听器共享。当启用时，它通过专用的 TLS 1.3 HTTP/1.1 端点提供 MCP 服务。

一个安全的部署有四个独立的控制措施：

网络可达性： MCP 监听器绑定到 127.0.0.1，而不是公共或私有局域网地址。
传输身份： 客户端验证由其信任的 CA 签发的证书。
应用程序身份验证： 每个请求都携带一个强效承载令牌。
管理访问权限： 操作员通过经过身份验证的 SSH 账户和隧道访问回环监听器。

这些控制措施没有一个可以替代另一个。没有私有网络路径的 TLS 仍然会暴露身份验证面。没有证书验证的隧道会使端点身份模糊。存放在世界可读文件中的承载令牌并不是秘密。

准备证书和令牌

从您的内部 CA 签发专用的 MCP 证书。对于下方显示的隧道，在证书的主题备用名称中包含 localhost 和 127.0.0.1，然后将签发的 CA 安装到 MCP 客户端机器的信任存储中。不要通过不安全的 TLS 选项来解决信任错误。

创建一个至少包含32个可打印ASCII字节且不含空格的唯一令牌。将32字节的随机值编码为十六进制会得到64个安全字符：

umask 077
openssl rand -hex 32

Webship 当前直接从受保护的 TOML 配置中读取 MCP 令牌；token_file 不受支持。将结果存储在仅 Webship 服务账户及其管理组可读取的配置文件中。不要将令牌放在 systemd 单元、shell 历史、工单、聊天消息或发送给 AI 模型的提示中。

在一个典型的 Debian 主机上：

sudo chown root:webship /etc/webship/production.toml
sudo chmod 0640 /etc/webship/production.toml
sudo chown root:webship /etc/webship/mcp-cert.pem /etc/webship/mcp-key.pem
sudo chmod 0644 /etc/webship/mcp-cert.pem
sudo chmod 0640 /etc/webship/mcp-key.pem

将服务用户和组适配到您的安装环境中。私钥和配置必须能够被 Webship 读取，但不能被无关账户读取。

启用隔离监听器

将此部分添加到活动的 Webship 配置中：

[security.mcp]
enabled = true
listen = "127.0.0.1:9443"
token = "replace-with-your-generated-64-character-token"
allowed_ips = []
expose_remote = false

[security.mcp.tls]
cert = "/etc/webship/mcp-cert.pem"
key = "/etc/webship/mcp-key.pem"

一个空的 allowed_ips 列表不会打开端点。回环客户端默认仍然被允许。expose_remote = false 明确了预期的边界：如果有人后来将 listen 更改为非回环地址，Webship 会拒绝该配置，而不是默默地发布控制平面。

Webship 还会拒绝没有 TLS、没有令牌、令牌过短或包含空格，或证书路径为空的已启用 MCP 监听器。在远程暴露之前会拒绝公共占位符令牌。

重启前验证

MCP 监听器、TLS 身份和令牌更改会重建控制平面，因此它们需要重新启动进程。请先验证完整配置：

/usr/local/bin/webship --check-config --config /etc/webship/production.toml
sudo systemctl restart webship
sudo systemctl status webship --no-pager

确认监听器仅存在于回环接口上：

ss -ltn | grep '127.0.0.1:9443'

不要将端口9443添加到主机的公共防火墙规则中。下一步通过SSH访问它。

创建私人隧道

从管理员工作站，将本地端口转发到 Webship 的回环侦听器：

ssh -N \
  -L 127.0.0.1:19443:127.0.0.1:9443 \
  webship-admin@edge.example.com

MCP 客户端现在连接到 https://localhost:19443/mcp。TCP 到达 SSH 服务器，SSH 将连接传递给主机，主机在回环地址上打开到 Webship 的最终连接。关闭 SSH 会话会立即移除该路径。

使用基于密钥的 SSH 认证，限制哪些管理员可以打开隧道，并应用您正常的主机访问控制。如果需要跳板主机，请将 MCP 监听器保留在 Webship 主机的回环接口上，并扩展 SSH 路径，而不是扩大监听器。

配置 MCP 客户端

客户端配置格式各不相同，但典型的 HTTP MCP 条目看起来像这样：

{
  "mcpServers": {
    "webship-production": {
      "url": "https://localhost:19443/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

当客户端有受保护的秘密机制时，请使用它。否则，将客户端配置限制在当前的操作系统账户。HTTP 客户端——而不是模型——应该附加授权头。切勿将实时令牌粘贴到对话中。

保持证书验证启用。如果客户端拒绝证书，请修复证书的备用主题名称或安装正确的内部 CA。不要添加永久绕过。

将第一次会话设置为只读

在隧道和客户端连接后，开始进行发现和检查：

请求 tools/list; 它的响应是当前发布版本的权威参数模式。
调用 webship.get_config 并记录当前配置版本。
根据需要检查webship.reverse_proxy.get_status、webship.security.get_status、webship.ddos.get_status和webship.tls.get_status。
在更改政策之前使用 webship.policy.explain 或 webship.security.simulate。
确认返回的配置会编辑承载令牌。

只有在非生产环境中测试变更后才执行。Webship 的配置变更需要当前版本 ID。陈旧的写入会被拒绝，而不是覆盖更新的更改。候选策略可以在激活前通过影子验证和流量实验场景进行检查。

Webship 同样拒绝选择的实时安全降级。MCP 请求无法关闭活动的 WAF、DDoS 层、API Shield、机器人挑战、边缘认证策略或响应头层。与进程绑定的监听器、协议、工作线程、运行时以及 MCP 认证的更改需要有意地重启。

那些守卫可以减少错误；它们并不能使每一个授权操作都无害。该令牌提供了强大的控制界面，包括更新和发布操作。审查提议的工具调用，就像你审查管理员的 shell 命令一样。

如果无法避免远程绑定

推荐的设计是回环加 SSH。如果您的环境需要私有网络监听器，请明确指出例外情况：

[security.mcp]
enabled = true
listen = "10.20.0.15:9443"
expose_remote = true
allowed_ips = ["10.20.10.0/24"]
token = "replace-with-your-generated-64-character-token"

保留前面示例中的 TLS 块，使用与私有 DNS 名称匹配的证书，并在主机和网络防火墙上强制相同的源范围。切勿将 0.0.0.0/0 或 ::/0 用作方便的允许列表。请记住，应用程序允许列表看到实际到达 Webship 的源地址；当负载均衡器、NAT 网关或服务网格位于其前面时，请验证其行为。

远程访问增加了集中访问日志、短操作窗口和快速轮换的价值。仅仅因为 MCP 客户端运行在另一台机器上并不需要这样做；这正是 SSH 隧道解决的问题。

有意地操作控制平面

使用此清单进行生产：

在没有代理或操作员需要它的地方保持 MCP 禁用。
默认绑定到回环地址并使用 SSH 隧道。
使用专用的 TLS 身份并保持证书验证启用。
为每个 Webship 环境生成一个唯一的持有者令牌。
使用文件系统权限保护 TOML、客户端配置、TLS 密钥和 SSH 密钥。
分开开发、测试和生产凭证。
在进行变异之前，先使用状态和策略模拟工具启动会话。
保存并审查 Webship 的安全审核事件。
在怀疑暴露后，旋转令牌并重新启动 Webship。
在管理会话结束时关闭隧道。

对于事件响应，应关闭活动隧道，限制 SSH 账户，替换受保护的 TOML 中的 MCP 令牌，重启 Webship，并审查最近的安全审核和配置版本记录。如果 TLS 私钥可能已泄露，应在同一次重启中签发新的证书和密钥。随后测试旧令牌，并确认其被拒绝。

控制平面应该保持为控制平面

MCP 很有用，因为代理可以检查真实状态并应用经过验证的更改，而无需通过公共请求路径路由这些操作。如果控制监听器变成另一个互联网端点，这种优势就会消失。

保持边界简单：一个独立的监听器、回环可达性、已验证的 TLS、一个受保护的承载凭证、一个经过身份验证的隧道、版本检查的更改，以及对强大操作的人为审查流程。Webship 提供协议和安全保护；操作员决定谁可以访问它们。

本指南基于 Webship 1.3.1 操作员文档、发布的配置示例、MCP 验证和传输代码、运行时配置保护以及工具目录。在将其应用于其他版本之前，请先查看当前 Webship 文档以及正在运行的服务器的 tools/list 响应。