Schema 扫描

文档版本：2026-06-11
所属模块：02 数据集成（数据库 EL）
页面路由：/workshop1/workbench/:id（工作台页面的「扫描表结构」按钮）
源码依据：前端 web/frontend/src/pages/workshop1/DataSourceWorkbench/index.tsx；后端 web/backend/apps/datasource/api.py

1 用途

从源数据库反射所有表结构并缓存到平台本地（SchemaCache 表），作为后续选择源表和配置同步策略的基础数据。

2 入口

数据源工作台顶部操作栏 → 「扫描表结构」按钮（需 datasource.read 权限）。

3 操作步骤

1. 进入数据源工作台（在数据源列表点击「管理」）
2. 点击顶部「扫描表结构」按钮
3. 系统连接源库，反射所有 schema 和表结构
4. 扫描完成后，左侧面板更新为最新的表列表

4 行为细节

4.1 扫描过程

后端使用 SQLAlchemy Inspector 执行以下反射操作：

1. 获取所有 schema 名称（insp.get_schema_names()）
2. 遍历每个 schema 下的所有表
3. 对每张表反射：
4. 列定义（类型、nullable、is_primary、source_sql_type 等）
5. 主键约束（get_pk_constraint）
6. 普通索引（get_indexes）
7. 唯一约束（get_unique_constraints）
8. 写入或更新 SchemaCache 记录

4.2 系统 Schema 跳过规则

反射时自动跳过以下系统 schema：

数据库类型	跳过的 schema
所有类型	information_schema、performance_schema、sys、mysql
SAP HANA	额外跳过 public、system、_sys_* 前缀

4.3 容错机制

• 对单张表的反射失败（如主键/索引读取异常）不阻断整库扫描
• 失败的 metadata 会被标记 reflection_failed=True，记录错误信息
• 这样即使源库中存在部分有问题的表，其余正常的表仍能被扫描到

4.4 缓存内容

每张表的 SchemaCache 记录包含：

字段	内容
columns	列定义列表（名称、类型、source_sql_type、nullable、is_primary、默认值、长度、精度等）
primary_key	主键约束（columns 列表、约束名）
indexes	普通索引列表
unique_constraints	唯一约束列表

4.5 行数估算

左侧面板每张表显示 ~N 行 估算行数，数据来自 SchemaCache.row_count_estimate 字段（由扫描时 row_count_estimate 返回）。

5 交互反馈

状态	页面表现	用户下一步
扫描中	「扫描表结构」按钮 loading	等待结果（前端超时 300 秒）
扫描成功	提示"成功同步 N 张表"，左侧面板刷新	在左侧浏览和选择表
扫描失败	弹出错误提示（如连接超时、权限不足等）	检查数据源连接信息

6 注意事项

• 首次扫描大库（>1000 张表）可能需要几十秒，前端超时设为 300 秒
• 扫描是覆盖式的：每次扫描会更新已有表的缓存，并保留不再存在的旧缓存记录
• 扫描不影响已有的源表配置（SourceTable/SourceColumn），只是更新 Schema 缓存
• 扫描完成后如果已有源表，工作台会自动对比 SchemaCache 和源表配置，标记源库中已删除的列为「缺失」

7 相关 API

• POST /api/datasources/{id}/refresh-schema/ — 扫描表结构
• GET /api/datasources/{id}/schema/ — 获取已缓存 Schema 列表

详见 api-reference/02-db-ingestion/datasources.md

8 验收点

验收项	操作	预期结果
正常扫描	创建 PostgreSQL 数据源后点击扫描	显示扫描到的表数量，左侧面板展示表列表
系统 schema 跳过	扫描包含 information_schema 等的库	系统表不在列表中出现
大库扫描	扫描超过 1000 张表的库	按钮持续 loading 直到完成
连接失败	数据库不可达时扫描	提示具体错误信息