Docker Build and Deployment Guide (mcpo project)

Docker 构建和部署指南（mcpo 项目）

感谢 @BigUncle 提交拉取请求

本指南系统地概述了 mcpo 项目在 Docker 容器环境中的构建、部署、故障排除和最佳实践，反映了项目的当前状态。

---

I. 项目概述和架构

本项目使用 Docker 和 Docker Compose 对 mcpo（Model Context Protocol OpenAPI Proxy）进行容器化部署。核心设计原则包括：

• 动态安装依赖项：容器启动时，start.sh 脚本会读取 config.json，并根据定义的 mcpServers 动态安装所需的 Python（uvx）和 Node.js（npx）工具。
• 以非 root 用户运行：容器最终以非 root 用户 appuser 运行，以增强安全性。
• 依赖项和数据持久化：通过 Docker Compose 卷挂载，将配置、日志、数据以及 uv 和 npm 的缓存目录持久化到主机。
• 灵活的源配置：支持通过构建参数（PIP_SOURCE）动态配置 pip 源，并默认使用阿里云镜像来加速 apt。
• 环境隔离：在 start.sh 中，每个 MCP 工具的安装都在子 shell 中进行，以避免环境变量冲突。

---

II. 构建和部署流程

1. 环境准备

• Docker 和 Docker Compose：建议使用 Docker 24+ 和 Docker Compose 2.x。

• .env 文件：在项目根目录中创建 .env 文件，用于存放敏感信息和配置。包含 MCPO_API_KEY。请参阅 .env.example。

  # .env file example
  # pip source used during Docker build (optional, uses default source if empty)
  PIP_SOURCE=https://mirrors.aliyun.com/pypi/simple/
  
  # API Key required for mcpo runtime (required)
  MCPO_API_KEY=your_mcpo_api_key_here
  
  # Other API Keys that may be needed for mcp servers (according to config.json)
  # AMAP_MAPS_API_KEY=your_amap_key
  # ... other required environment variables
  

• config.json：配置要启动的 MCP 服务。请参阅 config.example.json。

• 网络：确保能够访问 Debian（阿里云镜像）、NodeSource、PyPI（或指定的 PIP_SOURCE）。

2. 目录结构和关键文件

• Dockerfile：定义镜像构建流程。
  • 基础镜像：python:3.13-slim
  • 安装：bash、curl、jq、nodejs（v22.x）、git、uv（通过 pip 安装）
  • 用户：创建并以 appuser 身份运行。
  • 配置：支持 PIP_SOURCE 构建参数。
• start.sh：容器入口脚本。
  • 设置 HOME、UV_CACHE_DIR、NPM_CONFIG_CACHE。
  • 创建持久化目录。
  • 读取 config.json 并动态安装 MCP 工具（使用 uvx 或 npx）。
  • 启动 mcpo 主服务。
• docker-compose.yml：定义服务、构建参数、卷挂载和环境变量。
  • 将 PIP_SOURCE 传递给 Dockerfile。
  • 挂载 ./config.json、./logs、./data、./node_modules、./.npm、./.uv_cache。
  • 通过 env_file 将 .env 加载为运行时环境变量。
• readme-docker.md：本文档。
• test_mcp_tools.sh：基本功能测试脚本。

3. 构建镜像

# Pass PIP_SOURCE (compose will automatically read from .env if defined)
docker-compose build [--no-cache]

• --no-cache：强制重新构建所有层，确保最新更改生效。
• 构建过程使用 .env 文件中的 PIP_SOURCE（如果有效）来配置 pip 源。

4. 启动服务

# Start service (run in background)
docker-compose up -d

• docker-compose.yml 会将 .env 中的变量加载为容器运行时环境变量。
• start.sh 会执行，并动态安装 config.json 中定义的 MCP 工具。
• mcpo 主服务启动。

---

III. 常见问题和解决方案

1. npx: command not found / git: command not found

• 原因：未安装 npx（随 nodejs 一起安装）或 git，或者它们的路径不在 appuser 的 PATH 环境变量中。
• 解决方案：
  • 确认 Dockerfile 的 apt-get install 包含 nodejs 和 git。
  • 确认 ENV PATH 指令包含 /usr/bin（通过 apt 安装的 nodejs 和 git 通常位于此处）。Dockerfile 已包含 /app/.local/bin:/usr/bin:/usr/local/bin:$PATH。
  • 使用 docker-compose build --no-cache 重新构建。

2. mkdir: cannot create directory '/root': Permission denied

• 原因：容器以非 root 用户 appuser 运行，但脚本或依赖项尝试写入 /root 目录（例如默认缓存路径）。
• 解决方案：
  • 通过 ENV 指令（UV_CACHE_DIR、NPM_CONFIG_CACHE、HOME）将所有缓存目录（uv、npm）重定向到 /app。
  • start.sh 中的 mkdir -p 仅操作 /app 下的目录。
  • 将 docker-compose.yml 中对应的卷挂载路径更新为 /app/...。

3. pip 未使用自定义源（PIP_SOURCE）

• 原因：构建过程中未将 PIP_SOURCE 正确传递给 Dockerfile。
• 解决方案：
  • 确保 .env 文件包含 PIP_SOURCE=https://...。
  • 确保 docker-compose.yml 的 build.args 部分包含 - PIP_SOURCE=${PIP_SOURCE:-}。
  • Dockerfile 通过 ARG PIP_SOURCE 接收参数，并在 RUN 层中通过 export PIP_INDEX_URL 使用。

4. 网络缓慢或失败，以及依赖项安装问题

• 原因：网络连接不佳，访问官方源缓慢或超时。
• 解决方案：
  • Dockerfile 已配置为使用阿里云镜像加速 apt。
  • 可通过 .env 中的 PIP_SOURCE 为 pip 配置国内镜像。
  • Node.js（NodeSource）和 uv（PyPI/镜像）仍依赖网络；在极端情况下可考虑其他解决方案。

---

IV. 重要注意事项与最佳实践

• 非 root 用户：始终以 appuser 运行容器。
• 持久化：显式挂载 config.json、logs、data、node_modules、.npm、.uv_cache，以保留状态和依赖项。
• 密钥：使用 .env 文件管理 API 密钥和敏感信息，并通过 env_file 注入；切勿将 .env COPY 到镜像中，也不要硬编码密钥。.env 文件应加入 .gitignore。
• 动态安装：start.sh 的动态安装机制提供了灵活性，但首次启动或 config.json 更改后，启动时间会更长。
• 版本固定：为确保可复现性，建议在 Dockerfile 中固定 uv 版本（pip install --user uv==X.Y.Z），并在 config.json 中固定 npx 包版本（@amap/[email protected]）。
• 资源限制：在生产环境中，可考虑为 docker-compose.yml 中的服务设置内存和 CPU 限制。
• 日志：日志输出到挂载的 ./logs 目录，便于查看和管理。
• 测试：使用 test_mcp_tools.sh 脚本进行基本功能验证。

---

V. 命令速查

• 构建镜像：docker-compose build [--no-cache]
• 启动服务（后台运行）：docker-compose up -d