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 回應。