简体中文 | English
企业级 Data API 与元数据治理平台
Connect Data. Serve Intelligence.
云枢 · 数据服务平台是面向企业数据消费场景的一站式 Data-as-a-Service (DaaS) 中枢。它将物理表、自定义 SQL 与语义元数据统一封装为可治理、可审计、可观测的 RESTful API，为 AI Agent、运营控制台与业务系统提供标准化数据访问能力。
平台核心聚焦于以下能力矩阵：
- 🚀 动态资源服务化 (Resource-as-an-API)：
TABLE零代码映射与SQL复杂逻辑封装双模式；Jinja2 动态模板 + 统一 DSL 查询入口。 - 🧪 SQL 实验室 (SQL Lab)：在线编写、调试、AI 辅助生成与修复 SQL，一键发布为生产 API 资源。
- 🗂️ 元数据与数据源治理：多源连接管理（MySQL / ClickHouse / Oracle）、语义元数据、健康度评分与 RBAC 细粒度授权。
- 📦 数据产品目录 (Data Product Catalog)：API 资源产品化发布、业务域浏览、权限申请/审批、资产全景 KPI 与调用量洞察。
- 🛡️ 企业级安全审计：按天分表审计日志、AST 静态 SQL 护栏、API Key + Session 双认证、数据脱敏策略。
- 📊 全链路可观测性：24h/7d 调用趋势、Top 排行、分钟级统计聚合、连接池健康监控。
- 🔌 开放集成：标准化
/api/v1对外接口与管理后台 Portal API，可作为上游 云枢 · 智能体平台 的数据底座。
| 🔐 统一登录入口 (Login) | 📊 可观测性看板 (Dashboard) |
|---|---|
 |
 |
| 🚀 API 资源管理 (Resource Management) | 🧪 SQL 实验室 (SQL Lab) |
 |
 |
| 🛡️ 权限与角色 (RBAC) | 📋 全链路审计 (Audit Logs) |
 |
 |
| 📦 数据产品目录 (Catalog) | 🌐 资产全景 (Asset Panorama) |
 |
 |
- 双模式引擎：
TABLE模式直接映射物理表；SQL模式封装复杂查询逻辑。 - Jinja2 动态模板：在自定义 SQL 中注入条件分支，实现高性能参数化过滤。
- 统一查询 DSL：
/api/v1/query与/api/v1/resources/{key}支持EQ/IN/LIKE/ 范围比较等过滤器。
- 智能 SQL 辅助：LLM 生成、语法纠错、字段中文标签补全。
- 对话式分析：流式返回分析报告，自动生成 ECharts 可视化配置。
- 一键发布：调试通过的 SQL 即时发布为受 RBAC 管控的 API 资源。
- 多源连接池：统一管理 MySQL、ClickHouse、Oracle 连接与角色隔离。
- 语义元数据：数据集、表、字段、指标与实体关系的结构化建模。
- 健康度治理：元数据健康评分、创建人追踪与权限模拟器。
- 细粒度 RBAC：权限精确到数据源、物理表、API 资源点与 UI 元素。
- 全链路审计：
api_access_logs_YYYYMMDD按天分表，支持海量日志读写。 - SQL 安全护栏：
sqlparse静态分析拦截DELETE/DROP等高危操作，强制LIMIT。 - 数据脱敏：全局 / 角色 / 用户级脱敏策略，字段规则可配置。
- 实时看板：调用趋势、Top 接口/用户、在线用户统计。
- 分钟级聚合：
APScheduler异步汇总api_access_stats_1m，看板秒开。 - 连接池监控：各数据源连接池活跃度与健康状态可视化。
- 产品发布：从接口管理一键发布或批量上架至目录，支持草稿 → 已发布 → 下线全生命周期。
- 目录浏览：按业务域、调用量、精选推荐筛选；已发布产品元数据全员可见，权限状态一目了然。
- 权限申请：无权限用户可在产品详情页提交申请，负责人/管理员审批后自动同步 API 资源权限。
- 资产全景：域分布、零调用告警、KPI 统计与调用量趋势（
/api/portal/catalog/panorama）。 - 治理辅助：冗余产品检测、CSV 导出、负责人批量指定与 Playground 快捷调试入口。
- 注册数据源：在管理后台配置 MySQL / ClickHouse / Oracle 连接。
- 定义资源：通过表映射或 SQL 实验室创建
sys_resource_meta资源条目。 - 发布到目录：将 API 资源发布为数据产品，补充业务域、简介与负责人等元数据。
- 发现与申请：用户在数据产品目录浏览、筛选产品；无权限时提交申请，审批通过后获得访问权。
- 对外调用：客户端携带
X-API-Key调用/api/v1/query或资源直连接口。 - 审计回溯：所有调用写入按天分表日志，支持 Trace ID 排障。
详见 architech/design/API_INTEGRATION_GUIDE.md · docs/guides/getting-started.md
| 文档 | 说明 |
|---|---|
| HOW_TO_INSTALL.md | 安装部署与 FAQ |
| architech/README.md | 架构文档索引 |
| architech/design/API_INTEGRATION_GUIDE.md | 对外 API 集成指南 |
| architech/api-schema/sql_execution_api_usage.md | SQL 执行 API 说明 |
| docs/guides/getting-started.md | 开发者快速入门 |
| architech/design/ORACLE_INTEGRATION_GUIDE.md | Oracle 数据源接入 |
| db-prod/README.md | 数据库迁移与幂等 apply 工具 |
| docker/README.md | Docker 构建与部署 |
| architech/design/redis_key_design.md | Redis Key 设计说明 |
| tests/CHECKLIST.md | 自动化测试验收清单 |
.
├── app/ # 后端核心代码 (FastAPI)
│ ├── api/ # API 接口层 (v1 对外 API / portal 管理后台)
│ ├── core/ # 核心配置 (中间件、数据库、Redis)
│ ├── services/ # 业务逻辑 (元数据、权限、AI、查询引擎、产品目录)
│ │ └── data_adapter/ # 多源适配器 (MySQL / ClickHouse / Oracle)
│ ├── utils/ # 工具类 (分表路由、加解密)
│ └── jobs/ # 异步调度 (统计聚合、日志清理)
├── frontend/ # Vue 3 管理后台 (Vite + TailwindCSS)
├── architech/ # 架构设计文档与 API Schema 说明
├── db-prod/ # 数据库版本迁移脚本 (V0-VNN) 及 apply 工具
├── docker/ # 容器化打包与 Docker Compose 部署
├── docs/ # 集成指南与运维文档
├── scripts/ # 运维辅助脚本
├── tests/ # Pytest 自动化测试与验收清单
└── openspec/ # 接口规范变更追踪 (OpenSpec)
| 组件 | 版本要求 |
|---|---|
| Python | 3.10+（推荐 3.13） |
| Node.js | 18+ |
| MySQL | 8.0+ |
| Redis | 6.0+（可选，建议开启） |
1. 配置环境
cd docker
cp ../env.example .env # 配置数据库、Redis、ENCRYPTION_KEY 等2. 构建镜像并导出 tar
| 脚本 | 目标环境 |
|---|---|
./build_linux_x86.sh <version> |
x86_64 Linux 服务器（最常见） |
./build_linux_arm.sh <version> |
ARM64 Linux（鲲鹏 / Ampere 等） |
./build_native.sh <version> |
本机原生架构，仅用于本地试跑 |
# 生产环境（x86 服务器）— Mac 上打 x86 包也用此脚本
./build_linux_x86.sh 1.0.0产物输出至 docker/release/，例如 yunshu-api_1.0.0_linux-amd64_20260628.tar。离线部署：
docker load -i docker/release/yunshu-api_1.0.0_linux-amd64_*.tar
docker tag yunshu-api:1.0.0 yunshu-api:latestMac（Apple Silicon）部署到 x86 服务器时，务必使用
build_linux_x86.sh，不要用build_native.sh。
若提示 docker buildx 不可用（Homebrew docker + Colima 常见）：
./install-buildx.sh
./build_linux_x86.sh 1.0.03. 启动服务
./start-yunshu-api-server.sh服务默认监听 **http://localhost:8000**（管理后台、`/docs` API 文档）。
./dev.sh自动清理旧构建、编译前端、释放 8000 端口并以 --reload 模式后台启动后端，日志写入 app.log。
# 1. 准备环境
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp env.example .env
# 2. 数据库初始化（交互式，支持幂等重复执行）
./db-prod/apply-sql.sh
# 无 Python 环境时：./db-prod/apply-sql-native.sh
# 3. 创建管理员（若未导入 INIT-USER-ADMIN.sql）
python3 scripts/create_admin_user.py
# 4. 编译前端
cd frontend && npm install && npm run build && cd ..
# 5. 启动后端
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload# 终端 1：后端
uvicorn app.main:app --reload --port 8000
# 终端 2：前端热更新
cd frontend && npm run dev本平台是 云枢 · 智维 · AI 体系中的数据服务层，与 云枢 · 智能体平台 互补：
| 平台 | 定位 |
|---|---|
| 数据服务平台（本仓库） | Data API、元数据治理、SQL 实验室、数据产品目录、资产全景、审计与 RBAC |
| 智能体平台 | AI 对话、Agent 编排、ChatBI、知识库、MCP 插件 |
欢迎提交 Issue 与 Pull Request，一同完善这个平台。
- 分支规范：基于
main开发，功能分支命名feature/your-feature-name。 - 提交信息：使用 中文 Commit Message，遵循 Conventional Commits 规范。
- Pull Request：创建 PR 时请按 PULL_REQUEST_TEMPLATE.md 填写说明与测试清单。
- 测试验收：新增功能请更新 tests/CHECKLIST.md。
- 数据库变更：在
db-prod/新增V{N}-description.sql，确保迁移脚本可幂等重复执行。
- Issue：欢迎在 GitHub Issues 中反馈问题与功能建议。
- 邮件：可通过 Issue 留言与我们取得联系。
如果您在使用过程中有任何疑问、功能建议，或者想要获取更多技术资讯，欢迎扫码关注我们的微信公众号：
本项目采用 MIT License 开源，允许自由使用、复制、修改、合并、发布、分发、再许可及销售本软件副本。
Copyright © 2025-2026 Yunshu API Data Platform Contributors. All Rights Reserved.