docs/docs-cn/1-data-source-connections.md
适用版本: Data Formulator 0.7+ 面向读者: 使用 Data Formulator 连接数据库、文件存储或 BI 系统的用户与管理员
Data Formulator 的 Load Data 页面会把已经配置或已经连接的数据源显示为独立卡片。 用户不再需要进入旧的 "Database" 标签页逐层选择数据源，而是直接点击对应卡片浏览、 预览并导入数据。
常见入口包括：
在 Load Data 页面点击 Add Connection：
如果连接失败，请检查主机、端口、数据库名、用户名、密码或 token 是否正确。部分数据源还 需要管理员先安装对应依赖包。
每个连接实例都会显示为一张卡片，例如：
PostgreSQL · analytics
MySQL · staging
Superset · prod
同一种数据源可以有多个连接。例如你可以同时保留 MySQL · prod 和
MySQL · staging。它们是两个独立连接，互不共享连接状态和凭证。
管理员预配置的数据源也会显示为卡片，但普通用户不能删除这类连接。
点击一个数据源卡片后，会进入该连接的数据浏览界面：
导入后的表会进入 Data Formulator 的普通数据表列表，可以继续用于可视化、清洗和 Agent 分析。
支持智能筛选的数据源会在预览面板中显示筛选控件。用户可以按文本、数值、日期或布尔值 添加条件。导入时，筛选条件会尽量下推到外部数据源执行，减少导入的数据量。
当前主要支持：
其他数据源可能只支持预览和导入，不一定支持源端筛选。若某个连接器不支持筛选，筛选控件 可能不会显示或不会生效。
BI 系统可以把一个 dashboard 表示为一个可批量导入的数据包。以 Superset 为例：
如果某个数据集导入失败，其他数据集仍可能成功导入。完成后请查看提示信息中的成功和失败 明细。
从连接器导入的表会记录来源信息。只要连接仍然可用，就可以在数据表上执行刷新，重新从外部 数据源拉取数据。
刷新会使用导入时保存的源表、行数、排序和筛选条件。若外部系统权限变化、表被删除或凭证 过期，刷新可能失败，需要重新连接或重新导入。
| 操作 | 适用场景 | 结果 |
|---|---|---|
| Disconnect | 临时断开、切换账号、清理当前登录状态 | 卡片保留，但当前连接状态和保存的服务凭证会被清除 |
| Delete | 不再需要这个连接 | 卡片移除，用户连接配置和保存凭证被删除 |
管理员预配置的数据源通常不能删除。用户只能删除自己创建的连接。
连接数据库或外部系统时，密码、token 等敏感信息不会写入前端，也不会写入普通连接配置。 后端会通过凭证保险箱加密保存这些信息。
本地模式下系统会自动创建：
DATA_FORMULATOR_HOME/.vault_key
DATA_FORMULATOR_HOME/credentials.db
服务器迁移、备份或 Docker 部署时，这两个文件需要和用户数据一起保留。更多说明见
docs/docs-cn/6-credential-vault.md 和 docs/docs-cn/7-server-migration-guide.md。
Connect Local Folder 只在本地模式可用。它允许 Data Formulator 直接读取本机某个目录 中的文件，适合桌面或个人使用场景。
在多人服务器或云部署中，本机目录连接会被禁用，避免用户读取服务器上的任意文件。
可能是对应 Python 依赖未安装。管理员可以查看 /api/data-loaders 返回的 disabled 列表，
或查看服务端启动日志中的安装提示。
可能是服务重启、token 过期、手动断开或凭证已被清除。重新输入凭证或通过 SSO 登录即可。
Disconnect 适合临时断开，连接卡片仍会保留；Delete 会删除用户创建的连接卡片和保存凭证。
不同数据源支持能力不同。PostgreSQL、MySQL 和 Superset 已支持主要的源端筛选；其他数据源 需要等待对应 connector 实现。