01 — 产品概览与架构

文档版本：2026-06-11 · v3.0
适用读者：所有用户 — 产品、实施、测试、新成员、甲方验收
API 技术参考：api-reference/01-overview.md

---

1 产品定位

SMDS（单机现代数据栈）是一套面向中小企业的自助式数据平台，将现代数据栈的核心能力——数据集成、数据仓库、数据治理、数据服务——整合为 Docker Compose 一键部署的单机解决方案。

核心价值主张：

特性	说明
开箱即用	docker compose up 即可启动完整数据平台，无需逐个安装组件
低门槛	可视化 Web UI 操作，无需手写 EL 代码，业务人员也能参与数据治理
双通道数据集成	同时支持数据库直连（MSSQL / Postgres / MySQL / HANA 等）和 REST API 连接器
数据治理一体化	字段映射、质量规则、安全分级在一个工作流中完成
Dev / Prod 隔离	开发环境与生产环境的配置和调度完全隔离，通过发布中心一键同步

---

2 整体架构

2.1 数据流全景

flowchart TB
    subgraph 接入层["数据集成层（双通道）"]
        direction LR
        subgraph DBEL["DB EL 通道"]
            DB1["源库<br/>MSSQL / PG<br/>MySQL / HANA"]
            DB2["dlt<br/>YAML 驱动<br/>db_{id}.yml"]
        end
        subgraph APIEL["API EL 通道"]
            API1["REST API<br/>CRM / ERP<br/>WMS / OA"]
            API2["dlt 自定义 source<br/>api_{id}.yml"]
        end
    end

    subgraph 湖仓层["数据湖 / 仓库层"]
        ICE["MinIO / Iceberg<br/>ODS Raw（bronze）"]
        SR["StarRocks<br/>External Catalog"]
        DBT["dbt<br/>DWD → DWS → DM"]
    end

    subgraph 服务层["数据服务层"]
        DMUI["数据资产 UI<br/>查询 / 浏览 / 编辑"]
        DAPI["数据服务 API<br/>外部系统调用"]
    end

    DB1 --> DB2 --> ICE
    API1 --> API2 --> ICE
    ICE --> SR --> DBT
    DBT --> DMUI
    DBT --> DAPI

2.2 数仓分层（Medallion Architecture）

SMDS 采用数仓分层体系，由 dbt 模型串联各层：

层名	代码值（代码中统一）	含义	dbt 目录	StarRocks 数据库	写入方式
ODS Raw	—	原始数据着陆层	—	smds_{env}_db{id}_{db}_{schema}	dlt 写入 Iceberg（bronze 命名空间）
DWD	dwd	数据明细层（治理后的标准化表）	models/dwd/	smds_{env}_dwd	dbt staging（增量合并）
DWS	dws	数据汇总层（聚合 / 宽表）	models/dws/	smds_{env}_dws	dbt intermediate（增量合并 / 增量覆盖 / 全量重建）
DM	dm	数据集市层（面向应用的最终表）	models/dm/	smds_{env}_dm	dbt marts（增量 / 全量）

dbt 框架内部概念（staging / intermediate / marts）与业务命名（dwd / dws / dm）一一对应。代码存储值统一使用 dwd、dws、dm。

2.3 双 EL 通道

SMDS 提供两条并行数据集成通道，汇合后进入统一的 dbt 转换链路：

通道	数据源	驱动方式	YAML 模板	Iceberg 命名空间	详情
DB EL	MSSQL / Postgres / MySQL / HANA 等关系型数据库	dlt 连接器 + YAML 配置	db_{id}.yml	db{id}_{db}_{schema}	02 数据集成（DB）
API EL	REST API（CRM / ERP / WMS / OA 等 SaaS）	dlt 自定义 source	api_{id}.yml	api{id}_{connector_type}	03 API 集成

2.4 技术栈

组件	技术	用途
数据集成	dlt (data load tool)	DB EL 和 API EL 的执行引擎
数据湖	Apache Iceberg + Lakekeeper	数据存储格式和 REST Catalog
对象存储	MinIO	S3 兼容存储，存放 Iceberg 数据文件
OLAP 引擎	StarRocks	MPP 查询引擎，支持 External Catalog 直读 Iceberg
数据转换	dbt-core	SQL 模型定义和执行（DWD / DWS / DM）
编排调度	Dagster	任务编排、定时调度、自动化条件触发
后端 API	Django + Django Ninja	REST API 服务
前端	React + TypeScript + Vite + Ant Design	Web UI
桌面客户端	Electron（可选）	独立窗口、API 代理、系统托盘、自动更新
数据库	PostgreSQL	元数据存储（lakekeeper / dagster / smds 三个库）
反向代理	Nginx	统一入口、TCP/HTTP 代理

---

3 三车间工作流

平台核心操作按"车间"组织，对应左侧菜单"数据工厂"分组下的四个主要模块：

flowchart LR
    subgraph 一车间["一车间：数据集成"]
        W1A["创建数据源"]
        W1B["同步 Schema"]
        W1C["配置源表"]
    end
    subgraph 二车间["二车间：数据治理"]
        W2A["字段映射"]
        W2B["质量规则"]
        W2C["安全分级"]
        W2D["发布 DWD"]
    end
    subgraph 三车间["三车间：数据开发"]
        W3A["DWS/DM 模型"]
        W3B["SQL 编写"]
        W3C["质量测试"]
        W3D["发布"]
    end

    W1A --> W1B --> W1C
    W1C --> W2A --> W2B --> W2C --> W2D
    W2D --> W3A --> W3B --> W3C --> W3D
    W3D --> SERVICE["数据服务 / 数据资产"]

车间	模块名称	做什么	输出	文档
一车间	数据集成	连接数据源，把原始数据搬到平台	ODS Raw 原始表	02 数据集成（DB）、03 API 集成
二车间	数据治理	字段标准化、质量规则、安全分级	DWD 标准明细表	04 数据治理
三车间	数据开发	聚合计算、宽表生成、应用模型	DWS 汇总表 / DM 应用表	05 数据开发
四车间	数据服务	对外暴露 REST API	外部系统可调用	06 数据服务

核心流程口诀：接入 → 治理 → 加工 → 开放（02 → 04 → 05 → 06）

---

4 用户角色与权限

SMDS 面向中小企业的数据团队，通过 RBAC（基于角色的权限控制）管理各用户的功能访问权限。

4.1 角色定义

角色	典型人员	核心职责	常用模块
数据需求分析师 📋	业务人员、产品经理	定义数据标准、确认业务口径、探索数据	数据治理、数据资产、数据服务
数据开发工程师 🔧	数据工程师	配置数据源、设计模型、编写 SQL、执行发布	数据集成、数据治理、数据开发、发布与运维
数据分析人员 📊	BI 分析师、运营分析师	自助查询数据、调用 API、AI 辅助分析	数据资产、数据服务、AI 助手
平台管理员 ⚙️	IT 运维、管理员	管理用户权限、监控系统健康、执行发布	系统管理、发布与运维、资源监控

4.2 各角色关注模块

功能模块	数据需求分析 📋	数据开发 🔧	数据分析 📊	平台运维 ⚙️
02 数据集成（DB）	★ 了解可接入哪些数据	★★★ 配置数据源与同步	★ 了解数据从哪来	★ 监控同步运行
03 API 集成	★ 了解可对接哪些 SaaS	★★★ 配置连接器与任务	★ 了解数据从哪来	★ 监控同步运行
04 数据治理	★★★ 定义字段标准与质量规则	★★★ 执行治理与映射	★★ 查看标准化结果	—
05 数据开发	★★ 审核业务口径	★★★ 编写模型 SQL	★ 了解有哪些可用模型	—
06 数据服务	★★ 定义 API 需求	★ 配置端点	★ 调用 API 获取数据	★ 管理 API 应用
07 数据资产	★★★ 浏览和探索数据	★★ SQL 查询验证	★★★ 自助分析数据	—
08 血缘与监控	★ 查看数据来源	★ 排查问题	★ 确认数据新鲜度	★★★ 监控运行
09 发布与运维	—	★ 提交发布	—	★★★ 执行发布与回滚
10 系统与 AI	—	—	★★ AI 辅助分析	★★★ 用户管理与配置

★★★ = 核心使用者 ★★ = 常用 ★ = 了解即可 — = 一般不涉及

4.3 权限系统

• 所有页面和操作受角色权限树控制，角色与权限在「系统管理 → 角色与权限」页面配置。
• 超级管理员（is_superuser）自动跳过所有权限检查。
• 各模块的权限标识前缀详见对应模块文档中的"权限标识"章节。
• 详见 10 系统管理与 AI。

---

5 前端页面结构

Web UI 采用顶部导航栏 + 左侧菜单 + 内容区三栏布局。

5.1 顶部导航栏

区域	内容
左上角	Logo + 平台名称"安捷智数——数据集成与治理平台"
右上角	设置按钮、当前用户名、退出登录按钮

5.2 左侧菜单结构

三大菜单分组，对应路由代码 web/frontend/src/router/index.tsx 中 appRoutes 定义：

数据工厂

菜单项	前端路由	功能	文档
📊 数据集成	/workshop1	DB 数据源列表与工作台	02 数据集成
🔗 API 集成	/connector	连接器市场、授权、同步任务	03 API 集成
🛡 数据治理	/workshop2	治理资产列表与工作台	04 数据治理
🧪 数据开发	/workshop3	DWS / DM 模型管理	05 数据开发
🌐 数据服务	/workshop4	API 应用管理	06 数据服务
📜 任务运维	/runs	Dagster 任务运维	08 血缘与监控
✅ 数据契约概览	/contract-tests	dbt 测试概览	05 数据开发 — 数据契约概览

数据资产

菜单项	前端路由	功能	文档
📁 数据资产	/datamanage	数据目录、表浏览、SQL 查询、行内编辑	07 数据资产
🏢 数据血缘	/lineage	全链路资产血缘	08 血缘与监控

系统管理

菜单项	前端路由	功能	文档
👤 用户管理	/system/users	用户 CRUD + 角色分配	10 系统管理
👥 角色与权限	/system/roles	角色 CRUD + 权限树配置	10 系统管理
📋 审计日志	/system/audit	操作审计 + 查询审计	10 系统管理
⚙ AI 设置	/system/ai	模型 / 智能体 / 流水线 / MCP	10 系统管理
🔧 连接器配置	/connector/config	连接器级全局参数（管理员）	03 API 集成
🚀 发布中心	/ops/publish	Dev → Prod 发布与回滚	09 运维管理
☁ 资源监控	/ops/resources	MinIO 存储健康监控	09 运维管理

---

6 服务清单与访问方式

服务	角色	对外访问方式	启动 Profile
postgres	元数据存储（lakekeeper / dagster / smds 三个库）	Nginx TCP Stream → 宿主机 5432	默认
minio	Iceberg 数据文件（S3 兼容）	Nginx HTTP → 宿主机 9000（S3 API）/ 9001（Console）	默认
starrocks	MPP 查询引擎，FE + BE 合一	Nginx → 宿主机 9030（MySQL 协议）/ 8030（FE UI）/ 8040（Stream Load）	默认
lakekeeper	Iceberg REST Catalog	Nginx HTTP → 宿主机 8181	默认
dagster-webserver	Dagster UI & GraphQL	Nginx HTTP → 宿主机 3000	默认
web-backend	Django REST API	直接映射 8000:8000	--profile web
web-frontend	React + Vite 前端	直接映射 5173:5173	--profile web
smds-maintenance	Iceberg / dbt / PostgreSQL 维护任务调度	仅容器内 8090/health（Docker healthcheck）	--profile maintenance

部署和基础设施详情参见 11 部署与架构。

---

7 API 概览

所有 API 通过 /api/ 前缀访问，Swagger 文档地址：http://host:8000/api/docs

路由前缀	模块	说明	文档
/api/accounts/	用户与权限	登录、用户管理、角色与权限	10 系统管理 API
/api/datasources/	数据源管理	DB 数据源 CRUD、连接测试、Schema 同步	02 数据集成 API
/api/connectors/	REST API 连接器	连接器类型、凭证、同步任务	03 API 集成 API
/api/connector-webhook/	连接器 Webhook	OAuth 回调、消息接收	03 API 集成 API
/api/extract/	数据抽取（EL）	源表配置、列配置、游标候选	02 数据集成 API
/api/governance/	数据治理	治理资产、字段映射、质量规则、安全分级	04 治理 API
/api/transform/	数据转换（T）	dbt 模型 CRUD、质量测试、dbt parse	05 加工 API
/api/processing/	数据开发	DM 宽表、SQL 执行与 AI 辅助	05 加工 API
/api/datamanage/	数据资产	数据目录、表浏览、SQL 查询	07 数据资产 API
/api/monitor/	运行监控	Dagster 任务运维、状态查询	08 监控 API
/api/openservice/	服务与开放	API 应用、端点、调用日志	06 开放 API
/api/lineage/	血缘分析	全链路资产拓扑	08 血缘 API
/api/ops/	运维操作	发布、回滚、Schedule 控制、资源监控	09 运维 API
/api/maintenance/	平台维护	Iceberg / dbt / PostgreSQL 维护任务	09 运维 API
/api/audit/	审计日志	操作审计、查询审计	10 系统 API
/api/ai/	AI 能力	智能体、LLM、MCP、聊天、流水线	10 系统 API
/api/tasks/	异步任务	后台任务状态查询	—

---

8 桌面客户端

SMDS 除了通过浏览器访问（http://host:5173），还提供 Electron 桌面客户端（web/client/），主要特性：

特性	说明
独立窗口运行	不依赖浏览器标签页，提供桌面应用体验
自定义协议	通过 app:// 协议访问前端页面
API 代理	内置代理转发后端 API 请求，避免跨域问题
系统托盘	最小化到系统托盘，后台运行
自动更新	支持版本检测和自动更新

桌面客户端仅是浏览器版的包装壳，功能与浏览器版完全一致。日常使用两种方式均可。

---

9 快速上手路径

30 分钟体验全流程

建议按以下顺序操作，快速了解平台核心能力：

步骤	去哪里做	做什么	参考文档
① 登录系统	浏览器打开 http://localhost:5173	用默认账号登录（admin / admin）	10 系统管理
② 接入一个数据库	数据工厂 → 数据集成	注册数据源 → 同步 Schema → 选择源表 → 手动触发同步	02 数据集成
③ 治理源表	数据工厂 → 数据治理	自动创建资产 → 字段映射（可 AI 一键映射）→ 发布为 DWD	04 数据治理
④ 创建汇总模型	数据工厂 → 数据开发	新建 DWS 模型 → 编写聚合 SQL → 配置质量测试	05 数据开发
⑤ 查看数据	数据资产 → 数据资产	浏览 Catalog → 找到表 → 查看数据	07 数据资产
⑥ 发布到生产	系统管理 → 发布中心	Diff 预览 → 预检 → 发布	09 运维管理

💡 步骤 ② 也可以换成 API 连接器（接入一个 ERP / CRM 系统），参考 03 API 集成。

---

10 模块文档索引

完整的 11 个模块文档索引（含 API 参考与页面入口）见顶层 产品文档 README。本页（01 概览）聚焦产品定位、整体架构与核心概念。

---

11 安全注意事项

以下配置仅适用于开发环境。生产环境部署前必须按照下表替换：

项	当前开发值	生产环境替换要求
Lakekeeper 加密密钥	This-is-NOT-Secure!（写在 deploy/.env / docker-compose.yml）	替换为 32+ 字节强随机字符串，通过部署平台的 secret 管理注入
MinIO 凭据	docker-compose.yml 中明文写入的 access / secret key	替换为强随机 key，通过环境变量 / secret 管理注入
Lakekeeper 鉴权模式	allowall（开发模式，任何请求均放行）	切换为 kv2 或同等鉴权模式，配置实际 token / OIDC 提供方