MCP Box Deploy

MCPCan部署指南

本文档提供了使用Docker Compose部署MCPCan系统的详细说明，Docker Compose是目前推荐的部署方法。如果你需要Kubernetes部署，请参考 Helm快速入门.

项目链接

• 🌐 官方网站
• 📚 文档
• 🎮 现场演示
• 📦 主存储库
• 🚀 部署存储库

目录

- 先决条件 - 快速开始 - 自定义配置 - 常见维护命令 - 服务体系结构 - 高级配置 - 常见问题解答

1. Helm快速入门

Docker编写部署

此部署方案支持通过HTTP/HTTPS进行双协议访问，适用于本地开发、测试或轻量级生产环境部署。

先决条件

在开始之前，请确保您的环境符合以下要求：

• 操作系统：Linux（建议使用Ubuntu/CentOS）或macOS
• Docker引擎: 20.10.0+
• Docker Compose：v2.0.0+（Docker Compose v2插件命令 docker compose 推荐）
• 硬件资源:

- CPU：2核+ - 内存：4GB+ - 磁盘：10GB+

快速开始

1.获取代码

# GitHub (International Network)
git clone https://github.com/Kymo-MCP/mcpcan-deploy.git
cd mcpcan-deploy/docker-compose

# Gitee (Recommended for China Network)
git clone https://gitee.com/kymomcp/mcpcan-deploy.git
cd mcpcan-deploy/docker-compose

2.准备工作

1. 初始化环境配置:

复制示例环境文件 example.env 到 .env。此文件包含所有核心配置（如端口、数据库密码、版本号等）。

   cp example.env .env

*（可选）使用文本编辑器（例如 vim 或 nano)要修改中的配置 .env 例如，修改默认端口 MCP_ENTRY_SERVICE_PORT.*

1. 生成服务配置:

运行配置生成脚本。此脚本将从以下位置读取变量 .env 并将最终配置文件生成到 config/ 基于模板的目录 config-template/.

   chmod +x replace.sh
   ./replace.sh

*注意：如果您修改 .env 稍后，您必须重新运行此脚本以应用更改。*

3.启动服务

使用Docker Compose启动所有服务。第一次启动将自动提取图像并初始化数据库。

docker compose up -d

# Default Login Credentials
Login: admin/admin123

启动过程说明:

1. 基础服务启动MySQL和Redis首先启动。
2. 健康检查：等待MySQL和Redis状态变为 healthy.
3. 初始化：The mcp-init 容器启动，执行数据库迁移和种子数据写入。
4. 核心服务启动：之后 mcp-init 成功退出核心服务，如 mcp-authz, mcp-market，以及 mcp-gateway 开始。
5. 访问层启动：最后， mcp-web 和 traefik 网关启动，对外提供服务。

4.验证安装

服务启动后（通常需要1-2分钟），您可以通过浏览器访问：

• Web前端: http://localhost （或您配置的HTTP端口）
• HTTPS访问: https://localhost （或您配置的HTTPS端口）

- *注意：默认使用自签名证书；浏览器将提示它不安全，请单击“继续”继续。*

检查运行状态：

docker compose ps

确保所有服务状态 Up （或 Up (healthy))，以及 mcp-init 状态为 Exited (0).

自定义配置

环境变量配置

主要配置在 .env 文件。修改后，运行 ./replace.sh 生效。

配置热更新

生成的配置文件位于 config/ 目录。

• 临时修改：直接修改下的文件 config/，重新启动相关容器以生效（正在运行 ./replace.sh 将覆盖此修改）。
• 永久性修改：修改下的模板文件 config-template/，然后运行 ./replace.sh.

常见维护命令

以下命令需要在 docker-compose/ 目录。

更新图像并重新启动

发布新版本映像时使用（修改 VERSION 在 .env):

# 1. Pull latest images
docker compose pull

# 2. Recreate and start containers (only recreate changed containers)
docker compose up -d

强制重新创建容器

如果配置文件被修改或您想完全重置容器运行状态：

# --force-recreate Force destroy old containers and create new ones
docker compose up -d --force-recreate

重新启动所有服务

仅重启容器，不删除容器，不更新映像：

docker compose restart

停止服务

# Stop and remove containers, networks (retain data volumes)
docker compose down

查看服务日志

# View all logs (Ctrl+C to exit)
docker compose logs -f

# View specific service logs (e.g., mcp-gateway)
docker compose logs -f mcp-gateway

# View initialization task logs (troubleshoot startup failures)
docker compose logs mcp-init

清理未使用的图像

清理不再使用的旧映像以释放磁盘空间：

docker image prune -f

完全清洁的环境（小心使用）

警告：此操作将删除所有容器、网络和 持久化数据 （数据库、上传的文件等）。

docker compose down
rm -rf ./data

服务体系结构

高级配置

证书更换和热加载

MCPCan支持TLS证书动态热加载，无需重新启动服务。

1. 准备证书文件(.crt, .key).
2. 将证书放入 certs/ 目录。
3. 修改中的证书路径配置 config/dynamic.yaml.
4. Traefik将自动检测并应用新证书。

常见问题解答

Q： 为什么服务像 mcp-market 待在 Created 状态而不是开始？ A： 这是一种正常的依赖等待机制。它们配置了 condition: service_completed_successfully，必须等待 mcp-init 容器在启动前成功运行并完成（退出0）。请检查 mcp-init 用于确认初始化是否成功的日志：

docker compose logs mcp-init

Q： 如何修改数据库密码？ A： 修改 MYSQL_PASSWORD 在 .env那么 必须 删除旧数据库数据(rm -rf data/mysql)，然后重新运行 ./replace.sh && docker compose up -dMySQL仅在首次初始化数据目录时设置密码。

______________________________________________________________________

Helm快速入门

适用于Kubernetes环境部署。

快速安装脚本

此路径自动安装k3s、ingress nginx、Helm，并部署MCPCAN平台；适用于没有预装Kubernetes组件的全新环境。

# 1. Switch to root directory
cd ..

# 2. Execute installation script
# Standard Fast Install (International Mirrors)
./scripts/install-fast.sh

# Fast Install (Accelerated with China Mirrors)
./scripts/install-fast.sh --cn

成功后，脚本验证Helm发布状态并打印访问URL。

如需了解更多Helm自定义配置和详细说明，请查看 Helm图表库.