DataQ

# 数据质量监控平台 DataQ > 数据质量监控平台，基于 Great Expectations 构建，支持 Snowflake (DEV/QA/UAT)、ADLS Gen2、S3、Unity Catalog (Databricks)、Apache Iceberg (原生读取)，并与 ADF + Airflow + dbt 集成。 **📖 文档站点：<https://theurgicduke771.github.io/DataQ/>** (MkDocs Material — 快速入门、概念、架构、指南)。 **状态：** **v1.0.0 发布 (2026-07-04)** — 8 周路线图完成 (187/189；2 个项目有意识地重新规划到 v1 后)。v1 已**部署到 Azure 容器应用** — API + 工作进程 + 运行时配置的**前端容器应用**（唯一的公开界面；API 在其后面通过内部入口运行），带有 Key Vault、应用洞察和编排轮询。身份验证是一个**通用 OIDC 客户端**（针对 Azure AD 验证；ADR [0028](docs/adr/0028-cloud-neutral-image-runtime-config-generic-oidc.md)）。已完成的 v1 账本存档在 [docs/progress-v1.md](docs/progress-v1.md)；v1 后的实时进度在 [docs/progress.md](docs/progress.md)。 ## 功能 - **检查 5 个数据源** — Snowflake、Unity Catalog (Databricks)、ADLS Gen2 + S3 平面文件（CSV/Parquet，批处理模式）和 Apache Iceberg（原生 `pyiceberg` 读取）。五种检查样式：**GX 期望**、**自定义 SQL**（返回行数 = 失败）、**新鲜度/容量监视器** 和 **比较**（协调两个数据源的连接 — ADR 0015）；以及列分析器和每个数据源的干运行预览。[功能矩阵 →](https://theurgicduke771.github.io/DataQ/feature-matrix/) - **资产、血缘和事件** — 表/文件是一等公民：健康状况汇总到它针对的每个套件中，**表级血缘**（从 dbt 的清单或 OpenLineage 目录中获取源和影响范围的左侧到右侧图），以及开放事件。资产是主要视角 — 仪表板和侧边栏以资产为导向（ADR 0034）。[概念 →](https://theurgicduke771.github.io/DataQ/concepts/) - **按维度评估质量** — 每个检查都分类（准确性、完整性、一致性、完整性、及时性、唯一性、有效性），并根据检查类型自动填充。资产 **记分卡** 将其转化为人们实际提出的问题：不仅限于“检查是否通过”，还包括 **“什么都没有被监控”** — 资产如果没有及时性检查，则会显示，并且永远不会显示绿色勾选。[维度 →](https://theurgicduke771.github.io/DataQ/datasources-checks/) - **三种运行模式** — 立即运行（实时进度 + 取消）、**cron 调度**（时区/夏令时感知）和 **管道触发器**：ADF、Airflow **和 dbt** 运行受到监控，成功的管道可以触发绑定的套件。[调度 →](https://theurgicduke771.github.io/DataQ/scheduling/) · [编排 →](https://theurgicduke771.github.io/DataQ/orchestration/) - **严重程度 + 警报** — 警告/失败/严重分级对应每个检查的意外百分比；**Teams / Slack / 电子邮件** 警报，具有严重性感知路由、首次失败去重和每个检查的暂停。[通知 →](https://theurgicduke771.github.io/DataQ/notifications/) - **可共享的结果** — 仪表板健康评分 + 趋势，每个运行的深入分析，提供 **PII-已编辑** 的失败行样本，套件级共享（查看/编辑），管理员控制中心。[最佳实践 →](https://theurgicduke771.github.io/DataQ/best-practices/) ## 技术栈 | 层 | 技术 | |---|---| | 后端 | FastAPI · Celery · Great Expectations · SQLAlchemy + Alembic · PostgreSQL · Redis | | 前端 | React · Vite · Ant Design · 通用 OIDC (`oidc-client-ts`) | | 身份验证 / 机密 | OIDC — Azure AD 验证 (`AUTH_*` 合同，提供者中立) · Azure Key Vault | | 托管 | Azure 容器应用（API · 工作进程 · 前端）+ 应用洞察（已部署） | | AI 集成 | FastMCP — 8 个精选 MCP 工具位于 `/mcp`，适用于 Claude Desktop / Copilot / Cursor | ## 快速入门 ### 运行 DataQ — 预构建镜像（推荐） 评估或自我托管约 5 分钟：**无需源码检查，无需 Azure 租户**。只需 Docker。 ```bash curl -O https://raw.githubusercontent.com/TheurgicDuke771/DataQ/main/docker-compose.ghcr.yml docker compose -f docker-compose.ghcr.yml up ``` 打开 **<http://localhost:3000>** — 栈已迁移并填充了演示数据，处于 **dev-bypass 身份验证**（每个请求都是固定的演示用户；无需登录）。API + Swagger 位于 `http://localhost:8000/docs`。镜像从 GHCR 拉取，支持 **多架构**（amd64 + arm64），因此 Apple-Silicon 运行原生。端口仅绑定到 `127.0.0.1`。要固定版本而不是移动标签：`DATAQ_BACKEND_TAG=vX.Y.Z DATAQ_FRONTEND_TAG=vX.Y.Z docker compose -f docker-compose.ghcr.yml up`. > 使用您自己的 Azure AD 进行自我托管？已发布的 frontend 是 **一个通用镜像** — 评估运行使用 `DATAQ_AUTH_MODE=bypass`（关闭身份验证）。对于真正的 SSO，**无需重建**：使用 `DATAQ_AUTH_MODE=oidc` + `DATAQ_AUTH_AUTHORITY` / `DATAQ_AUTH_CLIENT_ID` / `DATAQ_AUTH_API_SCOPE`（运行时注入身份验证配置，ADR 0028）运行相同的镜像，并关闭 `AUTH_DEV_BYPASS`。参见 [入门](https://theurgicduke771.github.io/DataQ/getting-started/)。 ### 从源码开发 DataQ ```bash git clone https://github.com/TheurgicDuke771/DataQ.git cd DataQ ./scripts/setup.sh # conda 环境 + 预提交 + docker-compose + 迁移 conda activate dataq docker-compose up ``` 后端位于 `http://localhost:8000`（Swagger 位于 `/docs`），前端位于 `http://localhost:3000`。 ## MCP（AI 助手访问） DataQ 在 `/mcp` 处暴露了 8 个精选的 MCP 工具（可流式传输的 HTTP）— `list_suites`、`get_suite_results`、`get_health_score`、`get_adf_pipeline_status`、`trigger_suite_run`、`get_run_status`、`create_check`、`profile_column`。端点**受 Azure AD 保护**：呈现 Web UI 使用的相同 bearer token（针对相同的租户/受众/范围验证）。如果未配置 Azure 身份验证，则端点仅在本地 dev-bypass 模式下安装 — 在部署环境中从未未经身份验证（ADR [0008](docs/adr/0008-mcp-server.md)）。 将任何 MCP 客户端指向 `https://<your-dataq-host>/mcp/`（保留 **尾部斜杠** — `/mcp` 307-重定向，一些客户端在重定向时删除 `Authorization` 头部），并带有 `Authorization: Bearer <token>` 头部。配置后，所有 8 个工具都可用于自然语言查询（例如 *“今天 orders 套件中有什么失败？”*、*“在 DEV 上运行 orders 套件”*）。 每个客户端的配置（Claude Desktop / Claude.ai、VS Code / Copilot、Cursor），如何获取令牌，令牌卫生和故障排除：**[AI 助手（MCP 设置）](https://theurgicduke771.github.io/DataQ/mcp-setup/)** 在文档站点上。 ## 文档 | | | |---|---| | **工作协议 + 提交/PR 惯例** | [CONTRIBUTING.md](CONTRIBUTING.md) | | **文档站点（用户指南）** | <https://theurgicduke771.github.io/DataQ/> · 源代码位于 [docs/](docs/)，由 [.github/workflows/docs.yml](.github/workflows/docs.yml) 构建 | | **部署指南 + 环境变量参考** | [deploy/README.md](deploy/README.md) · [.env.app.example](.env.app.example) | | **AI 助手项目指南** | [CLAUDE.md](CLAUDE.md) | | **架构图 + 不变性** | [docs/architecture.md](docs/architecture.md) | | **架构决策记录** | [docs/adr/](docs/adr/) | | **实时任务跟踪器** | [docs/progress.md](docs/progress.md) | | **产品路线图（8 周，100 个任务）** | [context/DataQ_platform_roadmap.md](context/DataQ_platform_roadmap.md) | | **安全策略 + 责任披露** | [SECURITY.md](.github/SECURITY.md) | ## 许可证 MIT — 参见 [LICENSE](LICENSE)。