技术文档摘要

📊 MCP Server Chart MinIO

一个基于NestJS生成图表的服务，集成MinIO对象存储，支持22种以上的图表类型服务器端渲染。

✨ 主要特性

• 🎨 22种以上图表类型线形图、柱状图、饼图、雷达图、桑基图等
• 🚀 服务器端渲染基于@antv/gpt-vis-ssr的高性能图表生成
• ☁️ 云存储集成MinIO对象存储，自动生成访问URL
• 🔧 RESTful API完整的OpenAPI文档
• 🐳 (鲸鱼表情符号) Docker部署一键启动完整服务

📈 支持的图表类型

基础图表线形图（line chart）、面积图（area chart）、柱状图（column chart）、条形图（bar chart）、饼图（pie chart）、散点图（scatter plot）

高级图表直方图（histogram）、箱型图（box plot）、雷达图（radar chart）、漏斗图（funnel chart）、树状图（treemap）、桑基图（Sankey diagram）、词云图（word cloud）、双轴图（dual-axis chart）、液态图（liquid chart）、小提琴图（violin plot）、韦恩图（Venn diagram）

关系图思维导图、组织结构图、流程图、鱼骨图、网络图

🛠️ 系统需求

• Node.js (v18+)
• npm 或 yarn
• Docker (推荐)

🚀 快速开始

选项1：使用Docker Compose进行完整部署（推荐）

适用场景：生产环境、虚拟机部署、一键启动完整服务

🏠 本地测试部署

1. 克隆项目：

git clone <repository-url>
cd mcp-server-chart-minio

2. 使用Docker配置文件启动所有服务：

docker compose --env-file .env.docker up -d

3. 访问服务：
   • 📊 API服务http://localhost:3000
   • 📖 API文档http://localhost:3000/api/docs
   • 💾 MinIO控制台http://localhost:9001 (用户名：minioadmin 密码：minioadmin)

🌐 生产环境/虚拟机部署

重要配置参数说明（基于.env.production）：

1. 修改外部访问地址和凭证（必须） 创建或编辑.env.production至少设置：

   PUBLIC_API_URL=http://YOUR_SERVER_IP:3000
   MINIO_EXTERNAL_ENDPOINT=YOUR_SERVER_IP
   MINIO_EXTERNAL_PORT=9000
   MINIO_ROOT_USER=your_admin_user
   MINIO_ROOT_PASSWORD=your_secure_pwd
   MINIO_ACCESS_KEY=your_admin_user
   MINIO_SECRET_KEY=your_secure_pwd
   MINIO_AUTO_CREATE_BUCKET=false
   

2. 端口配置（可选）： 在.env.production中注释调整：

   • PORT 应用程序端口（默认 3000）
   • MINIO_EXTERNAL_PORT MinIO外部端口（默认 9000）

3. 数据持久化： 默认使用Docker卷存储。要指定路径，在Compose中设置：

   volumes:
     - /your/data/path:/data  # 替换为实际路径
   

快速部署脚本

Linux/macOS:

./deploy-production.sh

Windows:

deploy-production.bat

选项2：本地开发模式

适用场景：本地开发、调试和代码修改

1. 克隆项目：

git clone <repository-url>
cd mcp-server-chart-minio

2. 安装系统依赖项（用于Canvas图像渲染）：

# macOS
brew install pkg-config cairo pango libpng jpeg giflib librsvg pixman

# Ubuntu/Debian
sudo apt-get install pkg-config libcairo2-dev libpango1.0-dev libpng-dev libjpeg-dev libgif-dev librsvg2-dev libpixman-1-dev

3. 启动MinIO存储服务（仅MinIO）：

npm run docker:up:minio
# 或
docker compose -f docker-compose.minio.yml up -d

4. 安装项目依赖项：

npm install

5. 配置环境变量：

   • 确保存在.env文件（用于本地开发）
   • 默认配置连接到localhost:9000 MinIO

6. 启动开发服务器：

npm run start:dev

7. 访问服务：
   • 📊 API服务http://localhost:4000
   • 📖 API文档http://localhost:4000/api/docs
   • 💾 MinIO控制台http://localhost:9001

📊 API 使用示例

生成线形图

curl -X POST http://localhost:3000/api/chart-generators/line \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"time": "一月", "value": 100},
      {"time": "二月", "value": 120},
      {"time": "三月", "value": 140}
    ],
    "title": "销售趋势图"
  }'

生成饼图

curl -X POST http://localhost:3000/api/chart-generators/pie \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"category": "产品A", "value": 30},
      {"category": "产品B", "value": 25},
      {"category": "产品C", "value": 45}
    ],
    "title": "市场份额"
  }'

🔧 环境配置

配置文件描述

项目提供了两个环境配置文件：

文件	目的	使用场景
.env	本地开发配置	本地运行应用 + 使用Docker运行MinIO
.env.docker	完整Docker部署配置	使用Docker Compose部署全服务

主要区别：

# .env (本地开发)
MINIO_ENDPOINT=localhost        # 本地通过 localhost 访问 Docker 中的 MinIO
PORT=4000                       # 开发端口
NODE_ENV=development

# .env.docker (Docker 部署)
MINIO_ENDPOINT=minio           # 容器间通过服务名通信
PORT=3000                      # 生产端口
NODE_ENV=production

使用说明：

# 本地开发
docker compose -f docker-compose.minio.yml up -d  # 只启动 MinIO
npm run start:dev                                  # 本地运行 app

# Docker 完整部署
docker compose --env-file .env.docker up -d       # 启动所有服务

Docker Compose 参数详细解释

核心服务配置

参数	默认值	描述	修改建议
PUBLIC_API_URL	http://localhost:3000	API服务外部访问地址	生产环境中改为实际IP
MINIO_EXTERNAL_ENDPOINT	localhost	MinIO外部访问地址	生产环境中改为实际IP
MINIO_EXTERNAL_PORT	9000	MinIO外部访问端口	通常保持默认

MinIO存储配置

参数	默认值	描述	修改建议
MINIO_ROOT_USER	minioadmin	MinIO管理员用户名	生产环境中必须修改
MINIO_ROOT_PASSWORD	minioadmin	MinIO管理员密码	生产环境中必须修改（至少8位，包含字母、数字和特殊字符）
MINIO_BUCKET_NAME	charts 默认存储桶名称	根据需要修改
MINIO_ACCESS_KEY	minioadmin	应用访问MinIO账户	生产环境中必须修改
MINIO_SECRET_KEY	minioadmin	应用访问MinIO密码	生产环境中必须修改
MINIO_AUTO_CREATE_BUCKET	false	启动时自动创建存储桶	建议受限账户设为false

应用服务配置

参数	默认值	描述	修改建议
NODE_ENV	production	运行环境	保持默认
PORT	3000	应用程序端口	根据需要修改
HOST	0.0.0.0	监听地址	保持默认

生产环境部署检查清单

✅ 必须修改的配置

• [ ] 修改 PUBLIC_API_URL 实际服务器IP
• [ ] 修改 MINIO_EXTERNAL_ENDPOINT 实际服务器IP
• [ ] 修改 MINIO_ROOT_USER 和 MINIO_ROOT_PASSWORD
• [ ] 更新应用中的 MINIO_ACCESS_KEY 和 MINIO_SECRET_KEY

🔒 安全配置建议

• [ ] 使用强密码（至少8位，包括字母、数字和特殊字符）
• 配置防火墙，仅开放必要端口（3000, 9000, 9001）
• [ ] 启用HTTPS（推荐用于生产环境）
• 定期备份MinIO数据

🌐 网络配置检查

• 确保服务器端口3000、9000和9001是开放的
• [ ] 验证外部网络可以访问这些端口
• [ ] 检查防火墙和安全组设置

配置示例

开发环境配置

# 适用于本地开发，使用默认配置
environment:
  - PUBLIC_API_URL=http://localhost:3000
  - MINIO_EXTERNAL_ENDPOINT=localhost
  - MINIO_ROOT_USER=minioadmin
  - MINIO_ROOT_PASSWORD=minioadmin

生产环境配置

# 适用于生产部署，服务器 IP: 192.168.1.100
environment:
  - PUBLIC_API_URL=http://192.168.1.100:3000
  - MINIO_EXTERNAL_ENDPOINT=192.168.1.100
  - MINIO_ROOT_USER=chart_admin
  - MINIO_ROOT_PASSWORD=SecurePass2024!

本地开发配置示例

.env 文件（已包含在项目中）：

# 基础配置
NODE_ENV=development
PORT=4000
HOST=0.0.0.0
PUBLIC_API_URL=http://localhost:4000

# MinIO 连接配置（本地开发模式）
MINIO_ENDPOINT=localhost        # 连接本地 Docker 中的 MinIO
MINIO_PORT=9000
MINIO_USE_SSL=false
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin

# 存储桶配置
MINIO_BUCKET_NAME=charts
MINIO_AUTO_CREATE_BUCKET=false

# 外部访问配置
MINIO_EXTERNAL_ENDPOINT=localhost
MINIO_EXTERNAL_PORT=9000

Docker部署配置示例

.env.docker 文件（已包含在项目中）：

# 基础配置
NODE_ENV=production
PORT=3000
HOST=0.0.0.0
PUBLIC_API_URL=http://localhost:3000

# MinIO 连接配置（容器间通信）
MINIO_ENDPOINT=minio           # 使用 Docker 服务名
MINIO_PORT=9000
MINIO_USE_SSL=false
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin

# 存储桶配置
MINIO_BUCKET_NAME=charts
MINIO_AUTO_CREATE_BUCKET=true  # Docker 部署时自动创建

# 外部访问配置（生产环境需修改为实际 IP）
MINIO_EXTERNAL_ENDPOINT=localhost
MINIO_EXTERNAL_PORT=9000

🚨 常见问题

Docker Compose部署问题

外部访问问题

问题在虚拟机或服务器上部署后，无法从外部访问服务

解决方案：

1. 检查配置：

   # 展开并查看最终生效的配置（基于 .env.production）
   docker compose --env-file .env.production config
   

2. 修改配置：

   # 推荐直接编辑 .env.production
   nano .env.production
   

3. 重启服务：

   docker compose --env-file .env.production down
   docker compose --env-file .env.production up -d
   

端口冲突问题

问题启动时端口被占用

解决方案：

# 检查端口占用
netstat -tulpn | grep -E "(3000|9000|9001)"

# 修改端口映射（在 docker-compose.yml 中）
ports:
  - "3001:3000"  # 改为 3001
  - "9002:9000"  # 改为 9002
  - "9003:9001"  # 改为 9003

权限问题

问题MinIO数据目录权限不足

解决方案：

# 创建数据目录并设置权限
sudo mkdir -p /docker/minio-data
sudo chown -R 1000:1000 /docker/minio-data

# 在 docker-compose.yml 中指定路径
volumes:
  - /docker/minio-data:/data

网络连接问题

问题容器之间无法通信

解决方案：

# 检查网络状态
docker network ls
docker network inspect mcp-server-chart-minio_mcp-network

# 重新创建网络
docker compose down
docker system prune -f
docker compose up -d

Canvas依赖问题

如果在安装依赖项时遇到Canvas编译错误：

# 清除缓存重新安装
npm cache clean --force
rm -rf node_modules
npm install

# Apple Silicon Mac
arch -x86_64 npm install canvas

# Ubuntu/Debian 安装系统依赖
sudo apt-get update
sudo apt-get install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev

MinIO连接问题

1. 服务状态检查：

   # 检查容器状态
   docker compose ps
   
   # 查看 MinIO 日志
   docker compose logs minio
   
   # 检查健康状态
   docker compose exec minio curl -f http://localhost:9000/minio/health/live
   

2. 访问权限检查：

   # 测试 MinIO API 连接
   curl -I http://你的服务器IP:9000
   
   # 检查防火墙状态（Ubuntu）
   sudo ufw status
   sudo ufw allow 9000
   sudo ufw allow 9001
   

容器启动问题

内存不足

# 检查系统资源
docker system df
free -h

# 清理无用容器和镜像
docker system prune -a

镜像构建失败

# 重新构建镜像
docker compose build --no-cache app

# 查看构建日志
docker compose build app --progress=plain

数据持久性问题

数据丢失

预防措施：

# 备份 MinIO 数据
docker run --rm -v mcp-server-chart-minio_minio_data:/source -v $(pwd):/backup busybox tar czf /backup/minio-backup.tar.gz -C /source .

# 恢复数据
docker run --rm -v mcp-server-chart-minio_minio_data:/target -v $(pwd):/backup busybox tar xzf /backup/minio-backup.tar.gz -C /target

访问拒绝错误解决方案

问题描述

出现类似以下错误信息：

<Error>
<Code>AccessDenied</Code>
<Message>Access Denied.</Message>
<Key>chart-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png</Key>
<BucketName>charts</BucketName>
</Error>

根因分析

此错误通常是由于MinIO存储桶权限配置不正确导致的：

1. 存储桶缺少公开读取策略默认情况下，MinIO拒绝所有未经授权的访问
2. 权限策略未正确配置即使存储桶存在，也需要显式访问策略
3. 服务启动顺序问题应用程序服务可能在MinIO完全准备好之前尝试设置策略

解决方案

方法1：重启服务（推荐，最简单）

# 完全重启所有服务
docker compose down
docker compose up -d

# 或者只重启应用服务
docker compose restart app

方法2：手动配置存储桶策略

1. 访问MinIO管理控制台：http://localhost:9001（或您的服务器IP:9001）
2. 使用默认账户登录：
   • 用户名：minioadmin
   • 密码：minioadmin
3. 选择 charts 存储桶
4. 点击“访问策略”
5. 设置为“只读”或“读写”

方法3：使用诊断脚本