FastMCP¶

概述¶

FastMCP 是一個基於 MCP（Model Context Protocol）的聚合網關，當前版本為 fastmcp:3.4.6，對外暴露 173 個 tools，統一整合多個異構服務的 API，為上層 AI 應用提供單一、標準化的工具呼叫介面。此網關特別適合需要同時存取資料庫、向量檢索、雲端儲存及內容管理系統的企業環境。其核心價值在於減少客戶端直接連接觸發的複雜性與安全風險，並透過集中式路由簡化 tool 的版本管理與權限控制。

架構¶

FastMCP 位於 AI 應用與後端服務之間，作為 MCP 的統一入口。它透過模組化整合以下組件：

Dockhand：用於容器管理與動態服務調度，提供工具層面的容器操作能力。
PostgreSQL（PG）：作為關係型資料庫後端，支援結構化查詢與事務性操作。
Qdrant：向量資料庫，提供語意檢索及 RAG（檢索增強生成）相關工具。
Alist：檔案列表與掛載工具，支援多儲存源聚合，例如本機、S3、WebDAV 等。
Nextcloud：提供檔案同步、分享及協作功能，整合後可操作雲端文件與使用者目錄。
Cloudflare：整合 Cloudflare 相關 API，包括 DNS 管理、快取刷新與 Tunnel 配置。

所有向外連線均透過 Docker 自訂網絡 cf_network 進行，固定 IP 為 172.21.0.28，並以環境變數注入敏感參數，避免硬編碼。

部署（Docker Compose 片段）¶

以下為精簡可用的 Compose 配置，支援將 FastMCP 加入既有 cf_network，並掛載 rclone 配置及 OCI 憑證：

services:
  fastmcp:
    image: fastmcp:3.4.6
    container_name: fastmcp
    networks:
      cf_network:
        ipv4_address: 172.21.0.28
    volumes:
      - /opt/rclone/config:/config/rclone:ro
      - /home/opc/.oci:/home/opc/.oci:ro
    environment:
      - TZ=Asia/Hong_Kong
      - DOCKHAND_URL=${DOCKHAND_URL}
      - PG_HOST=${PG_HOST}
      - QDRANT_API_KEY=${QDRANT_API_KEY}
    restart: unless-stopped

部署前請確保 cf_network 已存在，且 IP 未被佔用。可透過 docker network create --subnet=172.21.0.0/16 cf_network 建立網絡。

配置與環境變數¶

FastMCP 依賴環境變數動態設定，主要變數如下：

變數	說明
`TZ`	時區，設定為 `Asia/Hong_Kong`
`DOCKHAND_URL`	Dockhand 服務的 base URL，用於容器調度
`PG_HOST`	PostgreSQL 主機位址，支援 IP 或 DNS 名稱
`QDRANT_API_KEY`	Qdrant 向量資料庫的 API 金鑰

PG_HOST 可同時透過其他環境變數傳遞使用者名稱、密碼或連線字串，視乎映像檔設計而定。若需 TLS 連線，請在對應變數中標明 sslmode=require。所有敏感資料建議以 .env 檔案管理，並在 Compose 中引用。

維運與監控¶

日常維運重點包括：

日誌檢視：使用 docker logs -f fastmcp 追蹤 MCP 請求與錯誤；建議搭配 Loki 或 ELK 集中收集。
健康檢查：可定期呼叫 docker exec fastmcp wget -qO- http://localhost:8080/health 檢查網關狀態；若無健康端點，可監控 TCP 連接至 172.21.0.28 的 MCP 埠。
效能監控：觀察 173 個 tools 的回應延遲與失敗率，可透過 Prometheus 抓取 /metrics（如有啟用）或使用腳本計時工具呼叫。
備份：FastMCP 本身無需持久化資料，但需備份 .env 及 rclone 配置檔 /opt/rclone/config。
更新流程：升級映像檔前先確認新版本 tools 數量及向後相容性，建議在測試環境重放典型查詢後再切換。

常見問題¶

1. 無法連線至 172.21.0.28？
先檢查 Docker 網絡：docker network inspect cf_network，確認 fastmcp 容器已連線且 IP 正確。若 IP 衝突，可將容器停止後重新啟動。

2. 部分 tools 無法使用，錯誤顯示上游服務逾時？
這通常與 Dockhand、PG 或 Qdrant 相關。請確認對應 URL 是否可達，並檢查環境變數是否有誤。其中 Qdrant 的 API Key 若錯誤，向量檢索功能會完全失效。

3. Alist 或 Nextcloud 的檔案存取權限不足？
檢查 rclone 設定檔是否已正確掛載，且容器內用戶對 /config/rclone 有唯讀權限；另外，OCI 憑證目錄 /home/opc/.oci 的權限建議設定為 700。

4. 更新後 tools 數量與預期不符？
官方文件列出的 173 個 tools 僅是預設組合，實際暴露數量會受環境變數影響。例如未設定 DOCKHAND_URL 時，相關容器工具將被隱藏。

FastMCP¶

概述¶

架構¶

部署（Docker Compose 片段）¶

配置與環境變數¶

維運與監控¶

常見問題¶

相關鏈接¶