✨ 项目简介

DataNexus 面向企业内部大模型、业务系统和自动化工具，提供统一的数据访问中枢。

核心约束

• 🔒 数据库访问只读，禁止 DML / DDL / 高风险 SQL
• 🛡️ 所有输出经过权限校验 → 风控 → 脱敏 → 审计
• ⚡ 双出口复用同一套服务层，零逻辑分叉
• 🚫 未授权默认拒绝，关键调用全链路可追溯
• 🔔 告警规则驱动通知（企业微信 / 钉钉 / 飞书 Webhook）

🏗️ 技术架构

┌─────────────────────────────────────────────────────────┐
│                     Client Layer                        │
│   🤖 AI Models        🌐 Business Systems    🖥️ Admin   │
└────────┬──────────────────┬──────────────────┬──────────┘
         │ MCP Protocol     │ HTTP REST        │ SPA
         ▼                  ▼                  ▼
┌─────────────────────────────────────────────────────────┐
│                   DataNexus Gateway                     │
│  ┌─────────┐  ┌──────────┐  ┌────────────────────────┐  │
│  │ MCP     │  │ REST API │  │ Auth / Rate-Limit /    │  │
│  │ Adapter │  │ Routes   │  │ Masking / Audit        │  │
│  └────┬────┘  └────┬─────┘  └──────────┬─────────────┘  │
│       └──────┬─────┘                   │                │
│         ┌────▼─────────────────────────▼──────────┐     │
│         │          Shared Service Layer            │     │
│         │  datasource · metadata · query · policy  │     │
│         └────────────────┬─────────────────────────┘     │
└──────────────────────────┼──────────────────────────────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
         PostgreSQL    MySQL/SQLS    Oracle …

🚀 快速开始

方式一：Docker Compose 开发环境（推荐）

git clone https://github.com/lm93129/DataNexus.git
cd DataNexus
docker compose -f docker-compose.yml up -d --build

开发环境会从本地 backend/、frontend/ 构建镜像，并启动内置 PostgreSQL。

默认管理员 → admin / admin123

方式二：Docker Compose 生产环境

生产环境使用已发布到 Docker Hub 的镜像，不在目标机器上重新构建代码：

export DATANEXUS_DATABASE_URL="postgresql+asyncpg://user:password@host:5432/datanexus"
export DATANEXUS_SECRET_KEY="replace-with-a-random-secret"
export DATANEXUS_AES_KEY="replace-with-a-random-aes-key"

docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

默认镜像为：

可通过以下变量覆盖镜像来源、版本和端口：

export DOCKERHUB_USERNAME="lm93129"
export DATANEXUS_IMAGE_TAG="latest"
export DATANEXUS_BACKEND_PORT="8000"
export DATANEXUS_FRONTEND_PORT="8088"

方式三：本地开发

cd backend
uv venv
uv pip install -e ".[dev]"
uv run alembic upgrade head
uv run uvicorn app.main:app --reload --port 8000

cd frontend
pnpm install
pnpm dev

📦 技术栈

🛠️ API 概览

MCP 工具

REST 端点

DataNexus 通过 SSE (Server-Sent Events) 传输协议对外暴露 MCP 服务，支持任何兼容 MCP 协议的客户端连接。

连接信息

认证方式

MCP 请求支持两种认证方式，通过 HTTP Header 传递：

Claude Desktop 配置

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "datanexus": {
      "url": "http://localhost:8000/mcp/sse",
      "headers": {
        "X-API-Key": "<your-api-key>"
      }
    }
  }
}

💡 获取 API Key：登录管理端 → 系统设置 → 生成 API Key，或调用 POST /api/v1/auth/api-key/generate

Cursor 配置

在 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "datanexus": {
      "url": "http://localhost:8000/mcp/sse",
      "headers": {
        "X-API-Key": "<your-api-key>"
      }
    }
  }
}

其他 MCP 客户端

任何支持 MCP SSE 传输的客户端均可接入，需配置：

Transport:  SSE
URL:        http://<host>:8000/mcp/sse
Headers:    X-API-Key: <your-api-key>

可用工具

连接成功后，客户端可调用以下 MCP 工具：

[
  {
    "name": "list_datasources",
    "description": "列出当前用户可访问的数据源列表",
    "inputSchema": {
      "type": "object",
      "properties": {},
      "required": []
    }
  },
  {
    "name": "get_database_schema",
    "description": "获取数据库元数据：表名列表或指定表的字段结构",
    "inputSchema": {
      "type": "object",
      "properties": {
        "datasource_id": { "type": "integer", "description": "数据源 ID" },
        "table_name":    { "type": "string",  "description": "表名（可选）" }
      },
      "required": ["datasource_id"]
    }
  },
  {
    "name": "query_database",
    "description": "执行安全的只读 SQL 查询，仅支持 SELECT 语句",
    "inputSchema": {
      "type": "object",
      "properties": {
        "datasource_id": { "type": "integer", "description": "数据源 ID" },
        "sql":           { "type": "string",  "description": "SELECT 查询语句" }
      },
      "required": ["datasource_id", "sql"]
    }
  },
  {
    "name": "call_custom_api",
    "description": "调用平台已封装的内部业务系统 API",
    "inputSchema": {
      "type": "object",
      "properties": {
        "api_name": { "type": "string",  "description": "API 名称" },
        "params":   { "type": "object",  "description": "调用参数（可选）" }
      },
      "required": ["api_name"]
    }
  }
]

注意事项

• 🔒 所有 MCP 工具调用受权限控制，API Key 对应的用户角色决定可访问的工具
• 📝 每次工具调用自动记录审计日志
• ⚠️ query_database 仅允许 SELECT 语句，INSERT / UPDATE / DELETE / DROP 等会被拦截
• 🔗 MCP 与 REST 共用同一套服务层，权限、脱敏、审计行为完全一致

📂 项目结构

DataNexus/
├── backend/                     # FastAPI 后端
│   ├── app/
│   │   ├── core/                # 配置、数据库连接、安全工具
│   │   ├── models/              # SQLAlchemy ORM 模型（含告警/通知）
│   │   ├── schemas/             # Pydantic 请求 / 响应 Schema
│   │   ├── services/            # 核心业务逻辑（双出口共用 + 告警通知）
│   │   ├── api/                 # HTTP REST 路由
│   │   ├── mcp/                 # MCP 协议出口
│   │   ├── datasource/          # 多数据源连接池
│   │   └── middleware/          # 限流、审计中间件
│   ├── tests/                   # pytest 测试套件
│   └── alembic/                 # 数据库迁移脚本
├── frontend/                    # Vue 3 管理端
│   └── src/
│       ├── api/                 # Axios 接口封装
│       ├── components/          # 通用组件
│       ├── layouts/             # 页面布局
│       ├── router/              # 路由 & 登录守卫
│       ├── stores/              # Pinia 状态管理
│       └── views/               # 页面视图
├── docker-compose.yml           # 开发环境编排（本地构建 + 内置 PostgreSQL）
└── docker-compose.prod.yml      # 生产环境编排（Docker Hub 镜像）

🧪 开发指南

运行测试

cd backend && uv run pytest -v

代码质量检查

# 后端：编译检查 + 迁移一致性
cd backend
uv run python -m compileall app tests
uv run alembic heads

# 前端：类型检查 + 生产构建
cd frontend
pnpm build

环境变量

🔐 安全

• 🚫 不要将 .env、API Key、数据库密码或生产密钥提交到仓库
• 🔑 生产环境必须替换 DATANEXUS_SECRET_KEY 和 DATANEXUS_AES_KEY
• 📋 审计日志仅记录请求 / 响应摘要，不保存原始敏感数据
• 🔄 MCP 与 REST 出口保持权限、风控、脱敏和审计行为完全一致

📄 License

MIT