一个完整的低代码Excel数据处理系统，提供Excel数据上传、解析、存储和可视化管理的全流程解决方案。
本项目是一个功能完整的低代码Excel数据处理系统，支持Excel文件上传、解析、存储、查询、编辑和导出等全流程操作。系统采用前后端分离架构，支持多种部署模式。
- 📊 Excel数据管理: 支持Excel文件上传、解析、动态表创建和数据存储
- 🔄 智能映射: 自动识别和建立表间映射关系，支持表名修改
- 📱 响应式界面: 基于Vue 3 + TypeScript + Element Plus的现代化UI
- 🗄️ 数据持久化: 支持MySQL和SQLite数据库，灵活适配不同环境
- 🐳 容器化部署: 完整的Docker部署方案，支持多容器和单容器模式
- 📚 API文档: 自动生成的Swagger API文档和前端API指南
- 🔍 数据查询: 支持复杂条件查询、分页和全文搜索
- ✏️ 数据编辑: 支持在线数据编辑、新增和删除操作
- 📤 数据导出: 支持将数据导出为Excel文件
- 📥 数据导入: 支持Excel数据导入到现有表，包含去重和冲突处理
- 🤖 MCP集成: 提供MCP服务器，支持通过Claude Desktop等工具操作数据
- 🔐 权限控制: 支持登录验证和查询专用页面
- 📊 系统监控: 实时显示系统状态、服务健康和部署信息
- 框架: Vue 3 + TypeScript
- UI组件库: Element Plus
- 路由: Vue Router 4
- 状态管理: Pinia
- 构建工具: Vite
- HTTP客户端: Axios
- 表格处理: SheetJS (xlsx)
- 运行时: Node.js
- 框架: Express.js
- 数据库: MySQL + Sequelize ORM
- 文件上传: Multer
- API文档: Swagger UI + Swagger JSDoc
- 安全: bcryptjs + jsonwebtoken
- 数据处理: SheetJS (xlsx)
- 容器化: Docker + Docker Compose
- Web服务器: Nginx
- 数据库: MySQL 8.0
- MCP 协议: Model Context Protocol
- 传输模式: stdio、HTTP streams
- 开发语言: TypeScript
- 核心依赖: @modelcontextprotocol/sdk、express、axios
Excel_lowCode/
├── backend/ # 后端服务
│ ├── config/ # 配置文件
│ │ └── database.js # 数据库配置
│ ├── controllers/ # 控制器
│ │ ├── deleteController.js
│ │ ├── editController.js
│ │ ├── queryController.js
│ │ ├── updateMappingController.js
│ │ └── uploadController.js
│ ├── docs/ # 文档
│ │ └── swagger.yaml # Swagger配置
│ ├── middleware/ # 中间件
│ │ └── upload.js # 文件上传中间件
│ ├── models/ # 数据模型
│ │ ├── index.js # 模型初始化
│ │ └── TableMapping.js # 表映射模型
│ ├── routes/ # 路由
│ │ ├── data.js # 数据操作路由
│ │ ├── mappings.js # 映射关系路由
│ │ └── upload.js # 文件上传路由
│ ├── utils/ # 工具类
│ │ ├── excelParser.js # Excel解析器
│ │ └── hashGenerator.js # 哈希生成器
│ ├── app.js # 应用入口
│ ├── package.json # 依赖配置
│ └── task.md # 开发任务
├── fe/ # 前端应用
│ ├── src/
│ │ ├── components/ # 组件
│ │ │ ├── Layout/ # 布局组件
│ │ │ │ └── MainLayout.vue
│ │ │ └── icons/ # 图标组件
│ │ ├── router/ # 路由配置
│ │ │ └── index.ts
│ │ ├── services/ # 服务层
│ │ │ └── api.ts # API服务
│ │ ├── stores/ # 状态管理
│ │ │ ├── counter.ts
│ │ │ ├── data.ts # 数据状态
│ │ │ └── files.ts # 文件状态
│ │ ├── views/ # 页面视图
│ │ │ ├── Dashboard.vue # 仪表板
│ │ │ ├── FileManagement.vue # 文件管理
│ │ │ ├── DataBrowser.vue # 数据浏览
│ │ │ ├── DataEditor.vue # 数据编辑
│ │ │ ├── MappingRelations.vue # 映射关系
│ │ │ └── ApiGuide.vue # API指南
│ │ ├── App.vue # 根组件
│ │ └── main.ts # 入口文件
│ ├── package.json # 依赖配置
│ └── task.md # 开发任务
├── docker/ # Docker配置
│ ├── frontend/ # 前端Docker配置
│ │ ├── Dockerfile
│ │ └── nginx.conf
│ ├── backend/ # 后端Docker配置
│ │ └── Dockerfile
│ ├── docker-compose.yml # 生产环境配置
│ ├── docker-compose.local.yml # 本地开发配置
│ ├── init-database.sql # 数据库初始化脚本
│ └── README.md # Docker部署文档
├── MCPServer/ # MCP 服务器
│ ├── src/ # 源代码
│ │ ├── main.ts # 主服务器入口
│ │ ├── tools/ # 工具定义
│ │ │ ├── excelTools.ts # Excel 相关工具
│ │ │ ├── dataTools.ts # 数据操作工具
│ │ │ └── mappingTools.ts # 映射关系工具
│ │ └── utils/ # 工具类
│ │ └── httpClient.ts # HTTP 客户端
│ ├── build/ # 编译输出
│ ├── package.json # 依赖配置
│ └── README.md # MCP 服务器文档
├── run.sh # 启动脚本
└── ReadMe.md # 项目文档
详细配置说明请参考: 项目配置指南
本文档提供完整的项目配置流程，从环境准备到使用 run.sh 启动项目的详细步骤。
- Node.js: >= 16.0.0 (推荐 20.x)
- MySQL: >= 8.0 (可选，支持 SQLite 本地模式)
- Docker: >= 20.10 (用于容器化部署)
使用 run.sh 脚本一键启动项目：
# 克隆项目
git clone <项目地址>
cd Excel_lowCode
# 配置环境变量
cd docker
cp .env.template .env
# 编辑 .env 文件，配置数据库连接等信息
# 返回项目根目录，启动项目
cd ..
./run.sh如需详细了解配置步骤，请参考 完整配置指南，包含：
- 环境准备和依赖安装
- 环境变量配置说明
- 数据库初始化
- 多种运行模式说明
- 故障排除和常见问题
# 本地 SQLite 模式 (推荐开发)
./run.sh --run-local
# 单容器模式 (推荐生产)
./run.sh --unified
# 自定义端口运行
./run.sh --backend-port 4000 --frontend-port 9000 --mcp-port 9100
# 构建后清理缓存
./run.sh --clean# 进入docker目录
cd docker
# 配置环境变量
cp .env.template .env.local
# 编辑.env.local文件
# 启动本地开发环境
./localRun.sh# 进入docker目录
cd docker
# 配置环境变量
cp .env.template .env
# 编辑.env文件，配置生产环境参数
# 构建镜像
./build.sh
# 部署应用
./deploy.sh- 系统概览和统计信息
- 快速访问常用功能
- Excel文件上传和解析
- 文件列表管理
- 文件状态监控
- 数据表格展示
- 数据筛选和搜索
- 分页浏览
- 在线数据编辑
- 批量操作支持
- 数据验证
- 表间关系管理
- 映射规则配置
- 关系可视化
- 接口文档查看
- 接口测试工具
- 使用示例
- Node.js: >= 18.0.0 (推荐 20.x)
- Excel数据管理系统: 运行在 http://localhost:3000
- MCP客户端: Claude Desktop 或其他支持 MCP 协议的客户端
cd MCPServer
npm installnpm run build复制 .env 文件并根据需要修改配置：
# Excel数据管理系统API配置
API_BASE_URL=http://localhost:3000
API_TIMEOUT=30000
# MCP服务器配置
MCP_SERVER_PORT=3001
NODE_ENV=development
# 传输模式配置
MODE=stdio # 可选: stdio, http-streams
# API密钥（HTTP streams模式需要）
API_KEYS=your_api_key1,your_api_key2# 开发模式（支持热重载）
npm run dev
# 或者
npm run start:dev# 构建项目
npm run build
# 启动服务器
npm startstdio 模式（默认） 适用于Claude Desktop等本地客户端：
MODE=stdio npm startHTTP streams 模式 适用于Web客户端和远程连接：
MODE=http-streams npm start在Claude Desktop的配置文件中添加MCP服务器：
{
"mcpServers": {
"excel-data-mcp-server": {
"command": "node",
"args": [
"--env-file=/path/to/your/MCPServer/.env",
"/path/to/your/MCPServer/build/main.js"
]
}
}
}当运行在HTTP streams模式时，服务器提供以下端点：
基础URL: http://localhost:3001 (或配置的端口)
端点:
POST /mcp- 初始化会话或发送MCP消息GET /mcp- 检索服务器到客户端通知（需要会话ID）DELETE /mcp- 终止MCP会话GET /health- 健康检查端点GET /info- 服务器信息端点
会话管理:
HTTP streams模式使用基于会话的通信。在初始化后，在请求中包含 mcp-session-id 头：
# 初始化新会话
curl -X POST \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}' \
http://localhost:3001/mcp
# 在后续请求中使用返回的会话ID
curl -X POST \
-H "x-api-key: your_api_key" \
-H "mcp-session-id: your-session-id" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
http://localhost:3001/mcp认证:
为所有请求设置 x-api-key 头，使用配置的API密钥之一。
curl http://localhost:3001/healthcurl http://localhost:3001/infonode test-websocket.jsupload_excel_file- 上传Excel文件并创建对应的数据表list_excel_files- 列出所有已上传的Excel文件及其映射关系get_excel_metadata- 根据哈希值获取Excel文件的详细信息
query_table_data- 根据哈希值查询对应表的数据（支持分页和条件查询）add_table_record- 向指定表中新增数据记录update_table_record- 根据条件更新表中的数据记录delete_table_record- 根据条件删除表中的数据记录
list_table_mappings- 列出所有Excel文件与动态表的映射关系get_table_info- 根据哈希值获取表的详细信息update_table_name- 根据哈希值更新表映射关系的表名delete_table_mapping- 根据哈希值删除表映射关系，并同步删除对应的数据表check_system_health- 检查Excel数据管理系统的健康状态
POST /api/upload- 上传Excel文件GET /api/upload/files- 获取文件列表
GET /api/data- 查询数据POST /api/data- 新增数据PUT /api/data/:id- 更新数据DELETE /api/data/:id- 删除数据
GET /api/mappings- 获取映射关系POST /api/mappings- 创建映射关系PUT /api/mappings/:id- 更新映射关系
启动后端服务后，访问以下地址查看完整的API文档：
http://localhost:3000/api-docs
CREATE TABLE table_mappings (
id INT AUTO_INCREMENT PRIMARY KEY,
table_name VARCHAR(255) NOT NULL,
hash_value VARCHAR(64) NOT NULL UNIQUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);系统会根据上传的Excel文件自动创建对应的数据表，表名格式为：data_[hash]
- 容器名: excel-lowcode-frontend
- 端口: 80 (生产) / 8080 (开发)
- 健康检查: http://localhost:80/health
- 容器名: excel-lowcode-backend
- 端口: 3000
- 健康检查: http://localhost:3000/health
- 容器名: excel-lowcode-mysql
- 端口: 3306
- 数据库: excel_lowcode
- 使用自定义桥接网络
app-network - 前端通过
backend主机名访问后端服务 - 后端通过
mysql主机名访问数据库服务
# 构建镜像
./build.sh
# 导出镜像
./export-images.sh
# 导入镜像
./import-images.sh# 生产环境部署
./deploy.sh
# 本地开发环境
./localRun.sh
# 服务状态查看
docker-compose ps
# 日志查看
docker-compose logs -f- 使用Vue 3 Composition API
- TypeScript类型支持
- Element Plus组件库
- Pinia状态管理
cd fe
# 开发模式
npm run dev
# 类型检查
npm run type-check
# 构建生产版本
npm run build
# 预览构建结果
npm run preview- Express.js框架
- Sequelize ORM
- JWT认证
- Swagger文档
cd backend
# 开发模式
npm run dev
# 生产模式
npm start
# 测试
npm test-
数据库连接失败
- 检查数据库服务状态
- 验证连接配置
- 检查网络连接
-
文件上传失败
- 检查文件大小限制
- 验证文件格式
- 检查存储权限
-
端口冲突
- 修改docker-compose.yml中的端口映射
- 停止占用端口的服务
-
镜像构建失败
- 清理Docker缓存
- 检查网络连接
- 重新构建镜像
-
MCP Server 连接失败
- 检查Excel数据管理系统是否运行在指定端口
- 验证API_BASE_URL配置是否正确
- 检查网络连接和防火墙设置
-
MCP 工具调用失败
- 检查MCP客户端配置是否正确
- 查看MCP服务器日志获取详细错误信息
- 验证传输模式配置（stdio/http-streams）
-
MCP Server 构建错误
- 运行
npm run build确保TypeScript编译成功 - 检查所有依赖是否已安装
- 验证Node.js版本是否符合要求（>=18.0.0）
- 运行
# 查看所有服务日志
docker-compose logs
# 实时查看日志
docker-compose logs -f
# 查看特定服务日志
docker-compose logs frontend
docker-compose logs backend如有问题，请按以下步骤排查：
- 检查环境变量配置
- 查看服务日志
- 验证数据库连接
- 检查端口占用情况
GPL v3 License
- CZH - 项目创建者和主要开发者
注意: 本文档会随着项目发展持续更新，请定期查看最新版本。