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

感谢 @BigUncle 的合并请求

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

---

一、项目概述与架构

该项目使用 Docker 和 Docker Compose 进行容器化部署 mcpo（模型上下文协议开放API代理）。核心设计原则包括：

• 动态依赖安装：容器启动时，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中进行，以避免环境变量冲突。

---

二、构建与部署流程

1. 环境准备

• Docker & Docker Compose：推荐使用 Docker 24+ 和 Docker Compose 2.x。

• .env 文件：在项目根目录创建一个 .env 文件，用于存储敏感信息和配置。包括 MCPO_API_KEY。参考 .env.example。

  # .env 文件示例
  # 在 Docker 构建期间使用的 pip 源（可选，如果为空则使用默认源）
  PIP_SOURCE=https://mirrors.aliyun.com/pypi/simple/
  
  # mcpo 运行时需要的 API Key（必需）
  MCPO_API_KEY=your_mcpo_api_key_here
  
  # 根据 config.json 配置可能需要的其他 API Keys
  # AMAP_MAPS_API_KEY=your_amap_key
  # ... 其他所需环境变量
  

• 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. 构建镜像

# 传递 PIP_SOURCE（compose 将自动从 .env 读取）
docker-compose build [--no-cache]

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

4. 启动服务

# 启动服务（后台运行）
docker-compose up -d

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

---

三、常见问题及解决方案

1. npx: 命令未找到 / git: 命令未找到

• 原因：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: 无法创建目录 '/root': 权限被拒绝

• 原因：容器以非root用户 appuser 运行，但脚本或依赖项尝试写入 /root 目录（例如默认缓存路径）。
• 解决方法：
  • 所有缓存目录（uv, npm）通过 ENV 指令重定向到 /app（UV_CACHE_DIR, NPM_CONFIG_CACHE, HOME）。
  • 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。
  • pip 可以通过 .env 中的 PIP_SOURCE 配置国内镜像。
  • Node.js（NodeSource）和 uv（PyPI/镜像）仍然依赖于网络；在极端情况下考虑替代方案。

---

四、关键考虑事项与最佳实践

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

---

五、快速参考命令

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