容器化部署工具

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

感谢@BigUncle的pull请求

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

一、项目概况及架构

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

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

二、构建和部署过程

1.环境准备

• Docker&Docker编写：推荐使用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 作为运行时环境变量，通过 env_file.
• 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：强制重建所有层以确保最新更改生效。
• 构建过程使用 PIP_SOURCE 从 .env 要配置的文件（如果有效） pip 来源。

4.启动服务

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

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

III、 常见问题及解决方法

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

• 原因: npx （已安装 nodejs)或 git 未安装或其路径不在 appusers PATH 环境变量。
• 解决方案:
  • 确认 Dockerfiles 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 目录（例如默认缓存路径）。
• 解决方案:
  • 所有缓存目录(uv, npm)重定向到 /app 通过 ENV 指令(UV_CACHE_DIR, NPM_CONFIG_CACHE, HOME).
  • mkdir -p 在……里面 start.sh 仅在以下目录上操作 /app.
  • 中的相应卷装载路径 docker-compose.yml 已更新至 /app/....

3. pip 不使用自定义源(PIP_SOURCE)

• 原因: PIP_SOURCE 在构建过程中未正确传递到Dockerfile。
• 解决方案:
  • 确保 .env 文件包含 PIP_SOURCE=https://....
  • 确保 docker-compose.ymls build.args 本节包括 - PIP_SOURCE=${PIP_SOURCE:-}.
  • Dockerfile接收 ARG PIP_SOURCE 并使用via export PIP_INDEX_URL 在……里面 RUN 层。

4.网络和依赖安装缓慢/失败

• 原因：网络连接不良，访问官方资源缓慢或超时。
• 解决方案:
  • Dockerfile配置为使用阿里云镜像加速 apt.
  • pip 可以通过以下方式配置家用镜子 PIP_SOURCE 在……里面 .env.
  • Node.js（NodeSource）和uv（PyPI/Mirror）仍然依赖于网络；在极端情况下考虑其他解决方案。

IV、 关键考虑因素和最佳实践

• 非root用户：始终按以下方式运行容器 appuser.
• 持久性：明确安装 config.json, logs, data, node_modules, .npm, .uv_cache 以保留状态和依赖关系。
• 秘密：使用管理API密钥和敏感信息 .env 文件，通过注入 env_file, 从不 COPY .env 输入图像或硬编码密钥。 .env 文件应该在 .gitignore.
• 动态安装: start.sh的动态安装机制提供了灵活性，但意味着首次启动或之后的启动时间更长 config.json 变化。
• 版本固定：为了再现性，建议固定 uv 版本在 Dockerfile (pip install --user uv==X.Y.Z)以及 npx 包版本在 config.json (@amap/amap-maps-mcp-server@X.Y.Z).
• 资源限制：在生产环境中，考虑为中的服务设置内存和CPU限制 docker-compose.yml.
• 日志：日志输出到已挂载 ./logs 目录，便于查看和管理。
• 测试：使用 test_mcp_tools.sh 用于基本功能验证的脚本。

V.快速参考命令

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