MCPCan部署指南
本文档提供了使用Docker Compose部署MCPCan系统的详细说明，Docker Compose是目前推荐的部署方法。如果你需要Kubernetes部署，请参考 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-compose2.准备工作
- 初始化环境配置:
复制示例环境文件 example.env 到 .env。此文件包含所有核心配置（如端口、数据库密码、版本号等）。
cp example.env .env*（可选）使用文本编辑器（例如 vim 或 nano)要修改中的配置 .env 例如，修改默认端口 MCP_ENTRY_SERVICE_PORT.*
- 生成服务配置:
运行配置生成脚本。此脚本将从以下位置读取变量 .env 并将最终配置文件生成到 config/ 基于模板的目录 config-template/.
chmod +x replace.sh
./replace.sh*注意：如果您修改 .env 稍后，您必须重新运行此脚本以应用更改。*
3.启动服务
使用Docker Compose启动所有服务。第一次启动将自动提取图像并初始化数据库。
docker compose up -d
# Default Login Credentials
Login: admin/admin123启动过程说明:
- 基础服务启动MySQL和Redis首先启动。
- 健康检查：等待MySQL和Redis状态变为
healthy. - 初始化：The
mcp-init容器启动，执行数据库迁移和种子数据写入。 - 核心服务启动：之后
mcp-init成功退出核心服务，如mcp-authz,mcp-market，以及mcp-gateway开始。 - 访问层启动：最后，
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 生效。
| 变量名称 | 默认值 | 描述 |
|---|---|---|
VERSION | 最新 | 图像版本标签 |
MCP_ENTRY_SERVICE_PORT | 80 | HTTP访问端口 |
MCP_ENTRY_SERVICE_HTTPS_PORT | 443 | HTTPS访问端口 |
MYSQL_PASSWORD | （见文件） | 数据库密码 |
RUN_MODE | prod | 运行模式（演示/prod） |
配置热更新
生成的配置文件位于 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服务体系结构
| 服务名称 | 描述 | 依赖关系 |
|---|---|---|
| 交通 | 统一入口网关，处理HTTP/HTTPS路由 | - |
| mcp初始化 | 初始化任务（数据库迁移/种子），完成后退出 | 取决于MySQL/Redis的运行状况 |
| mcp认证 | 身份验证和授权服务 | 等待mcp初始化完成 |
| mcp市场 | 插件市场核心服务 | 等待mcp初始化完成 |
| mcp网关 | API网关服务 | 等待mcp-init完成 |
| mcp网站 | 前端静态资源服务 | 取决于后端服务的启动 |
高级配置
证书更换和热加载
MCPCan支持TLS证书动态热加载，无需重新启动服务。
- 准备证书文件(
.crt,.key). - 将证书放入
certs/目录。 - 修改中的证书路径配置
config/dynamic.yaml. - Traefik将自动检测并应用新证书。
常见问题解答
Q： 为什么服务像 mcp-market 待在 Created 状态而不是开始？ A： 这是一种正常的依赖等待机制。它们配置了 condition: service_completed_successfully，必须等待 mcp-init 容器在启动前成功运行并完成（退出0）。请检查 mcp-init 用于确认初始化是否成功的日志：
docker compose logs mcp-initQ： 如何修改数据库密码？ 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图表库.